Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

79.0 KB
Raw Blame
import type {
  IAgentEventActorContextMeta,
  ICompactionSemanticIndexProjection,
} from '@librechat/data-schemas';
import type {
  Agents,
  TFile,
  TPendingSteer,
  UserSubmittedMessageFieldPath,
} from 'librechat-data-provider';
import type { ScheduleMCPOutcome, ScheduledMCPIdentity } from 'librechat-data-provider';
import type { RunStep, StandardGraph } from '@librechat/agents';
import type { AgentEventDetachedTerminalEvidence } from '~/agents/triggers/types';
import type { EarlyBufferOverflowState } from '../../types/earlyBufferRecovery';
import type { ActivityPhaseSnapshot } from '~/agents/activityPhases/runtime';
import type { ReplayLimits, ReplayPublication } from '../internal/replay';
import type { ResolvedAskUserQuestion } from '~/agents/hitl/resume';
import type { RecoveredSteerPayload } from '../SteerRecovery';
import type { AuthoredSkillBinding } from '~/agents/authored';
import type { MCPRuntimeRequestBody } from '~/mcp/types';

/**
 * Detached Event Actor execution guarantee advertised by a generation store.
 *
 * `process_local` keeps the lifecycle coherent while this process is alive.
 * `distributed` additionally permits restart recovery and replica handoff.
 * Absence means the store cannot host detached Event Actor actions.
 */
export type DetachedAgentEventActionStoreMode = 'process_local' | 'distributed';

/**
 * Rewrites string-enum members to their literal values, recursively. The SDK and
 * data-provider declare nominally distinct enums (`ContentTypes`, `StepTypes`, ...)
 * with identical string values; erasing that nominality is what lets the two run-step
 * contracts be compared structurally.
 */
type WireShape<T> = T extends string
  ? `${T}`
  : T extends readonly (infer U)[]
    ? WireShape<U>[]
    : T extends object
      ? { [K in keyof T]: WireShape<T[K]> }
      : T;

type StaticAssert<T extends true> = T;

/**
 * Compile-time proof that the SDK run step and the wire contract (`Agents.RunStep`)
 * agree structurally once enum nominality is erased: any added, removed, retyped, or
 * newly optional SDK field fails these assertions, so drift cannot silently enter
 * resume state through `toWireRunSteps`.
 *
 * `summary.content` is the one deliberately unchecked field: the SDK reuses its full
 * `MessageContentComplex` union there, while the wire contract narrows it to the plain
 * text blocks summarization actually emits. That narrowing is the single semantic
 * judgment this conversion vouches for.
 */
type _WireRunStepContractHolds = StaticAssert<
  WireShape<Omit<RunStep, 'summary'>> extends WireShape<Omit<Agents.RunStep, 'summary'>>
    ? true
    : false
>;

type _WireSummaryContractHolds = StaticAssert<
  WireShape<Omit<NonNullable<RunStep['summary']>, 'content'>> extends WireShape<
    Omit<NonNullable<Agents.RunStep['summary']>, 'content'>
  >
    ? true
    : false
>;

/**
 * Run steps living on the SDK graph serialize to exactly the wire shape
 * `Agents.RunStep` describes; the assertion is safe because
 * `_WireRunStepContractHolds` above proves the contracts identical modulo the
 * nominally-split enums, which share their string values at runtime.
 */
export function toWireRunSteps(steps: readonly RunStep[]): Agents.RunStep[] {
  return steps as Agents.RunStep[];
}

/**
 * A pause owner has this long to durably persist the interrupted turn before
 * the barrier is considered abandoned. An abandoned barrier must fail closed:
 * exposing its action id again would let a resume drive history that may never
 * have reached the message database.
 */
export const PAUSE_PERSISTENCE_TIMEOUT_MS = 30_000;
export const PAUSE_PERSISTENCE_TIMEOUT_ERROR = 'Paused response persistence timed out';
/** Maximum time a terminal provider owner may remain undrained before its
 * process is treated as lost. Terminal host settlement retains the last
 * durable evidence through this grace period, then releases the lane from a
 * crashed owner instead of refreshing its fence forever. */
export const PROVIDER_DRAIN_TIMEOUT_MS = 30_000;

/**
 * Job status enum.
 *
 * `requires_action` is non-terminal: the run has paused for human review
 * (e.g. tool approval) and is expected to be resumed by an approval route.
 * Stores must NOT cleanup `requires_action` jobs as if they were complete.
 */
export type JobStatus = 'running' | 'complete' | 'error' | 'aborted' | 'requires_action';

/** Immutable wire/storage contract selected when a generation is created.
 * Missing markers on pre-rollout records are interpreted as protocol v1. */
export type GenerationProtocolVersion = 1 | 2;

/** Read-only durable evidence, without attaching a runtime or recovering a slow save. */
export type GenerationSettlementState = Pick<
  SerializableJobData,
  'createdAt' | 'status' | 'terminalPersistencePending'
>;

/** Serializable job data without object references, suitable for external storage. */
export interface SerializableJobData {
  streamId: string;
  userId: string;
  tenantId?: string;
  status: JobStatus;
  createdAt: number;
  generationProtocolVersion?: GenerationProtocolVersion;
  /** Saver-level checkpoint scope for this exact generation. New jobs use a
   * globally unique opaque identity; LangGraph still sees an empty root
   * `checkpoint_ns`, which the saver adapter maps to this storage scope.
   * Legacy paused jobs omit it and use the historical unscoped storage. */
  checkpointNamespace?: string;
  completedAt?: number;
  conversationId?: string;
  error?: string;

  /** Durable, non-sensitive identity and one-shot outcome for an early replay
   * buffer overflow. This lets another replica account for recovery. */
  earlyBufferOverflow?: EarlyBufferOverflowState;

  /** Generation-level first subscriber claim shared across replicas. */
  firstSubscriberAttachedAt?: number;
  /** Expiring local subscriber-group leases (in-memory store only). */
  activeSubscriberLeases?: Record<string, number>;
  /** Generation-wide durable chunk frontier maintained by the store. */
  durableEventCount?: number;

  /** Stable identity of the HTTP submission that created this generation.
   * Internal-only: lets an expired idempotency lease recognize the same live
   * job instead of replacing and billing it again. */
  idempotencyClientRequestId?: string;

  /** Parked steer leased into this ordinary recovery turn. The source text is
   * hidden while this exact generation is active and consumed only after the
   * user message is durably persisted. */
  recoveredSteerId?: string;

  /** User message metadata */
  userMessage?: {
    messageId: string;
    parentMessageId?: string;
    conversationId?: string;
    text?: string;
    privacyRevision?: string;
    /** Quoted excerpts referenced on this turn, carried so resumable/aborted
     *  reconstructions of the user message keep their `MessageQuotes`. */
    quotes?: string[];
    /** Skill selections, carried so a HITL-resumed turn's requestMessage keeps its pills. */
    manualSkills?: string[];
    alwaysAppliedSkills?: string[];
    /** Uploaded files for the turn, carried so a HITL resume sources them from the job
     *  rather than a user DB row whose save can still be racing the approval prompt. */
    files?: unknown[];
  };

  /** Response message ID for reconnection */
  responseMessageId?: string;

  /** Whether this generation replaces an existing assistant branch. */
  isRegenerate?: boolean;
  /** Whether this generation is a manual context compaction; the abort paths
   * read it to stamp the stopped row with the compaction's identity. */
  compact?: boolean;
  /** Exact normalized MCP placeholder identity for this turn. */
  mcpRequestBody?: MCPRuntimeRequestBody;
  /** Exact assistant-message fields authored by the user during this running job. */
  userSubmittedPaths?: string[];
  /** Exact request-only message fields embedded at caller-authored paths. */
  userSubmittedMessageFieldPaths?: UserSubmittedMessageFieldPath[];
  /** Provenance that the latest approval claim replaced. Until that resume's provider
   * segment starts, its decision is not in the job's content, so an abort publishes
   * these paths instead of the claimed ones. */
  preResumeProvenance?: Pick<
    SerializableJobData,
    'userSubmittedPaths' | 'userSubmittedMessageFieldPaths'
  >;

  /**
   * Whether this run has activity labels enabled (per-endpoint
   * `activityLabel: true`). Set once at run start so the resume path can
   * decide whether to reconcile label gaps WITHOUT reading content — the
   * first label of a run can be claimed inside the snapshot->subscribe
   * window, so the snapshot itself is not a reliable signal.
   */
  activityLabels?: boolean;

  /**
   * Deferred-tool names discovered (via `tool_search`) before a HITL pause, captured
   * so a resume can replay them into `createRun` — the rebuilt graph uses `messages: []`
   * (state comes from the checkpoint), so without these the rebuilt model would lose
   * the discovered tool schemas.
   */
  discoveredTools?: string[];
  /** Skill identities authored by this generation, reauthorized on resume. */
  authoredSkills?: AuthoredSkillBinding[];
  /** Bounded collector state for continuing a phase across HITL resume. */
  activityPhaseSnapshot?: ActivityPhaseSnapshot;
  /** Exact bounded compaction guidance captured atomically with a HITL pause. */
  compactionSemanticIndex?: ICompactionSemanticIndexProjection;
  /** Calibration and fading state captured atomically with a HITL pause, so a resume seeds its rebuilt pruner from the same tier. */
  contextMeta?: IAgentEventActorContextMeta;
  /**
   * Whether the replica that OWNS this generation can seal mid-stream
   * (`PreemptBoundary` wiring). Recorded at createJob because the steer route
   * may land on a different replica — during a rolling deploy its own SDK
   * probe would answer for the wrong process. Absent on jobs created before
   * preempt shipped, which reads as incapable: the honest outcome.
   */
  preemptCapable?: boolean;
  /**
   * Transient owner assertion that this replica's drain merges
   * `SteerQueueItem.quotes` into the injected turn. Never stored as-is:
   * createJob and `ApprovalLifecycle.resolve` translate it into
   * `steerQuotesExecutionId` bound to the asserting owner's execution.
   */
  steerQuotesCapable?: boolean;
  /**
   * The `providerExecutionId` of the owner that asserted quote capability.
   * Valid only while it equals the LIVE `providerExecutionId`: a legacy
   * replica winning a HITL resume rewrites the execution id but cannot know
   * this field, so its stale assertion self-invalidates — which a bare
   * boolean could not do (an old resume patch omits rather than clears it).
   * The fenced enqueue evaluates the equality atomically and strips
   * `item.quotes` on mismatch, keeping the persisted item and the
   * `quotesAccepted` echo honest; the client re-stages dropped excerpts.
   */
  steerQuotesExecutionId?: string;

