@gestaltrun/dsh-im-runtime 0.1.0 → 0.1.5

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

@@ -1,10 +1,11 @@
 /** 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, 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, ImRemoveSimulationTargetRequest, ImRouteMutationResult, ImRouteOperationQuery, ImRouteResolution, ImRuntimeChange, ImRuntimeSnapshot, ImSaveRouteRequest, ImSaveSimulationTargetRequest, ImSetAccountPausedRequest, ImSimulationTargetMutationResult, ImSimulationTargetOperationQuery, ImCreateSimulationInstanceRequest, ImSimulationInjectionQuery, ImInjectSimulationManagedHumanRequest, ImInjectSimulationMemberRequest, ImImportSimulationHistoryRequest, ImImportSimulationHistoryResult, ImSimulationInstanceView, ImSimulationSessionScope } from './types.ts';
+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;
@@ -28,20 +29,105 @@ 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 the current durable configuration projection. */
+    /** @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. */
@@ -60,11 +146,26 @@ export interface ImRuntimeService {
     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 request - guarded persistent reconnect intent. @returns its durable outcome. */
+    /** @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>;
@@ -93,8 +194,14 @@ export interface ImRuntimeService {
     }): () => 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. */
@@ -122,14 +229,52 @@ export interface ImRuntimeService {
     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. */
@@ -148,6 +293,12 @@ export interface ImRuntimeService {
     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. */
@@ -158,6 +309,8 @@ export interface ImRuntimeService {
     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. */
@@ -174,6 +327,8 @@ export interface ImRuntimeService {
     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. */
@@ -202,6 +357,8 @@ export interface ImRuntimeService {
     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. */

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

@@ -1,13 +1,11 @@
-/**
- * Session log of one IM automatic-handling pause.
- *
- * Written when `setHandlingControl` pauses a scope that already has an Agent
- * Session (live or persisted). When no Session log exists, the event is not
- * written; SQLite handling control remains the source of truth.
- * Required-on-read. Secrets stay out.
- * @module @gestaltrun/dsh-im-runtime/session-events
- */
 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. */
@@ -19,6 +17,8 @@ export interface ImHandlingPausedEvent {
 }
 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.

package/lib/types/simulation-batch.d.ts

@@ -0,0 +1,40 @@
+import type { ImRuntimeService } from './service-types.ts';
+import type { ImCreateSimulationInstanceRequest, ImSimulationInstanceView } from './types.ts';
+/** Deployment limits for one batch controller. */
+export interface ImSimulationBatchConfig {
+    /** Maximum simultaneous instances; defaults to 2. */
+    readonly maxConcurrency?: number;
+}
+/** A caller-owned simulated-user Session and its work against one paired instance. */
+export interface ImSimulationBatchJob<T> {
+    readonly request: ImCreateSimulationInstanceRequest;
+    /** @param instance - Running pair owned by this batch. @param signal - Batch and caller cancellation. @returns Job result after all step work settles. */
+    execute(instance: ImSimulationInstanceView, signal: AbortSignal): Promise<T>;
+}
+/** Per-job result in input order; a failed job never discards completed siblings. */
+export type ImSimulationBatchResult<T> = {
+    readonly status: 'fulfilled';
+    readonly value: T;
+} | {
+    readonly status: 'rejected';
+    readonly error: unknown;
+};
+type Runtime = Pick<ImRuntimeService, 'createSimulationInstance' | 'beginStopSimulation' | 'waitSimulationStopped'>;
+/** Batch owner; caller-owned simulated-user Sessions remain available after instance cleanup. */
+export declare class ImSimulationBatch {
+    private readonly runtime;
+    private readonly concurrency;
+    private active;
+    /** @param runtime - Host instance lifecycle authority. @param config - Validated concurrency limit. */
+    constructor(runtime: Runtime, config?: ImSimulationBatchConfig);
+    /**
+     * Run one batch, retaining input order and stopping every created instance before resolving.
+     * @param jobs - Distinct live simulated-user Sessions; callbacks must settle on cancellation.
+     * @param signal - Optional caller cancellation; absent means only stop() can cancel the batch.
+     * @returns One result per job; cleanup failure cancels remaining jobs and retains both failures. Concurrent run calls reject.
+     */
+    run<T>(jobs: readonly ImSimulationBatchJob<T>[], signal?: AbortSignal): Promise<readonly ImSimulationBatchResult<T>[]>;
+    /** Cancel active work and queued creation, then await all callbacks and terminal cleanup. */
+    stop(): Promise<void>;
+}
+export {};

package/lib/types/simulation-controller.d.ts

@@ -3,7 +3,8 @@ import type { KvTable } from '@deepseek-ai/dsh-storage-domain';
 import type { ImInboundMessageView, ImInboundOperationQuery, ImOutboundView, ImSimulationDeliveryScope, ImSimulationInstanceId } from './delivery-types.ts';
 import type { ImAgentCoordinator } from './agent-coordinator.ts';
 import type { ImRuntime } from './runtime.ts';
-import type { ImCreateSimulationInstanceRequest, ImInjectSimulationManagedHumanRequest, ImInjectSimulationMemberRequest, ImSimulationInstanceView, ImSimulationInjectionQuery } from './types.ts';
+import { type ImInjectSimulationOperatorRequest, type ImSimulationOperatorReceipt } from './simulation-operator.ts';
+import type { ImCreateSimulationInstanceRequest, ImCreateManualSimulationInstanceRequest, ImInjectSimulationManagedHumanRequest, ImInjectSimulationMemberRequest, ImSimulationInstanceView, ImSimulationInjectionQuery } from './types.ts';
 /** Runtime-owned controller; durable state is authoritative and live handles are only execution resources. */
 export declare class ImSimulationController {
     private readonly ctx;
@@ -17,6 +18,7 @@ export declare class ImSimulationController {
     private readonly stopping;
     private readonly replyClosures;
     private creationTail;
+    private readonly hostBuyers;
     private disposed;
     private disposeCreated?;
     private disposeDisposed?;
@@ -28,12 +30,16 @@ export declare class ImSimulationController {
     dispose(): Promise<void>;
     /** Re-evaluate tool availability after target or instance state changes. */
     refreshAllTools(): void;
-    /** Create and durably publish one tested Session paired with the live simulated-user Session. */
-    create(request: ImCreateSimulationInstanceRequest): Promise<ImSimulationInstanceView>;
+    /** @param request - Live simulated-user Session and target conversation. @param formalOnly - Reject evaluation targets inside the serialized creation operation. @returns The durably published tested Session pair. */
+    create(request: ImCreateSimulationInstanceRequest, formalOnly: boolean): Promise<ImSimulationInstanceView>;
+    /** @param request - enabled all-direct route. @returns the empty, persisted tested Session. */
+    createManual(request: ImCreateManualSimulationInstanceRequest): Promise<ImSimulationInstanceView>;
     /** Inject one allow-listed participant through the instance-local adapter. */
     injectMember(request: ImInjectSimulationMemberRequest): Promise<ImInboundMessageView>;
     /** Inject the frozen account owner locally as operator input, never as a member. */
     injectManagedHuman(request: ImInjectSimulationManagedHumanRequest): Promise<ImInboundMessageView>;
+    /** @param request - Private operator text and retry identity. @returns Durable acceptance only in the running tested Session. */
+    injectOperator(request: ImInjectSimulationOperatorRequest): Promise<ImSimulationOperatorReceipt>;
     /** @param request - original instance and request id. @returns persisted inbound receipt without executing input. */
     queryInjection(request: ImSimulationInjectionQuery): ImInboundOperationQuery;
     private validateInjection;
@@ -46,11 +52,18 @@ export declare class ImSimulationController {
     /** Convert one locally settled tested-Agent reply into isolated inbound for its simulated-user Session. */
     deliverTestedReply(scope: ImSimulationDeliveryScope, outbound: ImOutboundView): Promise<void>;
     private createSerialized;
+    /** Creation includes conversation initialization; failure releases the tested handle and persists a failed instance. */
+    private completeCreation;
     private recoverCreating;
+    private seedManualConversation;
     private task;
     private createTestedAgent;
     private ingest;
     private queueReplies;
+    /** @param id - Running pair driven by a deterministic Host role. @returns Disposer restoring automatic buyer delivery after its owner stops the case. */
+    holdBuyer(id: ImSimulationInstanceId): () => void;
+    /** @param id - Running pair held by a Host driver. @returns Number of AI and eligible staff replies durably delivered to the buyer; rejects if the buyer is not held or live. */
+    deliverBuyerReplies(id: ImSimulationInstanceId): Promise<number>;
     private driveReplies;
     private submit;
     private scheduleStop;

package/lib/types/simulation-operator.d.ts

@@ -0,0 +1,19 @@
+import { type MessageId, type UserMessage } from '@deepseek-ai/dsh-llm';
+import type { Session, SessionId } from '@deepseek-ai/dsh-session';
+import type { ImDeliveryOperationId, ImSimulationInstanceId } from './delivery-types.ts';
+/** Caller-owned identity and text for one private operator message. */
+export interface ImInjectSimulationOperatorRequest {
+    readonly instanceId: ImSimulationInstanceId;
+    readonly requestId: ImDeliveryOperationId;
+    readonly text: string;
+}
+/** Durable inbox acceptance; it does not imply that the target has answered. */
+export interface ImSimulationOperatorReceipt {
+    readonly sessionId: SessionId;
+    readonly messageId: MessageId;
+    readonly status: 'accepted';
+}
+/** @param request - Private message with a stable retry identity. @returns Immutable, unlabelled user input with the same identity on retries. */
+export declare function simulationOperatorMessage(request: ImInjectSimulationOperatorRequest): UserMessage;
+/** @param session - Target's persisted event view. @param message - Expected retry identity and content. @returns Whether the same message is already queued or consumed; conflicting reuse throws. */
+export declare function hasSimulationOperatorMessage(session: Session, message: UserMessage): boolean;

package/lib/types/sqlite-connection.d.ts

@@ -0,0 +1,27 @@
+/** Connection-local SQLite locking and page-cache settings shared by product journals. */
+import type { DatabaseSync } from 'node:sqlite';
+/** SQLite locking policy; EXCLUSIVE requires sole ownership until connection close. */
+export type SqliteLockingMode = 'NORMAL' | 'EXCLUSIVE';
+/** Deployment settings; an absent cache budget keeps SQLite's default page cache. */
+export interface SqliteConnectionConfig {
+    readonly lockingMode?: SqliteLockingMode | undefined;
+    readonly cacheSizeKiB?: number | undefined;
+}
+/** Validated connection settings; null preserves SQLite's default cache budget. */
+export interface SqliteConnectionSpec {
+    readonly lockingMode: SqliteLockingMode;
+    readonly cacheSizeKiB: number | null;
+}
+/**
+ * Validate deployment settings before acquiring filesystem or database resources.
+ * @param config - Requested connection-local settings.
+ * @returns Explicit locking policy and optional page-cache budget in KiB.
+ */
+export declare function resolveSqliteConnectionSpec(config: SqliteConnectionConfig): SqliteConnectionSpec;
+/**
+ * Apply and verify connection-local settings before any reads or migrations; the caller closes on failure.
+ * EXCLUSIVE retains the file lock after a transaction, preventing other connections from reading or writing.
+ * @param db - Newly opened connection owned by the caller.
+ * @param spec - Validated deployment settings.
+ */
+export declare function configureSqliteConnection(db: DatabaseSync, spec: SqliteConnectionSpec): void;

package/lib/types/time.d.ts

@@ -0,0 +1,13 @@
+/** Minute-precision shop time for IM records and customer-service clock context. */
+/**
+ * Format an absolute instant in a configured shop time zone.
+ * @param instant - ISO timestamp or milliseconds since the Unix epoch.
+ * @param timeZone - IANA time zone; invalid zones fail immediately.
+ * @returns Gregorian YYYY-MM-DD HH:mm with a 24-hour clock.
+ */
+export declare function formatImTime(instant: string | number, timeZone: string): string;
+/** Instance-owned running clock; the Host can jump forward between completed steps. */
+export interface ImClockSource {
+    /** @returns Absolute Unix milliseconds. Throwing stops request preparation; there is no system-time fallback. */
+    now(): number;
+}