@gestaltrun/dsh-im-runtime 0.0.0-stage → 0.1.5

package/lib/types/schema.d.ts

@@ -0,0 +1,61 @@
+import { type CredentialKey } from '@deepseek-ai/dsh-credentials';
+import { type ZodType } from 'zod';
+import type { ImAccountId, ImAccountMutationResult, ImAccountView, ImRouteMutationResult, ImRouteView, ImSimulationTargetMutationResult, ImSimulationTargetView, ImSimulationInstanceId, ImSimulationInstanceView } from './types.ts';
+/**
+ * IM 账号凭据的规范地址；续签使用收据绑定的独立代次键，交接映射回此地址。
+ * @param accountId - 当前账号的稳定标识。
+ * @returns 本账号在 Credentials 中的地址。
+ */
+export declare function imAccountCredentialKey(accountId: ImAccountId): CredentialKey;
+/** Stored account fields; listener status is process state and is derived on read. */
+export type ImAccountRecord = Omit<ImAccountView, 'listener'> & {
+    readonly replacedHidden?: {
+        readonly connectionIntent: ImAccountView['connectionIntent'];
+    };
+};
+export declare const imAccountRecordSchema: ZodType<ImAccountRecord>;
+export declare const imRouteSchema: ZodType<ImRouteView>;
+interface StoredRouteOperation {
+    readonly fingerprint: string;
+    readonly result: ImRouteMutationResult;
+}
+interface StoredAccountMutationResult extends Omit<ImAccountMutationResult, 'account'> {
+    readonly account: ImAccountRecord;
+}
+interface StoredAccountOperation {
+    readonly fingerprint: string;
+    readonly result: StoredAccountMutationResult;
+}
+/** One atomic account aggregate: safe account facts, routes, and queryable operation receipts. */
+export interface ImAccountAggregate {
+    readonly account: ImAccountRecord;
+    readonly routes: Readonly<Record<string, ImRouteView>>;
+    readonly routeOperations: Readonly<Record<string, StoredRouteOperation>>;
+    readonly accountOperations: Readonly<Record<string, StoredAccountOperation>>;
+}
+export declare const imAccountAggregateSchema: ZodType<ImAccountAggregate>;
+export declare const imSimulationTargetSchema: ZodType<ImSimulationTargetView>;
+interface StoredSimulationTargetOperation {
+    readonly fingerprint: string;
+    readonly result: ImSimulationTargetMutationResult;
+}
+/** Workspace simulation-target aggregate retaining receipts after target removal. */
+export interface ImSimulationTargetAggregate {
+    readonly workspaceId: import('@deepseek-ai/dsh-workspace').WorkspaceId;
+    readonly target?: ImSimulationTargetView;
+    readonly operations: Readonly<Record<string, StoredSimulationTargetOperation>>;
+}
+export declare const imSimulationTargetAggregateSchema: ZodType<ImSimulationTargetAggregate>;
+/** Parser for one durable manual or two-Session simulation lifecycle. */
+export declare const imSimulationInstanceSchema: ZodType<ImSimulationInstanceView>;
+/** IM configuration storage schema. Cross-account or cross-table transactions are not implied. */
+export declare const imRuntimeDomainSpec: {
+    name: string;
+    version: number;
+    tables: {
+        accounts: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<ImAccountId, ImAccountAggregate>;
+        simulation_targets: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<import("@deepseek-ai/dsh-workspace/types").WorkspaceId, ImSimulationTargetAggregate>;
+        simulation_instances: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<ImSimulationInstanceId, ImSimulationInstanceView>;
+    };
+};
+export {};

package/lib/types/script-clock.d.ts

@@ -0,0 +1,14 @@
+/** Monotonic script time shared by the two Sessions of one simulation. */
+import type { ImClockSource } from './time.ts';
+/** Host-owned clock. Advance between Host steps, including reply-wait timeouts; an unfinished Agent uses the advanced time for later events. */
+export declare class ImScriptClock implements ImClockSource {
+    private readonly realNow;
+    private instant;
+    private anchoredAt;
+    /** @param initialAt - Script origin in 13-digit Unix milliseconds. @param realNow - Source of elapsed real milliseconds. */
+    constructor(initialAt: number, realNow?: () => number);
+    /** @returns Current script instant in Unix milliseconds. */
+    now(): number;
+    /** @param at - Next segment instant; earlier instants keep the running clock, invalid instants throw. */
+    advance(at: number): void;
+}

package/lib/types/sdk.d.ts