  /** Explicitly false until the provider-owning replica has installed its
   * generation-fenced abort subscription. Missing is conservative legacy
   * evidence and must be treated like true by replacement handoff. */
  providerAbortReady?: boolean;

  /** Opaque identity of the currently executing provider segment. A HITL resume
   * replaces it so an earlier paused segment cannot acknowledge the new run. */
  providerExecutionId?: string;
  /** Durable evidence that the current provider owner crossed its start CAS.
   * Unlike `providerDrained`, this identity survives terminal drain so host
   * compensation can distinguish a projected-but-never-started resume. */
  providerExecutionStartedId?: string;
  /** False while the identified provider segment can still mutate user data;
   * true before provider startup and after the owner has fully unwound. */
  providerDrained?: boolean;

  /** Whether the user-message created event has been emitted */
  createdEventEmitted?: boolean;

  /** Sender name for UI display */
  sender?: string;

  /** Whether sync has been sent to a client */
  syncSent: boolean;

  /** Trusted schedule identity copied atomically into the generation job. */
  scheduleId?: string;
  scheduledFor?: string;
  scheduleConfigRevision?: number;
  scheduleManual?: boolean;
  /** Original schedule root for a legacy completion, never occurrence bookkeeping. */
  scheduleMCPCompletion?: ScheduledMCPIdentity;
  /** Terminal outcome evidence retained when the schedule row could not be updated. */
  scheduleOutcome?: 'success' | 'error' | 'interrupted' | 'skipped_balance';
  scheduleOutcomeError?: string;
  /** Safe invocation denial retained until schedule settlement, never tool arguments. */
  scheduleMCPFailure?: ScheduleMCPOutcome;
  preserveForScheduleReconcile?: boolean;
  /**
   * A terminal transition (currently approval expiry) still owes a durable host
   * lifecycle hook. Set atomically with that transition and cleared only once the host
   * adapter acknowledges success, so the job is retained (not reaped) and enumerable by
   * cleanup across restarts and replicas until the hook completes. Generic: a host with
   * no action clears it immediately on its no-op success, so nothing accumulates.
   */
  terminalHostActionPending?: boolean;
  /** Redis-only durable marker for a detached Event Actor completion hook.
   * Capable stores expose it through `terminalHostActionPending` as well, but
   * keep the persisted field distinct so legacy reconciliation cannot index or
   * claim the completion through the ordinary terminal-action lane. */
  detachedAgentEventTerminalHostActionPending?: boolean;
  /** Logical terminal state hidden behind a versioned fail-closed shell while
   * a detached Event Actor host action remains unacknowledged. */
  detachedAgentEventTerminalStatus?: Extract<JobStatus, 'complete' | 'aborted' | 'error'>;
  /**
   * Last time a cleanup pass enumerated this pending host action for retry. Retention is
   * measured from this rather than `completedAt`, so evidence survives as long as some
   * replica is still actively retrying the hook (e.g. Mongo unreachable for days), while a
   * deployment that stops retrying entirely still lets it age out instead of leaking.
   */
  terminalHostActionRefreshedAt?: number;

  /** Serialized final event for replay */
  finalEvent?: string;

  /** Abort won its terminal CAS but the route is still saving the partial
   * response / pruning HITL state. No normal terminal payload may be exposed
   * while true. */
  terminalPersistencePending?: boolean;
  /** Crash-recovery deadline basis for `terminalPersistencePending`. */
  terminalPersistenceStartedAt?: number;

  /** Serialized title event for replay during active-stream resume */
  titleEvent?: string;

  /** Serialized replay-only stream events for active-stream resume */
  replayEvents?: string;

  /** Serialized latest context usage snapshot for active-stream resume */
  contextUsage?: string;

  /** Serialized token usage events for active-stream resume (cross-replica safe) */
  tokenUsage?: string;

  /** Endpoint metadata for abort handling - avoids storing functions */
  endpoint?: string;
  iconURL?: string;
  model?: string;
  promptTokens?: number;

  /**
   * Agent that initiated the run. Persisted so a HITL resume can verify it rebuilds
   * the SAME agent that paused — resuming Agent A's checkpoint on Agent B's graph
   * would mis-execute the paused tool calls.
   */
  agent_id?: string;

  /**
   * Whether the originating turn was a temporary (non-persisted) chat. Persisted so
   * a HITL resume keeps the resumed response temporary instead of saving it — the
   * resume request can't be trusted to re-send the flag.
   */
  isTemporary?: boolean;
  /** Original server-authenticated retention deadline, serialized across replicas. */
  retentionExpiresAt?: string;
  agentEventDeliveryKey?: string;
  /** Original actor invocation when an internal completion delivery owns this generation. */
  agentEventInvocationKey?: string;
  /** Original actor invocation generation retained across completion HITL resumes. */
  agentEventInvocationGenerationCreatedAt?: number;
  /** This generation must resume on a durable detached-action producer. */
  agentEventDetachedActionProducerRequired?: boolean;
  /** Durable retry payload captured before detached terminal evidence is written to Mongo. */
  agentEventDetachedTerminalEvidence?: AgentEventDetachedTerminalEvidence;
  /** Trusted actor binding copied from the authenticated delivery envelope. */
  agentEventBindingId?: string;
  agentEventExpectedAction?: import('~/agents/triggers/types').AgentTriggerExpectedAction;
  /** Versioned pointer to the canonical signed Conversation suspension. */
  agentEventSuspension?: import('~/agents/triggers/types').AgentEventSuspensionProjection;
  /** Exact durable legacy-turn fence carried across a HITL pause/resume. */
  agentEventLegacyTurnToken?: string;

  /**
   * Set when status is `requires_action`. Describes the human review the
   * run is waiting on. Cleared by the resume path before the job returns to `running`.
   */
  pendingAction?: Agents.PendingAction;

  /** Durable bridge between the resume claim and content reconstruction. An
   * abort can win while the resume controller is still rebuilding the client;
   * retaining the accepted answer here lets that terminal owner stamp it onto
   * the persisted partial response instead of losing it with the request. */
  resolvedAskUserQuestions?: ResolvedAskUserQuestion[];

  /**
   * Flat mirror of `pendingAction.actionId`, kept as a top-level field so an
   * atomic status transition can guard on it (a nested JSON field can't be
   * compared inside a Redis Lua CAS). Lets `resolve`/`expire` reject a stale
   * decision that targets a different action than the one currently pending.
   */
  pendingActionId?: string;

  /**
   * Liveness basis for the stale-running failsafe, refreshed when a paused job
   * is resumed. Without it, cleanup keys off `createdAt`, so an approval that
   * sat in `requires_action` past the running window would be reaped on the
   * next tick right after resuming. Falls back to `createdAt` when unset.
   */
  lastActiveAt?: number;

  /**
   * Flat flag set by the terminal close-and-drain (Redis: raw hash field the
   * enqueue Lua guards on; in-memory: a parallel set). Once set, new steers
   * are rejected until `createJob` reuses the stream id. Never written through
   * `updateJob` — listed here so cleanup paths can reference the key name.
   */
  steersClosed?: boolean;
}

/** Exact active hash replaced by one atomic job creation. Built-in stores keep
 * this as non-enumerable transaction metadata; Redis also retains a private
 * receipt in the replacement hash so a committed create with a lost reply can
 * reconstruct it without exposing it through normal job serialization. */
export type ReplacedGeneration = Pick<
  SerializableJobData,
  | 'createdAt'
  | 'status'
  | 'conversationId'
  | 'providerAbortReady'
  | 'providerExecutionId'
  | 'providerDrained'
>;

/** Latest generation epoch checked by a conditional create. A retained epoch
 * can outlive its job hash, so inactive mismatches intentionally omit job-only
 * metadata while still telling the caller which generation won the race.
 * When all predecessor evidence has expired, `createdAt` safely echoes the
 * caller's finite expected epoch and `verified` is false; the create is still
 * rejected, but response consumers can preserve the queued turn without
 * mistaking that fallback for an observed generation. */
export type GenerationPredecessorState = Pick<SerializableJobData, 'createdAt'> &
  Partial<Pick<SerializableJobData, 'status' | 'conversationId'>> & {
    active: boolean;
    /** False only when neither the job nor its retained epoch was observable.
     * Missing values are compatible with pre-marker mismatch producers. */
    verified?: boolean;
  };

export interface CreatedJobData extends SerializableJobData {
  /** The predecessor observed inside the same transaction that installed this
   * job. Non-enumerable in the built-in stores to keep it out of serializers. */
  replacedJob?: ReplacedGeneration;
  /** Transitive transaction receipts inherited from replacements whose
   * managers may have lost their create replies. Ordered oldest to newest. */
  replacedJobs?: readonly ReplacedGeneration[];
  /** Opaque manager-minted proof for one create invocation. Non-enumerable in
   * built-in stores and used only to reconcile a commit whose reply was lost. */
  creationAttemptId?: string;
}

