@gestaltrun/dsh-im-runtime 0.1.0 → 0.1.6

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

@@ -0,0 +1,28 @@
+/** Safe read-receipt projections and Host-only SDK correlation facts. */
+import type { ImDeliveryScope, ImInboundMessageView, ImOutboundRequestId, ImOutboundView, ImRealDeliveryScope } from './delivery-types.ts';
+import type { ImDirectRecipient } from './types.ts';
+import type { ImBuyerReadState } from './read-state.ts';
+/** Buyer status associated with one durable DSH outbound request. */
+export interface ImReadReceipt {
+    readonly requestId: ImOutboundRequestId;
+    readonly state: ImBuyerReadState;
+}
+/** One exact identifier match in durable OpenAPI history; content equality is never evidence. */
+export interface ImSdkMessageMatch {
+    readonly scope: ImRealDeliveryScope;
+    readonly buyer: ImDirectRecipient;
+    readonly inbound?: ImInboundMessageView;
+    readonly outbound?: ImOutboundView;
+}
+/** Safe read status provider, separate from transport send outcomes. */
+export interface ImReads {
+    /** @param scope - complete conversation. @returns durable buyer status; unknown is omitted. */
+    snapshot(scope: ImDeliveryScope): readonly ImReadReceipt[];
+    /** @param listener - committed scope change. @returns disposer. */
+    subscribe(listener: (scope: ImRealDeliveryScope) => void): () => void;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        imReads: ImReads;
+    }
+}

package/lib/types/restart-recovery.d.ts

@@ -0,0 +1,38 @@
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import type { UserMessage } from '@deepseek-ai/dsh-llm';
+import type { SessionEvent, SessionSeq, SessionLogOffset } from '@deepseek-ai/dsh-session';
+/** 一轮中断及已经登记的同一条跟进输入。 */
+export interface RestartRecovery {
+    readonly turnStartSeq: SessionSeq;
+    readonly message?: UserMessage;
+    readonly consumed: boolean;
+}
+/**
+ * 仅从持久日志或 live Session 的初始 seed 识别中断，再用完整日志核对跟进收据。
+ * @param events - 路由登记 Session 的实际日志。
+ * @param firstLiveSeq - live Session 的公开 seed 结束位置；冷读省略，使用完整持久日志。
+ * @returns 未完成的重启恢复证据；无中断时为空。
+ */
+export declare function restartRecovery(events: readonly SessionEvent[], firstLiveSeq?: SessionLogOffset): RestartRecovery | undefined;
+/** 单个路由 Session 的公开读接口；读取期间可能由其他消费者恢复。 */
+export interface RestartSessionSource {
+    /** @returns 当前已发布 Agent 的公开 seed 偏移；不存在时为空。 */
+    live(): {
+        readonly firstLiveSeq: SessionLogOffset;
+    } | undefined;
+    /** @param signal - Host 生命周期。 @returns 当前 live Session 的已提交事件已刷写；无 live Session 时不写入。 */
+    flush(signal: AbortSignal): Promise<void>;
+    /** @param signal - Host 生命周期。 @returns Session 是否已创建。 */
+    exists(signal: AbortSignal): Promise<boolean>;
+    /** @param signal - Host 生命周期。 @returns 调用者负责关闭的只读句柄。 */
+    open(signal: AbortSignal): Promise<Pick<import('@deepseek-ai/dsh-session-persistence').SessionHandle, 'read' | 'close'>>;
+}
+/**
+ * 读取单个登记 Session；未创建的 Session 留给普通准入恢复，冷读后重新观察 live 所有者。
+ * @param source - Session 的 live 与持久化读接口。
+ * @param signal - 取消读取并释放句柄；取消错误交给 Host 生命周期处理。
+ * @returns 中断与跟进日志证据，或无需恢复。
+ */
+export declare function discoverRestartRecovery(source: RestartSessionSource, signal: AbortSignal): Promise<RestartRecovery | undefined>;
+/** @param error - 公开恢复接口的原始错误。 @param sessionId - 本次恢复 Session。 @returns 同一个 Session 的写入所有权占用可以等待，其他失败必须报告。 */
+export declare function restartFailureDisposition(error: unknown, sessionId: SessionId): 'ownership-wait' | 'failed';

package/lib/types/runtime.d.ts

@@ -1,16 +1,30 @@
+/** Durable IM account, route, and simulation-target service. */
+import { type SqliteLockingMode } from './sqlite-connection.ts';
+import { type ImClockSource } from './time.ts';
+import type { ImInjectSimulationOperatorRequest, ImSimulationOperatorReceipt } from './simulation-operator.ts';
+import type { ImUploadBinding } from './upload-types.ts';
+import type { SqliteJournalMode } from './nas-host-lease.ts';
 import { Context, Service } from '@deepseek-ai/cordis';
 import type { UserMessage } from '@deepseek-ai/dsh-llm';
-import { type SessionId } from '@deepseek-ai/dsh-session';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { SessionId } from '@deepseek-ai/dsh-session';
 import './session-events.ts';
 import type { WorkspaceId } from '@deepseek-ai/dsh-workspace';
 import { type ZodType } from 'zod';
+import { type ImCheckpointActivity, type ImCheckpointTransport } from './checkpoint.ts';
 import type { ImExecutionAggregate } from './delivery-schema.ts';