@@ -0,0 +1,108 @@
+/** Optional Host SDK capability of an IM transport; account configuration remains runtime-owned. */
+import type { ImAccountId } from './types.ts';
+import type { Branded } from '@deepseek-ai/dsh-brand';
+import type { ImOutboundRequestId } from './delivery-types.ts';
+/** Verified platform single-chat identity, distinct from runtime delivery scopes. */
+export type ImSdkConversationId = Branded<'ImSdkConversationId'>;
+/** Platform message identity linked to persisted inbound or outbound data. */
+export type ImSdkMessageId = Branded<'ImSdkMessageId'>;
+/** Verified platform message recipient UID. */
+export type ImSdkReceiverId = Branded<'ImSdkReceiverId'>;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        imSdk: ImSdkProvider;
+    }
+}
+/** Credential-free process state of an SDK connection. */
+export type ImSdkState = 'offline' | 'connecting' | 'online' | 'reconnecting' | 'refreshing' | 'kicked' | 'login-required' | 'failed' | 'unknown';
+/** Stable SDK failure categories suitable for localized UI. */
+export type ImSdkFailureCode = 'SDK_AUTH_FAILED' | 'SDK_IDENTITY_MISMATCH' | 'SDK_LOGIN_REQUIRED' | 'SDK_STORAGE_FAILED' | 'SDK_REFRESH_UNKNOWN' | 'SDK_REFRESH_FAILED' | 'SDK_TOKEN_NOT_READY' | 'SDK_TOKEN_UNKNOWN' | 'SDK_NETWORK_FAILED' | 'SDK_CLOSED';
+/** Safe SDK process projection; generation identifies one admitted connection. */
+export interface ImSdkStatus {
+    readonly accountId: ImAccountId;
+    readonly state: ImSdkState;
+    readonly generation: number;
+    readonly error?: ImSdkFailureCode;
+}
+/** Host-only protocol notification. Readers validate message/recipient ownership before persistence or model use. */
+export interface ImSdkEvent {
+    readonly accountId: ImAccountId;
+    readonly generation: number;
+    readonly kind: 'message' | 'read-to-reader' | 'read-to-sender' | 'receipt' | 'typing';
+    readonly data: Readonly<Record<string, unknown>>;
+}
+/** Host-authorized bytes and verified direct buyer identity. Files require the observed buyer nickname; images do not. Bytes never enter the status Remote API. */
+export type ImSdkUpload = {
+    readonly name: string;
+    readonly mime: string;
+    readonly bytes: Uint8Array;
+    readonly receiver: ImSdkReceiverId;
+    readonly conversationId: ImSdkConversationId;
+} & ({
+    readonly kind: 'image';
+} | {
+    readonly kind: 'file';
+    readonly receiverNick: string;
+});
+/** Upload metadata is opaque platform JSON, never a local path or an authorization credential. */
+export type ImSdkUploaded = {
+    readonly kind: 'image';
+    readonly metadata: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: 'file';
+    readonly metadata: Readonly<Record<string, unknown>> | string;
+};
+/** One prepared submission. Media and text are exclusive; `requestId` is the SDK `clientId`. */
+export type ImSdkSend = {
+    readonly conversationId: ImSdkConversationId;
+    readonly receiver: ImSdkReceiverId;
+    readonly requestId: ImOutboundRequestId;
+} & ({
+    readonly media: ImSdkUploaded;
+    readonly text?: undefined;
+} | {
+    readonly text: string;
+    readonly media?: undefined;
+});
+/** One authenticated connection lease; methods reject after generation revocation. */
+export interface ImSdkLease {
+    readonly generation: number;
+    readonly signal: AbortSignal;
+    /** @param conversationId - verified single chat. @param messageIds - persisted inbound platform messages. @returns only after platform acknowledgement. */
+    markRead(conversationId: ImSdkConversationId, messageIds: readonly ImSdkMessageId[]): Promise<void>;
+    /** @param conversationId - verified single chat. @param messageId - linked platform message. @returns explicit per-recipient states; absence remains unknown. */
+    queryRead(conversationId: ImSdkConversationId, messageId: ImSdkMessageId): Promise<readonly {
+        readonly uid: ImSdkReceiverId;
+        readonly status: number;
+    }[]>;
+    /** @param conversationId - opaque cid from the raw SDK message. @param signal - optional caller cancellation within this generation. @returns true only when one SDK detail query confirms type 1 for that cid; absent capability, no result or an unconfirmed type leaves realtime reception to SaaS. */
+    isDirectConversation?(conversationId: ImSdkConversationId, signal?: AbortSignal): Promise<boolean>;
+    /** @param receiver - verified buyer UID, never a text transport conversation id. @param signal - optional operation cancellation. @returns SDK-owned single-chat identity; failure occurs before message submission. */
+    resolveConversation(receiver: ImSdkReceiverId, signal?: AbortSignal): Promise<ImSdkConversationId>;
+    /** @param file - authorized private bytes. @param signal - optional upload cancellation within the admitted connection. @returns preparation metadata; no chat message is submitted. */
+    upload(file: ImSdkUpload, signal?: AbortSignal): Promise<ImSdkUploaded>;
+    /** @param media - persisted upload metadata of an owned file message. @returns a fresh HTTPS download URL, never cached as a permanent file reference. */
+    downloadUrl(media: ImSdkUploaded): Promise<string>;
+    /** @param request - prepared media or text. `requestId` is sent as `clientId`. @param signal - caller cancellation. @param authorizeSubmission - optional automatic authority, called once after conversation resolution and immediately before page request dispatch; false refuses without submission. @returns the platform `messageId`, or `failed` only when nothing was submitted. A missing id, timeout, teardown, or rejection after dispatch is `unknown` and must not be resent automatically. */
+    sendMessages(request: ImSdkSend, signal?: AbortSignal, authorizeSubmission?: () => boolean): Promise<{
+        readonly state: 'sent';
+        readonly messageId: ImSdkMessageId;
+    } | {
+        readonly state: 'failed' | 'unknown';
+    }>;
+}
+/** Product SDK Provider projected through its existing platform transport. */
+export interface ImSdkProvider {
+    /** @param accountId - configured runtime account. @returns safe process status; no SDK initialization occurs. */
+    status(accountId: ImAccountId): ImSdkStatus;
+    /** @param accountId - configured account selected by the operator or admitted startup or placement recovery. @param signal - optional restoration cancellation; abort revokes connection admission before cleanup. @returns verified terminal login status. */
+    login(accountId: ImAccountId, signal?: AbortSignal): Promise<ImSdkStatus>;
+    /** @param accountId - account stopped by an explicit command or placement handoff; this method does not mutate online intent. @returns offline status after accepted SDK work, kickout intent writes and page cleanup settle; rejects if cleanup or required intent persistence fails. */
+    logout(accountId: ImAccountId): Promise<ImSdkStatus>;
+    /** @param listener - safe process-state observer. @returns disposer. */
+    subscribe(listener: () => void): () => void;
+    /** @param listener - trusted protocol consumer, responsible for recovery of its mutated state; a throwing consumer is withdrawn and reported without payloads. @returns disposer that stops admission and joins accepted callbacks. */
+    subscribeEvents(listener: (event: ImSdkEvent) => void | Promise<void>): () => Promise<void>;
+    /** @param accountId - account whose online generation is required. @param generation - generation observed from this Provider instance. @param consume - trusted Host consumer; must honor signal and keep private protocol data out of logs. @returns consumer result; rejected when stale or the Provider is withdrawn. */
+    withConnection<T>(accountId: ImAccountId, generation: number, consume: (lease: ImSdkLease) => Promise<T>): Promise<T>;
+}

package/lib/types/service-types.d.ts