/** The store installed a generation, but another creator replaced it before
 * cross-slot membership reconciliation completed. The exact predecessor
 * metadata still has to reach the manager so its owner is stopped/notified. */
export class JobCreationSupersededError extends Error {
  constructor(readonly createdJob: CreatedJobData) {
    super('Generation job was replaced during creation');
    this.name = 'JobCreationSupersededError';
  }
}

/** A conditional create observed a different current generation than the
 * caller's last authoritative status read. The store rejects before replacing
 * that generation, so queued client work can be restored safely. */
export class JobPredecessorMismatchError extends Error {
  readonly code = 'GENERATION_PREDECESSOR_MISMATCH';

  constructor(readonly currentJob: GenerationPredecessorState) {
    super('Generation predecessor changed before creation');
    this.name = 'JobPredecessorMismatchError';
  }
}

/** Thrown by `createJob` when the owner's account deletion began before the job could be admitted. */
export class GenerationAdmissionDeniedError extends Error {
  readonly code = 'ACCOUNT_DELETION_IN_PROGRESS';
  readonly status = 409;

  constructor() {
    super('Account deletion is in progress');
    this.name = 'GenerationAdmissionDeniedError';
  }
}

/** Thrown by `createJob` when the account admission check itself failed; carries no lookup diagnostics. */
export class GenerationAdmissionUnavailableError extends Error {
  readonly code = 'GENERATION_ADMISSION_UNAVAILABLE';
  readonly status = 503;

  constructor() {
    super('Generation admission could not be verified');
    this.name = 'GenerationAdmissionUnavailableError';
  }
}

export type JobMetadataPatch = Partial<
  Pick<
    SerializableJobData,
    | 'responseMessageId'
    | 'isRegenerate'
    | 'compact'
    | 'mcpRequestBody'
    | 'userSubmittedPaths'
    | 'userSubmittedMessageFieldPaths'
    | 'sender'
    | 'conversationId'
    | 'userMessage'
    | 'endpoint'
    | 'iconURL'
    | 'model'
    | 'agent_id'
    | 'isTemporary'
    | 'retentionExpiresAt'
    | 'agentEventDeliveryKey'
    | 'agentEventInvocationKey'
    | 'agentEventInvocationGenerationCreatedAt'
    | 'agentEventDetachedActionProducerRequired'
    | 'agentEventDetachedTerminalEvidence'
    | 'agentEventBindingId'
    | 'agentEventExpectedAction'
    | 'agentEventSuspension'
    | 'agentEventLegacyTurnToken'
    | 'scheduleId'
    | 'scheduledFor'
    | 'scheduleConfigRevision'
    | 'scheduleManual'
    | 'scheduleMCPCompletion'
    | 'scheduleOutcome'
    | 'scheduleOutcomeError'
    | 'scheduleMCPFailure'
    | 'preserveForScheduleReconcile'
    | 'promptTokens'
    | 'discoveredTools'
    | 'authoredSkills'
    | 'activityPhaseSnapshot'
    | 'compactionSemanticIndex'
    | 'contextMeta'
    | 'preemptCapable'
    | 'steerQuotesCapable'
    | 'steerQuotesExecutionId'
    | 'providerExecutionId'
    | 'providerDrained'
    | 'generationProtocolVersion'
    | 'resolvedAskUserQuestions'
  >
>;

/**
 * Whether a job's pending review has passed its `expiresAt`. Shared by the
 * stores so an expired approval is kept out of active-job listings (the client
 * stops polling; cleanup/expiry finalizes it).
 */
export function isPendingActionExpired(job: Pick<SerializableJobData, 'pendingAction'>): boolean {
  const exp = job.pendingAction?.expiresAt;
  return exp != null && exp <= Date.now();
}

/**
 * Whether a `requires_action` job has no live, resolvable prompt — either the
 * pendingAction is missing/malformed (e.g. dropped on deserialize) or past its
 * `expiresAt`. Such a job can't be rendered or resolved, so it must be kept out
 * of active listings and finalized by cleanup rather than left stuck active.
 */
export function isPendingActionStale(job: Pick<SerializableJobData, 'pendingAction'>): boolean {
  return !job.pendingAction || isPendingActionExpired(job);
}

/**
 * A user steering message queued for mid-run injection. Enqueued by the steer
 * route on any instance; drained FIFO by the owning process's run-scoped
 * PostToolBatch hook at the next tool-batch boundary.
 */
export interface SteerQueueItem {
  steerId: string;
  /** Client-generated correlation id. It lets a terminal event that beats the
   *  202 ACK match the server item to its optimistic local chip. */
  clientSteerId?: string;
  text: string;
  userId: string;
  createdAt: number;
  /** Attachment refs steered with the message. Display metadata only — the
   *  drain re-fetches each file by id scoped to the run's user and encodes
   *  fresh, so nothing here is trusted beyond identifying the file. */
  files?: Partial<TFile>[];
  /** Quoted excerpts steered with the message, normalized at admission
   *  (`getReferencedQuotes`). Kept separate from `text` so the persisted
   *  steer part stays clean; merged into the model-bound turn at injection. */
  quotes?: string[];
  /** The steer asked to seal the live model stream at the next provider-safe
   *  boundary instead of waiting for a tool step. Durable so a parked,
   *  claimed, or replayed chip keeps its "interrupting" label. */
  preempt?: boolean;
  /** Monotonic per-steer arm revision. A capability downgrade increments it
   * so an older cross-replica arm cannot resurrect after the disarm, while a
   * later explicit arm with a newer revision remains valid. */
  preemptRevision?: number;
}

/** Durable acknowledgement keyed by `clientSteerId`. It outlives the queue
 * and live job for a bounded window so a lost 202 cannot make Retry inject
 * the same instruction twice after drain, terminal cleanup, or replacement. */
export interface SteerReceipt {
  clientSteerId: string;
  /** Quote-INDEPENDENT content hash (text/files/preempt) — the one shape every
   * replica version computes, so lost-ACK retries replay across a rolling
   * deploy in both directions. */
  fingerprint: string;
  /** Identity of the REQUESTED quotes (pre any owner-capability strip),
   * recorded beside the fingerprint so quote-aware readers enforce quote
   * identity without making the fingerprint unreadable to legacy admission.
   * Absent on receipts written by pre-quotes replicas or for quote-less
   * requests. */
  requestedQuotesFingerprint?: string;
  userId: string;
  tenantId?: string;
  agentId?: string;
  endpoint?: string;
  /** Generation epoch that accepted the item. Receipts intentionally survive
   * replacement, so queue absence is only "delivered" while this exact
   * generation remains active; a newer epoch means the predecessor dropped
   * an undrained item and the client must recover it as a leftover. */
  generationCreatedAt: number;
  item: SteerQueueItem;
  position: number;
  /** `claimed` is the crash-recoverable window between an atomic queue drain
   * and the durable applied-content record. It is not settled: a live client
   * keeps the chip pending, and a dead/replaced generation repairs it to a
   * leftover instead of silently dropping the instruction. */
  /** `recovered` means one recovery surface already claimed a leftover. A
   * later retry is settled without re-queuing the same follow-up. */
  state: 'queued' | 'claimed' | 'delivered' | 'leftover' | 'recovered' | 'cancelled';
}

export type SteerReceiptInput = Omit<SteerReceipt, 'item' | 'position' | 'state'>;
export type SteerEnqueueReceiptResult = SteerReceipt | SteerEnqueueResult | number;

/** Capability-normalized atomic enqueue result for callers without a stable
 * client receipt id (legacy/API compatibility path). */
export interface SteerEnqueueResult {
  item: SteerQueueItem;
  position: number;
}

export type TerminalSteerAdmissionResult =
  | { outcome: 'claimed'; items: SteerQueueItem[] }
  | { outcome: 'open' | 'sealed' | 'unavailable' };

export interface TerminalSteerAdmissionPolicy {
  allowClaim: boolean;
  keepOpenWhenEmpty: boolean;
}

export type SteerEnqueueVersionedResult = SteerEnqueueResult | number;

/**
 * Cross-replica preempt signal. Unlike abort this does NOT stop the run — it
 * asks the generating replica to seal its current model stream at the next
 * provider-safe boundary so the queued steer can inject there. Fenced by
 * `createdAt`: a stale publish must never arm a replacement job on the same
 * streamId.
 */
export interface PreemptMessage {
  op: 'arm' | 'clear';
  /** Generation identity (`SerializableJobData.createdAt`) this belongs to. */
  createdAt: number;
  steerIds: string[];
  /** Per-id arm revision. Omitted by legacy senders (treated as revision 0). */
  revisions?: Record<string, number>;
}

/** {@link IJobStoreV2.armSteer}: `armed` flipped the flag in place; `missing`
 *  covers every unavailable interleaving (paused, drained, cancelled, closed,
 *  replaced generation); `incapable` means the live owner cannot seal. */
export type SteerArmOutcome = 'armed' | 'missing' | 'incapable';

export interface SteerArmResult {
  outcome: SteerArmOutcome;
  /** Present only for an armed item. */
  revision?: number;
  item?: SteerQueueItem;
}

/** Maximum steers a single run can have queued at once. */
export const STEER_QUEUE_MAX_DEPTH = 10;

/** `enqueueSteer` rejection: the job is missing or not `running`. */
export const STEER_ENQUEUE_NOT_RUNNING = -1;

/** `enqueueSteer` rejection: the queue is at {@link STEER_QUEUE_MAX_DEPTH}. */
export const STEER_ENQUEUE_QUEUE_FULL = -2;

