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

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

@@ -0,0 +1,77 @@
+import type { Context } from '@deepseek-ai/cordis';
+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 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;
+    private readonly runtime;
+    private readonly instances;
+    private readonly coordinator;
+    private readonly testedHandles;
+    private readonly toolDisposers;
+    private readonly tails;
+    private readonly creations;
+    private readonly stopping;
+    private readonly replyClosures;
+    private creationTail;
+    private readonly hostBuyers;
+    private disposed;
+    private disposeCreated?;
+    private disposeDisposed?;
+    /** @param ctx - injected Agent, Session, persistence, preset, tool, and Workspace services. @param runtime - IM delivery authority. @param instances - durable instance records. @param coordinator - normal IM admission coordinator. */
+    constructor(ctx: Context, runtime: ImRuntime, instances: KvTable<ImSimulationInstanceId, ImSimulationInstanceView>, coordinator: ImAgentCoordinator);
+    /** Recover incomplete lifecycles without resuming ordinary running Sessions. */
+    start(): Promise<void>;
+    /** Stop lifecycle work and release only handles and tool registrations owned here. */
+    dispose(): Promise<void>;
+    /** Re-evaluate tool availability after target or instance state changes. */
+    refreshAllTools(): void;
+    /** @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;
+    private inputOperationId;
+    private priorInjection;
+    /** Begin a deduplicated terminal stop and return after delivery closes durably. */
+    beginStop(instanceIdValue: ImSimulationInstanceId): Promise<ImSimulationInstanceView>;
+    /** Await an already-begun stop until its persisted terminal state. */
+    waitStopped(instanceIdValue: ImSimulationInstanceId): Promise<ImSimulationInstanceView>;
+    /** 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;
+    private convergeStop;
+    private refreshTools;
+    private workspaceForSession;
+    private scope;
+    private requireRunning;
+    private closeReplies;
+    private enqueue;
+}

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/simulation-tools.d.ts

@@ -0,0 +1,14 @@
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { Context } from '@deepseek-ai/cordis';
+import type { ImRuntime } from './runtime.ts';
+import type { ImSimulationSessionScope } from './types.ts';
+/**
+ * Register only the simulation operations available to one exact live Agent.
+ * @param ctx - Agent context that owns the registrations.
+ * @param runtime - Host simulation authority.
+ * @param agent - exact Agent whose Session is trusted by every operation.
+ * @param targetConfigured - whether this Agent's workspace can create a new instance.
+ * @param bound - existing instance role for this Session, when present.
+ * @returns disposer for every registered tool.
+ */
+export declare function registerSimulationTools(ctx: Context, runtime: ImRuntime, agent: Agent, targetConfigured: boolean, bound: ImSimulationSessionScope | undefined): () => void;

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

package/lib/types/tools.d.ts

@@ -0,0 +1,17 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import { type ImRuntime } from './runtime.ts';
+import type { ImDeliveryScope, ImOutboundRouteBinding } from './delivery-types.ts';
+import type { ImDirectRecipient } from './types.ts';
+/**
+ * Register IM tools and the takeover system-prompt section on a trusted Agent context.
+ * @param ctx - unpublished Agent context that owns the registrations.
+ * @param runtime - Host runtime that owns history, policy checks, and transports.
+ * @param scope - complete admitted conversation identity hidden from model arguments.
+ * @param binding - route, workspace, and account generation frozen for this Agent.
+ * @param directRecipient - provider peer identity frozen for a direct conversation.
+ * @param sessionId - Agent Session whose pre-step authorizes one handling generation.
+ * @returns disposer for the prompt section and both tools.
+ */
+export declare function registerImAgentTools(ctx: Context, runtime: ImRuntime, scope: ImDeliveryScope, binding: ImOutboundRouteBinding, directRecipient?: ImDirectRecipient, sessionId?: SessionId): () => void;
+export { registerSimulationTools } from './simulation-tools.ts';

package/lib/types/transport.d.ts

