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

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

@@ -0,0 +1,648 @@
+/** Client-safe IM delivery, history, cursor, and outbox values. */
+import type { Branded } from '@deepseek-ai/dsh-brand';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { WorkspaceId } from '@deepseek-ai/dsh-workspace/types';
+import type { ImAccountAuthorization, ImAccountConnectionIntent, ImAccountId, ImAccountIdentity, ImAccountListener, ImDirectRecipient, ImGroupTrigger, ImPlatform, ImRevision, ImRouteId } from './types.ts';
+/** Collision-safe identifier of one real or simulated conversation scope. */
+export type ImScopeId = Branded<'ImScopeId'>;
+/** Stable identity of one inbound message. */
+export type ImMessageId = Branded<'ImMessageId'>;
+/** Caller-owned identity of one inbound page or JSONL import. */
+export type ImDeliveryOperationId = Branded<'ImDeliveryOperationId'>;
+/** Caller-owned idempotency identity of one outbound intent. */
+export type ImOutboundRequestId = Branded<'ImOutboundRequestId'>;
+/** Host-minted identity of the sole platform send attempt for an intent. */
+export type ImOutboundAttemptId = Branded<'ImOutboundAttemptId'>;
+/** Host-minted identity of a future local simulation instance. */
+export type ImSimulationInstanceId = Branded<'ImSimulationInstanceId'>;
+/** Stable identity of one provider-owned polling or stream cursor. */
+export type ImProviderCursorId = Branded<'ImProviderCursorId'>;
+/** Host-minted identity of one Agent admission batch. */
+export type ImAdmissionId = Branded<'ImAdmissionId'>;
+/** Stable identity of one route-bound Agent task generation. */
+export type ImAgentTaskId = Branded<'ImAgentTaskId'>;
+/** Complete identity of a real platform conversation. */
+export interface ImRealDeliveryScope {
+    readonly kind: 'real';
+    readonly platform: ImPlatform;
+    readonly accountId: ImAccountId;
+    readonly conversationKind: 'direct' | 'group';
+    readonly conversationId: string;
+}
+/** Complete identity of a simulation conversation. */
+export interface ImSimulationDeliveryScope {
+    readonly kind: 'simulation';
+    readonly instanceId: ImSimulationInstanceId;
+    readonly platform: ImPlatform;
+    readonly accountId: ImAccountId;
+    readonly conversationKind: 'direct' | 'group';
+    readonly conversationId: string;
+}
+/** Real and simulated conversations share the same history and outbox methods. */
+export type ImDeliveryScope = ImRealDeliveryScope | ImSimulationDeliveryScope;
+/** Provider evidence for an external participant. */
+export interface ImExternalSenderAttribution {
+    readonly kind: 'external';
+    readonly senderId: string;
+    readonly senderDisplayName?: string;
+    readonly userId?: string;
+    readonly openDingTalkId?: string;
+}
+/** Provider evidence that the configured account spoke in its native client. */
+export interface ImHumanNativeSenderAttribution {
+    readonly kind: 'human-native';
+    readonly accountId: ImAccountId;
+    readonly providerActorId: string;
+}
+/** Durable outbox evidence that a human sent through DSH. */
+export interface ImHumanDshSenderAttribution {
+    readonly kind: 'human-dsh';
+    readonly outboundRequestId: ImOutboundRequestId;
+    /** Host-derived managed account actor when the provider exposes one. */
+    readonly providerActorId?: string;
+}
+/** Durable outbox evidence that an Agent reply was sent. */
+export interface ImAiSenderAttribution {
+    readonly kind: 'ai';
+    readonly outboundRequestId: ImOutboundRequestId;
+}
+/** Honest fallback when provider facts cannot establish an actor. */
+export interface ImUnknownSenderAttribution {
+    readonly kind: 'unknown';
+    readonly reason: 'insufficient-evidence' | 'unmatched-self' | 'unmatched-echo' | 'provider-unknown';
+    readonly observedSenderId?: string;
+}
+/** Evidence-bearing sender classification. Text equality never establishes a kind. */
+export type ImSenderAttribution = ImExternalSenderAttribution | ImHumanNativeSenderAttribution | ImHumanDshSenderAttribution | ImAiSenderAttribution | ImUnknownSenderAttribution;
+/** Provider facts admitted before the runtime assigns a sender category. */
+export type ImInboundSenderEvidence = {
+    readonly kind: 'external-actor';
+    readonly senderId: string;
+    readonly senderDisplayName?: string;
+    readonly userId?: string;
+    readonly openDingTalkId?: string;
+} | {
+    readonly kind: 'configured-native';
+    readonly providerActorId: string;
+} | {
+    readonly kind: 'configured-echo';
+    readonly externalMessageId: string;
+    readonly observedSenderId?: string;
+} | {
+    readonly kind: 'provider-unknown';
+    readonly observedSenderId?: string;
+};
+/** JSON value already reduced by a provider to display-safe message details. */
+export type ImSafeJsonValue = null | boolean | number | string | readonly ImSafeJsonValue[] | {
+    readonly [key: string]: ImSafeJsonValue;
+};
+/** Provider quote context shown without resolving or rewriting another message. */
+export interface ImMessageQuote {
+    readonly text: string;
+    readonly senderDisplayName?: string;
+    readonly externalMessageId?: string;
+}
+/** Text, image placeholder, or honest unsupported-message presentation. */
+export type ImMessageContent = {
+    readonly text: string;
+    readonly format: 'text' | 'markdown';
+    readonly quote?: ImMessageQuote;
+} | {
+    readonly text: string;
+    readonly format: 'image';
+    readonly quote?: ImMessageQuote;
+} | {
+    readonly text: string;
+    readonly format: 'unsupported';
+    readonly messageType: string;
+    readonly details: ImSafeJsonValue;
+    readonly quote?: ImMessageQuote;
+};
+/** One normalized inbound provider message before persistence. */
+export interface ImInboundMessageInput {
+    readonly externalMessageId: string;
+    readonly sender: ImSenderAttribution;
+    readonly content: ImMessageContent;
+    readonly occurredAt: string;
+    /** Provider-normalized evidence that this account was explicitly mentioned. */
+    readonly mentionedConfiguredAccount?: boolean;
+}
+/** Session attribution written with the existing durable `user/message` event. */
+export interface ImMessageSource {
+    readonly kind: 'im';
+    readonly scopeId: ImScopeId;
+    readonly messageId: ImMessageId;
+    readonly sequenceNumber: number;
+    /** Present when one Agent steering item represents a durable message batch. */
+    readonly admission?: ImAgentAdmissionSource;
+}
+/** OR-combined reason that made one inbound batch eligible for Agent input. */
+export type ImTriggerReason = 'direct' | 'mention' | 'every-n' | 'fixed-interval';
+/** Sender and order evidence copied into the Session source for reconstruction. */
+export interface ImAdmissionMessageSource {
+    readonly messageId: ImMessageId;
+    readonly sequenceNumber: number;
+    readonly externalMessageId: string;
+    readonly sender: ImSenderAttribution;
+    readonly occurredAt: string;
+}
+/** Frozen route and message evidence recorded with one Session user/message. */
+export interface ImAgentAdmissionSource {
+    readonly admissionId: ImAdmissionId;
+    /** Customer pause generation at automatic input admission; absent legacy values mean zero. */
+    readonly handlingEpoch?: number;
+    readonly scope: ImDeliveryScope;
+    readonly messageIds: readonly ImMessageId[];
+    readonly messages: readonly ImAdmissionMessageSource[];
+    readonly triggerReasons: readonly ImTriggerReason[];
+    readonly routeId: ImRouteId;
+    readonly routeRevision: ImRevision;
+    readonly accountRevision: ImRevision;
+    readonly workspaceId: WorkspaceId;
+}
+/** Durable Agent task identity frozen when its first batch is admitted. */
+export interface ImAgentTaskView {
+    readonly taskId: ImAgentTaskId;
+    readonly generation: number;
+    readonly scope: ImDeliveryScope;
+    readonly scopeId: ImScopeId;
+    readonly sessionId: SessionId;
+    readonly routeId: ImRouteId;
+    readonly routeRevision: ImRevision;
+    readonly accountRevision: ImRevision;
+    readonly workspaceId: WorkspaceId;
+    readonly agentPreset: string;
+    readonly controller?: string;
+    readonly groupTrigger?: ImGroupTrigger;
+    readonly directRecipient?: import('./types.ts').ImDirectRecipient;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+/** Durable inbound row safe for history UI and model tools. */
+export interface ImInboundMessageView {
+    readonly messageId: ImMessageId;
+    readonly scopeId: ImScopeId;
+    readonly externalMessageId: string;
+    readonly sender: ImSenderAttribution;
+    readonly content: ImMessageContent;
+    readonly origin: 'live' | 'jsonl-import';
+    readonly stage: 'received' | 'submitted';
+    readonly sequenceNumber: number;
+    readonly occurredAt: string;
+    /** Provider-normalized evidence; message text is never parsed to infer a mention. */
+    readonly mentionedConfiguredAccount?: boolean;
+    readonly receivedAt: string;
+    readonly submission?: {
+        readonly sessionId: SessionId;
+        readonly submittedAt: string;
+    };
+}
+/** Durable conversation progress. Imported history does not advance these live-delivery values. */
+export interface ImConversationCursor {
+    readonly scopeId: ImScopeId;
+    readonly platformCursor: string | null;
+    readonly lastReceivedSequenceNumber: number;
+    readonly lastSubmittedSequenceNumber: number;
+    readonly pendingCount: number;
+    /**
+     * Highest live sequence a route policy refused to admit.
+     * Later allow does not replay these ids; only newer inbound is eligible.
+     */
+    readonly lastSuppressedSequenceNumber?: number;
+    /** Last provider page admission; Agent submission does not change this value. */
+    readonly lastSyncedAt?: string;
+    readonly updatedAt: string;
+}
+/** Provider-known labels for one conversation. Missing fields remain unknown. */
+export interface ImConversationPresentation {
+    readonly displayName?: string;
+    readonly memberCount?: number;
+    readonly assignedActorId?: string;
+}
+/** Atomic provider page admission request. */
+export interface ImIngestInboundPageRequest {
+    readonly operationId: ImDeliveryOperationId;
+    readonly scope: ImDeliveryScope;
+    readonly observedCursor: string | null;
+    readonly nextCursor: string | null;
+    readonly presentation?: ImConversationPresentation;
+    readonly messages: readonly ImInboundMessageInput[];
+}
+/** Receipt stored with the conversation aggregate before a page call resolves. */
+export interface ImInboundPageResult {
+    readonly kind: 'page';
+    readonly operationId: ImDeliveryOperationId;
+    readonly status: 'applied' | 'conflict';
+    readonly acceptedCount: number;
+    /** Existing rows whose explicit mention evidence advanced monotonically to true. */
+    readonly evidenceMergedCount?: number;
+    readonly duplicateCount: number;
+    readonly messages: readonly ImInboundMessageView[];
+    readonly cursor: ImConversationCursor;
+}
+/** Provider cursor ownership stays separate from conversation scopes. */
+export interface ImProviderCursorOwner {
+    readonly platform: ImPlatform;
+    readonly accountId: ImAccountId;
+    /** Provider-defined feed identity, such as one admitted merchant inbox. */
+    readonly streamId: string;
+}
+/** One durable conversation-page receipt required before a provider cursor advances. */
+export interface ImProviderCursorPageReceipt {
+    readonly scope: ImRealDeliveryScope;
+    readonly operationId: ImDeliveryOperationId;
+}
+/** Advance one provider cursor after every referenced conversation page is durable. */
+export interface ImCommitProviderCursorRequest {
+    readonly operationId: ImDeliveryOperationId;
+    readonly owner: ImProviderCursorOwner;
+    readonly observedCursor: string | null;
+    readonly nextCursor: string | null;
+    readonly pages: readonly ImProviderCursorPageReceipt[];
+}
+/** Durable provider cursor and its last verified page set. */
+export interface ImProviderCursorView {
+    readonly id: ImProviderCursorId;
+    readonly owner: ImProviderCursorOwner;
+    readonly cursor: string | null;
+    readonly updatedAt: string;
+}
+/** Cursor CAS result; rejected results identify incomplete durable page evidence. */
+export interface ImProviderCursorCommitResult {
+    readonly operationId: ImDeliveryOperationId;
+    readonly status: 'applied' | 'unchanged' | 'conflict' | 'rejected';
+    readonly cursor: ImProviderCursorView;
+    readonly code?: 'IM_PROVIDER_PAGE_NOT_DURABLE';
+    readonly message?: string;
+}
+/** Lookup result for an uncertain provider-cursor response. */
+export type ImProviderCursorOperationQuery = {
+    readonly state: 'not-found';
+} | {
+    readonly state: 'known';
+    readonly result: ImProviderCursorCommitResult;
+};
+/** Query-only JSONL import request. Imported rows never enter pending delivery. */
+export interface ImImportJsonlHistoryRequest {
+    readonly operationId: ImDeliveryOperationId;
+    readonly scope: ImDeliveryScope;
+    /** Display source; the Host persists its basename only. */
+    readonly fileName: string;
+    readonly jsonl: string;
+}
+/** Durable JSONL import receipt. */
+export interface ImImportJsonlHistoryResult {
+    readonly kind: 'jsonl-import';
+    readonly operationId: ImDeliveryOperationId;
+    readonly status: 'applied';
+    readonly fileName: string;
+    readonly messageCount: number;
+    readonly importedCount: number;
+    readonly duplicateCount: number;
+}
+/** Durable inbound operation receipt. */
+export type ImInboundOperationResult = ImInboundPageResult | ImImportJsonlHistoryResult;
+/** Lookup result used after the caller loses an ingest or import response. */
+export type ImInboundOperationQuery = {
+    readonly state: 'not-found';
+} | {
+    readonly state: 'known';
+    readonly result: ImInboundOperationResult;
+};
+/** Cursor-based history request. `beforeSequenceNumber` is exclusive. */
+export interface ImHistoryQueryRequest {
+    readonly scope: ImDeliveryScope;
+    readonly limit: number;
+    readonly beforeSequenceNumber?: number;
+    readonly origins?: readonly ImInboundMessageView['origin'][];
+}
+/** One ascending history page plus the cursor for an older page. */
+export interface ImHistoryPage {
+    readonly items: readonly ImInboundMessageView[];
+    readonly hasMore: boolean;
+    readonly nextBeforeSequenceNumber?: number;
+}
+/** Pending live inbound request for the future Agent pump. */
+export interface ImPendingInboundRequest {
+    readonly scope: ImDeliveryScope;
+    readonly limit: number;
+}
+/** Mark Session-appended messages submitted without claiming a cross-log transaction. */
+export interface ImMarkSubmittedRequest {
+    readonly scope: ImDeliveryScope;
+    readonly messageIds: readonly ImMessageId[];
+    readonly sessionId: SessionId;
+    readonly submittedAt?: string;
+}
+/** Atomic submission result with current progress. */
+export interface ImMarkSubmittedResult {
+    readonly messages: readonly ImInboundMessageView[];
+    readonly cursor: ImConversationCursor;
+}
+/** Outbound author and policy category. */
+export type ImOutboundIntent = 'ai' | 'human-manual';
+/** Durable state of one outbound intent. */
+export type ImOutboundStatus = 'pending' | 'dispatching' | 'pre-send-failed' | 'sent' | 'result-unknown' | 'confirmed-failed';
+/** Shared lifecycle terms used by recorded Session and delivery projections. */
+export type ImMessageStage = 'received' | 'submitted' | 'sent';
+/** Safe provider receipt facts. */
+export interface ImOutboundReceipt {
+    readonly providerReceiptId?: string;
+    readonly providerStatus?: string;
+    readonly errorCode?: string;
+    readonly observedAt: string;
+}
+/** Frozen route identity for an automated real-platform reply. */
+export interface ImOutboundRouteBinding {
+    readonly routeId: ImRouteId;
+    readonly routeRevision: ImRevision;
+    readonly workspaceId: WorkspaceId;
+    /** Account generation prevents paused automated work from flushing after resume. */
+    readonly accountRevision: ImRevision;
+    /** Customer pause generation that authorized this automatic reply. */
+    readonly handlingEpoch?: number;
+}
+/** Durable outbound intent and its sole send attempt. */
+export interface ImOutboundView {
+    readonly requestId: ImOutboundRequestId;
+    readonly scopeId: ImScopeId;
+    readonly intent: ImOutboundIntent;
+    readonly content: ImMessageContent;
+    readonly status: ImOutboundStatus;
+    /** Scope-local admission order, independent of timestamps. */
+    readonly sequenceNumber: number;
+    /** Pause generation at registration; absence is the legacy zero generation. */
+    readonly handlingEpoch?: number;
+    readonly routeBinding?: ImOutboundRouteBinding;
+    readonly sender?: ImHumanDshSenderAttribution;
+    readonly manualBinding?: {
+        readonly sessionId: SessionId;
+        readonly taskId: ImAgentTaskId;
+    };
+    readonly retryOfRequestId?: ImOutboundRequestId;
+    readonly preSendFailureReason?: 'account-not-found' | 'platform-mismatch' | 'account-paused' | 'route-disabled' | 'route-unmatched' | 'route-changed' | 'cancelled';
+    readonly attempt?: {
+        readonly attemptId: ImOutboundAttemptId;
+        readonly startedAt: string;
+    };
+    readonly receipt?: ImOutboundReceipt;
+    readonly externalMessageId?: string;
+    readonly replyToExternalMessageId?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+/** Persist an outbound intent before any platform call. */
+export interface ImRegisterOutboundRequest {
+    readonly requestId: ImOutboundRequestId;
+    readonly scope: ImDeliveryScope;
+    readonly intent: ImOutboundIntent;
+    readonly content: ImMessageContent;
+    readonly sender?: ImHumanDshSenderAttribution;
+    readonly manualBinding?: {
+        readonly sessionId: SessionId;
+        readonly taskId: ImAgentTaskId;
+    };
+    readonly retryOfRequestId?: ImOutboundRequestId;
+    readonly replyToExternalMessageId?: string;
+}
+/** Durable real-Session assignment and safe identity confirmation for manual sends. */
+export interface ImRealSessionBinding {
+    readonly sessionId: SessionId;
+    readonly scope: ImRealDeliveryScope;
+    readonly taskId: ImAgentTaskId;
+    readonly routeId: ImRouteId;
+    readonly routeRevision: ImRevision;
+    readonly accountRevision: ImRevision;
+    readonly workspaceId: WorkspaceId;
+    /** Workspace record title; falls back to {@link workspaceId} when the registry has no title. */
+    readonly workspaceTitle?: string;
+    readonly directRecipient?: ImDirectRecipient;
+    readonly senderIdentity: {
+        readonly accountId: ImAccountId;
+        readonly platform: ImPlatform;
+        readonly displayName: string;
+        readonly identity: ImAccountIdentity;
+        readonly providerActorId: string;
+    };
+    readonly accountState: {
+        readonly authorization: ImAccountAuthorization;
+        readonly connectionIntent: ImAccountConnectionIntent;
+        readonly listener: ImAccountListener;
+        readonly paused: boolean;
+        readonly manualSend: ImManualSendAvailability;
+    };
+    /** Whether the frozen route still admits automatic handling. */
+    readonly routeEnabled: boolean;
+    /** Customer-level pause recorded by the Host handling control. */
+    readonly automaticHandlingPaused: boolean;
+    readonly destination: {
+        readonly conversationKind: 'direct';
+        readonly conversationId: string;
+        readonly displayName?: string;
+        readonly directRecipient?: ImDirectRecipient;
+    } | {
+        readonly conversationKind: 'group';
+        readonly conversationId: string;
+        readonly displayName?: string;
+        readonly memberCount?: number;
+    };
+    readonly sync?: {
+        readonly lastSyncedAt: string;
+        readonly platformCursor: string | null;
+    };
+}
+/** Current Host decision for a real Session's manual composer. */
+export type ImManualSendAvailability = {
+    readonly state: 'available';
+} | {
+    readonly state: 'unavailable';
+    readonly reason: 'disconnected' | 'authorization-required' | 'listener-unavailable';
+};
+/**
+ * GUI request for one idempotent real-platform manual message.
+ *
+ * Session-bound calls (an Agent task exists for {@link sessionId}) may send as
+ * any locally configured account that owns that task. Naming {@link scopeId}
+ * selects a stored real conversation when no task exists; Host then requires
+ * {@link accountId} and a conversation owned by that account. Unknown,
+ * other-account, and simulation scopes are rejected.
+ */
+export interface ImSendManualMessageRequest {
+    readonly sessionId: SessionId;
+    /** Wangwang conversation identity; used when {@link sessionId} has no Agent task. */
+    readonly scopeId?: ImScopeId;
+    /**
+     * Optional account constraint. Required together with {@link scopeId}.
+     * When present, the stored conversation must belong to this account.
+     * Session-bound callers that omit it may send as any locally configured
+     * account that owns the Session task.
+     */
+    readonly accountId?: ImAccountId;
+    readonly requestId: ImOutboundRequestId;
+    readonly text: string;
+}
+/** Query or confirmation input for a manual message bound through its Session or scope. */
+export interface ImManualMessageQueryRequest {
+    readonly sessionId: SessionId;
+    /** Wangwang conversation identity; used when {@link sessionId} has no Agent task. */
+    readonly scopeId?: ImScopeId;
+    /** Optional account constraint; required together with {@link scopeId}. */
+    readonly accountId?: ImAccountId;
+    readonly requestId: ImOutboundRequestId;
+}
+/** Explicit retry creates a distinct durable intent linked to an uncertain predecessor. */
+export interface ImRetryManualMessageRequest {
+    readonly sessionId: SessionId;
+    /** Wangwang conversation identity; used when {@link sessionId} has no Agent task. */
+    readonly scopeId?: ImScopeId;
+    /** Optional account constraint; required together with {@link scopeId}. */
+    readonly accountId?: ImAccountId;
+    readonly requestId: ImOutboundRequestId;
+    readonly retryOfRequestId: ImOutboundRequestId;
+}
+/** Safe result for rendering identity, destination, source origin, and delivery state together. */
+export interface ImManualMessageResult {
+    readonly binding: ImRealSessionBinding;
+    readonly sender: ImHumanDshSenderAttribution;
+    readonly outbound: ImOutboundView;
+}
+/** Durable lookup after an uncertain or lost manual-send response. */
+export type ImManualMessageQuery = {
+    readonly state: 'not-found';
+    readonly binding: ImRealSessionBinding;
+} | {
+    readonly state: 'known';
+    readonly result: ImManualMessageResult;
+};
+/** Start the sole provider attempt after a fresh route-policy check. */
+export interface ImBeginOutboundAttemptRequest {
+    readonly scope: ImRealDeliveryScope;
+    readonly requestId: ImOutboundRequestId;
+}
+/** Provider dispatch instruction or a durable reason not to call the platform. */
+export type ImBeginOutboundAttemptResult = {
+    readonly state: 'ready';
+    readonly attemptId: ImOutboundAttemptId;
+    readonly outbound: ImOutboundView;
+} | {
+    readonly state: 'blocked' | 'result-unknown';
+    readonly outbound: ImOutboundView;
+};
+/** Final or uncertain outcome of one provider attempt. */
+export interface ImSettleOutboundAttemptRequest {
+    readonly scope: ImRealDeliveryScope;
+    readonly requestId: ImOutboundRequestId;
+    readonly attemptId: ImOutboundAttemptId;
+    readonly status: 'sent' | 'result-unknown' | 'confirmed-failed';
+    readonly receipt?: ImOutboundReceipt;
+    readonly externalMessageId?: string;
+}
+/** Settle a simulation outbox locally without exposing a provider attempt. */
+export interface ImSettleSimulationOutboundRequest {
+    readonly scope: ImSimulationDeliveryScope;
+    readonly requestId: ImOutboundRequestId;
+}
+/** Query one outbound intent with its full scope identity. */
+export interface ImGetOutboundRequest {
+    readonly scope: ImDeliveryScope;
+    readonly requestId: ImOutboundRequestId;
+}
+/** Cursor-based outbound history request. */
+export interface ImOutboundQueryRequest {
+    readonly scope: ImDeliveryScope;
+    readonly limit: number;
+    readonly beforeSequenceNumber?: number;
+}
+/** Ascending outbound page. */
+export interface ImOutboundPage {
+    readonly items: readonly ImOutboundView[];
+    readonly hasMore: boolean;
+    readonly nextBeforeSequenceNumber?: number;
+}
+/** Result of comparing one durable Session log with pending IM submissions. */
+export interface ImSessionReconciliationResult {
+    readonly sessionId: SessionId;
+    readonly submittedMessageIds: readonly ImMessageId[];
+    readonly ignoredEvidenceCount: number;
+}
+/** Explicitly discard still-pending automated sends without touching manual intents. */
+export interface ImCancelPendingAiRequest {
+    readonly scope: ImDeliveryScope;
+    readonly reason: NonNullable<ImOutboundView['preSendFailureReason']>;
+}
+/** Post-commit delivery change for BFF feeds and provider pumps. */
+export interface ImDeliveryChange {
+    readonly sequence: number;
+    readonly scope: ImDeliveryScope;
+    readonly scopeId: ImScopeId;
+    readonly kind: 'inbound' | 'submitted' | 'outbound' | 'handling';
+    readonly messageIds?: readonly ImMessageId[];
+    readonly requestId?: ImOutboundRequestId;
+}
+/** Reader identity for GUI-only inbound watermarks. One Host user shares one id. */
+export type ImCustomerReaderId = Branded<'ImCustomerReaderId'>;
+/** Customer-index list filter. Real and simulated rows are never mixed. */
+export interface ImCustomerListRequest {
+    readonly accountId: ImAccountId;
+    readonly kind: 'real' | 'simulation';
+    readonly query?: string;
+    readonly limit: number;
+    readonly readerId: ImCustomerReaderId;
+    readonly after?: {
+        readonly lastActivity: string;
+        readonly customerKey: string;
+    };
+}
+/** One customer row projected from the rebuildable conversation index. */
+export interface ImCustomerRow {
+    readonly customerKey: string;
+    readonly scopeId: ImScopeId;
+    readonly kind: 'real' | 'simulation';
+    readonly platform: ImPlatform;
+    readonly accountId: ImAccountId;
+    readonly conversationId: string;
+    readonly instanceId?: ImSimulationInstanceId;
+    readonly displayName?: string;
+    readonly lastActivity?: string;
+    readonly messagePreview?: string;
+    readonly unreadCount: number;
+    readonly latestSessionId?: SessionId;
+    readonly latestWorkspaceId?: WorkspaceId;
+    readonly latestGeneration?: number;
+    readonly unidentified: boolean;
+    readonly automaticHandlingPaused: boolean;
+    readonly pauseReason?: string;
+}
+/** Keyset page of customer rows plus the change watermark at query time. */
+export interface ImCustomerListPage {
+    readonly items: readonly ImCustomerRow[];
+    readonly hasMore: boolean;
+    readonly nextAfter?: {
+        readonly lastActivity: string;
+        readonly customerKey: string;
+    };
+    readonly changeSeq: number;
+}
+/** GUI ack of the highest live inbound sequence the reader has rendered. */
+export interface ImCustomerReadAckRequest {
+    readonly readerId: ImCustomerReaderId;
+    readonly scopeId: ImScopeId;
+    readonly sequenceNumber: number;
+}
+/** Customer-level automatic-handling pause fact. */
+export interface ImHandlingControl {
+    readonly scopeId: ImScopeId;
+    readonly automaticHandlingPaused: boolean;
+    readonly reason?: string;
+    readonly revision: number;
+    readonly handlingEpoch: number;
+    readonly initiatingCallId?: string;
+    readonly updatedAt: string;
+}
+/** Persist or clear one scope's automatic-handling pause. */
+export interface ImSetHandlingControlRequest {
+    readonly scopeId: ImScopeId;
+    readonly automaticHandlingPaused: boolean;
+    readonly reason?: string;
+    readonly initiatingCallId?: string;
+}