/** `enqueueSteerWithReceipt` rejection: the bounded, unexpired receipt
 * history is full. Existing ids still replay; only a new identity is refused
 * so idempotency evidence is never evicted inside its recovery window. */
export const STEER_ENQUEUE_RECEIPT_FULL = -3;

/** The store rejected a status CAS because its atomic deadline had elapsed. */
export class JobStatusTransitionDeadlineError extends Error {
  readonly notAfterMs: number;

  constructor(notAfterMs: number) {
    super('The status transition deadline elapsed before the transition could commit');
    this.name = 'JobStatusTransitionDeadlineError';
    this.notAfterMs = notAfterMs;
  }
}

/**
 * Arguments for an atomic {@link IJobStore.transitionStatus} compare-and-set.
 */
export interface JobStatusTransition {
  /** Only fire the transition if the job is currently in this status. */
  from: JobStatus;
  /** Status to move to when the `from` guard holds. */
  to: JobStatus;
  /** Fields written in the same atomic step as the status change. */
  patch?: Partial<SerializableJobData>;
  /** Field names removed in the same atomic step (e.g. `pendingAction`). */
  clear?: Array<keyof SerializableJobData & string>;
  /**
   * Additional guard: only fire if the job's `pendingActionId` equals this.
   * Checked atomically alongside the `from` status so a stale decision can't
   * resolve a job that has since paused for a different action.
   */
  expectActionId?: string;
  /**
   * Additional guard: only fire if the job's creation epoch equals this value.
   * Prevents a stale owner from transitioning a replacement job that reuses
   * the same stream ID.
   */
  expectCreatedAt?: number;
  /**
   * Additional guard: reject the transition when the store's clock has reached
   * this absolute deadline. The comparison is part of the same atomic operation
   * as the status change, so queueing or storage latency cannot publish stale state.
   */
  notAfterMs?: number;
  /** Extend all current steer receipts in the SAME atomic step as this
   * transition. Used by running→requires_action so no enqueue can land between
   * a pre-pause TTL pass and the status CAS. */
  steerReceiptTtlSeconds?: number;
}

/** Value stored under an idempotency claim: the stream a retried request should attach to. */
export interface IdempotencyClaimValue {
  streamId: string;
  conversationId: string;
  /** Wire/storage protocol selected by the request that first won this claim.
   * Missing values are legacy v1. Keeping the marker in both idempotency
   * tombstones lets a retry recover the original contract after its job hash
   * has already been cleaned up. */
  generationProtocolVersion?: GenerationProtocolVersion;
  /** Epoch ms the claim was written — lets a losing duplicate tell a winner that is still
   *  starting (recent, no job yet → retry) from one that already finished and was cleaned
   *  up (old, no job → attach and let the client refetch). */
  claimedAt?: number;
  /** Lease owner verified atomically by createJob; stale-request takeover
   * changes it so the abandoned winner can no longer create a generation. */
  claimToken?: string;
  /** Proof that a takeover token was derived by CAS from this predecessor.
   * If a connection drops after the primary CAS but before the legacy CAS,
   * the next replica can finish only that exact, same-coordinate split rather
   * than treating an arbitrary token mismatch as repairable. */
  previousClaimToken?: string;
  /** Written atomically with job creation. Once present, a missing job is an
   * already-started/cleaned generation and can never be taken over as an
   * abandoned pre-create lease. */
  startedAt?: number;
  /** Recovery closed an unpublished claim without admitting a generation. */
  recoveryFence?: true;
}

/** Result of an atomic {@link IJobStore.claimIdempotencyKey} attempt. */
export interface IdempotencyClaimResult {
  /** True when this caller won the claim and should create the job. */
  claimed: boolean;
  /** When `claimed` is false, the stream the original request is already driving. */
  existing?: IdempotencyClaimValue;
  /** The durable namespace that established the result. Manager-level claims
   * use `legacy` only for an old, tokenless claim that must remain
   * duplicate-only during a rolling upgrade. Store implementations may omit
   * this field because they operate on one physical key at a time. */
  source?: 'primary' | 'legacy';
}

/** Owner-authorized parked recovery payload plus the protocol that controls
 * its delivery semantics. V1 is destructive (legacy GETDEL); v2 is leased. */
export interface ParkedSteerClaim {
  payload: string;
  generationProtocolVersion: GenerationProtocolVersion;
}

/**
 * Usage metadata for token spending across different LLM providers.
 *
 * This interface supports two mutually exclusive cache token formats:
 *
 * **OpenAI format** (GPT-4, o1, etc.):
 * - Uses `input_token_details.cache_creation` and `input_token_details.cache_read`
 * - Cache tokens are nested under the `input_token_details` object
 *
 * **Anthropic format** (Claude models):
 * - Uses `cache_creation_input_tokens` and `cache_read_input_tokens`
 * - Cache tokens are top-level properties
 *
 * When processing usage data, check both formats:
 * ```typescript
 * const cacheCreation = usage.input_token_details?.cache_creation
 *   || usage.cache_creation_input_tokens || 0;
 * ```
 */
export interface UsageMetadata {
  /** Logical usage bucket for accounting/reporting. Defaults to model response usage. */
  usage_type?: 'message' | 'summarization' | 'subagent' | 'sequential';
  /** Total input tokens (prompt tokens) */
  input_tokens?: number;
  /** Total output tokens (completion tokens) */
  output_tokens?: number;
  /** Total billed tokens when provided by the model/runtime */
  total_tokens?: number;
  /** Model identifier that generated this usage */
  model?: string;
  /** Provider identifier that generated this usage */
  provider?: string;
  /** Agent that produced this usage (graph agent id / subagent agent id). Lets
   *  multi-endpoint graphs price each call with its own endpoint token config. */
  agentId?: string;
  /** Authoritative display cost attached by the host before durable child persistence. */
  cost?: number;
  /**
   * OpenAI-style cache token details.
   * Present for OpenAI models (GPT-4, o1, etc.)
   */
  input_token_details?: {
    /** Tokens written to cache */
    cache_creation?: number;
    /** Subset of `cache_creation` written to Anthropic's 1-hour cache (see `getModelEndUsage`) */
    cache_creation_1h?: number;
    /** Tokens read from cache */
    cache_read?: number;
    /** OpenAI GPT-5.6+ cache-write tokens (billed above the input rate) */
    cache_write_tokens?: number;
  };
  /**
   * Anthropic-style cache creation tokens.
   * Present for Claude models. Mutually exclusive with input_token_details.
   */
  cache_creation_input_tokens?: number;
  /**
   * OpenAI GPT-5.6+ cache-write tokens, reported at the top level of
   * `prompt_tokens_details`/`input_tokens_details`. Distinct from cached
   * (read) tokens and billed at a premium over the input rate.
   */
  cache_write_tokens?: number;
  /**
   * Anthropic-style cache read tokens.
   * Present for Claude models. Mutually exclusive with input_token_details.
   */
  cache_read_input_tokens?: number;
  /**
   * Breakdown of output token counts. Per the LangChain core contract,
   * `output_tokens` is the sum of all output token types — these fields
   * are subsets of `output_tokens`, *not* additional charges.
   */
  output_token_details?: {
    /** Reasoning/thinking tokens generated as chain-of-thought (o1, Gemini thinking, etc.) */
    reasoning?: number;
    /** Alternate provider/runtime alias for reasoning tokens. */
    reasoning_tokens?: number;
    audio?: number;
  };
}

/**
 * Result returned from aborting a job - contains all data needed
 * for token spending and message saving without storing callbacks
 */
export interface AbortResult {
  /** Whether the abort was successful */
  success: boolean;
  /** Why the abort did not land. EVERY `success: false` return carries one, so a
   * caller can separate a generation it must not settle (`generation_replaced`,
   * `job_not_found`) from one that is still live (`job_still_active`) and from one
   * that had already reached a terminal state (`already_settled` — the provider has
   * also drained when `awaitProviderDrain` was requested). The ABSENCE of this field
   * is not a stop confirmation; use `isStopConfirmed`. */
  failureReason?: 'generation_replaced' | 'job_still_active' | 'job_not_found' | 'already_settled';
  /** The generation was stopped, but the caller's required durable side
   * effects failed before normal FINAL publication. The manager emitted a
   * conservative reconciliation frame instead. */
  persistenceFailed?: boolean;
  /** The job data at time of abort */
  jobData: SerializableJobData | null;
  /** Aggregated content from the stream */
  content: Agents.MessageContentComplex[];
  /** Final event to send to client */
  finalEvent: unknown;
  /** Concatenated text from all content parts for token counting fallback */
  text: string;
  /** Collected usage metadata from all models for token spending */
  collectedUsage: UsageMetadata[];
  /** Steers drained at abort time (never injected); surfaced to the client for restore */
  pendingSteers?: TPendingSteer[];
}

/**
 * Canonical "did this generation actually stop?" predicate — one definition shared by
 * every caller that settles durable state on the answer (schedule outcomes, checkpoint
 * pruning, capacity release).
 *
 * A landed abort confirms the stop. So does `already_settled`: the generation reached a
 * terminal state on its own and, when the caller asked for `awaitProviderDrain`, its
 * provider segment has drained, so nothing can still write. Every OTHER failure leaves a
 * generation that is either still live (`job_still_active`), owned by someone else
 * (`generation_replaced`), or unobservable from here without a drain (`job_not_found`) —
 * none of which may be settled on.
 */
export function isStopConfirmed(result: AbortResult | null | undefined): boolean {
  return result != null && (result.success === true || result.failureReason === 'already_settled');
}

/**
 * Resume state for reconnecting clients
 */