+import { ImInputDrain, type ImInputPause } from './input-drain.ts';
+import { type ImAccountCheckpointRecovery } from './checkpoint-recovery.ts';
+import { type ImAccountPlacementSlice } from './account-placement.ts';
+import { type ImAdmissionAnnotator, type ImAdmissionAnnotationInput } from './admission-annotations.ts';
+import type { ImSendMediaMessageRequest } from './delivery-types.ts';
+import { ImTyping } from './typing.ts';
 import { ImRoutePolicies } from './policies.ts';
 import type { ImPolicyCheckKind, ImPolicyCheckRequest, ImPolicyDecision } from './policies.ts';
 import { ImTransports } from './transports.ts';
 import type { ImAutomaticSendAuthorization } from './transport.ts';
-import type { ImBeginOutboundAttemptRequest, ImBeginOutboundAttemptResult, ImAgentTaskId, ImAgentTaskView, ImCancelPendingAiRequest, ImCommitProviderCursorRequest, ImConversationCursor, 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, ImOutboundAttemptId, ImOutboundRouteBinding, ImOutboundView, ImPendingInboundRequest, ImProviderCursorCommitResult, ImProviderCursorOperationQuery, ImProviderCursorOwner, ImProviderCursorView, ImRealDeliveryScope, ImRealSessionBinding, ImRegisterOutboundRequest, ImRetryManualMessageRequest, ImSendManualMessageRequest, ImSessionReconciliationResult, ImSenderAttribution, ImSetHandlingControlRequest, ImSettleOutboundAttemptRequest, ImSettleSimulationOutboundRequest, ImSimulationDeliveryScope, ImSimulationInstanceId, ImScopeId } from './delivery-types.ts';
-import type { ImAccountId, ImAccountCandidate, ImAccountSetupId, ImAccountSetupPreview, ImCancelAccountSetupResult, ImConfirmAccountSetupRequest, ImAccountLifecycleRequest, ImAccountSetupRequest, ImAccountMutationResult, ImAccountOperationQuery, ImAccountView, ImAssignedActorCandidate, ImConversationCandidate, ImConversationCandidatePage, ImConversationKind, ImDirectRecipient, ImCreateRouteRequest, ImDeleteRouteRequest, ImOperationId, ImPlatform, ImPlatformLoginAttemptId, ImPlatformLoginStatus, ImRebindRouteRequest, ImRemoveSimulationTargetRequest, ImRouteMutationResult, ImRouteOperationQuery, ImRouteResolution, ImRouteTarget, ImRouteView, ImRuntimeChange, ImRuntimeSnapshot, ImSaveRouteRequest, ImSaveSimulationTargetRequest, ImSetAccountPausedRequest, ImSimulationTargetMutationResult, ImSimulationTargetOperationQuery, ImCreateSimulationInstanceRequest, ImSimulationInjectionQuery, ImInjectSimulationManagedHumanRequest, ImInjectSimulationMemberRequest, ImImportSimulationHistoryRequest, ImImportSimulationHistoryResult, ImSimulationInstanceView, ImSimulationSessionScope, ImSimulationTargetView } from './types.ts';
+import type { ImBeginOutboundAttemptRequest, ImBeginOutboundAttemptResult, ImAgentTaskId, 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, ImOutboundAttemptId, ImOutboundRouteBinding, ImOutboundView, ImPendingInboundRequest, ImProviderCursorCommitResult, ImProviderCursorOperationQuery, ImProviderCursorOwner, ImProviderCursorView, ImRealDeliveryScope, ImRealSessionBinding, ImRegisterOutboundRequest, ImRetryManualMessageRequest, ImSendManualMessageRequest, ImSessionReconciliationResult, ImSenderAttribution, ImSetHandlingControlRequest, ImSettleOutboundAttemptRequest, ImSettleSimulationOutboundRequest, ImSimulationDeliveryScope, ImSimulationInstanceId, ImScopeId } from './delivery-types.ts';
+import type { ImAccountId, ImAccountCandidate, ImAccountSetupId, ImAccountSetupPreview, ImCancelAccountSetupResult, ImConfirmAccountSetupRequest, ImAccountLifecycleRequest, ImAccountSetupRequest, ImAccountMutationResult, ImAccountOperationQuery, ImAccountView, ImAssignedActorCandidate, ImConversationCandidate, ImConversationCandidatePage, ImConversationKind, ImDirectRecipient, ImCreateRouteRequest, ImDeleteRouteRequest, ImOperationId, ImPlatform, ImPlatformLoginAttemptId, ImPlatformLoginStatus, ImRebindRouteRequest, ImRemoveSimulationTargetRequest, ImRevision, ImRouteId, ImRouteMutationResult, ImRouteOperationQuery, ImRouteResolution, ImRouteTarget, ImRouteView, ImRuntimeChange, ImRuntimeSnapshot, ImSaveRouteRequest, ImSaveSimulationTargetRequest, ImSetAccountPausedRequest, ImSimulationTargetMutationResult, ImSimulationTargetOperationQuery, ImCreateSimulationInstanceRequest, ImCreateManualSimulationInstanceRequest, ImSimulationInjectionQuery, ImInjectSimulationManagedHumanRequest, ImInjectSimulationMemberRequest, ImImportSimulationHistoryRequest, ImImportSimulationHistoryResult, ImSimulationInstanceView, ImSimulationSessionScope, ImSimulationTargetView } from './types.ts';
 import type { ImRuntimeService } from './service-types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Events {