@@ -0,0 +1,366 @@
+/** Host service and event declarations kept out of the client-safe DTO entry. */
+import type { ImAutomaticSendAuthorization } from './transport.ts';
+import type { ImInjectSimulationOperatorRequest, ImSimulationOperatorReceipt } from './simulation-operator.ts';
+import type { WorkspaceId } from '@deepseek-ai/dsh-workspace';
+import type { UserMessage } from '@deepseek-ai/dsh-llm';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { ImBeginOutboundAttemptRequest, ImOutboundAttemptId, ImBeginOutboundAttemptResult, ImAgentTaskView, ImCancelPendingAiRequest, ImCommitProviderCursorRequest, ImConversationCursor, ImConversationProjection, ImConversationRecords, ImCustomerSessionListRequest, ImCustomerSessionPage, ImCustomerListPage, ImCustomerListRequest, ImCustomerReadAckRequest, ImDeliveryChange, ImDeliveryOperationId, ImDeliveryScope, ImGetOutboundRequest, ImHandlingControl, ImHistoryPage, ImHistoryQueryRequest, ImImportJsonlHistoryRequest, ImImportJsonlHistoryResult, ImInboundMessageView, ImInboundSenderEvidence, ImInboundOperationQuery, ImInboundPageResult, ImIngestInboundPageRequest, ImMarkSubmittedRequest, ImMarkSubmittedResult, ImManualMessageQuery, ImManualMessageQueryRequest, ImManualMessageResult, ImMessageId, ImMessageSource, ImOutboundPage, ImOutboundQueryRequest, ImOutboundView, ImPendingInboundRequest, ImProviderCursorCommitResult, ImProviderCursorOperationQuery, ImProviderCursorOwner, ImProviderCursorView, ImRealDeliveryScope, ImRealSessionBinding, ImRegisterOutboundRequest, ImRetryManualMessageRequest, ImSendManualMessageRequest, ImSetHandlingControlRequest, ImSettleOutboundAttemptRequest, ImSettleSimulationOutboundRequest, ImSessionReconciliationResult, ImSenderAttribution, ImScopeId } from './delivery-types.ts';
+import type { ImAccountId, ImAccountCandidate, ImAccountSetupId, ImAccountSetupPreview, ImCancelAccountSetupResult, ImConfirmAccountSetupRequest, ImAccountLifecycleRequest, ImAccountMutationResult, ImAccountOperationQuery, ImAccountSetupRequest, ImAccountView, ImAssignedActorCandidate, ImConversationCandidate, ImConversationCandidatePage, ImConversationKind, ImCreateRouteRequest, ImDeleteRouteRequest, ImOperationId, ImPlatform, ImPlatformLoginAttemptId, ImPlatformLoginStatus, ImRebindRouteRequest, ImRevision, ImRouteView, ImRemoveSimulationTargetRequest, ImRouteMutationResult, ImRouteOperationQuery, ImRouteResolution, ImRuntimeChange, ImRuntimeSnapshot, ImSaveRouteRequest, ImSaveSimulationTargetRequest, ImSetAccountPausedRequest, ImSimulationTargetMutationResult, ImSimulationTargetOperationQuery, ImCreateSimulationInstanceRequest, ImCreateManualSimulationInstanceRequest, ImSimulationInjectionQuery, ImInjectSimulationManagedHumanRequest, ImInjectSimulationMemberRequest, ImImportSimulationHistoryRequest, ImImportSimulationHistoryResult, ImSimulationInstanceView, ImSimulationSessionScope } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        imRuntime: ImRuntimeService;
+    }
+    interface Events {
+        /**
+         * IM configuration or process listener state changed. The emitted revision is newer than every prior event from this process.
+         * @param change - changed account, route, target, instance, transport, or listener and its process generation revision.
+         * @mode emit
+         */
+        'imRuntime/changed'(change: ImRuntimeChange): void;
+        /**
+         * Durable inbound, submission, or outbox state changed.
+         * @param change - committed scope and affected message or request identities.
+         * @mode emit
+         */
+        'imRuntime/delivery-changed'(change: ImDeliveryChange): void;
+    }
+}
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** Stable IM identity used to reconcile a Session append with the delivery domain. */
+        im: ImMessageSource;
+        /** 重启中断的稳定日志位置；普通 user/message 和 inbox 事件持有同一输入。 */
+        'im-restart': {
+            readonly kind: 'im-restart';
+            readonly turnStartSeq: import('@deepseek-ai/dsh-session').SessionSeq;
+        };
+    }
+}
+/** Read and mutation surface consumed by the product BFF. */
+export interface ImRuntimeService {
+    /** Process-local sidebar typing; never persisted or sent to an Agent. */
+    readonly typing: Pick<import('./typing.ts').ImTyping, 'snapshot' | 'subscribe'>;
+    /** Instance-private evaluation root and simulation upload queue; absent when using formal storage. */
+    readonly standbyStorageRoot?: string | undefined;
+    /**
+     * Whether this runtime bound a NAS host lease.
+     * This is the condition `ensureEvaluationAccount` uses to reject with `正式云端接待不能创建评测账号`. It stays true after hosting intent is turned off: intent only changes the projected route and does not dispose the lease or call `releaseHostingLease`.
+     * `NasHostLease.holderIdentity()` is a different read. It is undefined before admission and after a fence, while this method can still be true.
+     * The control plane releases the lease only from `CloudNasHostLease.releaseOnStop`, and only when `shouldReleaseOnStop()` is true. The cloud host sets that flag in `releaseFailedPlacement` and `stopLive`, immediately before disposing the lease fiber. A fence or `stopHost` exits without `releaseHostingLease`; the control-plane holder remains until it expires.
+     * Evaluation command proxy (#1216) reads this method, not hosting intent and not `CsHostingEvaluationSummary.canStart`.
+     * @returns True when `nasHostLease` was bound at IM startup, including before admission and while hosting intent is off.
+     */
+    holdsNasLease(): boolean;
+    /** @param sellerId - Host-verified seller. @param workspaceId - Tested Workspace, aligned on every call. @returns Credential-free account and its fixed disabled route; leased cloud runtimes (`holdsNasLease()`), conflicting formal ids and unavailable evaluation data reject. Calls for one runtime are serialized. */
+    ensureEvaluationAccount(sellerId: string, workspaceId: WorkspaceId): Promise<{
+        readonly account: ImAccountView;
+        readonly route: ImRouteView;
+    }>;
+    /** @param accountId - Account to classify by its evaluation domain. @param sellerId - Optional exact seller identity. @returns Whether the stored evaluation account matches; names and id prefixes grant no evaluation authority. */
+    isEvaluationAccount(accountId: ImAccountId, sellerId?: string): boolean;
+    /** @param accountId - Evaluation account whose run finished. @param observedRevision - Route generation held by the run. @returns True after removing that route, or if already absent; false for unknown accounts or a changed generation. The account remains durable. Formal routes cannot be removed. */
+    releaseEvaluationAccountRoute(accountId: ImAccountId, observedRevision: ImRevision): Promise<boolean>;
+    /** @returns After evaluation consumers and handles close; failures reject. */
+    closeEvaluationResources(): Promise<void>;
+    /** @returns After reload against an admitted lease; caller reacquires consumers. */
+    reloadWithNasLease(): Promise<void>;
+    /** @param annotator - Product-owned optional admission analysis. @returns Disposer that prevents further calls. */
+    registerAdmissionAnnotator(annotator: import('./admission-annotations.ts').ImAdmissionAnnotator): () => Promise<void>;
+    /** @param request - owned manual file message and Session or scope. @returns a fresh URL requiring an authenticated SDK generation. */
+    mediaDownloadUrl(request: ImManualMessageQueryRequest): Promise<string>;
+    /** @param request - scope-verified media and private bytes. @param signal - operation lifetime. @returns durable outbox result without automatic resubmission. */
+    sendMediaMessage(request: import('./delivery-types.ts').ImSendMediaMessageRequest, signal?: AbortSignal): Promise<ImOutboundView>;
+    /** @returns 暂停新输入的所有权；等待已准入工作后由调用者恢复。 */
+    pauseInput(): import('./input-drain.ts').ImInputPause;
+    /** @param accountId - 待交接账号。 @returns 仅该账号的暂停；不改变路由代次或其他 Workspace 的运行。停止监听后 resume 拒绝，必须核验交接。 */
+    pauseAccountInput(accountId: ImAccountId): import('./input-drain.ts').ImInputPause;
+    /** @param accountId - 已持有账号输入暂停的账号；只取消其当前实际拥有的运行任务，保留 inbox。 */
+    cancelAccountActivityForPlacement(accountId: ImAccountId): void;
+    /** @param accountId - 已排空账号。 @returns SDK 已主动登出、已接纳踢线意图已提交、监听已停止且未发送自动回复已取消；保留在线意图，失败不恢复。 */
+    stopAccountForPlacement(accountId: ImAccountId): Promise<void>;
+    /** @param accountId - 已鉴权的旺旺账号。 @param workspaceId - 来源客服内置 Workspace。 @returns 最终导出前须排空的独立切片。 */
+    exportAccountForPlacement(accountId: ImAccountId, workspaceId: WorkspaceId): import('./account-placement.ts').ImAccountPlacementSlice;
+    /** @param accountId - Incoming leased account in a Host without startup or maintenance pause, including a previously exported account. @param signal - Drain and incoming transfer lifetime. @returns Account standby held and owned Agent persistence locks released before Session import; failures retain reception stop. */
+    beginAccountPlacementImport(accountId: ImAccountId, signal: AbortSignal): Promise<void>;
+    /** @param accountId - Successfully established incoming account standby; caller must obtain fresh lease authorization and prepare Agents first. Releases this account's import hold and schedules reception without releasing Host startup holds. */
+    releaseAccountPlacement(accountId: ImAccountId): void;
+    /** @param accountId - Account under import hold with its listener stopped. @param checkpoint - Parsed cursor-only checkpoint. @param signal - Pre-CAS validation lifetime. @returns Existing nonnull local cursors match exactly and checkpoint counts are zero; failures preserve stopped reception. */
+    validateAccountCheckpointRecovery(accountId: ImAccountId, checkpoint: import('./checkpoint-recovery.ts').ImAccountCheckpointRecovery['checkpoint'], signal: AbortSignal): Promise<void>;
+    /** @param accountId - Fenced recovery account with an established account import hold. @param request - Parsed checkpoint and caller-verified continuous source fence. @param signal - Activation lifetime. @returns New local task generations are prepared with a logged history-gap notice; old Sessions stay untouched and reception stays paused. Nonzero checkpoint pending/unknown counts reject. */
+    recoverAccountPlacement(accountId: ImAccountId, request: import('./checkpoint-recovery.ts').ImAccountCheckpointRecovery, signal: AbortSignal): Promise<void>;
+    /** @param slice - 已鉴权并校验的切片。 @param workspaceId - 目标内置 Workspace。 @returns 提交配置与投递事实，保持停止；失败可能部分提交，调用者核验。 */
+    importAccountForPlacement(slice: import('./account-placement.ts').ImAccountPlacementSlice, workspaceId: WorkspaceId): Promise<void>;
+    /** @param accountId - 已导入或已在本端接待的账号。 @param prepare - 接收同一空闲 Agent 及已核验账号、Workspace 和持久化会话头的当前任务，准备续写。 @param signal - 激活与身份寿命。 @returns 当前任务准备完毕；未知 Session 不会被创建，失败保留启动暂停。 */
+    prepareAccountPlacement(accountId: ImAccountId, prepare: (agent: import('@deepseek-ai/dsh-agent').Agent, task: import('./delivery-types.ts').ImAgentTaskView) => Promise<void>, signal: AbortSignal): Promise<void>;
+    /** @param accountId - 已释放启动暂停的账号。 @param signal - 激活与身份寿命。 @returns 当前监听已就绪并完成初始追平，或账号按原连接意图保持空闲；失败不代表激活完成。 */
+    waitAccountPlacementReady(accountId: ImAccountId, signal: AbortSignal): Promise<void>;
+    /** @param accountId - 当前账号。 @returns 账号停止、账号暂停或启动暂停中的任一门禁是否生效。 */
+    inputPaused(accountId: ImAccountId): boolean;
+    /** 控制面授权、导入和 prepareResume 完成后幂等释放目标启动暂停，不授予租约。 */
+    releasePlacementStartup(): void;
+    /** 首次开通已生成的账号。之后确认旺旺账号时使用它，不再另生成。 */
+    reservePlacementAccount(accountId: ImAccountId): void;
+    /** @param platform - installed provider selected by the operator. @param signal - caller lifetime until safe instructions are available. @returns current safe interactive login state. */
+    startPlatformLogin(platform: ImPlatform, signal?: AbortSignal): Promise<ImPlatformLoginStatus>;
+    /** @param platform - owning provider. @param attemptId - login identity returned by start. @returns current safe login state. */
+    platformLoginStatus(platform: ImPlatform, attemptId: ImPlatformLoginAttemptId): ImPlatformLoginStatus;
+    /** @param platform - owning provider. @param attemptId - login identity returned by start. @returns cancelled or already-terminal state. */
+    cancelPlatformLogin(platform: ImPlatform, attemptId: ImPlatformLoginAttemptId): Promise<ImPlatformLoginStatus>;
+    /** @returns Formal accounts, their routes and simulation targets referencing visible formal accounts; evaluation resources are excluded. */
+    snapshot(): ImRuntimeSnapshot;
+    /** @param listener - post-commit change observer. @returns disposer for this subscription. */
+    subscribe(listener: (change: ImRuntimeChange) => void): () => void;
+    /** In standby, only evaluation simulation messages are uploaded from private storage. @param binding - hosted traffic eligibility and authenticated upload. @returns async disposer that aborts and awaits requests. */
+    bindMessageUpload(binding: import('./upload-types.ts').ImUploadBinding): () => Promise<void>;
+    /**
+     * Send throttled hosting checkpoints through this transport.
+     * The runtime calls it for durable cursors and reception state changes. The transport owns the lease epoch.
+     * @param transport - one server reporter. A later bind replaces it.
+     * @param activity - current product intent, admission and model availability.
+     * @returns disposer that stops reporting. Local cursors stay.
+     */
+    bindCheckpointTransport(transport: import('./checkpoint.ts').ImCheckpointTransport, activity?: (accountId: ImAccountId) => Omit<import('./checkpoint.ts').ImCheckpointActivity, 'inFlight'>): () => void;
+    /** @param accountId - account whose reception intent, admission, or model state changed. */
+    noteCheckpoint(accountId: ImAccountId): void;
+    /**
+     * Report again after the held lease epoch changes.
+     * A rejected epoch is not reused.
+     * @param accountId - account whose new epoch is now held.
+     */
+    resumeCheckpoint(accountId: ImAccountId): void;
+    /** @param platform - provider whose installed or admitted identities are requested. @param signal - caller lifetime. @returns safe selectable candidates. */
+    listAccountCandidates(platform: ImPlatform, signal?: AbortSignal): Promise<readonly ImAccountCandidate[]>;
+    /** @param accountId - configured account whose provider conversations are listed. @param signal - caller lifetime. @returns provider-known titles with stable conversation ids. */
+    discoverConversations(accountId: ImAccountId, signal?: AbortSignal): Promise<ImConversationCandidatePage>;
+    /** @param accountId - configured account. @param conversationId - platform conversation identifier. @param conversationKind - provider category. @param signal - caller lifetime. @returns provider-known title, or the identifier when the title is unknown. */
+    inspectConversation(accountId: ImAccountId, conversationId: string, conversationKind: ImConversationKind, signal?: AbortSignal): Promise<ImConversationCandidate>;
+    /** @param accountId - configured account. @param signal - caller lifetime. @returns assigned service accounts when the platform exposes them. */
+    listAssignedActors(accountId: ImAccountId, signal?: AbortSignal): Promise<readonly ImAssignedActorCandidate[]>;
+    /** @param request - candidate-bound write-only setup input. @param signal - caller lifetime. @returns safe verified facts and a short-lived Host setup identifier. */
+    previewAccountSetup(request: ImAccountSetupRequest, signal?: AbortSignal): Promise<ImAccountSetupPreview>;
+    /** @param request - setup identifier and idempotency identifier. @returns the durable account-creation outcome. */
+    confirmAccountSetup(request: ImConfirmAccountSetupRequest): Promise<ImAccountMutationResult>;
+    /** @param setupId - unconfirmed setup to release. @returns whether it was released or had already advanced. */
+    cancelAccountSetup(setupId: ImAccountSetupId): ImCancelAccountSetupResult;
+    /** @param accountId - receiving account. @param conversationKind - provider category. @param conversationId - provider conversation. @returns precedence-ordered route resolution. */
+    resolveRoute(accountId: ImAccountId, conversationKind: ImConversationKind, conversationId: string, assignedActorId?: string): ImRouteResolution;
+    /** @param request - candidate-bound setup input for non-interactive Host consumers. @param signal - caller lifetime. @returns the persisted safe account. */
+    addAccount(request: ImAccountSetupRequest, signal?: AbortSignal): Promise<ImAccountView>;
+    /** @param request - account and observed revision. @param setup - verified credentials for the same merchant. @param signal - optional generation cancellation; absent uses an uncancelled operation. @returns durable renewal receipt preserving pause, intent, rules, and history. */
+    renewAccount(request: ImAccountLifecycleRequest, setup: ImAccountSetupRequest, signal?: AbortSignal): Promise<ImAccountMutationResult>;
+    /** @returns all retained Host account facts, including replaced records omitted from Client snapshots. */
+    retainedAccounts(): readonly {
+        readonly account: ImAccountView;
+        readonly replacedHidden: boolean;
+    }[];
+    /** @param request - old account and observed revision after replacement OAuth succeeds. @returns durable disconnection and list removal; rules and history remain retained. */
+    hideReplacedAccount(request: ImAccountLifecycleRequest): Promise<ImAccountMutationResult>;
+    /** @param request - retained account and observed revision. @param setup - new verified credentials for the same merchant. @param signal - optional authorization generation; absent does not cancel. @returns explicit restoration of a replaced account; concurrent lifecycle changes win. */
+    restoreReplacedAccount(request: ImAccountLifecycleRequest, setup: ImAccountSetupRequest, signal?: AbortSignal): Promise<ImAccountMutationResult>;
+    /** @param request - guarded account pause mutation. @returns its durable outcome. */
+    setAccountPaused(request: ImSetAccountPausedRequest): Promise<ImAccountMutationResult>;
+    /** @param request - guarded persistent disconnect intent. @returns its durable outcome. */
+    disconnectAccount(request: ImAccountLifecycleRequest): Promise<ImAccountMutationResult>;
+    /** @param accountId - retained runtime account. @param intent - explicit online intent, persistent kickout, or absence after logout. @param expectedIntent - optional intent-generation CAS for asynchronous connection observations. @returns whether the account write was accepted; rejects if durability cannot be confirmed. */
+    setSdkConnectionIntent(accountId: ImAccountId, intent: ImAccountView['sdkConnectionIntent'], expectedIntent?: {
+        readonly revision: ImAccountView['sdkConnectionIntentRevision'];
+    }): Promise<boolean>;
+    /** @param request - account revision and idempotent operation for a disconnected account or failed listener. @returns durable intent acknowledgement; a fresh accepted operation resets the listener retry budget and starts reconciliation. */
+    reconnectAccount(request: ImAccountLifecycleRequest): Promise<ImAccountMutationResult>;
+    /** @param request - guarded account deletion. @returns its durable outcome; conversation history remains. */
+    deleteAccount(request: ImAccountLifecycleRequest): Promise<ImAccountMutationResult>;
+    /** @param request - guarded provider authorization refresh. @param signal - caller lifetime. @returns its durable outcome. */
+    refreshAccount(request: ImAccountLifecycleRequest, signal?: AbortSignal): Promise<ImAccountMutationResult>;
+    /** @param accountId - owning account. @param operationId - idempotency identifier. @returns stored result or an explicit miss. */
+    queryAccountOperation(accountId: ImAccountId, operationId: ImOperationId): ImAccountOperationQuery;
+    /** @param request - new route tuple and workspace owner. @returns its durable outcome. */
+    createRoute(request: ImCreateRouteRequest): Promise<ImRouteMutationResult>;
+    /** @param request - guarded non-ownership route edit. @returns its durable outcome. */
+    saveRoute(request: ImSaveRouteRequest): Promise<ImRouteMutationResult>;
+    /** @param request - guarded ownership transfer. @returns its durable outcome. */
+    rebindRoute(request: ImRebindRouteRequest): Promise<ImRouteMutationResult>;
+    /** @param request - guarded route deletion. @returns its durable outcome. */
+    deleteRoute(request: ImDeleteRouteRequest): Promise<ImRouteMutationResult>;
+    /** @param accountId - owning account. @param operationId - idempotency identifier. @returns stored result or an explicit miss. */
+    queryRouteOperation(accountId: ImAccountId, operationId: ImOperationId): ImRouteOperationQuery;
+    /**
+     * Keep history flowing for one account without an enabled admit route.
+     * @param accountId - connected account.
+     * @param observation - conversation kind and target to receive.
+     */
+    registerObservation(accountId: ImAccountId, observation: {
+        readonly conversationKind: ImConversationKind;
+        readonly target: import('./types.ts').ImRouteTarget;
+    }): () => void;
+    /** @param request - guarded simulation-target save. @returns its durable outcome. */
+    saveSimulationTarget(request: ImSaveSimulationTargetRequest): Promise<ImSimulationTargetMutationResult>;
+    /** @param request - Formal route and observed target revision. @returns Durable result; evaluation requested, current or receipt targets reject inside the serialized operation before any write. */
+    saveFormalSimulationTarget(request: ImSaveSimulationTargetRequest): Promise<ImSimulationTargetMutationResult>;
+    /** @param workspaceId - Simulated-user Workspace. @returns Its current Host target, including evaluation targets. */
+    simulationTargetForWorkspace(workspaceId: WorkspaceId): import('./types.ts').ImSimulationTargetView | undefined;
+    /** @param request - guarded simulation-target removal. @returns its durable outcome. */
+    removeSimulationTarget(request: ImRemoveSimulationTargetRequest): Promise<ImSimulationTargetMutationResult>;
+    /** @param request - Workspace and observed formal target revision. @returns Durable result; evaluation current or receipt targets reject inside the serialized operation before any write. */
+    removeFormalSimulationTarget(request: ImRemoveSimulationTargetRequest): Promise<ImSimulationTargetMutationResult>;
+    /** @param workspaceId - target-owning workspace. @param operationId - idempotency identifier. @returns stored result or an explicit miss. */
+    querySimulationTargetOperation(workspaceId: WorkspaceId, operationId: ImOperationId): ImSimulationTargetOperationQuery;
+    /** @param sessionId - durable real IM task Session. @returns its frozen target plus current safe account, listener, presentation, and sync facts. */
+    realScopeForSession(sessionId: SessionId): ImRealSessionBinding | undefined;
+    /** @param scopeId - complete conversation identity. @returns current safe account, listener, presentation, and sync facts, even before an Agent task exists. */
+    realBindingForScope(scopeId: ImScopeId): ImRealSessionBinding | undefined;
+    /**
+     * Send one human-manual message.
+     * Session-bound calls may use any locally configured account that owns the
+     * Agent task. Hosting-console callers name the selected {@link ImSendManualMessageRequest.accountId}
+     * and, when no task exists, {@link ImSendManualMessageRequest.scopeId}; unknown,
+     * other-account, and simulation scopes are rejected.
+     * @param request - Session- or scope-bound stable request and text.
+     * @param signal - caller lifetime.
+     * @returns durable manual delivery and identity facts when the account is available.
+     */
+    sendManualMessage(request: ImSendManualMessageRequest, signal?: AbortSignal): Promise<ImManualMessageResult>;
+    /** @param request - Session- or scope-bound stable request identity. @returns durable result without provider activity. */
+    queryManualMessage(request: ImManualMessageQueryRequest): ImManualMessageQuery;
+    /** @param request - Session- or scope-bound uncertain request. @param signal - caller lifetime. @returns provider-confirmed or still-unknown result without sending. */
+    confirmManualMessage(request: ImManualMessageQueryRequest, signal?: AbortSignal): Promise<ImManualMessageResult>;
+    /** @param request - new request linked to an uncertain predecessor. @param signal - caller lifetime. @returns explicit retry delivery result. */
+    retryManualMessage(request: ImRetryManualMessageRequest, signal?: AbortSignal): Promise<ImManualMessageResult>;
+    /** @returns all durable simulation instances in creation order. */
+    listSimulationInstances(): readonly ImSimulationInstanceView[];
+    /** @param instanceId - Host-minted instance identity. @returns its durable state or absence. */
+    getSimulationInstance(instanceId: import('./delivery-types.ts').ImSimulationInstanceId): ImSimulationInstanceView | undefined;
+    /**
+     * Pause automatic buyer delivery and remove simulation operator tools while a Host drives the buyer.
+     * @param instanceId - Running paired simulation; only one Host driver may hold it.
+     * @returns Idempotent disposer; release after stopping the instance, otherwise queued replies resume automatic delivery.
+     */
+    holdSimulationBuyer(instanceId: import('./delivery-types.ts').ImSimulationInstanceId): () => void;
+    /**
+     * Deliver pending AI replies and, during a Host-driven confirmed handoff, received human-dsh replies through native IM input.
+     * AI rows are marked submitted. Staff rows keep their received stage; durable buyer input deduplicates their delivery.
+     * The Host must prepare its buyer state before calling; delivery wakes the buyer Agent.
+     * @param instanceId - Running paired simulation held by exactly one Host driver; otherwise rejects.
+     * @returns Number of AI and eligible staff replies durably delivered to the buyer Session or inbox; zero when none are pending.
+     */
+    deliverSimulationBuyerReplies(instanceId: import('./delivery-types.ts').ImSimulationInstanceId): Promise<number>;
+    /** IANA shop zone configured at runtime load; defaults to Asia/Shanghai. */
+    readonly timeZone: string;
+    /**
+     * Register an external clock for both Sessions of one creating or running simulation.
+     * The source is sampled synchronously for every request step; the caller advances it only
+     * between settled steps. It must return valid Unix milliseconds; its failures stop preparation.
+     * Registration is Host-local and is not persisted or transferred. Re-register after restart.
+     * Real Sessions and other instances always retain their own source or the system clock.
+     * @param instanceId - Host-minted simulation identity; unknown, terminal, or already registered instances fail without mutation.
+     * @param source - caller-owned clock; never modified or disposed by the runtime.
+     * @returns Idempotent disposer restoring system time; also released at instance termination or runtime disposal.
+     */
+    registerSimulationClock(instanceId: import('./delivery-types.ts').ImSimulationInstanceId, source: import('./time.ts').ImClockSource): () => void;
+    /**
+     * @param sessionId - either simulation Session or any real/ordinary Session.
+     * @returns Current Unix milliseconds from that instance's registered source, or Date.now when absent. Source errors propagate.
+     */
+    currentTime(sessionId: SessionId): number;
+    /** @param sessionId - either side of a simulation pair. @returns Host-authoritative role, peer, workspace, and delivery scope. */
+    scopeForSession(sessionId: SessionId): ImSimulationSessionScope | undefined;
+    /** @param request - enabled all-direct route. @returns a durable tested Session with no simulated-user Session. */
+    createManualSimulationInstance(request: ImCreateManualSimulationInstanceRequest): Promise<ImSimulationInstanceView>;
+    /** @param request - live simulated-user Session and optional all-route conversation. @returns durable pair after tested Session flush. */
+    createSimulationInstance(request: ImCreateSimulationInstanceRequest): Promise<ImSimulationInstanceView>;
+    /** @param request - Live simulated-user Session and optional conversation. @returns A pair using a non-evaluation account; evaluation targets reject inside the serialized creation operation. */
+    createFormalSimulationInstance(request: ImCreateSimulationInstanceRequest): Promise<ImSimulationInstanceView>;
+    /** @param request - allow-listed member identity and text. @returns shared-path durable inbound message. */
+    injectSimulationMember(request: ImInjectSimulationMemberRequest): Promise<ImInboundMessageView>;
+    /** @param request - instance and text; Host derives the frozen account actor. @returns shared-path durable inbound message. */
+    injectSimulationManagedHuman(request: ImInjectSimulationManagedHumanRequest): Promise<ImInboundMessageView>;
+    /** @param request - Private operator text and retry identity for a running instance. @returns Durable acceptance in the tested Session; no IM row or transport send. */
+    injectSimulationOperator(request: ImInjectSimulationOperatorRequest): Promise<ImSimulationOperatorReceipt>;
+    /** @param request - original injection identity. @returns durable receipt; never resends. */
+    querySimulationInjection(request: ImSimulationInjectionQuery): ImInboundOperationQuery;
+    /** @param instanceId - instance to close. @returns durable stopping or terminal state without awaiting caller activity. */
+    beginStopSimulation(instanceId: import('./delivery-types.ts').ImSimulationInstanceId): Promise<ImSimulationInstanceView>;
+    /** @param sessionId - trusted tool caller Session. @returns its instance's durable stopping or terminal state. */
+    beginStopSimulationForSession(sessionId: SessionId): Promise<ImSimulationInstanceView>;
+    /** @param instanceId - already-stopping instance. @returns terminal state after both sides and derived work quiesce. */
+    waitSimulationStopped(instanceId: import('./delivery-types.ts').ImSimulationInstanceId): Promise<ImSimulationInstanceView>;
+    /** @param request - instance identity, stable operation, display filename, and local JSONL. @returns durable query-only source counts and updated instance. */
+    importSimulationHistory(request: ImImportSimulationHistoryRequest): Promise<ImImportSimulationHistoryResult>;
+    /** @param listener - post-commit delivery observer. @returns disposer for this subscription. */
+    subscribeDelivery(listener: (change: ImDeliveryChange) => void): () => void;
+    /** @param request - complete real scope, cursor CAS, and provider page. @returns durable page receipt. */
+    ingestInboundPage(request: ImIngestInboundPageRequest): Promise<ImInboundPageResult>;
+    /** @param scope - complete conversation identity. @param operationId - page or import operation. @returns durable receipt or explicit miss. */
+    queryInboundOperation(scope: ImDeliveryScope, operationId: ImDeliveryOperationId): ImInboundOperationQuery;
+    /** @param scope - complete conversation identity. @returns current live-delivery cursor. */
+    getConversationCursor(scope: ImDeliveryScope): ImConversationCursor;
+    /**
+     * Derive one value per conversation whenever its document is parsed or written, so later reads need no document read.
+     * @param project - pure function of one conversation's records; the result must depend only on them and must not keep them.
+     * @returns accessor of the derived values; the caller disposes it with its own lifetime.
+     */
+    projectConversations<T extends object>(project: (records: ImConversationRecords) => T): ImConversationProjection<T>;
+    /** @param owner - platform account and provider feed identity. @returns current feed cursor without claiming conversation ownership. */
+    getProviderCursor(owner: ImProviderCursorOwner): ImProviderCursorView;
+    /** @param request - feed cursor CAS and every durable conversation-page receipt. @returns stored cursor outcome. */
+    commitProviderCursor(request: ImCommitProviderCursorRequest): Promise<ImProviderCursorCommitResult>;
+    /** @param owner - provider feed identity. @param operationId - uncertain cursor operation. @returns durable receipt or explicit miss. */
+    queryProviderCursorOperation(owner: ImProviderCursorOwner, operationId: ImDeliveryOperationId): ImProviderCursorOperationQuery;
+    /** @param request - bounded history cursor and origin filter. @returns ascending message page. */
+    queryHistory(request: ImHistoryQueryRequest): ImHistoryPage;
+    /** @param request - account, real/simulation filter, optional substring, and reader. @returns a keyset page of customer rows. */
+    listCustomers(request: ImCustomerListRequest): ImCustomerListPage;
+    /** @param request - account, source, search and cursor. @returns customer Session references without unread calculations. */
+    listCustomerSessions(request: ImCustomerSessionListRequest): ImCustomerSessionPage;
+    /** @param request - reader, scope, and observed arrival sequence. */
+    ackCustomerRead(request: ImCustomerReadAckRequest): void;
+    /** @param request - scope and pause fields. @returns the stored handling control. */
+    setHandlingControl(request: ImSetHandlingControlRequest): ImHandlingControl;
+    /** @param scopeId - Customer whose durable journal pause needs reconciliation. @param pending - Hold automatic processing until persistence and acknowledgement complete; caller disposal does not release it. */
+    setAutomaticHandlingPausePending(scopeId: ImScopeId, pending: boolean): void;
+    /** @param scopeId - Complete customer scope. @returns Pending journal or durable handling pause blocks automatic processing. */
+    isAutomaticHandlingBlocked(scopeId: ImScopeId): boolean;
+    /** @param scopeId - complete conversation identity. @returns the stored handling control, or absence. */
+    getHandlingControl(scopeId: ImScopeId): ImHandlingControl | undefined;
+    /** @param scopeId - complete conversation identity. @returns the stored scope, or absence. */
+    getDeliveryScope(scopeId: ImScopeId): ImDeliveryScope | undefined;
+    /** @param request - scope and maximum pending live messages. @returns oldest received rows. */
+    pendingInbound(request: ImPendingInboundRequest): readonly ImInboundMessageView[];
+    /** @param scope - complete conversation identity. @returns frozen Agent task assignment, or absence before admission. */
+    getAgentTask(scope: ImDeliveryScope): ImAgentTaskView | undefined;
+    /** @param sessionId - real or simulated IM Agent Session. @returns its newest retained task generation, or absence without creating an Agent or reading Session history. */
+    executionForSession(sessionId: SessionId): ImAgentTaskView | undefined;
+    /** @param scope - complete conversation identity. @param messageId - stored inbound identity. @returns source for an existing Session user/message event. */
+    messageSource(scope: ImDeliveryScope, messageId: ImMessageId): ImMessageSource;
+    /** @param scope - complete conversation identity. @param messageId - stored inbound identity. @returns identified Session user message with durable IM source. */
+    sessionUserMessage(scope: ImDeliveryScope, messageId: ImMessageId): UserMessage;
+    /** @param sessionId - durable Session log to compare with pending delivery rows. @returns matched submissions and ignored stale evidence. */
+    reconcileSession(sessionId: SessionId): Promise<ImSessionReconciliationResult>;
+    /** @param request - Session evidence for atomically submitted inbound rows. @returns committed rows and cursor. */
+    markSubmitted(request: ImMarkSubmittedRequest): Promise<ImMarkSubmittedResult>;
+    /** @param request - query-only JSONL history and idempotency identity. @returns durable import receipt. */
+    importJsonlHistory(request: ImImportJsonlHistoryRequest): Promise<ImImportJsonlHistoryResult>;
+    /** @param request - outbound intent persisted before any send. @returns durable safe outbox row. */
+    registerOutbound(request: ImRegisterOutboundRequest): Promise<ImOutboundView>;
+    /** @param request - Durable automatic dispatch attempt. @param signal - Tool cancellation. @returns Epoch-scoped authorization disposed after provider settlement. */
+    automaticSendAuthorization(request: ImBeginOutboundAttemptRequest & {
+        readonly attemptId: ImOutboundAttemptId;
+    }, signal: AbortSignal): ImAutomaticSendAuthorization;
+    /** @param request - real scope and pending request. @returns sole attempt or durable block. */
+    beginOutboundAttempt(request: ImBeginOutboundAttemptRequest): Promise<ImBeginOutboundAttemptResult>;
+    /** @param request - provider attempt and observed outcome. @returns settled outbox row. */
+    settleOutboundAttempt(request: ImSettleOutboundAttemptRequest): Promise<ImOutboundView>;
+    /** @param request - simulation scope and local request. @returns locally sent outbox row. */
+    settleSimulationOutbound(request: ImSettleSimulationOutboundRequest): Promise<ImOutboundView>;
+    /** @param request - complete scope and request identity. @returns outbox row or absence. */
+    getOutbound(request: ImGetOutboundRequest): ImOutboundView | undefined;
+    /** @param request - bounded outbox history cursor. @returns ascending outbox page. */
+    queryOutbound(request: ImOutboundQueryRequest): ImOutboundPage;
+    /** @param request - scope and terminal reason. @returns discarded automated rows. */
+    cancelPendingAi(request: ImCancelPendingAiRequest): Promise<readonly ImOutboundView[]>;
+    /** @param accountId - authenticated SDK account. @param messageId - platform message ID. @param clientId - SDK UUID. @returns exact durable single-chat matches, without matching content. */
+    matchSdkMessage(accountId: ImAccountId, messageId: string, clientId?: string): readonly import('./read-types.ts').ImSdkMessageMatch[];
+    /** @param scope - complete real scope. @param externalMessageId - provider message identity. @returns matching sent outbox evidence. */
+    findSentOutbound(scope: ImRealDeliveryScope, externalMessageId: string): ImOutboundView | undefined;
+    /** @param scope - complete real conversation. @param evidence - provider actor or echo facts without message-text heuristics. @returns evidence-backed sender category, including human-native for remembered native-client actors. */
+    classifyInboundSender(scope: ImRealDeliveryScope, evidence: ImInboundSenderEvidence): ImSenderAttribution;
+}

