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

package/lib/types/policies.d.ts

@@ -0,0 +1,63 @@
+/** Registry of product controllers that authorize IM admission and automated sends. */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types';
+import type { ImDeliveryScope } from './delivery-types.ts';
+import type { ImRouteControllerId, ImRouteId } from './types.ts';
+export type { ImRouteControllerId };
+/** Moments a declared route controller must authorize. */
+export type ImPolicyCheckKind = 'admit' | 'send' | 'manual-send' | 'recover' | 'simulation-end';
+/** One authorization request for a declared controller. */
+export interface ImPolicyCheckRequest {
+    readonly kind: ImPolicyCheckKind;
+    readonly controller: ImRouteControllerId;
+    readonly scope: ImDeliveryScope;
+    readonly routeId: ImRouteId;
+    readonly workspaceId: WorkspaceId;
+}
+/** Allow, or refuse with a stable code. */
+export type ImPolicyDecision = {
+    readonly allow: true;
+} | {
+    readonly allow: false;
+    readonly code: string;
+    readonly message: string;
+};
+/** 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;
+    }
+}
+/** Registry whose entries live and die with their registering Cordis fiber. */
+export declare class ImRoutePolicies extends Service {
+    private readonly policies;
+    /** @param ctx - owning Cordis context. */
+    constructor(ctx: Context);
+    /**
+     * Register the policy for one controller identity.
+     * @param controller - product controller recorded on the route.
+     * @param policy - authorization Provider.
+     * @returns disposer that releases the registration.
+     */
+    register(controller: ImRouteControllerId, policy: ImRoutePolicy): () => void;
+    /**
+     * Authorize one admission or send for a declared controller.
+     * Missing Providers refuse; ordinary routes without a controller skip this registry.
+     * @param request - controller, scope, and check kind.
+     */
+    authorize(request: ImPolicyCheckRequest): Promise<ImPolicyDecision>;
+}

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

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/route-resolve.d.ts

@@ -0,0 +1,10 @@
+/** Explicit Agent-preset resolution for an IM route. */
+import type { ImRouteView } from './types.ts';
+/**
+ * Resolve the Agent preset a route uses.
+ * A recorded preset is used as-is. Absence takes the runtime default.
+ * Callers must fail when a recorded preset cannot mount; they must not fall back.
+ * @param route - stored route fields.
+ * @param defaultId - AgentPresets default when the route omitted a preset.
+ */
+export declare function resolveRouteAgentPreset(route: Pick<ImRouteView, 'agentPreset'>, defaultId: string): string;