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

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

@@ -0,0 +1,209 @@
+/** Host service and event declarations kept out of the client-safe DTO entry. */
+import type { ImAutomaticSendAuthorization } from './transport.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';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        imRuntime: ImRuntimeService;
+    }
+    interface Events {
+        /**
+         * IM configuration or process listener state changed. The emitted revision is newer than every prior event from this process.
+         * @param change - changed account, route, target, instance, transport, or listener and its process generation revision.
+         * @mode emit
+         */
+        'imRuntime/changed'(change: ImRuntimeChange): void;
+        /**
+         * Durable inbound, submission, or outbox state changed.
+         * @param change - committed scope and affected message or request identities.
+         * @mode emit
+         */
+        'imRuntime/delivery-changed'(change: ImDeliveryChange): void;
+    }
+}
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        /** Stable IM identity used to reconcile a Session append with the delivery domain. */
+        im: ImMessageSource;
+    }
+}
+/** Read and mutation surface consumed by the product BFF. */
+export interface ImRuntimeService {
+    /** @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. */
+    snapshot(): ImRuntimeSnapshot;
+    /** @param listener - post-commit change observer. @returns disposer for this subscription. */
+    subscribe(listener: (change: ImRuntimeChange) => void): () => 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. */
+    discoverConversations(accountId: ImAccountId, signal?: AbortSignal): Promise<ImConversationCandidatePage>;
+    /** @param accountId - 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(accountId: ImAccountId, conversationId: string, conversationKind: ImConversationKind, signal?: AbortSignal): Promise<ImConversationCandidate>;
+    /** @param accountId - configured account. @param signal - caller lifetime. @returns assigned service accounts when the platform exposes them. */
+    listAssignedActors(accountId: ImAccountId, signal?: AbortSignal): Promise<readonly ImAssignedActorCandidate[]>;
+    /** @param request - candidate-bound write-only setup input. @param signal - caller lifetime. @returns safe verified facts and a short-lived Host setup identifier. */
+    previewAccountSetup(request: ImAccountSetupRequest, signal?: AbortSignal): Promise<ImAccountSetupPreview>;
+    /** @param request - setup identifier and idempotency identifier. @returns the durable account-creation outcome. */
+    confirmAccountSetup(request: ImConfirmAccountSetupRequest): Promise<ImAccountMutationResult>;
+    /** @param setupId - unconfirmed setup to release. @returns whether it was released or had already advanced. */
+    cancelAccountSetup(setupId: ImAccountSetupId): ImCancelAccountSetupResult;
+    /** @param accountId - receiving account. @param conversationKind - provider category. @param conversationId - provider conversation. @returns precedence-ordered route resolution. */
+    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 - 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. */
+    reconnectAccount(request: ImAccountLifecycleRequest): Promise<ImAccountMutationResult>;
+    /** @param request - guarded account deletion. @returns its durable outcome; conversation history remains. */
+    deleteAccount(request: ImAccountLifecycleRequest): Promise<ImAccountMutationResult>;
+    /** @param request - guarded provider authorization refresh. @param signal - caller lifetime. @returns its durable outcome. */
+    refreshAccount(request: ImAccountLifecycleRequest, signal?: AbortSignal): Promise<ImAccountMutationResult>;
+    /** @param accountId - owning account. @param operationId - idempotency identifier. @returns stored result or an explicit miss. */
+    queryAccountOperation(accountId: ImAccountId, operationId: ImOperationId): ImAccountOperationQuery;
+    /** @param request - new route tuple and workspace owner. @returns its durable outcome. */
+    createRoute(request: ImCreateRouteRequest): Promise<ImRouteMutationResult>;
+    /** @param request - guarded non-ownership route edit. @returns its durable outcome. */
+    saveRoute(request: ImSaveRouteRequest): Promise<ImRouteMutationResult>;
+    /** @param request - guarded ownership transfer. @returns its durable outcome. */
+    rebindRoute(request: ImRebindRouteRequest): Promise<ImRouteMutationResult>;
+    /** @param request - guarded route deletion. @returns its durable outcome. */
+    deleteRoute(request: ImDeleteRouteRequest): Promise<ImRouteMutationResult>;
+    /** @param accountId - owning account. @param operationId - idempotency identifier. @returns stored result or an explicit miss. */
+    queryRouteOperation(accountId: ImAccountId, operationId: ImOperationId): ImRouteOperationQuery;
+    /**
+     * Keep history flowing for one account without an enabled admit route.
+     * @param accountId - connected account.
+     * @param observation - conversation kind and target to receive.
+     */
+    registerObservation(accountId: ImAccountId, observation: {
+        readonly conversationKind: ImConversationKind;
+        readonly target: import('./types.ts').ImRouteTarget;
+    }): () => void;
+    /** @param request - guarded simulation-target save. @returns its durable outcome. */
+    saveSimulationTarget(request: ImSaveSimulationTargetRequest): Promise<ImSimulationTargetMutationResult>;
+    /** @param request - guarded simulation-target removal. @returns its durable outcome. */
+    removeSimulationTarget(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. */
+    realScopeForSession(sessionId: SessionId): ImRealSessionBinding | undefined;
+    /** @param scopeId - complete conversation identity. @returns current safe account, listener, presentation, and sync facts, even before an Agent task exists. */
+    realBindingForScope(scopeId: ImScopeId): ImRealSessionBinding | undefined;
+    /**
+     * Send one human-manual message.
+     * Session-bound calls may use any locally configured account that owns the
+     * Agent task. Hosting-console callers name the selected {@link ImSendManualMessageRequest.accountId}
+     * and, when no task exists, {@link ImSendManualMessageRequest.scopeId}; unknown,
+     * other-account, and simulation scopes are rejected.
+     * @param request - Session- or scope-bound stable request and text.
+     * @param signal - caller lifetime.
+     * @returns durable manual delivery and identity facts when the account is available.
+     */
+    sendManualMessage(request: ImSendManualMessageRequest, signal?: AbortSignal): Promise<ImManualMessageResult>;
+    /** @param request - Session- or scope-bound stable request identity. @returns durable result without provider activity. */
+    queryManualMessage(request: ImManualMessageQueryRequest): ImManualMessageQuery;
+    /** @param request - Session- or scope-bound uncertain request. @param signal - caller lifetime. @returns provider-confirmed or still-unknown result without sending. */
+    confirmManualMessage(request: ImManualMessageQueryRequest, signal?: AbortSignal): Promise<ImManualMessageResult>;
+    /** @param request - new request linked to an uncertain predecessor. @param signal - caller lifetime. @returns explicit retry delivery result. */
+    retryManualMessage(request: ImRetryManualMessageRequest, signal?: AbortSignal): Promise<ImManualMessageResult>;
+    /** @returns all durable simulation instances in creation order. */
+    listSimulationInstances(): readonly ImSimulationInstanceView[];
+    /** @param instanceId - Host-minted instance identity. @returns its durable state or absence. */
+    getSimulationInstance(instanceId: import('./delivery-types.ts').ImSimulationInstanceId): ImSimulationInstanceView | undefined;
+    /** @param sessionId - either side of a simulation pair. @returns Host-authoritative role, peer, workspace, and delivery scope. */
+    scopeForSession(sessionId: SessionId): ImSimulationSessionScope | undefined;
+    /** @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 - 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 - 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. */
+    beginStopSimulation(instanceId: import('./delivery-types.ts').ImSimulationInstanceId): Promise<ImSimulationInstanceView>;
+    /** @param sessionId - trusted tool caller Session. @returns its instance's durable stopping or terminal state. */
+    beginStopSimulationForSession(sessionId: SessionId): Promise<ImSimulationInstanceView>;
+    /** @param instanceId - already-stopping instance. @returns terminal state after both sides and derived work quiesce. */
+    waitSimulationStopped(instanceId: import('./delivery-types.ts').ImSimulationInstanceId): Promise<ImSimulationInstanceView>;
+    /** @param request - instance identity, stable operation, display filename, and local JSONL. @returns durable query-only source counts and updated instance. */
+    importSimulationHistory(request: ImImportSimulationHistoryRequest): Promise<ImImportSimulationHistoryResult>;
+    /** @param listener - post-commit delivery observer. @returns disposer for this subscription. */
+    subscribeDelivery(listener: (change: ImDeliveryChange) => void): () => void;
+    /** @param request - complete real scope, cursor CAS, and provider page. @returns durable page receipt. */
+    ingestInboundPage(request: ImIngestInboundPageRequest): Promise<ImInboundPageResult>;
+    /** @param scope - complete conversation identity. @param operationId - page or import operation. @returns durable receipt or explicit miss. */
+    queryInboundOperation(scope: ImDeliveryScope, operationId: ImDeliveryOperationId): ImInboundOperationQuery;
+    /** @param scope - complete conversation identity. @returns current live-delivery cursor. */
+    getConversationCursor(scope: ImDeliveryScope): ImConversationCursor;
+    /** @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. */
+    commitProviderCursor(request: ImCommitProviderCursorRequest): Promise<ImProviderCursorCommitResult>;
+    /** @param owner - provider feed identity. @param operationId - uncertain cursor operation. @returns durable receipt or explicit miss. */
+    queryProviderCursorOperation(owner: ImProviderCursorOwner, operationId: ImDeliveryOperationId): ImProviderCursorOperationQuery;
+    /** @param request - bounded history cursor and origin filter. @returns ascending message page. */
+    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 - reader, scope, and observed arrival sequence. */
+    ackCustomerRead(request: ImCustomerReadAckRequest): void;
+    /** @param request - scope and pause fields. @returns the stored handling control. */
+    setHandlingControl(request: ImSetHandlingControlRequest): ImHandlingControl;
+    /** @param scopeId - Customer whose durable journal pause needs reconciliation. @param pending - Hold automatic processing until persistence and acknowledgement complete; caller disposal does not release it. */
+    setAutomaticHandlingPausePending(scopeId: ImScopeId, pending: boolean): void;
+    /** @param scopeId - Complete customer scope. @returns Pending journal or durable handling pause blocks automatic processing. */
+    isAutomaticHandlingBlocked(scopeId: ImScopeId): boolean;
+    /** @param scopeId - complete conversation identity. @returns the stored handling control, or absence. */
+    getHandlingControl(scopeId: ImScopeId): ImHandlingControl | undefined;
+    /** @param scopeId - complete conversation identity. @returns the stored scope, or absence. */
+    getDeliveryScope(scopeId: ImScopeId): ImDeliveryScope | undefined;
+    /** @param request - scope and maximum pending live messages. @returns oldest received rows. */
+    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 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. */
+    sessionUserMessage(scope: ImDeliveryScope, messageId: ImMessageId): UserMessage;
+    /** @param sessionId - durable Session log to compare with pending delivery rows. @returns matched submissions and ignored stale evidence. */
+    reconcileSession(sessionId: SessionId): Promise<ImSessionReconciliationResult>;
+    /** @param request - Session evidence for atomically submitted inbound rows. @returns committed rows and cursor. */
+    markSubmitted(request: ImMarkSubmittedRequest): Promise<ImMarkSubmittedResult>;
+    /** @param request - query-only JSONL history and idempotency identity. @returns durable import receipt. */
+    importJsonlHistory(request: ImImportJsonlHistoryRequest): Promise<ImImportJsonlHistoryResult>;
+    /** @param request - outbound intent persisted before any send. @returns durable safe outbox row. */
+    registerOutbound(request: ImRegisterOutboundRequest): Promise<ImOutboundView>;
+    /** @param request - Durable automatic dispatch attempt. @param signal - Tool cancellation. @returns Epoch-scoped authorization disposed after provider settlement. */
+    automaticSendAuthorization(request: ImBeginOutboundAttemptRequest & {
+        readonly attemptId: ImOutboundAttemptId;
+    }, signal: AbortSignal): ImAutomaticSendAuthorization;
+    /** @param request - real scope and pending request. @returns sole attempt or durable block. */
+    beginOutboundAttempt(request: ImBeginOutboundAttemptRequest): Promise<ImBeginOutboundAttemptResult>;
+    /** @param request - provider attempt and observed outcome. @returns settled outbox row. */
+    settleOutboundAttempt(request: ImSettleOutboundAttemptRequest): Promise<ImOutboundView>;
+    /** @param request - simulation scope and local request. @returns locally sent outbox row. */
+    settleSimulationOutbound(request: ImSettleSimulationOutboundRequest): Promise<ImOutboundView>;
+    /** @param request - complete scope and request identity. @returns outbox row or absence. */
+    getOutbound(request: ImGetOutboundRequest): ImOutboundView | undefined;
+    /** @param request - bounded outbox history cursor. @returns ascending outbox page. */
+    queryOutbound(request: ImOutboundQueryRequest): ImOutboundPage;
+    /** @param request - scope and terminal reason. @returns discarded automated rows. */
+    cancelPendingAi(request: ImCancelPendingAiRequest): Promise<readonly ImOutboundView[]>;
+    /** @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. */
+    classifyInboundSender(scope: ImRealDeliveryScope, evidence: ImInboundSenderEvidence): ImSenderAttribution;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * 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';
+/** Payload recorded when automatic handling is paused for one conversation. */
+export interface ImHandlingPausedEvent {
+    /** Frozen conversation identity. */
+    readonly scope: ImDeliveryScope;
+    /** Pause reason such as `operator-pause` or `forward-*`; never a secret. */
+    readonly reason: string;
+    /** Tool or GUI call identity that initiated the pause; empty when none. */
+    readonly callId: string;
+}
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * Automatic handling was paused for one IM scope. Records the scope, pause
+         * reason, and initiating call id. Contains no secrets. Required-on-read.
+         */
+        'im/handling-paused': ImHandlingPausedEvent;
+    }
+}

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