@@ -0,0 +1,202 @@
+/** Provider-facing IM transport capability registered with the runtime. */
+import type { CredentialRecord } from '@deepseek-ai/dsh-credentials';
+import type { ImSdkProvider } from './sdk.ts';
+import type { ImDeliveryOperationId, ImConversationPresentation, ImInboundPageResult, ImInboundSenderEvidence, ImMessageContent, ImProviderCursorCommitResult, ImProviderCursorOwner, ImProviderCursorView, ImRealDeliveryScope } from './delivery-types.ts';
+import type { ImAccountCandidate, ImAccountIdentity, ImAccountSetupRequest, ImAccountView, ImAssignedActorCandidate, ImConversationCandidate, ImConversationCandidatePage, ImConversationKind, ImDirectRecipient, ImPlatform, ImPlatformLoginAttemptId, ImPlatformLoginStatus, ImRevision, ImRouteId, ImRouteTarget } from './types.ts';
+export type { ImAccountSetupRequest, ImConversationCandidate, ImConversationCandidatePage, ImDingTalkAccountSetupRequest, ImWangwangAccountSetupRequest } from './types.ts';
+/** Safe provider result plus an optional opaque credential record for durable storage. */
+export interface ImPreparedAccount {
+    readonly displayName: string;
+    readonly identity: ImAccountIdentity;
+    readonly authorization: ImAccountView['authorization'];
+    readonly credentialRecord?: CredentialRecord;
+}
+/** Authorization facts observed by a provider without changing the configured identity. */
+export interface ImTransportAccountInspection {
+    readonly authorization: ImAccountView['authorization'];
+}
+/** Provider message before the runtime classifies sender evidence. */
+export interface ImTransportInboundMessage {
+    /** Provider facts for this message; absent fields stay unknown after persistence. */
+    readonly uploadIdentity?: import('./upload-types.ts').ImUploadIdentity;
+    readonly externalMessageId: string;
+    readonly senderEvidence: ImInboundSenderEvidence;
+    /** Provider-normalized safe presentation; raw credentials, headers, and connection settings are excluded. */
+    readonly content: ImMessageContent;
+    readonly occurredAt: string;
+    /** True only when the provider protocol identifies this configured account in its mention metadata. */
+    readonly mentionedConfiguredAccount?: boolean;
+}
+/** One conversation group within a provider-owned receive page. */
+export interface ImTransportConversationPage {
+    readonly operationId: ImDeliveryOperationId;
+    readonly conversationId: string;
+    readonly conversationKind: ImConversationKind;
+    /** Provider-known group or peer labels; absent facts stay absent. */
+    readonly presentation?: ImConversationPresentation;
+    /** Platform-provided peer identity for direct sends; never the conversation id. */
+    readonly directRecipient?: ImDirectRecipient;
+    readonly messages: readonly ImTransportInboundMessage[];
+}
+/** One provider page that may span multiple conversations. */
+export interface ImTransportInboundPage {
+    readonly operationId: ImDeliveryOperationId;
+    readonly owner: ImProviderCursorOwner;
+    readonly observedCursor: string | null;
+    readonly nextCursor: string | null;
+    readonly conversations: readonly ImTransportConversationPage[];
+}
+/** Durable per-conversation receipts followed by the provider-cursor result. */
+export interface ImTransportInboundPageReceipt {
+    readonly conversations: readonly ImInboundPageResult[];
+    readonly cursor: ImProviderCursorCommitResult;
+}
+/** Enabled route facts needed to choose provider subscriptions and evidence feeds. */
+export interface ImTransportRoutePlan {
+    readonly routeId: ImRouteId;
+    readonly routeRevision: ImRevision;
+    readonly conversationKind: ImConversationKind;
+    readonly target: ImRouteTarget;
+    readonly needsMentionEvidence: boolean;
+    /** Admission routes wake Agents; observe routes only retain history. Absence is admit. */
+    readonly mode?: 'admit' | 'observe';
+}
+/** Host observation that keeps history flowing without an enabled route. */
+export interface ImTransportObservationPlan {
+    readonly conversationKind: ImConversationKind;
+    readonly target: ImRouteTarget;
+}
+/** Listener plan computed from enabled routes and optional observation leases. */
+export interface ImTransportListenPlan {
+    readonly routes: readonly ImTransportRoutePlan[];
+    readonly observations?: readonly ImTransportObservationPlan[];
+}
+/** Provider listener lifetime returned only after the listener is ready. */
+export interface ImTransportListener {
+    /** Settles after the listener ends; rejects with ImTransportListenerError when the provider can classify a failure. The runtime owns bounded retry scheduling. */
+    readonly done: Promise<void>;
+    /** Request an orderly stop. The `done` promise must settle after this request. @returns when provider stop has been requested. */
+    dispose(): Promise<void>;
+}
+/** One SDK message; the runtime resolves its buyer into an existing SaaS conversation. */
+export interface ImRealtimeInboundRequest {
+    readonly account: ImAccountView;
+    readonly sdkGeneration: number;
+    readonly buyerUid: string;
+    readonly externalMessageId: string;
+    readonly content: ImMessageContent;
+    readonly occurredAt: string;
+}
+/** No deferred message is persisted; storage failures reject rather than returning duplicate. */
+export type ImRealtimeInboundResult = {
+    readonly state: 'admitted' | 'duplicate';
+    readonly scope: ImRealDeliveryScope;
+} | {
+    readonly state: 'deferred';
+    readonly reason: 'account-changed' | 'sdk-offline' | 'sdk-generation' | 'buyer-unknown' | 'buyer-ambiguous' | 'assignment-route' | 'route-unavailable' | 'native-sender';
+};
+/** Exact platform message lookup, optionally confined to one complete conversation identity. */
+export type ImInboundContentQuery = {
+    readonly externalMessageId: string;
+} & ({
+    readonly conversationId: string;
+    readonly conversationKind: ImConversationKind;
+} | {
+    readonly conversationId?: never;
+    readonly conversationKind?: never;
+});
+/** Sink owned by the runtime while a provider listener is active. */
+export interface ImTransportSink {
+    /**
+     * Persist every conversation group before advancing the provider-owned cursor.
+     * A partial failure leaves successful groups durable so a replay can deduplicate them.
+     * @param page - stable provider/page identities, cursor CAS, and normalized groups.
+     * @returns every durable group receipt and the final cursor result.
+     */
+    receivePage(page: ImTransportInboundPage): Promise<ImTransportInboundPageReceipt>;
+    /** @param request - SDK account generation, peer and normalized message. @param signal - optional caller cancellation while waiting for reception; absence uses the listener lifetime. @returns admission into an existing scope, a duplicate, or a deferred reason; never advances SaaS cursors. */
+    receiveRealtime(request: ImRealtimeInboundRequest, signal?: AbortSignal): Promise<ImRealtimeInboundResult>;
+    /** @param request - exact platform message id, optionally restricted to one conversation in this listener account. @returns stored content or absence; storage failures throw. */
+    findInboundContent(request: ImInboundContentQuery): ImMessageContent | undefined;
+    /** @param uid - SDK sender UID. @returns whether it names the configured merchant, main account or an observed native service account; storage failures throw. */
+    isNativeSender(uid: string): boolean;
+    /** @param owner - provider feed identity. @returns the durable merchant cursor, or a null cursor before the first listen. */
+    getProviderCursor(owner: ImProviderCursorOwner): ImProviderCursorView;
+}
+/** Send authority survives preparation only within the caller's customer handling epoch. */
+export interface ImAutomaticSendAuthorization {
+    /** Cancellation during preparation; customer revocation stops affecting it after submission. */
+    readonly signal: AbortSignal;
+    /** Whether a provider has obtained permission to submit externally. */
+    readonly submitted: boolean;
+    /** @returns Current authorization. Providers call once, after asynchronous preparation and immediately before submission. */
+    authorizeSubmission(): boolean;
+    /** Release cancellation listeners after the provider settles. */
+    dispose(): void;
+}
+/** Provider outbound request. */
+export interface ImTransportSendRequest {
+    readonly account: ImAccountView;
+    readonly conversationId: string;
+    readonly conversationKind: ImConversationKind;
+    readonly directRecipient?: ImDirectRecipient;
+    readonly requestId: string;
+    readonly text: string;
+    readonly aiTag?: boolean;
+    /** Required for automatic sends and handling-constrained manual sends. Providers authorize immediately before external submission. */
+    readonly submission?: ImAutomaticSendAuthorization;
+}
+/** Provider send outcome before or after receipt confirmation. */
+export type ImTransportSendResult = {
+    readonly state: 'sent';
+    readonly externalMessageId: string;
+    readonly rawStatus?: string;
+} | {
+    readonly state: 'failed';
+    readonly code: string;
+    readonly message: string;
+} | {
+    readonly state: 'unknown';
+    readonly externalMessageId?: string;
+};
+/** Receipt lookup input for an uncertain outbound result. */
+export interface ImTransportConfirmRequest {
+    readonly account: ImAccountView;
+    readonly requestId: string;
+    readonly externalMessageId?: string;
+    readonly conversationId?: string;
+    readonly conversationKind?: ImConversationKind;
+    readonly text?: string;
+}
+/** Complete provider capability registered under one platform. */
+export interface ImTransport {
+    readonly platform: ImPlatform;
+    /** Optional secondary SDK connection. Wangwang text and media both require an online generation of this connection. */
+    readonly sdk?: ImSdkProvider | undefined;
+    /** Start or rejoin an interactive provider login. Implementations return only safe authorization instructions. */
+    startLogin?(signal: AbortSignal): Promise<ImPlatformLoginStatus>;
+    /** @param attemptId - provider-minted login identity. @returns its current safe state. */
+    loginStatus?(attemptId: ImPlatformLoginAttemptId): ImPlatformLoginStatus;
+    /** @param attemptId - provider-minted login identity. @returns the terminal cancelled state. */
+    cancelLogin?(attemptId: ImPlatformLoginAttemptId): Promise<ImPlatformLoginStatus>;
+    /** @param signal - caller lifetime. @returns installed or admitted identities safe for account selection. */
+    listAccountCandidates(signal: AbortSignal): Promise<readonly ImAccountCandidate[]>;
+    /** @param request - write-only setup input. @param signal - caller lifetime. @returns verified safe facts and credential payload. */
+    prepareAccount(request: ImAccountSetupRequest, signal: AbortSignal): Promise<ImPreparedAccount>;
+    /** @param account - configured safe identity. @param signal - caller lifetime. @returns current provider authorization facts. */
+    inspectAccount(account: ImAccountView, signal: AbortSignal): Promise<ImTransportAccountInspection>;
+    /** @param account - configured safe identity. @param signal - caller lifetime. @returns refreshed authorization facts. */
+    refreshAccount(account: ImAccountView, signal: AbortSignal): Promise<ImTransportAccountInspection>;
+    /** @param account - safe configured account. @param cursor - provider cursor. @param signal - caller lifetime. @returns one candidate page. */
+    discoverConversations(account: ImAccountView, cursor: string | undefined, signal: AbortSignal): Promise<ImConversationCandidatePage>;
+    /** @param account - safe configured account. @param conversationId - platform conversation identifier. @param conversationKind - provider category. @param signal - caller lifetime. @returns provider-known title, or the identifier when the title is unknown. */
+    inspectConversation(account: ImAccountView, conversationId: string, conversationKind: ImConversationKind, signal: AbortSignal): Promise<ImConversationCandidate>;
+    /** @param account - safe configured account. @param signal - caller lifetime. @returns assigned service accounts when the platform exposes them. */
+    listAssignedActors?(account: ImAccountView, signal: AbortSignal): Promise<readonly ImAssignedActorCandidate[]>;
+    /** @param account - account to listen on. @param plan - enabled routes and required provider evidence. @param sink - runtime-owned durable sink. @param signal - listener lifetime. @returns lifetime handle only after the provider has established and verified the usable listener. */
+    listen(account: ImAccountView, plan: ImTransportListenPlan, sink: ImTransportSink, signal: AbortSignal): Promise<ImTransportListener>;
+    /** @param request - normalized outbound request. @param signal - caller lifetime. @returns provider result. */
+    send(request: ImTransportSendRequest, signal: AbortSignal): Promise<ImTransportSendResult>;
+    /** @param request - uncertain delivery to inspect. @param signal - caller lifetime. @returns current provider result. */
+    confirm(request: ImTransportConfirmRequest, signal: AbortSignal): Promise<ImTransportSendResult>;
+}

