@gestaltrun/dsh-im-runtime 0.1.0 → 0.1.6

package/lib/types/evaluation-accounts.d.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+import type { ImAccountId, ImRevision, ImRouteId } from './types.ts';
+/** Evaluation records reject credentials, SDK intent and enabled or foreign routes. */
+export declare const imEvaluationAccountSchema: z.ZodObject<{
+    account: z.ZodObject<{
+        id: z.ZodPipe<z.ZodString, z.ZodTransform<ImAccountId, string>>;
+        platform: z.ZodLiteral<"wangwang">;
+        displayName: z.ZodString;
+        identity: z.ZodObject<{
+            platform: z.ZodLiteral<"wangwang">;
+            merchantId: z.ZodString;
+            displayName: z.ZodString;
+        }, z.core.$strict>;
+        authorization: z.ZodObject<{
+            state: z.ZodLiteral<"unchecked">;
+        }, z.core.$strict>;
+        connectionIntent: z.ZodLiteral<"disconnected">;
+        paused: z.ZodLiteral<false>;
+        revision: z.ZodPipe<z.ZodString, z.ZodTransform<ImRevision, string>>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strict>;
+    routeId: z.ZodPipe<z.ZodString, z.ZodTransform<ImRouteId, string>>;
+    route: z.ZodOptional<z.ZodObject<{
+        id: z.ZodPipe<z.ZodString, z.ZodTransform<ImRouteId, string>>;
+        platform: z.ZodLiteral<"wangwang">;
+        accountId: z.ZodPipe<z.ZodString, z.ZodTransform<ImAccountId, string>>;
+        conversationKind: z.ZodLiteral<"direct">;
+        target: z.ZodObject<{
+            kind: z.ZodLiteral<"all">;
+        }, z.core.$strict>;
+        workspaceId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@deepseek-ai/dsh-workspace/types").WorkspaceId, string>>;
+        enabled: z.ZodLiteral<false>;
+        agentPreset: z.ZodLiteral<"cs-hosting">;
+        controller: z.ZodLiteral<"cs-hosting">;
+        revision: z.ZodPipe<z.ZodString, z.ZodTransform<ImRevision, string>>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** Persisted identity and fixed route id; cleanup removes only the active route. */
+export type ImEvaluationAccountAggregate = z.infer<typeof imEvaluationAccountSchema>;
+/** Separate version-one domain; invalid data disables evaluation without blocking formal IM. */
+export declare const imEvaluationAccountsDomainSpec: {
+    name: string;
+    version: number;
+    tables: {
+        accounts: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<ImAccountId, {
+            account: {
+                id: ImAccountId;
+                platform: "wangwang";
+                displayName: string;
+                identity: {
+                    platform: "wangwang";
+                    merchantId: string;
+                    displayName: string;
+                };
+                authorization: {
+                    state: "unchecked";
+                };
+                connectionIntent: "disconnected";
+                paused: false;
+                revision: ImRevision;
+                createdAt: string;
+                updatedAt: string;
+            };
+            routeId: ImRouteId;
+            route?: {
+                id: ImRouteId;
+                platform: "wangwang";
+                accountId: ImAccountId;
+                conversationKind: "direct";
+                target: {
+                    kind: "all";
+                };
+                workspaceId: import("@deepseek-ai/dsh-workspace/types").WorkspaceId;
+                enabled: false;
+                agentPreset: "cs-hosting";
+                controller: "cs-hosting";
+                revision: ImRevision;
+                createdAt: string;
+                updatedAt: string;
+            } | undefined;
+        }>;
+    };
+};

package/lib/types/index.d.ts

@@ -1,19 +1,51 @@
 /** Product-owned IM Host runtime and transport registry. */
 import './session-events.ts';
+import './preset-model.ts';
 export type * from './types.ts';
 export type * from './transport.ts';
+export type * from './sdk.ts';
+export type * from './read-types.ts';
 export type { ImRuntimeService } from './service-types.ts';
 export { ImRuntimeError } from './errors.ts';
 export type { ImRuntimeErrorCode } from './errors.ts';
 export { imRuntimeDomainSpec } from './schema.ts';
 export { encodeImProviderCursorId, encodeImScopeId } from './delivery.ts';
 export { IM_DELIVERY_SCHEMA_VERSION, ImDeliverySqlite } from './delivery-sqlite.ts';
-export { ImTransportError, ImTransports } from './transports.ts';
+export { ImTransportError, ImTransportListenerError, ImTransports } from './transports.ts';
 export type { ImTransportErrorCode } from './transports.ts';
 export { ImRoutePolicies } from './policies.ts';
 export type { ImPolicyCheckKind, ImPolicyCheckRequest, ImPolicyDecision, ImRoutePolicy } from './policies.ts';
 export type { ImRouteControllerId } from './types.ts';
 export { resolveRouteAgentPreset } from './route-resolve.ts';
 export { ImRuntime, ImRuntime as default } from './runtime.ts';
+export type { ImRuntime as ImRuntimeType } from './runtime.ts';
+export { bindKnowledgeImageResolver, hasKnowledgeImageResolver, resolveKnowledgeImage, imageMime } from './knowledge-image.ts';
+export type { KnowledgeImageFailureCode, KnowledgeImageResolution, KnowledgeImageResolver, ResolvedKnowledgeImage } from './knowledge-image.ts';
 export type { Config as ImRuntimeConfig } from './runtime.ts';
-export type { ImHandlingPausedEvent } from './session-events.ts';
+export { checkpointFailureDiagnostic } from './checkpoint.ts';
+export type { ImCheckpointFacts, ImCheckpointReportResult, ImCheckpointTransport, ImCheckpointDiagnostic } from './checkpoint.ts';
+export type { ImHandlingPausedEvent, ImMessageReadEvent } from './session-events.ts';
+export { NasHostLease } from './nas-host-lease.ts';
+export type { SqliteJournalMode } from './nas-host-lease.ts';
+export type { ImInputPause } from './input-drain.ts';
+export type { ImUploadTarget, ImUploadMessage, ImUploadResult, ImUploadTransport, ImUploadBinding, ImUploadIdentity, ImUploadConversationEvent } from './upload-types.ts';
+export { parseImDeliveryAccountSlice, ImPlacementSliceError } from './placement-slice.ts';
+export type { ImDeliveryAccountSlice } from './placement-slice.ts';
+export { ImInputPauseError } from './input-drain.ts';
+export { parseImAccountPlacementSlice, ImPlacementStateError } from './account-placement.ts';
+export type { ImAccountPlacementSlice } from './account-placement.ts';
+export { ImConsumerChatLinks, ImConsumerChatLinkError } from './consumer-chat-links.ts';
+export type { ImConsumerChatLinkQuery, ImConsumerChatLinkResolution, ImConsumerChatLinkProvider, ImConsumerChatLinkErrorCode } from './consumer-chat-links.ts';
+export { formatImTime } from './time.ts';
+export { formatInbound } from './agent-prompt.ts';
+export type { ImClockSource } from './time.ts';
+export type { ImAdmissionAnnotator, ImAdmissionAnnotationInput } from './admission-annotations.ts';
+export { ImScriptClock } from './script-clock.ts';
+export { ImSimulationBatch } from './simulation-batch.ts';
+export type { ImSimulationBatchConfig, ImSimulationBatchJob, ImSimulationBatchResult } from './simulation-batch.ts';
+export type { ImInjectSimulationOperatorRequest, ImSimulationOperatorReceipt } from './simulation-operator.ts';
+export { ImCheckpointRecoveryError } from './checkpoint-recovery.ts';
+export type { ImAccountCheckpointRecovery } from './checkpoint-recovery.ts';
+export { resolveSqliteConnectionSpec, configureSqliteConnection } from './sqlite-connection.ts';
+export type { SqliteLockingMode, SqliteConnectionConfig, SqliteConnectionSpec } from './sqlite-connection.ts';
+export { buyerUid, senderUid } from './read-state.ts';

package/lib/types/inline-image.d.ts

@@ -0,0 +1,7 @@
+/** Recognize inline IM raster images without treating their encoded bytes as message text. */
+import type { EncodedImageAttachment } from '@deepseek-ai/dsh-attachment';
+import type { ImMessageContent } from './delivery-types.ts';
+/** @param content - stored provider presentation, including older text-classified images. @returns an encoded raster image for attachment admission, or undefined for ordinary messages and placeholders. */
+export declare function inlineImImage(content: ImMessageContent): EncodedImageAttachment | undefined;
+/** @param content - stored message presentation. @returns text for text-only consumers, replacing inline raster bytes with an image label. */
+export declare function imMessageText(content: ImMessageContent): string;

package/lib/types/input-drain.d.ts

@@ -0,0 +1,73 @@
+/** Host 内存中的输入排空；暂停不写游标，不取消已准入的 turn。 */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+/** 一次暂停的所有者；等待到期后由调用者决定保留暂停或恢复。 */
+export interface ImInputPause {
+    /** @param signal - 等待预算与调用者寿命。 @returns 已接收页面、准入驱动及 turn 全部结束。 */
+    drained(signal: AbortSignal): Promise<void>;
+    /** @param listener - 立即及数量变化时接收按 Session 去重的在途 turn 与回复准入预约数，不含维护 activity 或页面接收。 @returns 取消观察；缺省表示旧 Provider 不支持计数。 */
+    observeReplies?(listener: (remaining: number) => void): () => void;
+    /** 幂等地撤销本次暂停；最后一个所有者释放后重新接收。 */
+    resume(): void;
+}
+/** Host 升级与账号交接不能并发持有同一 Agent 的 maintenance 暂停。 */
+export declare class ImInputPauseError extends Error {
+    /** 另一个维护所有者占用输入暂停。 */
+    readonly code = "IM_INPUT_PAUSE_CONFLICT";
+    constructor();
+}
+/** IM 接收、Agent 准入和 Host turn 共用的排空计数。 */
+export declare class ImInputDrain {
+    private readonly accepts;
+    /** @param accepts - 本计数器管理的 Agent；缺省覆盖整个 Host，账号交接使用已确认的 Session 归属。 */
+    constructor(accepts?: (agent: Agent) => boolean);
+    private readonly replyObservers;
+    private readonly contexts;
+    private readonly joining;
+    private readonly parked;
+    private failure;
+    private holds;
+    private busy;
+    private changed;
+    private readonly lifetime;
+    private reception;
+    private readonly turns;
+    private readonly reservations;
+    /** 当前是否禁止新的页面和准入。 */
+    get paused(): boolean;
+    /** @param ctx - Agent 生命周期及 Session 持久化服务。 @returns 在关闭 Agent 前释放并等待本作用域的 maintenance 预约。 */
+    mount(ctx: Context): () => Promise<void>;
+    /** @param sessionId - 已准入输入的 Session。 @returns 输入提交失败时释放首个 step 的预约计数。 */
+    reserve(sessionId: SessionId): () => void;
+    private reserveSession;
+    /** @returns 同步关闭新输入后的暂停所有权。 */
+    pause(): ImInputPause;
+    /** @returns 未暂停时取得工作计数，否则调用者保留待处理数据。 */
+    tryEnter(): (() => void) | undefined;
+    /** @returns 页面接收的工作计数；暂停期间等待，卸载时拒绝且不提交游标。 */
+    receive(): Promise<() => void>;
+    /**
+     * 等两个计数器都允许接收后同步取得两份工作计数，等待期间不占用任一排空计数。
+     * @param other - Host 或账号的另一个计数器；任一卸载均取消等待。
+     * @param cancellation - 提供时取消尚未接收的页面；缺省仅由页面停止或计数器卸载取消，不提交游标。
+     * @returns 两份计数的幂等释放函数。
+     */
+    receiveWith(other: ImInputDrain, cancellation?: AbortSignal): Promise<() => void>;
+    /** 停止页面接收且不恢复已拒绝页面；保留 Agent 输入暂停与维护预约，已准入页面仍可完成。 */
+    stopReceiving(): void;
+    /** Reopen pages only while input remains paused after an authenticated placement import begins. */
+    preparePlacementReception(): void;
+    /** 停止所有等待；在 runtime 拆卸时调用。 */
+    dispose(): void;
+    /** 空闲 Agent 的 maintenance 预约发生在 Inbox claim 前，保持新输入仍在持久化队列中。 */
+    private park;
+    /** 完整等待已准入的 activity，随后先预约空闲状态，再允许排空完成。 */
+    private joinActivity;
+    private repark;
+    private recordFailure;
+    private enter;
+    private waitOpen;
+    private waitChange;
+    private publish;
+}

package/lib/types/knowledge-image.d.ts

@@ -0,0 +1,64 @@
+/** Why a knowledge image was not turned into an attachment. */
+export type KnowledgeImageFailureCode = 'not-in-session' | 'shop-mismatch' | 'reference-stale' | 'source-unavailable' | 'forbidden' | 'deleted' | 'invalid-image' | 'too-large' | 'timeout';
+/** One resolved knowledge image, already limited to an allowed bitmap. */
+export interface ResolvedKnowledgeImage {
+    /** Image bytes. */
+    readonly bytes: Uint8Array;
+    /** MIME type derived from the bitmap header. */
+    readonly mime: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/bmp';
+    /** Display name stored with the attachment. */
+    readonly name: string;
+    /** Reference id and content hash recorded with the send. */
+    readonly sourceMetadata: {
+        readonly referenceId: string;
+        readonly sha256: string;
+    };
+}
+/** Result of resolving one `knowledge-image` reference in the current shop and session. */
+export type KnowledgeImageResolution = {
+    readonly ok: true;
+    readonly value: ResolvedKnowledgeImage;
+} | {
+    readonly ok: false;
+    readonly code: KnowledgeImageFailureCode;
+};
+/** Reads one reference from the calling session and the current shop. */
+export interface KnowledgeImageResolver {
+    /**
+     * @param request - reference, session, and cancellation.
+     * @returns image bytes, or a stable failure code. Nothing is sent on failure.
+     */
+    resolve(request: {
+        readonly referenceId: string;
+        readonly sessionId: string;
+        readonly signal: AbortSignal;
+    }): Promise<KnowledgeImageResolution>;
+}
+/**
+ * Register the knowledge plugin's resolver on one IM runtime.
+ * A proxy and the raw instance share this symbol, so a later `im_send_message` sees the same resolver.
+ * @param runtime - runtime that owns `im_send_message` for this Host.
+ * @param resolver - current-shop image reader.
+ * @returns a disposer that removes this resolver only.
+ */
+export declare function bindKnowledgeImageResolver(runtime: object, resolver: KnowledgeImageResolver): () => void;
+/**
+ * @param runtime - IM runtime handling the send. May be the service instance or its context proxy.
+ * @returns whether knowledge images can be resolved on this runtime.
+ */
+export declare function hasKnowledgeImageResolver(runtime: object): boolean;
+/**
+ * @param runtime - IM runtime handling the send.
+ * @param request - reference to resolve.
+ * @returns the resolver's result, or `source-unavailable` when knowledge did not register one.
+ */
+export declare function resolveKnowledgeImage(runtime: object, request: {
+    readonly referenceId: string;
+    readonly sessionId: string;
+    readonly signal: AbortSignal;
+}): Promise<KnowledgeImageResolution>;
+/**
+ * @param bytes - file bytes to classify.
+ * @returns the bitmap MIME type, or undefined for HTML, SVG, and any other payload.
+ */
+export declare function imageMime(bytes: Uint8Array): ResolvedKnowledgeImage['mime'] | undefined;

package/lib/types/media-lifetime.d.ts

@@ -0,0 +1,22 @@
+/** One owner retains accepted sends and exact consumer disposal tasks until storage can close. */
+export declare class ImMediaLifetime {
+    private readonly cancellation;
+    private readonly pending;
+    private readonly consumers;
+    private readonly resources;
+    private closing;
+    private disposal;
+    /** @param operation - resource initialization or complete send through its final durable write and publication. @param signal - caller cancellation. @returns the admitted result; new sends are rejected once teardown starts. */
+    run<T>(operation: (signal: AbortSignal) => Promise<T>, signal: AbortSignal): Promise<T>;
+    /** @param stop - consumer cleanup that may also be invoked by its own fiber. @returns the exact idempotent disposer whose completion this owner retains. */
+    stopWith(stop: () => void | Promise<void>): () => Promise<void>;
+    /** @param domain - caller-owned domain whose facility may request fallback closure during root unload. Configuration reads remain available until admitted media completes. */
+    ownDomain(domain: {
+        close(): Promise<void>;
+    }): void;
+    /** @param close - acquired resource closer, invoked in reverse acquisition order after consumers finish. */
+    closeWith(close: () => void | Promise<void>): void;
+    /** Reject new sends, cancel preparation, join accepted operations and consumers, then release storage even after cleanup failures. */
+    dispose(): Promise<void>;
+    private drain;
+}

package/lib/types/media.d.ts

@@ -0,0 +1,32 @@
+import type { ImDeliverySqlite } from './delivery-sqlite.ts';
+import { type ImDeliveryStore } from './delivery.ts';
+import type { ImRuntime } from './runtime.ts';
+import type { ImMediaInput, ImMessageContent, ImOutboundView, ImSendMediaMessageRequest } from './delivery-types.ts';
+/** @param input - bytes crossing a wire or Host tool interface. @param maxBytes - configured per-file limit. @returns stable display content without bytes, credentials or upload authorization. */
+export declare function mediaContent(input: ImMediaInput, maxBytes: number): Extract<ImMessageContent, {
+    format: 'media';
+}>;
+/** One runtime owns all in-flight media work and joins it before releasing its database. */
+export declare class ImMediaSender {
+    private readonly runtime;
+    private readonly records;
+    private readonly delivery;
+    private readonly owner;
+    private readonly work;
+    private readonly lifetime;
+    private readonly receipts;
+    private readonly providers;
+    /** @param runtime - authoritative outbox and authorization owner. @param records - private staging store. @param delivery - serialized outbox mutations and publications. */
+    constructor(runtime: ImRuntime, records: ImDeliverySqlite, delivery: ImDeliveryStore);
+    /** @param request - registered, scope-verified intent and private original bytes. @param signal - operation cancellation. @returns the settled or uncertain outbox record; repeated ids join rather than resubmit. */
+    send(request: ImSendMediaMessageRequest, signal: AbortSignal): Promise<ImOutboundView>;
+    /** @param request - scope-checked durable file intent. @returns a fresh download URL; the signed location is never stored as a permanent reference. */
+    download(request: import('./delivery-types.ts').ImGetOutboundRequest): Promise<string>;
+    /** Stop preparation and join all owned sends before releasing durable storage. */
+    dispose(): Promise<void>;
+    /** Observe registered SDK receipts after startup without initiating an upload or a send. */
+    followTransport(): void;
+    private followReceipts;
+    private consumeReceipt;
+    private dispatch;
+}

package/lib/types/message-preview.d.ts

@@ -0,0 +1,4 @@
+/** Compact customer-list text derived from stored IM content. */
+import type { ImMessageContent } from './delivery-types.ts';
+/** @param content - canonical message content, retained unchanged. @returns history-compatible image or unsupported labels, with embedded Base64 image data replaced inside ordinary text. */
+export declare function imMessagePreview(content: ImMessageContent): string;

package/lib/types/message-upload.d.ts

@@ -0,0 +1,55 @@
+import type { ImUploadObservation, ImUploadResult, ImUploadTransport } from './upload-types.ts';
+import type { ImAccountId } from './types.ts';
+import type { ImDeliveryScope } from './delivery-types.ts';
+/** Retains the operation failure as cause and every failed close/unlink in errors. */
+export declare class ImUploadQueueCleanupError extends AggregateError {
+    readonly cleanup: readonly unknown[];
+    readonly name = "ImUploadQueueCleanupError";
+    readonly operationCode: string;
+    readonly cleanupCodes: readonly string[];
+    /** @param primary - failed write, sync, close, rename, or startup removal. @param cleanup - additional failures while releasing owned resources. */
+    constructor(primary: unknown, cleanup: readonly unknown[]);
+}
+/** Retry-safe queue; append and acknowledgement each replace a fully synced file. */
+export declare class ImMessageUploadQueue {
+    private readonly path;
+    private readonly send;
+    private readonly canSend;
+    private entries;
+    private rejected;
+    private readonly writer;
+    private readonly lifetime;
+    private closing;
+    private tail;
+    lastResult: ImUploadResult | undefined;
+    /**
+     * Hold an exclusive writer lease until close(); remove only this queue's UUID-named crash temporaries after acquisition. A competing writer fails before cleanup. The lock file is never unlinked.
+     * @param path - private queue file, separate from runtime SQLite.
+     * @param send - authenticated, cancellable server transport.
+     * @param canSend - current account placement admission; defaults to allowing every scope.
+     * @throws {Error} When writer ownership is unavailable or an existing queue cannot be read or parsed; callers must retain the SQLite journal and retry without replacing the file.
+     */
+    constructor(path: string, send: ImUploadTransport, canSend?: (scope: ImDeliveryScope) => boolean);
+    /** Includes observations waiting for a provider message id. */
+    get pendingCount(): number;
+    /** Persistently rejected observations are retained and excluded from automatic submission. */
+    get rejections(): readonly {
+        readonly id: string;
+        readonly reason: string;
+    }[];
+    /** @param accountId - account included in a placement copy. @returns unacknowledged immutable observations; source copies remain retryable. */
+    pendingForAccount(accountId: ImAccountId): readonly ImUploadObservation[];
+    /**
+     * @param observations - immutable SQLite transfer journal entries; repeated ids are ignored.
+     * @throws {Error} On storage failure; the caller retains its journal until a later successful append.
+     */
+    append(observations: readonly ImUploadObservation[]): void;
+    /** @param signal - owning worker lifetime. @returns completion of one serialized pass; retry outcomes retain the original rows. */
+    flush(signal: AbortSignal): Promise<void>;
+    /** @returns completion after owned requests stop and the writer lease is released; later append/flush calls are rejected. */
+    close(): Promise<void>;
+    private assertOpen;
+    private cleanInterruptedWrites;
+    private flushOnce;
+    private persist;
+}

package/lib/types/nas-host-lease.d.ts

@@ -0,0 +1,33 @@
+import type { ImAccountId } from './types.ts';
+import { Service, type Context } from '@deepseek-ai/cordis';
+/** SQLite 部署日志模式；NAS 使用 DELETE，本地缺省使用 WAL。 */
+export type SqliteJournalMode = 'WAL' | 'DELETE';
+/** 云端 Host 准入及同步写入隔离；租约失效后同一实例不得重新准入。 */
+export declare abstract class NasHostLease extends Service {
+    /** @param ctx - Host 的 Cordis 上下文。 */
+    constructor(ctx: Context);
+    private readonly databases;
+    /** @param path - 数据库绝对路径。 @returns 关闭连接后释放占用；同一 Host 不能重复打开。 */
+    reserveDatabase(path: string): () => void;
+    /** 此云端 Host 独占的 IM 账号。 */
+    abstract readonly accountId: ImAccountId;
+    /** 等待可信旧实例退出确认，并 CAS 取得新代次或续约控制面已提交的本次交接代次；失败时拒绝。 */
+    abstract readonly ready: Promise<void>;
+    /** 当前 Host 已准入的代次，未准入时拒绝访问。 */
+    abstract get epoch(): number;
+    /** 检查本地期限；过期时先隔离写入并请求停止 Host，然后抛出错误。 */
+    abstract assertActive(): void;
+    /** @param close - 失效时同步关闭资源，不进行业务写入。 @returns 撤销关闭回调的函数。 */
+    abstract onFence(close: () => void): () => void;
+    /** @returns 当前已准入租约的商家成员与云端沙箱，供客户数据写入构造租约证明；未准入、已失效或实现不提供时为 undefined。 */
+    holderIdentity(): {
+        readonly userId: string;
+        readonly sandboxId: string;
+    } | undefined;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** 云端 NAS 单写者租约；本地配置不依赖此服务。 */
+        nasHostLease: NasHostLease;
+    }
+}

package/lib/types/placement-slice.d.ts

@@ -0,0 +1,30 @@
+import type { ImDeliveryAggregate, ImExecutionAggregate, ImProviderCursorAggregate } from './delivery-schema.ts';
+import type { ImCustomerReaderId, ImHandlingControl, ImScopeId } from './delivery-types.ts';
+import type { ImAccountId } from './types.ts';
+/** 一个真实账号的全部投递事实；交接编排负责排空、epoch 授权和独占目标。 */
+export interface ImDeliveryAccountSlice {
+    readonly version: 1;
+    readonly accountId: ImAccountId;
+    readonly scopes: readonly ImDeliveryAggregate[];
+    readonly executions: readonly ImExecutionAggregate[];
+    readonly cursors: readonly ImProviderCursorAggregate[];
+    readonly nativeActors: readonly string[];
+    readonly reads: readonly {
+        readonly scopeId: ImScopeId;
+        readonly readerId: ImCustomerReaderId;
+        readonly sequence: number;
+    }[];
+    readonly handling: readonly ImHandlingControl[];
+}
+/**
+ * 校验真实会话记录、游标和任务之间的账号归属。
+ * @param value - 已限制正文大小、经过交接鉴权的网络或暂存 JSON。
+ * @returns 仅包含声明账号真实会话的切片；无效输入的错误不携带正文，调用者保持接待停止。
+ */
+export declare function parseImDeliveryAccountSlice(value: unknown): ImDeliveryAccountSlice;
+/** 切片导入失败；不携带消息、游标或凭据。 */
+export declare class ImPlacementSliceError extends Error {
+    readonly code: 'IM_PLACEMENT_SLICE_INVALID' | 'IM_PLACEMENT_SLICE_CONFLICT';
+    /** @param code - 解析或目标数据冲突的稳定失败代码。 */
+    constructor(code: 'IM_PLACEMENT_SLICE_INVALID' | 'IM_PLACEMENT_SLICE_CONFLICT');
+}

package/lib/types/policies.d.ts

@@ -25,8 +25,18 @@ export type ImPolicyDecision = {
 /** Product Provider that owns one controller identity. */
 export interface ImRoutePolicy {
     check(request: ImPolicyCheckRequest): ImPolicyDecision | Promise<ImPolicyDecision>;
+    /** @param listener - 准入条件变化通知。 @returns 撤销本订阅。 */
+    subscribe?(listener: () => void): () => void;
 }
 declare module '@deepseek-ai/cordis' {
+    interface Events {
+        /**
+         * 控制器注册或准入状态变化；等待恢复的 Session 可以重新核对。
+         * @param controller - 发生变化的托管控制器。
+         * @mode emit
+         */
+        'imRoutePolicies/changed'(controller: ImRouteControllerId): void;
+    }
     interface Context {
         /** IM admission and automated-send policies keyed by route controller. */
         imRoutePolicies: ImRoutePolicies;

package/lib/types/preset-model.d.ts

@@ -0,0 +1,50 @@
+/** Optional pin that keeps one IM preset on a Host-owned model route. */
+import type { Context } from '@deepseek-ai/cordis';
+/** Preset id whose model must be the shop cloud route. Matches the cs-hosting preset. */
+export declare const SHOP_CLOUD_PRESET_ID = "cs-hosting";
+/** A pinned preset's model, or why the call must wait. No key and no message body. */
+export type ImPresetModelDecision = {
+    readonly kind: 'ready';
+    readonly provider: string;
+    readonly model: string;
+    readonly models: readonly string[];
+} | {
+    readonly kind: 'blocked';
+    readonly code: string;
+};
+/**
+ * Host gate for presets that must not use the member's own model.
+ * `warm` resolves the route before IM submits a batch. A blocked decision leaves that batch pending.
+ */
+export interface ImPresetModelGate {
+    /** @param presetId - agent preset about to run. */
+    pins(presetId: string): boolean;
+    /** @param signal - cancels the admission read. */
+    warm(signal?: AbortSignal): Promise<ImPresetModelDecision>;
+    /** @param listener - runs when the admission changes. @returns its disposer. */
+    subscribe(listener: () => void): () => void;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Present when a product preset pins its model. Absent presets keep the member default. */
+        imPresetModelGate?: ImPresetModelGate;
+    }
+}
+/** Model options for one new or resumed IM agent. */
+export type PresetAgentSelection = {
+    readonly kind: 'default';
+} | {
+    readonly kind: 'pinned';
+    readonly provider: string;
+    readonly model: string;
+} | {
+    readonly kind: 'hold';
+};
+/**
+ * Resolve agent options for a preset.
+ * The shop-cloud preset fails when the gate is missing, and holds when the gate is blocked.
+ * @param ctx - Host context.
+ * @param presetId - recorded route preset.
+ * @param signal - cancels a pinned read.
+ */
+export declare function resolvePresetAgentOptions(ctx: Context, presetId: string, signal?: AbortSignal): Promise<PresetAgentSelection>;

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

@@ -0,0 +1,27 @@
+/** Durable buyer-read facts become context at the next accepted model step. */
+import type { Context } from '@deepseek-ai/cordis';
+import { type UserMessage } from '@deepseek-ai/dsh-llm';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { KvTable } from '@deepseek-ai/dsh-storage-domain';
+import type { ImRealDeliveryScope, ImScopeId, ImOutboundRequestId } from './delivery-types.ts';
+import type { ImReadAssociation, ImReadRecord } from './read-records.ts';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** Receipt attribution preserves its JSON metadata for readers without this projection.
+         * @persistenceAttribution
+         */
+        'im-read': {
+            readonly kind: 'im-read';
+            readonly scopeId: ImScopeId;
+            readonly requestId: ImOutboundRequestId;
+            readonly form: 'notice';
+            readonly summary: string;
+        };
+    }
+}
+/** @param ctx - optional live Agent and persistence services. @param scope - verified outbound scope. @param row - confirmed buyer evidence. @returns after a live Session fact is durable; absent Agents receive it at their next pre-step. */
+export declare function recordLiveRead(ctx: Context, scope: ImRealDeliveryScope, row: ImReadAssociation): Promise<void>;
+/** @param session - recorded facts and previously admitted contexts. @param proposed - contexts already proposed for this step. @returns each previously unannounced read once; source facts reconstruct the notification after a restart. */
+export declare function readContextMessages(session: Session, proposed?: readonly UserMessage[]): readonly UserMessage[];
+/** @param ctx - registration owner. @param table - independent durable read evidence. @returns exact child disposer, joined before the table closes. Context reconstruction does not wake idle Agents. */
+export declare function installReadContext(ctx: Context, table: KvTable<ImScopeId, ImReadRecord>): () => Promise<void>;

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

@@ -0,0 +1,10 @@
+/** Single-chat read synchronization after durable, exact-identity correlation. */
+import type { Context } from '@deepseek-ai/cordis';
+/** Bounded admission for SDK messages waiting for their OpenAPI durable counterparts. */
+export interface Config {
+    readonly pendingMessageLimit?: number;
+}
+/** Host services required before opening independent read storage. */
+export declare const inject: string[];
+/** @param ctx - durable runtime and storage owner. @param config - bounded unmatched-message admission. @returns after the read domain and optional SDK consumers are installed. */
+export declare function apply(ctx: Context, config?: Config): Promise<void>;

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

@@ -0,0 +1,30 @@
+import { SessionId } from '@deepseek-ai/dsh-session';
+import type { ImOutboundRequestId, ImRealDeliveryScope, ImScopeId } from './delivery-types.ts';
+import type { ImBuyerReadState } from './read-state.ts';
+/** Exact platform association and monotonically confirmed buyer state. */
+export interface ImReadAssociation {
+    readonly requestId: ImOutboundRequestId;
+    readonly platformMessageId: string;
+    readonly sdkConversationId: string;
+    readonly buyerUid: string;
+    readonly singleton: boolean;
+    readonly queried: boolean;
+    readonly state: ImBuyerReadState;
+    readonly observedAt: string;
+    readonly sessionId?: SessionId;
+}
+/** One independently versioned conversation read record. */
+export interface ImReadRecord {
+    readonly schema: 'gestaltrun.im-reads.v1';
+    readonly scope: ImRealDeliveryScope;
+    readonly reported: Readonly<Record<string, true>>;
+    readonly outbounds: Readonly<Record<string, ImReadAssociation>>;
+}
+/** Product-owned read records; opening older IM configuration requires no migration. */
+export declare const imReadsDomainSpec: {
+    name: string;
+    version: number;
+    tables: {
+        scopes: import("@deepseek-ai/dsh-storage-domain").DomainTableSpec<ImScopeId, ImReadRecord>;
+    };
+};

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

@@ -0,0 +1,18 @@
+import type { ImDirectRecipient } from './types.ts';
+/** Consumer-read evidence; absence or ambiguity remains unknown. */
+export type ImBuyerReadState = 'unknown' | 'unread' | 'read';
+/** @param buyer - verified direct recipient. @returns its SDK user id when present, otherwise the platform actor id. */
+export declare function buyerUid(buyer: ImDirectRecipient): string;
+/** @param sender - SDK sender string or object; absent receipt senders remain absent. @returns the supplied sender UID, or absence. */
+export declare function senderUid(sender: string | {
+    readonly uid: string;
+} | undefined): string | undefined;
+/** @param uid - SDK identity. @param buyer - verified OpenAPI buyer UID. @returns whether domain-qualified or unqualified SDK identity names this buyer. */
+export declare function sameBuyer(uid: string, buyer: string): boolean;
+/** @param data - raw 40103 counts. @param singleton - independently verified receiver set consists solely of the target buyer. @returns conservative buyer state. */
+export declare function buyerReadState(data: Readonly<Record<string, unknown>>, singleton: boolean): ImBuyerReadState;
+/** @param data - ListMessageReadStatus response body. @param buyer - independently verified buyer UID. @returns matched status and whether the response establishes a singleton receiver set. */
+export declare function buyerReadQuery(data: unknown, buyer: string): {
+    readonly state: ImBuyerReadState;
+    readonly singleton: boolean;
+};