export interface ResumeState {
  runSteps: Agents.RunStep[];
  aggregatedContent: Agents.MessageContentComplex[];
  userMessage?: SerializableJobData['userMessage'];
  responseMessageId?: string;
  conversationId?: string;
  sender?: string;
  iconURL?: string;
  model?: string;
  titleEvent?: {
    event: 'title';
    data?: {
      conversationId?: string;
      title?: string;
    };
  };
  replayEvents?: Array<{
    event: string;
    data?: unknown;
    [key: string]: unknown;
  }>;
  /** Pending MCP authorization prompts projected from durable stream state. */
  pendingOAuthPrompts?: Agents.PendingMCPOAuthPrompt[];
}

/**
 * Backward-compatible public job-store contract.
 *
 * This is the pre-v2 extension surface kept for third-party stores compiled
 * against earlier `@librechat/api` releases. The generation manager validates
 * the additional {@link IJobStoreV2} capabilities before accepting a custom
 * store at runtime.
 */
/** Captured stale provider identity. Recovery requires positive host termination proof. */
export interface ScheduleProviderOwner {
  streamId: string;
  createdAt: number;
  providerExecutionId: string;
  scheduleId: string;
  scheduledFor: string;
  userId: string;
  tenantId: string | null;
  lastActiveAt: number;
}

export interface ScheduleCleanupScope {
  scheduleId?: string;
  userId?: string;
}

export interface IJobStore {
  readonly detachedAgentEventActionStoreMode?: DetachedAgentEventActionStoreMode;
  /** Receipt evidence survives loss of the generation worker; absent is volatile. */
  readonly durableScheduleReceipts?: boolean;

  /** Synchronous exact-epoch notification after a retained stale transition.
   * Cancellation is not drain acknowledgement; provider owners still record drain. */
  setStaleGenerationHandler?(handler?: (streamId: string, createdAt: number) => void): void;

  initialize(): Promise<void>;

  createJob(
    streamId: string,
    userId: string,
    conversationId?: string,
    tenantId?: string,
    initialMetadata?: JobMetadataPatch,
  ): Promise<SerializableJobData>;

  getJob(streamId: string): Promise<SerializableJobData | null>;
  updateJob(
    streamId: string,
    updates: Partial<SerializableJobData>,
    expectedCreatedAt?: number,
  ): Promise<void>;
  transitionStatus(streamId: string, args: JobStatusTransition): Promise<boolean>;

  claimIdempotencyKey(
    key: string,
    value: IdempotencyClaimValue,
    ttlSeconds: number,
  ): Promise<IdempotencyClaimResult>;
  releaseIdempotencyKey(key: string): Promise<void>;

  /** Read-only existence probe used to identify a confirmed retry before
   * request-rate admission. Optional stores keep the conservative behavior
   * where every request remains subject to the limiter. */
  hasIdempotencyKey?(key: string): Promise<boolean>;

  /** Read-only claim receipt used by durable source reconcilers. Optional
   * stores fall back to inspecting the current generation only. */
  getIdempotencyClaim?(key: string): Promise<IdempotencyClaimValue | null>;

  deleteJob(streamId: string, expectedCreatedAt?: number): Promise<boolean>;
  hasJob(streamId: string): Promise<boolean>;
  getRunningJobs(): Promise<SerializableJobData[]>;
  /** Optional durable paused-job enumeration. Built-in stores implement it so
   * the manager can own approval expiry even after the original runtime died. */
  getRequiresActionJobs?(): Promise<SerializableJobData[]>;
  /** Optional durable enumeration of terminal jobs that still owe a host lifecycle
   * hook (see `terminalHostActionPending`). Built-in stores implement it so cleanup can
   * retry the host adapter after a restart / on another replica, even though the job is
   * no longer in the requires_action index. */
  getTerminalHostActionJobs?(): Promise<SerializableJobData[]>;
  /** Generation-scoped schedule settlement outbox, including already-bookkept runs. */
  getScheduleReconcileJobs?(limit: number): Promise<SerializableJobData[]>;
  /** Independent of active Mongo runs. Missing capability cannot certify cleanup. */
  hasScheduleCleanupObligation?(scope: ScheduleCleanupScope): Promise<boolean>;
  /** Used only after trusted host process-loss confirmation; status/epoch/segment/liveness CAS. */
  recoverScheduleProviderOwnerLoss?(owner: ScheduleProviderOwner): Promise<boolean>;
  /** Enumerates detached Event Actor completion generations from a versioned
   * retry lane known only to capable consumers. Redis keeps this lane separate
   * from `getTerminalHostActionJobs` so a rolling-deployment replica that only
   * understands the legacy job identity can never claim it. */
  getDetachedAgentEventTerminalHostActionJobs?(): Promise<SerializableJobData[]>;
  /** Clears the pending-host-action marker once the adapter acknowledges success.
   * Identity-fenced on `expectedCreatedAt` so a replacement generation at the same
   * streamId is never cleared through its predecessor. */
  clearTerminalHostAction?(streamId: string, expectedCreatedAt?: number): Promise<void>;
  cleanup(): Promise<number>;
  recordActivity?(streamId: string, expectedCreatedAt?: number): void;
  getJobCount(): Promise<number>;
  getJobCountByStatus(status: JobStatus): Promise<number>;
  destroy(): Promise<void>;
  getActiveJobIdsByUser(userId: string, tenantId?: string): Promise<string[]>;

  /** Complete owner cleanup query, including terminal host work and legacy-index recovery.
   * Managers retain the global-index fallback for older third-party stores. */
  getCleanupJobIdsByUser?(userId: string, tenantId?: string): Promise<string[]>;

  /** Enumerates every extant job in the owner's retained index, including a
   * stale paused generation that account deletion must erase before its worker
   * finalizes it. Optional custom stores fall back to cleanup-blocking jobs. */
  getRetainedJobIdsByUser?(userId: string, tenantId?: string): Promise<string[]>;
  setGraph(streamId: string, graph: StandardGraph, expectedCreatedAt?: number): void;
  setContentParts(
    streamId: string,
    contentParts: Agents.MessageContentComplex[],
    expectedCreatedAt?: number,
  ): void;
  getContentParts(
    streamId: string,
    expectedCreatedAt?: number,
    options?: { durableOnly?: boolean },
  ): Promise<{
    content: Agents.MessageContentComplex[];
    reconstructedEventCount?: number;
    durableEventCount?: number;
  } | null>;

  getRunSteps(streamId: string, expectedCreatedAt?: number): Promise<Agents.RunStep[]>;

  /** Legacy stores returned `void`; v2 stores return whether the epoch-fenced
   * append committed. Accept both here so existing implementations remain
   * source-compatible. */
  appendChunk(
    streamId: string,
    event: unknown,
    expectedCreatedAt?: number,
  ): Promise<void | boolean>;

  /** Optional batching capability: persist any coalesced appends buffered for
   * this stream now. Stores without append coalescing simply omit it. */
  flushPendingAppends?(streamId: string): Promise<void>;

  clearContentState(streamId: string, expectedCreatedAt?: number): void;
  saveRunSteps?(
    streamId: string,
    runSteps: Agents.RunStep[],
    expectedCreatedAt?: number,
  ): Promise<void>;
  setCollectedUsage(
    streamId: string,
    collectedUsage: UsageMetadata[],
    expectedCreatedAt?: number,
  ): void;
  getCollectedUsage(streamId: string, expectedCreatedAt?: number): UsageMetadata[];

  enqueueSteer(streamId: string, item: SteerQueueItem, expectedCreatedAt?: number): Promise<number>;
  drainSteers(streamId: string, expectedCreatedAt?: number): Promise<SteerQueueItem[]>;
  closeAndDrainSteers(streamId: string, expectedCreatedAt?: number): Promise<SteerQueueItem[]>;
  peekSteers(streamId: string, expectedCreatedAt?: number): Promise<SteerQueueItem[]>;
  removeSteer(streamId: string, steerId: string): Promise<boolean>;
  parkSteers(streamId: string, payload: string, expectedCreatedAt?: number): Promise<void>;
  claimParkedSteers(streamId: string, ownerFragment: string): Promise<string | undefined>;
  clearSteers(streamId: string): Promise<void>;
}

/**
 * Full store contract required by the current generation runtime.
 *
 * Built-in stores implement this interface. Its overrides deliberately narrow
 * the legacy return types while its extra methods provide the atomicity needed
 * for terminal ownership, durable steering receipts, recovery, and idempotent
 * generation startup.
 */
export interface IJobStoreV2 extends IJobStore {
  /** Initialize the store (e.g., connect to Redis, start cleanup intervals) */
  initialize(): Promise<void>;

  /** Create a new job */
  createJob(
    streamId: string,
    userId: string,
    conversationId?: string,
    tenantId?: string,
    initialMetadata?: JobMetadataPatch,
    recoveredSteerId?: string,
    idempotencyClaimKey?: string,
    idempotencyClaimToken?: string,
    idempotencyClientRequestId?: string,
    recoveredSteerPayload?: RecoveredSteerPayload,
    creationAttemptId?: string,
    expectedPredecessorCreatedAt?: number,
    rejectActivePredecessor?: boolean,
  ): Promise<CreatedJobData>;

  /** Remove transaction-time predecessor receipts after their handoff was
   * delivered. The current creation attempt id fences a late acknowledgement
   * from clearing receipts inherited by a replacement. */
  acknowledgeReplacedJobs?(
    streamId: string,
    creationAttemptId: string,
    replacedCreatedAts: readonly number[],
  ): Promise<boolean>;

  /** Get a job by streamId (streamId === conversationId) */
  getJob(streamId: string): Promise<SerializableJobData | null>;

  /**
   * Update job data. When `expectedCreatedAt` is supplied, apply the write only
   * if the stream still belongs to that generation.
   */
  updateJob(
    streamId: string,
    updates: Partial<SerializableJobData>,
    expectedCreatedAt?: number,
  ): Promise<void>;