package/lib/types/transports.d.ts

@@ -0,0 +1,48 @@
+/** Cordis registry for product IM transport providers. */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { ImPlatform } from './types.ts';
+import type { ImTransport } from './transport.ts';
+/** Stable transport registry failure codes. */
+export type ImTransportErrorCode = 'IM_TRANSPORT_CONFLICT' | 'IM_TRANSPORT_UNAVAILABLE' | 'IM_TRANSPORT_AUTHORIZATION_REQUIRED';
+/** Structured transport registry failure. */
+export declare class ImTransportError extends Error {
+    readonly code: ImTransportErrorCode;
+    /** @param code - stable failure code. @param message - diagnostic detail. */
+    constructor(code: ImTransportErrorCode, message: string);
+}
+/** Provider listener failure with a safe code and an explicit authorization disposition. */
+export declare class ImTransportListenerError extends Error {
+    readonly code: string;
+    readonly authorization: boolean;
+    /** @param code - stable platform error code. @param authorization - whether credentials require operator action. @param cause - underlying provider failure, excluded from public state. */
+    constructor(code: string, authorization?: boolean, cause?: unknown);
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        imTransports: ImTransports;
+    }
+    interface Events {
+        /**
+         * A platform transport became available or unavailable.
+         * @param platform - changed platform reservation.
+         * @mode emit
+         */
+        'imTransports/changed'(platform: ImPlatform): void;
+    }
+}
+/** Registry whose entries live and die with their registering Cordis fiber. */
+export declare class ImTransports extends Service {
+    private readonly providers;
+    /** @param ctx - owning Cordis context. */
+    constructor(ctx: Context);
+    /** @param provider - complete transport capability. @returns disposer that releases the platform reservation. */
+    register(provider: ImTransport): () => void;
+    /** @param platform - platform to resolve. @returns the registered provider. */
+    require(platform: ImPlatform): ImTransport;
+    /** @param platform - platform to inspect. @returns the transport, or absence while unloaded. */
+    get(platform: ImPlatform): ImTransport | undefined;
+    /** @returns currently registered transport platforms in stable display order. */
+    registeredPlatforms(): readonly ImPlatform[];
+    /** Notify post-registration observers without making their failure revoke the committed reservation. */
+    private publish;
+}