package/lib/types/session-events.d.ts

@@ -0,0 +1,28 @@
+import type { ImDeliveryScope } from './delivery-types.ts';
+/** Confirmed buyer reading of one exact durable outbound; observation time is not the buyer's reading time. */
+export interface ImMessageReadEvent {
+    readonly scope: import('./delivery-types.ts').ImRealDeliveryScope;
+    readonly requestId: import('./delivery-types.ts').ImOutboundRequestId;
+    readonly platformMessageId: import('./sdk.ts').ImSdkMessageId;
+    readonly observedAt: string;
+}
+/** Payload recorded when automatic handling is paused for one conversation. */
+export interface ImHandlingPausedEvent {
+    /** Frozen conversation identity. */
+    readonly scope: ImDeliveryScope;
+    /** Pause reason such as `operator-pause` or `forward-*`; never a secret. */
+    readonly reason: string;
+    /** Tool or GUI call identity that initiated the pause; empty when none. */
+    readonly callId: string;
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /** Buyer read evidence for one identified outbound. Required-on-read; the corresponding im-read context is reconstructed from this fact. */
+        'im/message-read': ImMessageReadEvent;
+        /**
+         * Automatic handling was paused for one IM scope. Records the scope, pause
+         * reason, and initiating call id. Contains no secrets. Required-on-read.
+         */
+        'im/handling-paused': ImHandlingPausedEvent;
+    }
+}