  /** Atomically marks only the exact provider segment as fully unwound. */
  markProviderExecutionDrained(
    streamId: string,
    expectedCreatedAt: number,
    providerExecutionId: string,
  ): Promise<boolean>;

  /** Activates the provider only while its exact generation is still running. */
  beginProviderExecution(
    streamId: string,
    expectedCreatedAt: number,
    providerExecutionId: string,
  ): Promise<boolean>;

  /** Includes terminal jobs whose provider still owns user-data writes. */
  getCleanupBlockingJobIdsByUser(userId: string, tenantId?: string): Promise<string[]>;

  /** Atomically replaces an abort persistence-pending marker with the one
   * terminal payload that late subscribers may consume. Exactly one of the
   * owner, its failure path, or stale-owner recovery wins. */
  finalizeTerminalPersistence(
    streamId: string,
    expectedCreatedAt: number,
    finalEvent: string,
  ): Promise<boolean>;

  /**
   * Atomically transition a job's status, **only if** it is currently `from`.
   * Returns `true` when the transition fired, `false` when the job was missing
   * or no longer in `from` (lost a race / illegal transition).
   *
   * `patch` fields are written and `clear` fields removed in the same atomic
   * step, and the running / requires_action membership sets plus live-key TTLs
   * are reconciled to match `to`. This is the race-safe primitive behind the
   * approval lifecycle — it prevents two concurrent resumes from both driving a
   * paused run (a double-drive would re-execute tools / double-bill).
   *
   * Distinct from {@link updateJob}, which writes status unconditionally for
   * callers that don't know the prior state. Reach for `transitionStatus`
   * whenever the legal prior state is known.
   *
   * Atomicity: fully atomic on in-memory and single-node / sentinel Redis
   * (Lua). On Redis Cluster the status guard is best-effort — the membership
   * sets live on a different hash slot from the job hash — matching the store's
   * existing cluster posture for status writes.
   */
  transitionStatus(streamId: string, args: JobStatusTransition): Promise<boolean>;

  /**
   * Terminal variant of {@link transitionStatus} that atomically captures and
   * parks every queued/claimed steer owned by the winning generation. `null`
   * means the status CAS lost; an array (including an empty one) means it won.
   *
   * Abort uses this primitive so it can include exact leftovers in its final
   * event without destructively draining a run before terminal ownership is
   * established.
   */
  transitionStatusAndDrainSteers(
    streamId: string,
    args: JobStatusTransition,
  ): Promise<SteerQueueItem[] | null>;

  /**
   * Atomically claim an idempotency key so a retried start-generation request
   * attaches to the original stream instead of starting a second billed
   * generation. The first caller gets `{ claimed: true }` and should create the
   * job; a later caller for the same key gets `{ claimed: false, existing }`
   * carrying the stream the original request is already driving.
   *
   * Atomicity: single-key `SET NX` on Redis (one hash slot, cluster-safe) /
   * check-and-set on the single-threaded in-memory store.
   *
   * @param key - Caller-scoped key, e.g. `${userId}:${clientRequestId}`.
   * @param value - The stream a duplicate request should attach to.
   * @param ttlSeconds - Claim lifetime; outlive the generation so a late retry still dedups.
   */
  claimIdempotencyKey(
    key: string,
    value: IdempotencyClaimValue,
    ttlSeconds: number,
  ): Promise<IdempotencyClaimResult>;

  /** Compare-and-swap an abandoned pre-create claim. */
  takeoverIdempotencyKey(
    key: string,
    expected: IdempotencyClaimValue,
    value: IdempotencyClaimValue,
    ttlSeconds: number,
  ): Promise<boolean>;

  /** Mark a token-owned claim as having created its generation. Used by the
   * rolling-upgrade bridge to tombstone the legacy key after the same-slot
   * primary key was committed by createJob. */
  markIdempotencyKeyStarted(
    key: string,
    claimToken: string,
    startedAt: number,
    ttlSeconds: number,
  ): Promise<boolean>;

  /** Atomically attach a freshly reacquired claim to the still-live job that
   * was created by the same client request. The job and claim keys share a
   * Redis hash slot, so a replacement cannot cross this validation. */
  adoptIdempotencyKeyForJob(
    key: string,
    expected: IdempotencyClaimValue,
    streamId: string,
    userId: string,
    clientRequestId: string,
    tenantId: string | undefined,
    expectedCreatedAt: number,
    ttlSeconds: number,
    /** A pre-bridge job has no durable request id. This mode may tombstone a
     * freshly reacquired claim against that exact active owner/epoch, but must
     * still reject every different non-empty request id. */
    allowMissingClientRequestId?: boolean,
  ): Promise<boolean>;

  /**
   * Release a previously-claimed idempotency key so the submission can be retried
   * (e.g. the start failed before generation began). No-op if the key is absent.
   */
  releaseIdempotencyKey(key: string, expected?: IdempotencyClaimValue): Promise<void>;

  /**
   * Delete a job, optionally only when the stream still belongs to the expected
   * generation. Returns true only when a matching job was actually deleted.
   */
  deleteJob(streamId: string, expectedCreatedAt?: number): Promise<boolean>;

  /** Check if job exists */
  hasJob(streamId: string): Promise<boolean>;

  /** Get all running jobs (for cleanup) */
  getRunningJobs(): Promise<SerializableJobData[]>;

  /** Get durable paused jobs so approval expiry is not process-runtime-dependent. */
  getRequiresActionJobs?(): Promise<SerializableJobData[]>;

  /** Cleanup expired jobs */
  cleanup(): Promise<number>;

  /**
   * Record generation activity for a job (e.g. a chunk was emitted), refreshing
   * its "last active" timestamp so the stale-running-job failsafe does not reap a
   * stream that is still producing output.
   *
   * In-memory: updates an internal last-activity timestamp used by cleanup().
   * Redis: no-op — the running-job TTL is already refreshed on each appendChunk.
   *
   * @param streamId - The stream identifier
   * @param expectedCreatedAt - Optional generation identity. When supplied, replacement activity
   *   is not refreshed by a stale emitter.
   */
  recordActivity?(streamId: string, expectedCreatedAt?: number): void;

  /**
   * Persist any coalesced chunk appends still buffered for this stream.
   * Terminal transitions must flush first so the batch lands under the
   * generation's live status instead of fencing against its own completion.
   *
   * Presence of this method is how a store advertises append-coalescing
   * support; see the transport's flushPendingChunks for the pairing rule.
   */
  flushPendingAppends?(streamId: string): Promise<void>;

  /** Get total job count */
  getJobCount(): Promise<number>;

  /** Get job count by status */
  getJobCountByStatus(status: JobStatus): Promise<number>;

  /** Destroy the store and release resources */
  destroy(): Promise<void>;

  /**
   * Get active job IDs for a user.
   * Returns conversation IDs of running jobs belonging to the user.
   * Also performs self-healing cleanup of stale entries.
   *
   * @param userId - The user ID to query
   * @returns Array of conversation IDs with active jobs
   */
  getActiveJobIdsByUser(userId: string, tenantId?: string): Promise<string[]>;

  // ===== Content State Methods =====
  // These methods manage volatile content state tied to each job.
  // In-memory: Uses WeakRef to graph for live access
  // Redis: Persists chunks and reconstructs on demand

  /**
   * Set the graph reference for a job (in-memory only).
   * The graph provides live access to contentParts and contentData (run steps).
   *
   * In-memory: Stores WeakRef to graph
   * Redis: No-op (graph not transferable, uses chunks instead)
   *
   * @param streamId - The stream identifier
   * @param graph - The StandardGraph instance
   */
  setGraph(streamId: string, graph: StandardGraph, expectedCreatedAt?: number): void;

  /**
   * Set content parts reference for a job.
   *
   * In-memory: Stores direct reference to content array
   * Redis: No-op (content built from chunks)
   *
   * @param streamId - The stream identifier
   * @param contentParts - The content parts array
   */
  setContentParts(
    streamId: string,
    contentParts: Agents.MessageContentComplex[],
    expectedCreatedAt?: number,
  ): void;

  /**
   * Get aggregated content for a job.
   *
   * In-memory: Returns live content from graph.contentParts or stored reference
   * Redis: Reconstructs from stored chunks
   *
   * @param streamId - The stream identifier
   * @returns Content parts or null if not available
   */
  getContentParts(
    streamId: string,
    expectedCreatedAt?: number,
    options?: { durableOnly?: boolean },
  ): Promise<{
    content: Agents.MessageContentComplex[];
    reconstructedEventCount?: number;
    durableEventCount?: number;
  } | null>;

  /** Atomically records the only recovery outcome for one overflow identity. */
  settleEarlyBufferRecovery(
    streamId: string,
    expectedCreatedAt: number,
    overflowId: string,
    settlement: Pick<
      EarlyBufferOverflowState,
      'recoveryMethod' | 'recoveryOutcome' | 'recoveryCompletedAt' | 'recoveryFailureReason'
    >,
  ): Promise<boolean>;

  /** Atomically replaces an unresolved pending overflow marker with its
   * finalized durable frontier. A concurrent recovery settlement wins over
   * this owner-side finalization. */
  finalizeEarlyBufferOverflow(
    streamId: string,
    expectedCreatedAt: number,
    overflowId: string,
    overflow: EarlyBufferOverflowState,
  ): Promise<boolean>;

  /** Whether this generation has admitted any subscriber on any replica. */
  hasSubscriberAttached(streamId: string, expectedCreatedAt: number): Promise<boolean>;

  /** Atomically claims the first subscriber for one generation epoch. */
  claimFirstSubscriber(
    streamId: string,
    expectedCreatedAt: number,
    attachedAt: number,
    subscriberId: string,
    leaseExpiresAt: number,
  ): Promise<boolean>;