@@ -27,32 +41,114 @@ declare module '@deepseek-ai/cordis' {
 }
 /** Stable Wangwang refusal when a direct send has no observed counterpart sender. */
 export declare const WANGWANG_DIRECT_RECIPIENT_UNAVAILABLE = "WANGWANG_DIRECT_RECIPIENT_UNAVAILABLE";
-/** Runtime limits applied to one durable Agent admission. */
+/** Runtime admission, listener recovery, storage, and checkpoint settings. */
 export interface Config {
+    /** IANA shop time zone for inbound records and clock context; defaults to Asia/Shanghai. */
+    readonly timeZone?: string;
+    /** Milliseconds before a verified typing observation disappears; defaults to 5000. */
+    readonly typingTimeoutMs?: number;
+    /** Maximum decoded bytes in one selected media file; SDK and platform limits may be lower. */
+    readonly mediaMaxBytes?: number;
+    /** Delay between durable upload retries; network failures never stop IM delivery. */
+    readonly uploadRetryMs?: number;
+    /** Explicit test run marks real-provider messages as test traffic. */
+    readonly uploadTestRunId?: string | undefined;
     /** Maximum inbound messages copied into one Agent input. */
     readonly admissionBatchSize?: number;
     /** Time that unconfirmed provider setup material remains in Host memory. */
     readonly accountSetupTtlMs?: number;
     /** Sqlite file for conversation, cursor, and execution records. */
     readonly deliverySqlitePath?: string | undefined;
+    /** SQLite 日志模式，本地缺省 WAL，NAS 配置为 DELETE。 */
+    readonly deliveryJournalMode?: SqliteJournalMode;
+    /** Connection locking policy; EXCLUSIVE requires sole ownership until close. Defaults to NORMAL. */
+    readonly deliveryLockingMode?: SqliteLockingMode;
+    /** Page-cache budget in KiB, from 1 through 2147483647; omitted keeps SQLite defaults. */
+    readonly deliveryCacheSizeKiB?: number | undefined;
+    /** 投递库语句遇锁等待毫秒数；NAS 交接窗口内旧实例短暂持锁时等待而非立即失败。整数 0–60000，缺省 2000。 */
+    readonly deliveryBusyTimeoutMs?: number;
+    /** 投递库迁移单步遇锁重试的时间预算毫秒数；超限抛 `IM_DELIVERY_SQLITE_BUSY` 且版本号保持不变。整数 0–600000，缺省 30000。 */
+    readonly deliveryMigrationRetryBudgetMs?: number;
+    /** 云端必须等待 nasHostLease 准入；缺失服务时启动失败。 */
+    readonly requireNasLease?: boolean;
+    /** Private evaluation resources and simulation upload queue when the cloud Host has no lease; requires placement standby. */
+    readonly standbyStorageRoot?: string | undefined;
+    /** 交接目标在导入和 prepareResume 完成前停止监听与新 turn，由 Host 显式释放。 */
+    readonly placementStandby?: boolean;
+    /** Minimum interval between hosting checkpoint reports for one Host. Cursor advances inside the interval share one report. */
+    readonly checkpointIntervalMs?: number;
+    /** Delay before the first listener reconnect attempt, in milliseconds. */
+    readonly listenerReconnectInitialMs?: number;
+    /** Maximum exponential reconnect delay, in milliseconds. */
+    readonly listenerReconnectMaxMs?: number;
+    /** Maximum reconnect starts before stable reception; zero disables retries. */
+    readonly listenerReconnectMaxAttempts?: number;
+    /** Continuous running time before retry reset, in milliseconds; a page committed while running resets it earlier. */
+    readonly listenerReconnectStableMs?: number;
 }
 interface ResolvedConfig {
+    readonly timeZone: string;
+    readonly typingTimeoutMs: number;
+    readonly mediaMaxBytes: number;
+    readonly uploadRetryMs: number;
+    readonly uploadTestRunId?: string;
     readonly admissionBatchSize: number;
     readonly accountSetupTtlMs: number;
+    readonly deliveryJournalMode: SqliteJournalMode;
+    readonly deliveryLockingMode: SqliteLockingMode;
+    readonly deliveryCacheSizeKiB: number | null;
+    readonly deliveryBusyTimeoutMs: number;
+    readonly deliveryMigrationRetryBudgetMs: number;
+    readonly requireNasLease: boolean;
+    readonly standbyStorageRoot?: string | undefined;
+    readonly placementStandby: boolean;
+    readonly checkpointIntervalMs: number;
+    readonly listenerReconnectInitialMs: number;
+    readonly listenerReconnectMaxMs: number;
+    readonly listenerReconnectMaxAttempts: number;
+    readonly listenerReconnectStableMs: number;
     readonly deliverySqlitePath?: string | undefined;
 }
 /** Host service implementing the durable configuration half of IM takeover. */
 export declare class ImRuntime extends Service implements ImRuntimeService {
     static inject: string[];
     static Config: ZodType<Config>;
+    private readonly admissionAnnotations;
+    private readonly simulationClocks;
+    private uploadBinding;
+    private uploadQueue;
+    private settleUploads;
+    private wakeUploads;
+    private readonly restartOwner;
+    private nasLease;
+    /** Instance-private evaluation resource root; absent for formal storage. */
+    standbyStorageRoot: string | undefined;
+    private evaluationAccounts?;
+    private evaluationTail;
     private accounts?;
     private simulationTargets?;
     private simulationInstances?;
     private deliveryRecords?;
+    private readonly mediaLifetime;
+    private mediaSender?;
     private delivery?;
+    /** Host 输入排空；不改变持久化的账号和托管意图。 */
+    readonly inputDrain: ImInputDrain;
+    private readonly placementSdkImports;
+    private placementStandby;
+    private readonly placementImports;
+    private readonly placementRecoveries;
+    private readonly placementImportPauses;
+    /** Input holds of rejected placement-import attempts; the next attempt reuses them instead of adding a hold release cannot reach. */
+    private readonly placementRetryPauses;
+    private readonly placementStopped;
+    private readonly accountInputs;
+    private agentScope;
+    private agentAccounts;
     private coordinator;
     private simulationController;
     private readonly pendingAutomaticPauses;
+    private checkpointReporter;
     private readonly automaticSendEpochs;
     private generation;
     private deliveryGeneration;
@@ -60,15 +156,48 @@ export declare class ImRuntime extends Service implements ImRuntimeService {
     private readonly activeListeners;
     private readonly listenerStates;
     private readonly listenerTails;
+    private readonly listenerRetries;
+    private readonly listenerAttempts;
+    private listenersDisposed;
     private readonly pendingAccountSetups;
+    private readonly setupAccounts;
+    private reservedPlacementAccountId;
     private readonly observations;
     readonly transports: ImTransports;
     readonly policies: ImRoutePolicies;
+    /** Transient sidebar typing; independent of durable delivery and Agent input. */
+    readonly typing: ImTyping;
+    /** Shop time zone used by inbound records and customer-service context. */
+    get timeZone(): string;
     readonly config: ResolvedConfig;
     /** @param ctx - Cordis context carrying StorageDomain and Credentials. @param config - validated Agent admission limits. */
     constructor(ctx: Context, config?: Config);
+    /** @param annotator - Optional product analysis. @returns Disposer that prevents further calls. */
+    registerAdmissionAnnotator(annotator: ImAdmissionAnnotator): () => Promise<void>;
+    /** @param input - Frozen message batch. @param signal - Coordinator lifetime. @returns Results frozen into the pending admission before append. */
+    annotateAdmission(input: ImAdmissionAnnotationInput, signal: AbortSignal): Promise<readonly import('./delivery-types.ts').ImAdmissionAnnotation[]>;
     /** Open the authoritative configuration domain before publishing the service. */
     protected [Service.init](): Promise<void>;
+    private initializeMediaResources;
+    /**
+     * Bind the product's authenticated customer-message transport. Standby uploads only evaluation simulation messages from private storage. A journal in each SQLite mutation bridges crashes before the external queue is synced.
+     * @param binding - capture eligibility and credential-free destination, plus cancellable transport.
+     * @returns async disposer that aborts and awaits the current request before SQLite closes.
+     */
+    bindMessageUpload(binding: ImUploadBinding): () => Promise<void>;
+    private reportUpload;
+    /**
+     * Send throttled hosting checkpoints through this transport.
+     * @param transport - server reporter. A later bind replaces the previous one.
+     * @param activity - product-owned intent, admission and model availability.
+     * @returns disposer that stops reporting.
+     */
+    bindCheckpointTransport(transport: ImCheckpointTransport, activity?: (accountId: ImAccountId) => Omit<ImCheckpointActivity, 'inFlight'>): () => void;
+    /** @param accountId - account whose held lease epoch changed. */
+    resumeCheckpoint(accountId: ImAccountId): void;
+    /** @param accountId - account whose automatic reception state changed. */
+    noteCheckpoint(accountId: ImAccountId): void;
+    private checkpointFacts;
     snapshot(): ImRuntimeSnapshot;
     subscribe(listener: (change: ImRuntimeChange) => void): () => void;
     startPlatformLogin(platform: ImPlatform, signal?: AbortSignal): Promise<ImPlatformLoginStatus>;
@@ -82,16 +211,55 @@ export declare class ImRuntime extends Service implements ImRuntimeService {
     previewAccountSetup(request: ImAccountSetupRequest, signal?: AbortSignal): Promise<ImAccountSetupPreview>;
     confirmAccountSetup(request: ImConfirmAccountSetupRequest): Promise<ImAccountMutationResult>;
     cancelAccountSetup(setupId: ImAccountSetupId): ImCancelAccountSetupResult;
+    /** @returns After all evaluation consumers and storage handles have closed; call from the placement owner after evaluation and CLI join. */
+    closeEvaluationResources(): Promise<void>;
+    /** @returns After this runtime reloads against an admitted NAS lease; consumers must be reacquired by the caller. */
+    reloadWithNasLease(): Promise<void>;
+    /** @inheritdoc */
+    holdsNasLease(): boolean;
+    /** @inheritdoc */
+    ensureEvaluationAccount(sellerId: string, workspaceId: WorkspaceId): Promise<{
+        readonly account: ImAccountView;
+        readonly route: ImRouteView;
+    }>;
+    /** @inheritdoc */
+    isEvaluationAccount(accountId: ImAccountId, sellerId?: string): boolean;
+    /** @inheritdoc */
+    releaseEvaluationAccountRoute(accountId: ImAccountId, observedRevision: ImRevision): Promise<boolean>;
+    private evaluationOperation;
+    private evaluationAccountTable;
     addAccount(request: ImAccountSetupRequest, signal?: AbortSignal): Promise<ImAccountView>;
     setAccountPaused(request: ImSetAccountPausedRequest): Promise<ImAccountMutationResult>;
     disconnectAccount(request: ImAccountLifecycleRequest): Promise<ImAccountMutationResult>;
+    /** @inheritdoc */
+    setSdkConnectionIntent(accountId: ImAccountId, intent: ImAccountView['sdkConnectionIntent'], expectedIntent?: {
+        readonly revision: ImAccountView['sdkConnectionIntentRevision'];
+    }): Promise<boolean>;
     reconnectAccount(request: ImAccountLifecycleRequest): Promise<ImAccountMutationResult>;
+    /** @inheritdoc */
+    retainedAccounts(): readonly {
+        readonly account: ImAccountView;
+        readonly replacedHidden: boolean;
+    }[];
+    /** @inheritdoc */
+    hideReplacedAccount(request: ImAccountLifecycleRequest): Promise<ImAccountMutationResult>;
+    /** @inheritdoc */
+    restoreReplacedAccount(request: ImAccountLifecycleRequest, setup: ImAccountSetupRequest, signal?: AbortSignal): Promise<ImAccountMutationResult>;
     /**
      * Delete one configured account after comparing its observed revision.
      * @param request - account identity and revision observed before confirmation.
      * @returns the durable deletion receipt.
      */
     deleteAccount(request: ImAccountLifecycleRequest): Promise<ImAccountMutationResult>;
+    /**
+     * Install verified credentials for the same merchant under the observed revision.
+     * @param request - account and revision observed before the OAuth allocation started.
+     * @param setup - Host-only credentials for that same merchant; never a replacement merchant.
+     * @param signal - generation lifetime during verification and installation.
+     * @returns a durable receipt; a concurrent lifecycle command wins without changing credentials.
+     */
+    renewAccount(request: ImAccountLifecycleRequest, setup: ImAccountSetupRequest, signal?: AbortSignal): Promise<ImAccountMutationResult>;
+    private renewCredentials;
     refreshAccount(request: ImAccountLifecycleRequest, signal?: AbortSignal): Promise<ImAccountMutationResult>;
     queryAccountOperation(accountId: ImAccountId, operationId: ImOperationId): ImAccountOperationQuery;
     createRoute(request: ImCreateRouteRequest): Promise<ImRouteMutationResult>;
@@ -123,20 +291,42 @@ export declare class ImRuntime extends Service implements ImRuntimeService {
     /** @param scope - durable real conversation. @returns last admitted presentation, including the assigned service account when known. */
     getConversationPresentation(scope: ImRealDeliveryScope): import('./delivery-types.ts').ImConversationPresentation | undefined;
     saveSimulationTarget(request: ImSaveSimulationTargetRequest): Promise<ImSimulationTargetMutationResult>;
+    /** @inheritdoc */
+    saveFormalSimulationTarget(request: ImSaveSimulationTargetRequest): Promise<ImSimulationTargetMutationResult>;
+    private saveTarget;
     removeSimulationTarget(request: ImRemoveSimulationTargetRequest): Promise<ImSimulationTargetMutationResult>;
+    /** @inheritdoc */
+    removeFormalSimulationTarget(request: ImRemoveSimulationTargetRequest): Promise<ImSimulationTargetMutationResult>;
+    private removeTarget;
+    private requireNonEvaluationTargets;
     querySimulationTargetOperation(workspaceId: WorkspaceId, operationId: ImOperationId): ImSimulationTargetOperationQuery;
     listSimulationInstances(): readonly ImSimulationInstanceView[];
     getSimulationInstance(instanceId: ImSimulationInstanceId): ImSimulationInstanceView | undefined;
+    holdSimulationBuyer(instanceId: ImSimulationInstanceId): () => void;
+    deliverSimulationBuyerReplies(instanceId: ImSimulationInstanceId): Promise<number>;
+    registerSimulationClock(instanceId: ImSimulationInstanceId, source: ImClockSource): () => void;
+    private deliveryTime;
+    currentTime(sessionId: SessionId): number;
     scopeForSession(sessionId: SessionId): ImSimulationSessionScope | undefined;
     realScopeForSession(sessionId: SessionId): ImRealSessionBinding | undefined;
     realBindingForScope(scopeId: ImScopeId): ImRealSessionBinding | undefined;
     sendManualMessage(request: ImSendManualMessageRequest, signal?: AbortSignal): Promise<ImManualMessageResult>;
+    private sendManualMediaMessage;
+    /** @param request - Host-authorized media bytes and owning scope; automatic calls require the frozen task route. @param signal - operation cancellation. @returns durable media outbox result; uncertain submission is never repeated. */
+    sendMediaMessage(request: ImSendMediaMessageRequest, signal?: AbortSignal): Promise<ImOutboundView>;
+    private dispatchMediaMessage;
+    /** @param request - manual Session or scope identity and an owned file request. @returns a fresh download URL, requiring the current online IM generation. */
+    mediaDownloadUrl(request: ImManualMessageQueryRequest): Promise<string>;
     queryManualMessage(request: ImManualMessageQueryRequest): ImManualMessageQuery;
     confirmManualMessage(request: ImManualMessageQueryRequest, signal?: AbortSignal): Promise<ImManualMessageResult>;
     retryManualMessage(request: ImRetryManualMessageRequest, signal?: AbortSignal): Promise<ImManualMessageResult>;
+    createManualSimulationInstance(request: ImCreateManualSimulationInstanceRequest): Promise<ImSimulationInstanceView>;
     createSimulationInstance(request: ImCreateSimulationInstanceRequest): Promise<ImSimulationInstanceView>;
+    /** @inheritdoc */
+    createFormalSimulationInstance(request: ImCreateSimulationInstanceRequest): Promise<ImSimulationInstanceView>;
     injectSimulationMember(request: ImInjectSimulationMemberRequest): Promise<ImInboundMessageView>;
     injectSimulationManagedHuman(request: ImInjectSimulationManagedHumanRequest): Promise<ImInboundMessageView>;
+    injectSimulationOperator(request: ImInjectSimulationOperatorRequest): Promise<ImSimulationOperatorReceipt>;
     querySimulationInjection(request: ImSimulationInjectionQuery): ImInboundOperationQuery;
     beginStopSimulation(instanceId: ImSimulationInstanceId): Promise<ImSimulationInstanceView>;
     beginStopSimulationForSession(sessionId: SessionId): Promise<ImSimulationInstanceView>;
@@ -145,6 +335,7 @@ export declare class ImRuntime extends Service implements ImRuntimeService {
     ingestInboundPage(request: ImIngestInboundPageRequest): Promise<ImInboundPageResult>;
     queryInboundOperation(scope: ImDeliveryScope, operationId: ImDeliveryOperationId): ImInboundOperationQuery;
     getConversationCursor(scope: ImDeliveryScope): ImConversationCursor;
+    projectConversations<T extends object>(project: (records: ImConversationRecords) => T): ImConversationProjection<T>;
     getProviderCursor(owner: ImProviderCursorOwner): ImProviderCursorView;
     commitProviderCursor(request: ImCommitProviderCursorRequest): Promise<ImProviderCursorCommitResult>;
     queryProviderCursorOperation(owner: ImProviderCursorOwner, operationId: ImDeliveryOperationId): ImProviderCursorOperationQuery;
@@ -154,6 +345,8 @@ export declare class ImRuntime extends Service implements ImRuntimeService {
      * @param request - account, real/simulation filter, optional substring, and reader.
      */
     listCustomers(request: ImCustomerListRequest): ImCustomerListPage;
+    /** @param request - account, source, search and cursor. @returns customer Session references without unread calculations. */
+    listCustomerSessions(request: ImCustomerSessionListRequest): ImCustomerSessionPage;
     /**
      * Advance one reader's live inbound watermark with max semantics.
      * @param request - reader, scope, and observed arrival sequence.
@@ -223,8 +416,11 @@ export declare class ImRuntime extends Service implements ImRuntimeService {
     getOutbound(request: ImGetOutboundRequest): ImOutboundView | undefined;
     queryOutbound(request: ImOutboundQueryRequest): ImOutboundPage;
     cancelPendingAi(request: ImCancelPendingAiRequest): Promise<readonly ImOutboundView[]>;
+    /** @param accountId - authenticated transport account. @param messageId - observed SDK platform message. @param clientId - observed SDK UUID. @returns exact identifier matches in live single-chat history or confirmed outbox; never matches text. */
+    matchSdkMessage(accountId: ImAccountId, messageId: string, clientId?: string): readonly import('./read-types.ts').ImSdkMessageMatch[];
     findSentOutbound(scope: ImRealDeliveryScope, externalMessageId: string): ImOutboundView | undefined;
     private confirmUnknownOutbound;
+    private storedInbound;
     private inboundSender;
     classifyInboundSender(scope: ImRealDeliveryScope, evidence: ImInboundSenderEvidence): ImSenderAttribution;
     private isNativeActor;
@@ -234,6 +430,10 @@ export declare class ImRuntime extends Service implements ImRuntimeService {
     routeForSimulationTarget(target: ImSimulationTargetView): ImRouteView | undefined;
     /** @param target - current workspace target setting. @returns its exact safe account when still present. */
     accountForSimulationTarget(target: ImSimulationTargetView): ImAccountView | undefined;
+    /** @param accountId - Simulation-owned account reference. @returns Formal or evaluation identity, excluding replaced accounts; never use for formal authorization. */
+    accountForSimulation(accountId: ImAccountId): ImAccountView | undefined;
+    /** @param accountId - Simulation-owned account reference. @param routeId - Exact route reference. @returns Its live formal or fixed evaluation route; never use for formal route mutation. */
+    routeForSimulation(accountId: ImAccountId, routeId: ImRouteId): ImRouteView | undefined;
     /** @param scope - claimed frozen simulation scope. @returns whether its exact instance accepts delivery. */
     isSimulationScopeRunning(scope: ImSimulationDeliveryScope): boolean;
     /** Emit a post-commit instance notification for BFF followers. @param instanceId - changed instance. */
@@ -250,14 +450,14 @@ export declare class ImRuntime extends Service implements ImRuntimeService {
     private bindingFromTask;
     /**
      * Direct peer that a send may use.
-     * Wangwang accepts a stored id only when this scope has observed that external sender; otherwise it uses the latest observed sender. The conversation id is never a recipient. Other platforms keep a stored peer, then an observed sender.
+     * Wangwang uses an observed external sender before the latest platform-provided peer saved on the conversation. The conversation id is never a recipient. Other platforms keep a stored peer, then an observed sender.
      * @param scope - conversation being sent or displayed.
      * @param stored - recipient frozen on the task, when one exists.
-     * @returns usable peer, or absence when Wangwang has not observed a counterpart.
+     * @returns usable peer, or absence when neither sender evidence nor a platform peer exists.
      */
     usableDirectRecipient(scope: ImDeliveryScope, stored?: ImDirectRecipient): ImDirectRecipient | undefined;
     /**
-     * Store the Wangwang peer a send is allowed to use, including clearing one that no observed sender supports.
+     * Store the Wangwang peer a send is allowed to use, including clearing one unsupported by sender evidence or the platform.
      * @param sessionId - Agent Session that owns the task, when one exists.
      * @param recipient - usable peer, or absence.
      */
@@ -278,10 +478,13 @@ export declare class ImRuntime extends Service implements ImRuntimeService {
     private settleManualResult;
     private prepareVerifiedAccount;
     private persistPreparedAccount;
+    /** 把首次开通生成的账号固定给后续确认。重复调用必须是同一个 id。 */
+    reservePlacementAccount(accountId: ImAccountId): void;
     private accountIdForSetup;
     private expireAccountSetup;
     private releaseAccountSetup;
     private clearAccountSetups;
+    private assertFormalAccess;
     private accountTable;
     private simulationTargetTable;
     private simulationInstanceTable;
@@ -313,6 +516,8 @@ export declare class ImRuntime extends Service implements ImRuntimeService {
      * @returns the stored next record.
      */
     updateExecution(id: ImAgentTaskId, fn: (current: ImExecutionAggregate) => ImExecutionAggregate): Promise<ImExecutionAggregate>;
+    /** @returns 当前客服托管路由登记的最新 Session；只查账号与会话索引。 */
+    hostingRecoveryTasks(): readonly ImExecutionAggregate[];
     /**
      * List task generations for one conversation in generation order.
      * @param scopeId - complete conversation identity.
@@ -342,18 +547,121 @@ export declare class ImRuntime extends Service implements ImRuntimeService {
     private reconcileListener;
     /** Stop one exact listener before publishing a later start for the same account. */
     private stopListener;
-    /** Observe an established listener without turning completion into automatic retry. */
+    /** Consume a listener's terminal result before scheduling replacement work. */
     private observeListener;
-    /** Publish one exact listener generation's terminal state. */
+    /** Release the completed provider generation on the same queue as starts and stops. */
     private finishListener;
+    /** Cancel stability observation for one exact listener generation. */
+    private cancelListenerStableTimer;
+    /** Reset retries only for the running generation that demonstrated stable reception. */
+    private markListenerStable;
+    /** Cancel the sole retry callback owned by an account. */
+    private cancelListenerRetry;
+    /** Retain a safe error code and spend the retry budget until reception stabilizes. */
+    private retryListener;
     /** Stop one ready provider handle and consume its terminal signal without exposing provider errors. */
     private closeListenerHandle;
     /** Drain every provider listener owned by this runtime. */
     private stopAllListeners;
-    /** Bind a provider page sink to one configured account and its platform. */
+    /**
+     * 关闭新页面、Agent 输入及 turn；已准入工作可结束，不取消 turn。
+     * @returns 暂停所有权；调用者在取消、保留期到期或卸载时 resume。
+     */
+    pauseInput(): ImInputPause;
+    /** @param accountId - 交接账号；不改变持久化连接或路由代次。 @returns 仅该账号的输入暂停所有权；其他账号和个人 Workspace 继续运行。 */
+    pauseAccountInput(accountId: ImAccountId): ImInputPause;
+    /**
+     * 取消排空超时的账号任务，保留尚未准入的输入。
+     * @param accountId - 已持有独立输入暂停的账号；子 Agent 按当前进程的实际所有权归属。
+     */
+    cancelAccountActivityForPlacement(accountId: ImAccountId): void;
+    /**
+     * 停止已排空的来源账号，或仍持有目标启动暂停的账号。
+     * @param accountId - 本次显式交接的账号。
+     * @returns SDK 已登出且踢线意图已提交，监听已确认停止、未发出的自动回复已标记取消；保留在线意图，失败保留停止门，目标也不能释放启动暂停。
+     */
+    stopAccountForPlacement(accountId: ImAccountId): Promise<void>;
+    /** @param accountId - 已鉴权的真实旺旺账号。 @param workspaceId - 来源客服内置 Workspace。 @returns 独立切片，凭据引用按本账号成功续签收据核验并映射为规范键；预复制可读取，最终导出前调用方必须排空并停止监听。 */
+    exportAccountForPlacement(accountId: ImAccountId, workspaceId: WorkspaceId): ImAccountPlacementSlice;
+    /**
+     * Stop one account and release its live Sessions before an authenticated incoming transfer.
+     * @param accountId - Account selected by the incoming lease, including a previously exported local account.
+     * @param signal - Drain budget and incoming transfer lifetime.
+     * @returns Account import standby is held; failures retain the stop gate and cannot activate reception. A later call retries a rejected attempt with its retained input hold.
+     */
+    beginAccountPlacementImport(accountId: ImAccountId, signal: AbortSignal): Promise<void>;
+    private beginPlacementImport;
+    /**
+     * Activate an imported account only after the caller obtains fresh lease authorization and prepares its Agents.
+     * @param accountId - Account whose import standby was successfully established.
+     */
+    releaseAccountPlacement(accountId: ImAccountId): void;
+    /**
+     * Check whether local delivery records permit cursor-only recovery before lease acquisition.
+     * @param accountId - Account with an established import hold and stopped history listener.
+     * @param checkpoint - Parsed checkpoint; pending or unknown bodies cannot be reconstructed.
+     * @param signal - Preflight lifetime.
+     * @returns Existing nonnull local cursors match exactly; rejection leaves delivery records and the hold unchanged.
+     */
+    validateAccountCheckpointRecovery(accountId: ImAccountId, checkpoint: ImAccountCheckpointRecovery['checkpoint'], signal: AbortSignal): Promise<void>;
+    /**
+     * Adopt cursor-only cloud recovery while account import standby remains held.
+     * @param accountId - Account fenced by the completed outbound handoff and fresh incoming lease.
+     * @param request - Parsed checkpoint and caller-verified continuous source fence; no cloud Session is reconstructed.
+     * @param signal - Incoming activation lifetime.
+     * @returns Old local Sessions remain untouched; fresh task generations and their logged recovery notice are ready, reception still paused.
+     */
+    recoverAccountPlacement(accountId: ImAccountId, request: ImAccountCheckpointRecovery, signal: AbortSignal): Promise<void>;
+    private recoverCheckpointAccount;
+    /** @param slice - 已通过网络解析和目标 epoch 鉴权的账号切片。 @param workspaceId - 目标端已物化的客服内置 Workspace。 @returns 配置与投递事实已提交，接待仍停止；部分提交失败不恢复接待，调用者按原交接核验。 */
+    importAccountForPlacement(slice: ImAccountPlacementSlice, workspaceId: WorkspaceId): Promise<void>;
+    /**
+     * 使用本端 preset 和模型准入恢复本账号的当前任务；不转移来源 Agent 配置。
+     * @param accountId - 已导入或已在本端接待的当前账号。
+     * @param prepare - 在同一空闲 Agent 上按已核验的当前任务完成续写准备。
+     * @param signal - 本次激活及身份寿命。
+     * @returns 当前任务已准备，仍持有启动暂停；模型不可用或任一失败均不释放暂停。
+     */
+    prepareAccountPlacement(accountId: ImAccountId, prepare: (agent: Agent, task: ImAgentTaskView) => Promise<void>, signal: AbortSignal): Promise<void>;
+    /**
+     * 等待本账号当前监听的建立与 Provider 初始追平；不以启动调度代替就绪。
+     * @param accountId - 已释放启动暂停的导入账号。
+     * @param signal - 激活预算及身份寿命。
+     * @returns 需要接收时监听已就绪；暂停、断开或无接收路由时保持原意图，不擅自开启。
+     */
+    waitAccountPlacementReady(accountId: ImAccountId, signal: AbortSignal): Promise<void>;
+    /** Host 在控制面授权、导入与 prepareResume 完成后调用；幂等释放自己的启动暂停，不释放其他暂停。 */
+    releasePlacementStartup(): void;
+    private publishPlacementSdkRecovery;
+    /**
+     * 读取 Host 与账号的共同暂停状态。
+     * @param accountId - 当前真实或模拟账号。
+     * @returns 任一暂停或已停止时为 true。
+     */
+    inputPaused(accountId: ImAccountId, kind?: ImDeliveryScope['kind']): boolean;
+    /**
+     * 同步预约 Host 与账号的输入计数。
+     * @param accountId - 当前准入账号。
+     * @returns 两份计数的释放函数；任一暂停时不准入。
+     */
+    tryEnterInput(accountId: ImAccountId, kind?: ImDeliveryScope['kind']): (() => void) | undefined;
+    /**
+     * 为已准入输入保留首个 step 的工作计数。
+     * @param accountId - 当前准入账号。
+     * @param sessionId - 已确认归属该账号的 Session。
+     * @returns 输入提交后的两份预约释放函数。
+     */
+    reserveInput(accountId: ImAccountId, sessionId: SessionId): () => void;
+    private accountInput;
+    private accountOwnsAgent;
+    private agentAccount;
+    /** Bind page receipts and stability evidence to one exact listener generation. */
     private transportSink;
+    private receiveRealtime;
     /** Persist every conversation page before committing the provider-owned cursor. */
     private receiveTransportPage;
+    private persistTransportPage;
+    private persistTransportConversation;
     /** Publish process listener facts without scheduling another reconciliation. */
     private publishListener;
 }

package/lib/types/schema.d.ts

@@ -1,7 +1,18 @@
+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'>;
+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 {
@@ -35,7 +46,7 @@ export interface ImSimulationTargetAggregate {
     readonly operations: Readonly<Record<string, StoredSimulationTargetOperation>>;
 }
 export declare const imSimulationTargetAggregateSchema: ZodType<ImSimulationTargetAggregate>;
-/** Parser for one durable two-Session simulation lifecycle. */
+/** 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: {

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;
+}