@@ -0,0 +1,64 @@
+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 { ImCreateSimulationInstanceRequest, 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 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;
+    /** Create and durably publish one tested Session paired with the live simulated-user Session. */
+    create(request: ImCreateSimulationInstanceRequest): 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 - 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;
+    private recoverCreating;
+    private task;
+    private createTestedAgent;
+    private ingest;
+    private queueReplies;
+    private driveReplies;
+    private submit;
+    private scheduleStop;
+    private convergeStop;
+    private refreshTools;
+    private workspaceForSession;
+    private scope;
+    private requireRunning;
+    private closeReplies;
+    private enqueue;
+}

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/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,162 @@
+/** Provider-facing IM transport capability registered with the runtime. */
+import type { CredentialRecord } from '@deepseek-ai/dsh-credentials';
+import type { ImDeliveryOperationId, ImConversationPresentation, ImInboundPageResult, ImInboundSenderEvidence, ImMessageContent, ImProviderCursorCommitResult, ImProviderCursorOwner, ImProviderCursorView } 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 {
+    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;
+    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 when an established listener fails. */
+    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>;
+}
+/** 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 owner - provider feed identity. @returns the durable merchant cursor, or a null cursor before the first listen. */
+    getProviderCursor(owner: ImProviderCursorOwner): ImProviderCursorView;
+}
+/** Automatic-send authority survives preparation only within its customer's 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; absent for manual sends. Providers must 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;
+    /** 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,41 @@
+/** 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);
+}
+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;
+}