  detachSubscriber(
    streamId: string,
    expectedCreatedAt: number,
    subscriberId: string,
  ): Promise<void>;

  hasActiveSubscriber(
    streamId: string,
    expectedCreatedAt: number,
    observedAt: number,
  ): Promise<boolean>;

  /**
   * Get run steps for a job (for resume state).
   *
   * In-memory: Returns live run steps from graph.contentData
   * Redis: Fetches from persistent storage
   *
   * @param streamId - The stream identifier
   * @returns Run steps or empty array
   */
  getRunSteps(streamId: string, expectedCreatedAt?: number): Promise<Agents.RunStep[]>;

  /**
   * Append a streaming chunk for later reconstruction.
   *
   * In-memory: No-op (content available via graph reference)
   * Redis: Uses XADD for append-only log efficiency
   *
   * @param streamId - The stream identifier
   * @param event - The SSE event to append
   * @param expectedCreatedAt - Optional generation identity. When supplied, the append is
   *   refused if the stream ID now belongs to a replacement generation.
   */
  appendChunk(
    streamId: string,
    event: unknown,
    expectedCreatedAt?: number,
    /** When present, the same durable write records this drained steer as
     * delivered. Redis performs both mutations in one same-slot Lua step. */
    deliveredSteer?: SteerQueueItem,
    /** Hot-path hint: `coalesce` marks a plain streaming delta whose durable
     * append may batch with its window peers. Stores without batching (and any
     * append carrying a steer receipt) ignore it and stay per-event. */
    options?: { coalesce?: boolean },
  ): Promise<boolean>;

  /**
   * Clear all content state for a job.
   * Called on job completion/cleanup.
   *
   * @param streamId - The stream identifier
   * @param expectedCreatedAt - Optional generation identity. When supplied, replacement content
   *   is not cleared by a stale terminal cleanup.
   */
  clearContentState(streamId: string, expectedCreatedAt?: number): void;

  /**
   * Save run steps to persistent storage.
   * In-memory: No-op (run steps accessed via graph reference)
   * Redis: Persists for resume across instances
   *
   * @param streamId - The stream identifier
   * @param runSteps - Run steps to save
   * @param expectedCreatedAt - Optional generation identity. When supplied, the save is refused
   *   if the stream ID now belongs to a replacement generation.
   */
  saveRunSteps?(
    streamId: string,
    runSteps: Agents.RunStep[],
    expectedCreatedAt?: number,
  ): Promise<void>;

  /**
   * Set collected usage reference for a job.
   * This array accumulates token usage from all models during generation.
   *
   * @param streamId - The stream identifier
   * @param collectedUsage - Array of usage metadata from all models
   */
  setCollectedUsage(
    streamId: string,
    collectedUsage: UsageMetadata[],
    expectedCreatedAt?: number,
  ): void;

  /**
   * Get collected usage for a job.
   *
   * @param streamId - The stream identifier
   * @returns Array of usage metadata or empty array
   */
  getCollectedUsage(streamId: string, expectedCreatedAt?: number): UsageMetadata[];

  // ===== Steering Queue Methods =====
  // FIFO queue of mid-run user messages, keyed by streamId. Writable from any
  // instance (the steer route), drained only by the run's owning process.

  /**
   * Atomically append a steer, guarded on the job being `running` AND the
   * queue not being closed by a terminal drain. Returns the new queue depth,
   * {@link STEER_ENQUEUE_NOT_RUNNING} when the job is missing, not running,
   * or closed, or {@link STEER_ENQUEUE_QUEUE_FULL} at max depth.
   */
  enqueueSteer(streamId: string, item: SteerQueueItem, expectedCreatedAt?: number): Promise<number>;

  /** Atomic capability-normalized enqueue. Unlike enqueue→arm, no fallible
   * mutation occurs after the item becomes durable and before its ACK. */
  enqueueSteerVersioned(
    streamId: string,
    item: SteerQueueItem,
    wantsPreempt: boolean,
    expectedCreatedAt?: number,
  ): Promise<SteerEnqueueVersionedResult>;

  /** Atomic receipt lookup + capability-normalized enqueue. An existing
   * receipt wins even if the live queue is now full, paused, drained, or the
   * generation has ended/replaced. Numeric results are enqueue rejection
   * codes (including {@link STEER_ENQUEUE_RECEIPT_FULL}); a receipt reports
   * either the existing or newly inserted item. */
  enqueueSteerWithReceipt(
    streamId: string,
    item: SteerQueueItem,
    receipt: SteerReceiptInput,
    wantsPreempt: boolean,
    expectedCreatedAt?: number,
  ): Promise<SteerEnqueueReceiptResult>;

  /** Read a bounded receipt without requiring the live job/queue. */
  getSteerReceipt(streamId: string, clientSteerId: string): Promise<SteerReceipt | null>;

  /**
   * Atomically take ALL queued steers, FIFO. Empty array when none. With
   * `expectedCreatedAt`, the drain is refused (atomically, inside the store)
   * when the live job's `createdAt` differs — a stale run's drain must never
   * consume a replacement job's queue.
   */
  drainSteers(streamId: string, expectedCreatedAt?: number): Promise<SteerQueueItem[]>;

  /** Put a failed claimed batch back at the FIFO front, preserving its order
   * and receipt state. This is the rollback for a durable applied-part write
   * that failed after the atomic drain. */
  restoreClaimedSteers(
    streamId: string,
    items: SteerQueueItem[],
    expectedCreatedAt?: number,
  ): Promise<boolean>;

  /**
   * Terminal admission fence. When `allowClaim` and queued work are both
   * present, atomically claim the FIFO batch while leaving admission open for
   * the continued run. Otherwise atomically close admission so a racing steer
   * is rejected and remains an ordinary follow-up, unless
   * `keepOpenWhenEmpty` proves another folded Stop hook already planned a
   * continuation. V1 generations always seal because they lack
   * crash-recoverable claimed-steer receipts.
   */
  admitTerminalSteers(
    streamId: string,
    policy: TerminalSteerAdmissionPolicy,
    expectedCreatedAt?: number,
  ): Promise<TerminalSteerAdmissionResult>;

  /**
   * Atomically CLOSE the queue to new steers, then take all queued items
   * FIFO. Used by the terminal paths (final event, abort) so a steer POST
   * racing finalization can never be 202-ACKed after the last drain and then
   * silently cleared — once closed, `enqueueSteer` rejects until the next
   * `createJob` reopens the stream id. `expectedCreatedAt` guards exactly
   * like {@link drainSteers}: a stale run's finalization can neither close
   * nor steal a replacement job's queue.
   */
  closeAndDrainSteers(streamId: string, expectedCreatedAt?: number): Promise<SteerQueueItem[]>;

  /**
   * Non-destructive FIFO read of the queued steers (status/resume surfaces).
   * With `expectedCreatedAt`, returns an empty snapshot if the stream belongs
   * to another generation.
   */
  peekSteers(streamId: string, expectedCreatedAt?: number): Promise<SteerQueueItem[]>;

  /** Drained but not yet durably applied items. Kept separate from the live
   * FIFO so a reconnect can render them without a second owner injecting them. */
  peekClaimedSteers(streamId: string, expectedCreatedAt?: number): Promise<SteerQueueItem[]>;

  /** Remove ONE queued steer by id (user-cancelled before injection).
   *  False when it was no longer queued — already drained or run ended — or
   *  when `expectedCreatedAt` belongs to a replaced generation. */
  removeSteer(streamId: string, steerId: string, expectedCreatedAt?: number): Promise<boolean>;

  /**
   * Atomically set `preempt: true` on ONE queued steer IN PLACE, preserving
   * its FIFO position (the user escalated a waiting steer to an interrupt;
   * the whole queue drains at the seal, so its order must not change).
   * Guarded like {@link enqueueSteer}: `missing` when the job is not running,
   * the steer is no longer queued, the queue is closed, or (with
   * `expectedCreatedAt`) the stream belongs to another generation. The owner's
   * LIVE `preemptCapable` is part of the same atomic predicate — a HITL resume
   * on a rolling deploy can rewrite it for the SAME generation, so a value
   * read before the call is not trustworthy — and an incapable owner answers
   * `incapable` with the item left unflagged.
   */
  armSteer(streamId: string, steerId: string, expectedCreatedAt?: number): Promise<SteerArmOutcome>;

  /** Versioned form used by the HTTP arm route so its publication carries
   * the revision atomically assigned with the durable flag. */
  armSteerVersioned(
    streamId: string,
    steerId: string,
    expectedCreatedAt?: number,
  ): Promise<SteerArmResult>;

  /** Atomically remove `preempt` from every queued steer only when the
   * generation's current owner is incapable. Returns the changed steer ids
   * (used to tombstone late arm publications), or `null` when the generation
   * is missing/replaced or currently capable. */
  downgradeSteerPreempts(
    streamId: string,
    expectedCreatedAt?: number,
  ): Promise<SteerQueueItem[] | null>;

  /**
   * Persist terminally-drained steers under their OWN bounded-TTL key so a
   * client with no live subscriber can recover them via the status route.
   * Deliberately independent of the job record — the default `completeJob`
   * path deletes the job immediately, and recovery must survive that.
   * Merges with any prior payload. `createJob` leases the selected recovery
   * item while that generation is active; the item is removed only after its
   * ordinary user message is durably persisted.
   * When `expectedCreatedAt` is supplied, the write is conditional on that
   * generation still owning the stream ID.
   */
  parkSteers(streamId: string, payload: string, expectedCreatedAt?: number): Promise<void>;

  /** Owner-gated recovery read. A source leased to a matching active recovery
   * generation is hidden but retained; it becomes visible again if startup
   * fails, and is removed only after durable user-message persistence. */
  claimParkedSteers(
    streamId: string,
    ownerUserId: string,
    ownerTenantId?: string,
  ): Promise<string | undefined>;

  /** Protocol-aware form of {@link claimParkedSteers}. Existing callers may
   * keep using the payload-only method. */
  claimParkedSteersDetailed(
    streamId: string,
    ownerUserId: string,
    ownerTenantId?: string,
    requestedProtocolVersion?: GenerationProtocolVersion,
  ): Promise<ParkedSteerClaim | undefined>;

  /** Commit a recovery handoff after its ordinary user message is durable.
   * Guarded by generation identity and owner, and idempotent for retries. */
  consumeParkedSteer(
    streamId: string,
    steerId: string,
    ownerUserId: string,
    ownerTenantId: string | undefined,
    expectedCreatedAt: number,
  ): Promise<boolean>;

  /** Owner-gated terminal reclaim. Atomically removes one leftover from the
   * parked payload and marks its receipt cancelled, making edit/queue/dismiss
   * retries idempotent without reviving an already-started recovery. */
  discardSteerLeftover(
    streamId: string,
    clientSteerId: string,
    steerId: string,
    ownerUserId: string,
    ownerTenantId?: string,
    expectedGenerationCreatedAt?: number,
  ): Promise<boolean>;

  /** Drop any queued steers (terminal cleanup backstop). */
  clearSteers(streamId: string): Promise<void>;
}

export type GenerationTerminalEventType = 'done' | 'error';

/** A terminal publication lost the generation fence to a replacement. This is
 * an expected safety outcome: the successor owns all further stream output. */
export class GenerationPublicationFencedError extends Error {
  readonly code = 'GENERATION_PUBLICATION_FENCED';

  constructor(
    readonly eventType: GenerationTerminalEventType,
    readonly streamId: string,
    readonly generationId?: number,
  ) {
    super(
      eventType === 'done'
        ? 'Generation DONE publication was fenced by a replacement'
        : 'Generation error publication was fenced by a replacement',
    );
    this.name = 'GenerationPublicationFencedError';
  }
}

/**
 * Interface for pub/sub event transport.
 * Implementations can use EventEmitter, Redis Pub/Sub, etc.
 */
export interface IEventTransport {
  /**
   * Subscribe to events for a stream. `ready` resolves once the transport can receive messages.
   *
   * Redis callers can defer sequenced delivery until `syncReorderBuffer()` establishes the
   * replay frontier. This prevents pub/sub copies of locally buffered events from racing ahead
   * of, and then being duplicated by, first-subscriber replay.
   */
  subscribe(
    streamId: string,
    handlers: {
      /** `generationId` identifies the immutable generation that emitted the chunk. */
      onChunk: (event: unknown, generationId?: number) => void;
      /** One ordered snapshot before live delivery, only for replay subscriptions. */
      onReplay?: (events: unknown[]) => void;
      /** `generationId` identifies the immutable generation that emitted the done event. */
      onDone?: (event: unknown, generationId?: number) => void;
      /** `generationId` identifies the immutable generation that emitted the error. */
      onError?: (error: string, generationId?: number) => void;
    },
    options?: {
      /** Hold sequenced events until syncReorderBuffer establishes the replay frontier. */
      deferSequenceDelivery?: boolean;
      /** Per-viewer bounded replay; does not rewind other subscribers. */
      replay?: ReplayLimits;
      /** After opening a fresh Pub/Sub channel, atomically capture its sequence frontier
       * and fence delivery so synchronization cannot lose an attachment-time frame. */
      captureSequenceFrontier?: boolean;
    },
  ): {
    unsubscribe: () => void;
    ready?: Promise<void>;
    /** Synchronize only the transport state captured by this concrete subscription. */
    syncReorderBuffer?: () => void | Promise<void>;
  };

  /**
   * Publish a chunk event.
   * Redis returns the assigned absolute sequence so locally replayed events can
   * advance a subscriber to the exact ordering frontier.
   */
  emitChunk(streamId: string, event: unknown, generationId?: number): void | Promise<void | number>;

  /** Retain an observational chunk even with no viewers, then publish it atomically. */
  emitReplayableChunk?(
    streamId: string,
    event: unknown,
    limits: ReplayLimits,
    publication?: ReplayPublication,
  ): Promise<void>;
  emitReplayableDone?(
    streamId: string,
    event: unknown,
    limits: ReplayLimits,
    publication?: ReplayPublication,
  ): Promise<void>;

  /**
   * Publish a done event - returns Promise in Redis mode for ordered delivery.
   * `generationId` is optional for compatibility with legacy, untagged publishers.
   */
  emitDone(streamId: string, event: unknown, generationId?: number): void | Promise<void>;

  /**
   * Publish an error event - returns Promise in Redis mode for ordered delivery.
   * `generationId` is optional for compatibility with legacy, untagged publishers.
   */
  emitError(streamId: string, error: string, generationId?: number): void | Promise<void>;

  /** Optional live-view demand marker used by observational streams that do not replay. */
  renewDemand?(streamId: string, ttlMs: number): void | Promise<void>;

  /** Returns whether at least one live viewer recently renewed demand for this stream. */
  hasDemand?(streamId: string): boolean | Promise<boolean>;

  /**
   * Publish an abort signal to all replicas (Redis mode).
   * Enables cross-replica abort: user aborts on Replica B,
   * generating Replica A receives signal and stops.
   * Optional - only implemented in Redis transport.
   */
  emitAbort?(streamId: string, generationId?: number): void;

  /** Awaitable, generation-correlated abort handoff. Resolves true only after
   * the replica owning that generation processes the abort. */
  emitAbortConfirmed?(streamId: string, generationId: number): Promise<boolean>;

  /** Persist proof that this process synchronously stopped the exact generation.
   * A delayed replacement can use the proof after the owner's listeners retire. */
  recordAbortAcknowledgement?(streamId: string, generationId: number): Promise<boolean>;

  /** Persist/read exact proof that a provider segment can no longer mutate user data. */
  recordProviderDrain?(
    streamId: string,
    generationId: number,
    providerExecutionId: string,
  ): Promise<boolean>;
  hasProviderDrain?(
    streamId: string,
    generationId: number,
    providerExecutionId: string,
  ): Promise<boolean>;

  /** Publish a predecessor DONE only while the current job's opaque creation
   * attempt still carries that predecessor in its durable receipt chain. */
  emitReplacedDoneConfirmed?(
    streamId: string,
    event: unknown,
    replacedGenerationId: number,
    creationAttemptId: string,
  ): Promise<void>;

  /**
   * Register callback for abort signals from any replica (Redis mode).
   * Called when abort is triggered from any replica.
   * An async implementation resolves only after it can receive abort messages.
   * The returned function removes only this registration, allowing a terminal
   * generation to release its channel without affecting a same-stream replacement.
   * Optional - only implemented in Redis transport.
   */
  onAbort?(
    streamId: string,
    /** Return true only when this replica owns and stopped the tagged generation. */
    callback: (generationId?: number) => void | boolean,
  ): void | (() => void) | Promise<void | (() => void)>;

  /**
   * Publish a preempt arm/clear to all replicas (Redis mode). Unlike abort
   * this does NOT stop the run — it asks the generating replica to seal its
   * current model stream at the next provider-safe boundary. Fenced by
   * {@link PreemptMessage.createdAt} against replacement jobs.
   * Optional - only implemented in Redis transport.
   */
  emitPreempt?(streamId: string, msg: PreemptMessage): void | Promise<number>;

  /**
   * Register callback for preempt signals from any replica (Redis mode).
   * An async implementation resolves only after it can receive messages.
   * The returned function removes only this registration, allowing a terminal
   * generation to release its channel without affecting a same-stream replacement.
   * Optional - only implemented in Redis transport.
   */
  onPreempt?(
    streamId: string,
    callback: (msg: PreemptMessage) => void,
  ): void | (() => void) | Promise<void | (() => void)>;

  /** Get subscriber count for a stream */
  getSubscriberCount(streamId: string): number;

  /** Check if this is the first subscriber (for ready signaling) */
  isFirstSubscriber(streamId: string): boolean;

  /** Listen for all subscribers leaving */
  onAllSubscribersLeft(streamId: string, callback: () => void): void;

  /**
   * Advance subscriber reorder buffer to match publisher sequence (cross-replica safe).
   * @param replayedNextSeq - Absolute Redis sequence immediately after the last event replayed
   *   from the local early-event buffer. Pending entries below it are duplicates; entries at
   *   or above it are live. Undefined means no local replay, so the Redis counter is trusted.
   */
  syncReorderBuffer?(streamId: string, replayedNextSeq?: number): void | Promise<void>;

  /**
   * Notify and detach subscribers attached to this process without broadcasting a terminal event.
   * Must trigger all-subscribers-left cleanup so graceful shutdown can drain partial persistence.
   */
  closeLocalSubscribers?(streamId: string, error: string): void;

  /**
   * Publish any coalesced chunk publications still buffered for this stream.
   * Callers about to transition a generation's status must flush first, or the
   * batch would land behind the transition and fence itself.
   *
   * Presence of this method is how a transport advertises delta-coalescing
   * support: the generation manager only sends `coalesce` hints (and only
   * stops awaiting per-delta receipts) when both the transport and the job
   * store expose their flush capability.
   */
  flushPendingChunks?(streamId: string): Promise<void>;

  /** Cleanup transport resources for a specific stream */
  cleanup(streamId: string): void;

  /** Get all tracked stream IDs (for orphan cleanup) */
  getTrackedStreamIds(): string[];

  /** Destroy all transport resources */
  destroy(): void;
}