@makaio/framework 1.0.0-dev-1781022866275 → 1.0.0-dev-1781023871421

package/dist/base-orchestrator-wyumsn3b.d.mts

@@ -0,0 +1,772 @@
+import { SubjectDefinition } from "@makaio/framework/core";
+import { SessionLineageKind, SessionMessageBlock, SessionMetadata } from "@makaio/framework/contracts";
+import { JsonObject } from "type-fest";
+
+//#region adapters/core/src/log-importer/types.d.ts
+/**
+ * Normalized event produced by log importers.
+ *
+ * Represents a single event extracted from an external tool's log file,
+ * normalized to Makaio's subject/payload format for emission to the bus.
+ * @remarks
+ * Events may include optional {@link ImportMetadata} to distinguish
+ * imported events from live events and preserve original timestamps.
+ * @see {@link LogImporter} - Interface that produces these events
+ * @see {@link ImportMetadata} - Provenance metadata for imported events
+ */
+interface NormalizedEvent {
+  /** The Makaio subject definition for this event */
+  subject: SubjectDefinition;
+  /** Event payload matching the subject's schema, may include _import metadata */
+  payload: Record<string, unknown>;
+}
+/**
+ * Base interface for adapter name identifiers used in log import provenance.
+ *
+ * Extended via declaration merging by adapters and extensions to register
+ * new adapter names for log import provenance.
+ * @remarks
+ * Adapters and extensions extend this interface to add their adapter names:
+ * ```typescript
+ * declare module '@makaio/framework/adapters' {
+ *   interface ExternalToolIdentifiers {
+ *     'claude-code-cli': ExternalToolMeta;
+ *     'my-custom-adapter': ExternalToolMeta;
+ *   }
+ * }
+ * ```
+ * @see {@link ExternalToolMeta} - Metadata interface for adapter identifiers
+ * @see {@link ExternalToolIdentifier} - Type alias for registered adapter names
+ */
+interface ExternalToolIdentifiers {}
+/**
+ * Metadata interface for external tool identifiers.
+ *
+ * Currently empty - provides a seam for future metadata like display names,
+ * log format descriptions, or file patterns.
+ * @remarks
+ * Future extension might include:
+ * - `displayName?: string` - Human-readable tool name
+ * - `format?: 'jsonl' | 'json' | 'text'` - Expected log format
+ * - `filePattern?: string` - Glob pattern for log files
+ */
+interface ExternalToolMeta {}
+/**
+ * Known adapter names used for log import provenance.
+ *
+ * Used in {@link ImportMetadata.tool} to identify the source adapter.
+ * Extensible via declaration merging of {@link ExternalToolIdentifiers}.
+ * Falls back to `string` when no augmentations are in scope, so the core
+ * package is usable standalone while still providing autocomplete for
+ * known keys when augmentations are present.
+ */
+type ExternalToolIdentifier = keyof ExternalToolIdentifiers | (string & {});
+/**
+ * Provenance metadata for imported events.
+ *
+ * Added to event payloads under `_import` key to distinguish
+ * imported events from live events and preserve original context.
+ * @remarks
+ * This metadata enables:
+ * - Filtering imported vs live events in queries
+ * - Accurate timeline reconstruction with original timestamps
+ * - Debugging import issues by tracing back to source files
+ * @see {@link NormalizedEvent} - Events containing this metadata
+ */
+interface ImportMetadata {
+  /** Always 'external' to indicate imported (not live) event */
+  source: 'external';
+  /** Adapter name that produced the original log (e.g., 'claude-code-cli') */
+  tool: ExternalToolIdentifier;
+  /** Original timestamp from the external tool's log record (ISO 8601) */
+  originalTimestamp?: string;
+  /** Always false for imported events (they are replayed, not streamed) */
+  streaming: false;
+}
+/**
+ * Cursor position for tracking import progress within a file.
+ *
+ * Used to resume import from the last successfully processed position
+ * after restarts, avoiding duplicate event emission.
+ * @remarks
+ * Cursors track byte offsets rather than line numbers for efficiency
+ * and to handle partial lines correctly. The lastModified timestamp
+ * enables detection of file truncation/rotation.
+ * @see {@link LogImporter} - Uses cursors for incremental import
+ */
+interface ImportCursorPosition {
+  /** Absolute path to the log file being tracked */
+  filePath: string;
+  /** Number of bytes successfully read and processed */
+  bytesRead: number;
+  /** ISO 8601 timestamp of file's last modification when cursor was saved */
+  lastModified: string;
+  /**
+   * Session context for incremental imports (persisted on first read).
+   * Contains adapter-specific state needed to resume processing mid-session.
+   */
+  sessionContext?: SessionMetadata & {
+    /** Adapter's native session identifier */adapterSessionId: string; /** Session discovered event (emitted once at session start) */
+    sessionEvent: NormalizedEvent; /** Agent started event (emitted once at session start) */
+    startedEvent: NormalizedEvent; /** Serialized adapter-specific state for resumption */
+    state: JsonObject;
+  };
+}
+/**
+ * Session context for incremental log imports.
+ *
+ * Contains adapter-specific state that must persist across chunks during
+ * incremental import. Created on first read and restored from cursor on
+ * subsequent reads.
+ * @typeParam TState - Adapter-specific resumable state type
+ * @see {@link LogImporter.extractSessionContext} - Creates this context
+ * @see {@link LogImporter.processRecords} - Uses this context
+ */
+interface LogImportSessionContext<TState = unknown> extends SessionMetadata {
+  /** Adapter's native session identifier */
+  adapterSessionId: string;
+  /**
+   * Session discovered event (adapter creates with adapter-specific payload).
+   * Emitted once when the session is first discovered.
+   */
+  sessionEvent: NormalizedEvent;
+  /**
+   * Agent started event (adapter creates with model, cwd, etc.).
+   * Emitted once when the session starts processing.
+   */
+  startedEvent: NormalizedEvent;
+  /** Resumable import state - adapter-specific */
+  state: TState;
+}
+/**
+ * Message payload ready for persistence via MessageStorageSubjects.
+ *
+ * Adapters return this from {@link ProcessLogFileResult.messagePayloads}.
+ * Uses {@link SessionMessageBlock} as the canonical block type.
+ */
+interface StorageMessagePayload {
+  /** Adapter's native message ID — used for upsert deduplication */
+  adapterMessageId: string;
+  /** Message role */
+  role: 'user' | 'assistant';
+  /** Plain text for FTS indexing */
+  contentText: string;
+  /** Structured content blocks */
+  blocks: SessionMessageBlock[];
+  /** Agent ID (defaults to 'main' for non-subagent messages) */
+  agentId: string;
+  /** Adapter's session ID */
+  adapterSessionId: string;
+  /** Unix ms timestamp */
+  timestamp: number;
+  /** Input modality or origin. `'compact'` = injected summary after a compaction boundary. */
+  origin?: 'voice' | 'text' | 'compact';
+}
+/**
+ * Canonical lineage metadata for an import segment.
+ *
+ * Every imported session segment carries explicit lineage — there is no
+ * "unknown" state.  Root sessions use `kind: 'root'` with a null parent.
+ */
+interface ImportSegmentLineage {
+  /** Relationship of this segment to its parent. */
+  kind: SessionLineageKind;
+  /** Adapter session ID of the parent segment, null for root sessions. */
+  parentAdapterSessionId: string | null;
+  /** Message ID where this session diverged from parent (null for root, subagent, and compress). */
+  forkPointMessageId: string | null;
+}
+/**
+ * Compaction boundary metadata from the external tool's log.
+ */
+interface CompactionMetadata {
+  /** How compaction was triggered. */
+  trigger: 'manual' | 'auto';
+  /** Token count before compaction (null if unavailable). */
+  preTokens: number | null;
+  /** Unix ms timestamp of the compaction event (null if unavailable). */
+  timestamp: number | null;
+}
+/**
+ * Canonical import segment — the structural tree of imported session data.
+ *
+ * This is the single source of truth for compaction structure and lineage
+ * during import.  The importer is the canonical owner of this contract.
+ * @remarks
+ * - Every segment carries explicit {@link ImportSegmentLineage}
+ * - Children represent compaction boundaries or nested segments
+ * - Use {@link toImportSegment} to convert a {@link ProcessLogFileResult}
+ */
+interface ImportSegment {
+  /** Adapter's native session identifier for this segment. */
+  adapterSessionId: string;
+  /** Explicit lineage metadata — always present, never inferred post-import. */
+  lineage: ImportSegmentLineage;
+  /** Storage-ready message payloads for this segment. */
+  messages: StorageMessagePayload[];
+  /** Compaction metadata from the boundary record (absent if not a compress child). */
+  compaction?: CompactionMetadata;
+  /** Child segments (compress children, nested compactions). */
+  children?: ImportSegment[];
+}
+/**
+ * Result of processing a complete log file.
+ *
+ * The full import pipeline result. For the structural tree without event data,
+ * see {@link ImportSegment} and {@link toImportSegment}.
+ * @see {@link LogImporter.processLogFile}
+ */
+interface ProcessLogFileResult {
+  /** Adapter session ID extracted from the log */
+  adapterSessionId: string;
+  /** Session discovered event (adapter.session.discovered) */
+  sessionEvent: NormalizedEvent;
+  /** All normalized message events including agent.started */
+  messageEvents: NormalizedEvent[];
+  /** Storage-ready message payloads extracted from records */
+  messagePayloads: StorageMessagePayload[];
+  /** Explicit lineage metadata — always present, never inferred post-import. */
+  lineage: ImportSegmentLineage;
+  /** Compress child results — one per compaction boundary. Absent when no compaction. */
+  compressChildren?: ProcessLogFileResult[];
+  /** Compaction metadata from the boundary record. */
+  compactionMetadata?: CompactionMetadata;
+}
+/**
+ * Converts a {@link ProcessLogFileResult} to a canonical {@link ImportSegment}.
+ *
+ * Strips bus-emission fields (sessionEvent, messageEvents) and recursively
+ * converts children, producing the clean structural tree.
+ * @param result - The full import result from an adapter
+ * @returns A canonical import segment tree
+ */
+declare function toImportSegment(result: ProcessLogFileResult): ImportSegment;
+/**
+ * Lightweight metadata extracted during session discovery.
+ *
+ * Contains only the fields needed to populate the `adapter.session.discovered`
+ * event without running the full import pipeline.
+ * @see {@link LogImporter.extractDiscoveryMetadata} - Method that returns this type
+ */
+interface DiscoveryMetadata {
+  /** Session identifier from the external tool */
+  adapterSessionId: string;
+  /** Model used (null if unknown or not present in logs) */
+  model: string | null;
+  /** Working directory (null if not present in logs) */
+  cwd: string | null;
+  /** Human-readable session title (truncated to 200 chars) */
+  title: string;
+  /**
+   * Whether the log file contains at least one importable message (user or assistant).
+   * Files with only system/metadata records should set this to `false` so the
+   * discovery orchestrator can skip them.
+   * Optional for backward compatibility with out-of-tree importers; consumers
+   * should treat `undefined` as `false`.
+   */
+  hasMessages?: boolean;
+  /** Parent session's adapter ID (null/undefined if root session). */
+  parentAdapterSessionId?: string | null;
+  /** Message ID where this session diverged from parent (null/undefined if root or subagent). */
+  forkPointMessageId?: string | null;
+  /** Relationship to parent: root session, user fork, or subagent. Defaults to 'root' if omitted. */
+  kind?: SessionLineageKind;
+  /** Unix ms timestamp of when the session started in the external tool. */
+  startedAt?: number;
+}
+/**
+ * Contract for log importers (adapters and extensions).
+ *
+ * Importers implement this interface to import external session logs
+ * into Makaio's event system. Both AI adapters (Claude Code, Codex, Gemini)
+ * and extensions can provide log importers.
+ * @remarks
+ * The importer is responsible for:
+ * - Locating log files in tool-specific directories
+ * - Parsing tool-specific log formats
+ * - Detecting compatible log formats via {@link canHandle}
+ * - Extracting session context from initial records
+ * - Processing records into normalized events with context
+ * - Serializing/deserializing state for cursor persistence
+ * - Detecting sessions already managed by Makaio (to skip)
+ *
+ * The generic `TRecord` type represents the tool's native log record format
+ * (e.g., Claude Code's JSONL records with `type`, `message`, `sessionId`).
+ * @typeParam TRecord - The tool's native log record type
+ * @typeParam TState - The resumable state type (defaults to unknown)
+ * @see {@link NormalizedEvent} - Output format for normalized events
+ * @see {@link ImportMetadata} - Provenance metadata added to events
+ * @see {@link ImportCursorPosition} - Cursor tracking for incremental import
+ * @see {@link LogImportSessionContext} - Session context for incremental imports
+ */
+interface LogImporter<TRecord, TState = unknown> {
+  /**
+   * Check if this importer can handle the given log sample.
+   *
+   * Used for auto-detection during log upload to match importers with
+   * unknown log formats. Inspects a sample record/line to determine compatibility.
+   * @param sample - Sample log content (JSONL line or parsed JSON object)
+   * @returns Boolean or confidence score (0-1) indicating compatibility
+   * @remarks
+   * Simple implementations return boolean. Advanced implementations can return
+   * a confidence score for disambiguation when multiple importers claim support.
+   *
+   * Example implementations:
+   * - Claude Code: Check for `type` field in `['started', 'message', 'tool_use']`
+   * - Codex: Check for `event` field matching Codex schema patterns
+   * - Gemini: Check for Gemini-specific log structure
+   *
+   * Return `{ confidence: 0.95 }` for high confidence matches,
+   * `{ confidence: 0.5 }` for ambiguous formats, or `false` for incompatible.
+   */
+  canHandle(sample: string | JsonObject): boolean | {
+    confidence: number;
+  };
+  /**
+   * Get the root directory containing this tool's log files.
+   * @returns Absolute path to the log directory (may contain subdirectories)
+   * @remarks
+   * Examples of log directories:
+   * - Claude Code: `~/.claude/projects/` (contains `session.jsonl` files)
+   * - Codex: `~/.codex/sessions/` (date-organized subdirectories)
+   * - Gemini: `~/.gemini/tmp/` (hash-organized project directories)
+   */
+  getLogDirectory(): string;
+  /**
+   * Parse a single line/record from log file content.
+   * @param content - Raw line content from the log file (JSONL) or full file (JSON)
+   * @param sourceFilePath - Optional path to the source file (for importers that need path context)
+   * @returns Parsed record or null if line is malformed/unparseable
+   * @remarks
+   * Implementations should be lenient - return null for malformed records
+   * rather than throwing. The caller will log a warning and continue.
+   *
+   * The optional `sourceFilePath` parameter enables importers to store file path
+   * context in records when needed (e.g., deriving storage roots from path structure).
+   */
+  parseRecord(content: string | JsonObject, sourceFilePath?: string): TRecord | null;
+  /**
+   * Check if a session is managed by Makaio (should be skipped during import).
+   * @param sessionId - The external tool's session identifier
+   * @returns True if Makaio manages this session, false if it should be imported
+   * @remarks
+   * This prevents re-importing sessions that Makaio already tracks via live
+   * streaming. Implementation typically queries AdapterSessionStorage for the
+   * sessionId to check if the session has status='live'.
+   *
+   * May be async to support database lookups.
+   */
+  isMakaioManaged(sessionId: string): Promise<boolean>;
+  /**
+   * Extract lightweight discovery metadata from a log file.
+   *
+   * Optimized for minimal I/O — reads only enough of the file to populate
+   * the four discovery fields. Used by the DiscoveryOrchestrator to avoid
+   * the full parseFile → extractSessionContext pipeline.
+   * @param filePath - Absolute path to the log file
+   * @returns Discovery metadata with session ID, model, cwd, and title
+   */
+  extractDiscoveryMetadata(filePath: string): Promise<DiscoveryMetadata>;
+  /**
+   * Extract session context from records (called on first read only).
+   *
+   * Creates the session context including session/started events and
+   * initial adapter state. This is only called when no existing cursor
+   * context exists (i.e., first time reading this file).
+   * @param records - Initial batch of parsed records from the file
+   * @returns Session context with events and initial state
+   * @remarks
+   * The returned context is persisted in the cursor and restored on
+   * subsequent reads via {@link deserializeState}.
+   */
+  extractSessionContext(records: TRecord[]): LogImportSessionContext<TState>;
+  /**
+   * Process records into events (context always provided).
+   *
+   * Converts adapter-specific records to normalized Makaio events using
+   * the provided session context. Updates context.state as needed for
+   * stateful processing (e.g., turn tracking).
+   * @param records - Batch of parsed records to process
+   * @param context - Session context (from extractSessionContext or restored)
+   * @returns Array of normalized events (may be empty)
+   * @remarks
+   * This replaces the stateless `toNormalizedEvents` method. The context
+   * provides session metadata and mutable adapter state for tracking
+   * things like conversation turns across chunks.
+   *
+   * Implementations should add {@link ImportMetadata} to payloads
+   * under the `_import` key for provenance tracking.
+   */
+  processRecords(records: TRecord[], context: LogImportSessionContext<TState>): NormalizedEvent[];
+  /**
+   * Serialize adapter state for cursor persistence.
+   *
+   * Converts the adapter's typed state to a JSON-serializable object
+   * for storage in the cursor.
+   * @param state - Adapter-specific state to serialize
+   * @returns JSON-serializable representation of the state
+   */
+  serializeState(state: TState): JsonObject;
+  /**
+   * Restore adapter state from cursor.
+   *
+   * Converts the serialized state back to the adapter's typed state
+   * when resuming from a persisted cursor.
+   * @param raw - Serialized state from cursor storage
+   * @returns Restored adapter-specific state
+   */
+  deserializeState(raw: JsonObject): TState;
+  /**
+   * Process a complete log file in a single call.
+   *
+   * Composes extractSessionContext + processRecords + message extraction.
+   * Adapters that need special handling (fork detection, field normalization)
+   * should override this method.
+   * @param records - All parsed records from the log file
+   * @returns Combined session metadata, events, and message payloads
+   */
+  processLogFile(records: TRecord | TRecord[]): ProcessLogFileResult;
+}
+/**
+ * Configuration for log importer constructor.
+ *
+ * Minimal config required to instantiate a log importer for testing.
+ */
+interface LogImporterConfig {
+  /** Unique identifier for the adapter instance */
+  adapterId: string;
+  /** Human-readable adapter name */
+  adapterName: string;
+  /** Optional session ownership check used by importer implementations that can skip Makaio-managed sessions. */
+  checkMakaioManaged?: (sessionId: string) => Promise<boolean>;
+}
+/**
+ * Test configuration for log import conformance tests.
+ *
+ * Host-owned log importer packages may use this shape to describe their
+ * test fixtures and importer constructors.
+ * @see {@link LogImporter} - Base interface that LogImporterClass must implement
+ */
+interface LogImportTestConfig<TRecord = unknown, TState = unknown> {
+  /**
+   * Fixture file name for conformance tests.
+   *
+   * Relative to the conformance harness fixture directory.
+   * @example 'codex-session.jsonl' or 'gemini-session.json'
+   */
+  fixtureFile: string;
+  /**
+   * Log importer class constructor.
+   *
+   * Must implement {@link LogImporter} for conformance tests.
+   */
+  LogImporterClass: new (config: LogImporterConfig) => LogImporter<TRecord, TState>;
+}
+//#endregion
+//#region adapters/core/src/log-importer/event-queue.d.ts
+interface LogImportEventQueueConfig {
+  readonly eventsPerSecond: number;
+  readonly onEventEmitted: () => void;
+}
+/**
+ * Serializes log-import event delivery and cursor writes.
+ *
+ * Cursor tasks accept the event promises they depend on, so event emission
+ * failures reject the cursor task instead of advancing import progress.
+ */
+declare class LogImportEventQueue {
+  private readonly eventQueue;
+  private readonly cursorQueue;
+  private readonly onEventEmitted;
+  constructor(config: LogImportEventQueueConfig);
+  /**
+   * Queue a normalized event and return its delivery promise.
+   * @param event - Normalized event to emit
+   * @returns Promise that resolves after delivery or rejects on emit failure
+   */
+  queueEvent(event: NormalizedEvent): Promise<void>;
+  /**
+   * Queue a cursor/progress task behind previously queued event deliveries.
+   * @param task - Cursor/progress task to run after event delivery succeeds
+   * @param precedingEventPromises - Emission promises queued before this task
+   * @returns Promise that rejects if a preceding event or the task itself fails
+   */
+  queueAfterEvents(task: () => Promise<void>, precedingEventPromises?: readonly Promise<void>[]): Promise<void>;
+  /** Wait until all queued event and cursor tasks finish. */
+  drain(): Promise<void>;
+  /** Alias for callers that use queue-idle terminology instead of shutdown-drain terminology. */
+  onIdle(): Promise<void>;
+}
+//#endregion
+//#region adapters/core/src/log-importer/log-import-watcher.d.ts
+interface LogFileChangeEvent {
+  /** Absolute path to the changed file. */
+  filePath: string;
+  /** Current file stats needed for cursor and rotation handling. */
+  stat: {
+    /** File size in bytes. */size: number; /** Last modification time. */
+    mtime: Date;
+  };
+  /** Type of change detected by the watcher. */
+  changeType: 'created' | 'modified' | 'rotated';
+}
+interface LogImportWatcherOptions {
+  /** Directory to watch for log files. */
+  directory: string;
+  /** Glob pattern used to discover log files. */
+  pattern: string;
+  /** Polling interval in milliseconds. */
+  pollIntervalMs: number;
+}
+/**
+ * Adapter-log watcher facade used by orchestrators.
+ *
+ * Keeps the concrete file-watcher package out of the exported orchestrator API,
+ * while preserving the small operations subclasses need for discovery tracking.
+ */
+declare class LogImportWatcher {
+  private readonly watcher;
+  constructor(options: LogImportWatcherOptions);
+  /** @returns True when the underlying watcher is actively polling. */
+  isRunning(): boolean;
+  /** Start watching the configured log directory. */
+  start(): Promise<void>;
+  /** Stop watching while preserving tracked file state. */
+  stop(): void;
+  /** Dispose watcher resources and listeners. */
+  dispose(): void;
+  /**
+   * Subscribe to file change events.
+   * @param handler - Callback receiving a log file change event.
+   * @returns Function that unsubscribes the handler.
+   */
+  onChange(handler: (event: LogFileChangeEvent) => void | Promise<void>): () => void;
+  /**
+   * Subscribe to watcher errors.
+   * @param handler - Callback receiving the error and optional file path.
+   * @returns Function that unsubscribes the handler.
+   */
+  onError(handler: (event: {
+    error: Error;
+    filePath?: string;
+  }) => void | Promise<void>): () => void;
+  /**
+   * Subscribe to tracked-file deletion events.
+   * @param handler - Callback receiving the deleted file path.
+   * @returns Function that unsubscribes the handler.
+   */
+  onDeleted(handler: (event: {
+    filePath: string;
+  }) => void | Promise<void>): () => void;
+  /**
+   * Subscribe to completed watcher poll cycles.
+   * @param handler - Callback receiving the current tracked file path set.
+   * @returns Function that unsubscribes the poll handler.
+   */
+  onPolled(handler: (trackedFilePaths: ReadonlySet<string>) => void | Promise<void>): () => void;
+  /**
+   * Read the watcher's last observed mtime for a file.
+   * @param filePath - Absolute path to inspect.
+   * @returns Last observed mtime in milliseconds, or undefined when untracked.
+   */
+  getTrackedFileMtimeMs(filePath: string): number | undefined;
+  /**
+   * Schedule a single-file watcher poll.
+   * @param filePath - Absolute path to poll immediately.
+   */
+  triggerImmediatePoll(filePath: string): void;
+  /**
+   * Seed watcher state from persisted cursor positions.
+   * @param cursors - Cursor positions used to initialize tracked file state.
+   */
+  seedFromCursors(cursors: Array<Pick<ImportCursorPosition, 'filePath' | 'bytesRead' | 'lastModified'>>): void;
+}
+//#endregion
+//#region adapters/core/src/log-importer/orchestrator-config.d.ts
+/** Configuration for log import orchestrators. */
+interface LogOrchestratorConfig {
+  enabled: boolean;
+  directory?: string;
+  pollIntervalMs?: number;
+  eventsPerSecond?: number;
+  adapterId: string;
+  adapterName: string;
+  checkMakaioManaged?: (sessionId: string) => Promise<boolean>;
+}
+/** Result of parsing a log file. */
+interface ParseFileResult<TRecord> {
+  records: TRecord[];
+  bytesRead?: number;
+  errors?: Array<{
+    line?: number;
+    error: string;
+  }>;
+}
+//#endregion
+//#region adapters/core/src/log-importer/base-orchestrator.d.ts
+/**
+ * Abstract base class for log import orchestrators.
+ *
+ * Supports JSONL (byte offset cursors) and JSON (mtime-based) file formats.
+ * Concrete implementations provide adapter-specific file parsing.
+ * @typeParam TRecord - The adapter's native log record type
+ * @typeParam TState - The adapter's resumable state type (default: unknown)
+ */
+declare abstract class BaseLogOrchestrator<TRecord, TState = unknown> {
+  protected readonly config: Required<Omit<LogOrchestratorConfig, 'checkMakaioManaged' | 'directory'>> & {
+    checkMakaioManaged?: LogOrchestratorConfig['checkMakaioManaged'];
+    directory?: string;
+  };
+  protected readonly watcher: LogImportWatcher;
+  protected readonly eventQueue: LogImportEventQueue;
+  /** Log prefix for console output - set by subclass */
+  protected abstract readonly logPrefix: string;
+  /** Importer instance - subclasses create and manage their own typed instance. */
+  protected readonly importer: LogImporter<TRecord, TState>;
+  private readonly managedSessionCache;
+  private unsubscribeChange?;
+  private unsubscribeError?;
+  private unsubscribeDeleted?;
+  private readonly stats;
+  private readonly watcherTasks;
+  private progressTimer?;
+  protected constructor(config: LogOrchestratorConfig, importer: LogImporter<TRecord, TState>);
+  /** Get the glob pattern for log files to watch. */
+  protected abstract getLogFilePattern(): string;
+  /**
+   * Determine whether a discovered file should be skipped before processing.
+   *
+   * Default implementation never skips. Subclasses may override to exclude
+   * files by name (e.g., ephemeral compaction summary files).
+   * @param _filePath - Absolute path to the candidate file
+   * @returns `true` to skip the file entirely, `false` to process normally
+   */
+  protected shouldSkipFile(_filePath: string): boolean;
+  /**
+   * Parse a log file from the given byte offset.
+   * @param filePath - Path to the log file
+   * @param startOffset - Byte offset to start reading from
+   * @param maxRecords - Optional maximum number of records to return (for shallow discovery)
+   */
+  protected abstract parseFile(filePath: string, startOffset: number, maxRecords?: number): Promise<ParseFileResult<TRecord>>;
+  /**
+   * Validate and filter parsed records. Default: returns records as-is.
+   * @param records - Raw parsed records
+   * @returns Validated/filtered records
+   */
+  protected validateRecords(records: TRecord[]): TRecord[];
+  /**
+   * Returns the maximum number of records to parse per file.
+   * Override in subclasses to limit parsing (e.g., discovery mode).
+   * @returns Maximum record count, or `undefined` for no limit.
+   */
+  protected getMaxRecords(): number | undefined;
+  /**
+   * Builds the serialized session context for cursor persistence.
+   * @param context - The import session context to serialize.
+   * @returns Serialized cursor session context.
+   */
+  protected buildCursorSessionContext(context: LogImportSessionContext<TState>): NonNullable<ImportCursorPosition['sessionContext']>;
+  /**
+   * Check if this orchestrator uses JSON format (mtime-based cursor).
+   * @returns True if JSON format, false for JSONL
+   */
+  protected usesJsonFormat(): boolean;
+  isEnabled(): boolean;
+  isRunning(): boolean;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  dispose(): Promise<void>;
+  /** @returns Function that checks if a session is Makaio-managed. */
+  static createDefaultCheckMakaioManaged(): (sessionId: string) => Promise<boolean>;
+  protected updateCursor(filePath: string, bytesRead: number, mtime: Date, sessionContext?: ImportCursorPosition['sessionContext']): Promise<void>;
+  /**
+   * Handle a file-change event: resolve cursor state and route to first-read or
+   * incremental-read as appropriate.
+   *
+   * Subclasses (e.g., {@link DiscoveryOrchestrator}) may override this method to
+   * substitute an entirely different dispatch strategy.
+   * @param event - File change event from the watcher
+   */
+  protected handleFileChange(event: LogFileChangeEvent): Promise<void>;
+  /**
+   * Track a watcher-triggered file import so shutdown can wait for any cursor
+   * work that the handler enqueues before draining the shared FIFO queue.
+   * @param event - File change event to process
+   */
+  protected trackFileChange(event: LogFileChangeEvent): void;
+  /**
+   * Handle the first read of a log file.
+   *
+   * Extracts session context, emits session lifecycle events, processes records,
+   * and saves the cursor. Subclasses may override to change behavior (e.g.,
+   * {@link DiscoveryOrchestrator} skips message processing).
+   * @param filePath - Path to the log file
+   * @param records - Records parsed from the file
+   * @param bytesRead - Bytes read during this parse
+   * @param mtime - File modification time
+   * @param isJsonFormat - Whether the file uses JSON (mtime-based) format
+   * @param startOffset - Byte offset this read started from
+   * @param emitLifecycleEvents - Whether to emit session and started lifecycle events for this pass
+   */
+  protected handleFirstRead(filePath: string, records: TRecord[], bytesRead: number, mtime: Date, isJsonFormat: boolean, startOffset: number, emitLifecycleEvents?: boolean): Promise<void>;
+  /**
+   * Record that a session has been imported, updating import statistics.
+   *
+   * Protected to allow subclasses to update stats when processing additional
+   * sessions (e.g., compress child sessions from compacted files).
+   * @param adapterSessionId - The session ID that was imported
+   */
+  protected trackImportedSession(adapterSessionId: string): void;
+  /**
+   * Handle an incremental read of a log file.
+   *
+   * Processes new records since the last cursor position. Subclasses may override
+   * to skip incremental processing (e.g., {@link DiscoveryOrchestrator}).
+   * @param filePath - Path to the log file
+   * @param records - New records since last read
+   * @param cursorContext - Existing cursor session context
+   * @param bytesRead - Bytes read during this parse
+   * @param mtime - File modification time
+   * @param isJsonFormat - Whether the file uses JSON (mtime-based) format
+   * @param startOffset - Byte offset this read started from
+   */
+  protected handleIncrementalRead(filePath: string, records: TRecord[], cursorContext: NonNullable<ImportCursorPosition['sessionContext']>, bytesRead: number, mtime: Date, isJsonFormat: boolean, startOffset: number): Promise<void>;
+  protected maybeUpdateCursor(filePath: string, bytesRead: number, startOffset: number, mtime: Date, isJsonFormat: boolean, sessionContext?: ImportCursorPosition['sessionContext']): Promise<void>;
+  /**
+   * Determine whether an adapter session should be skipped from import.
+   *
+   * Delegates to the managed-session cache so concurrent checks for the same
+   * `adapterSessionId` share one storage lookup and tracked skips update stats.
+   * @param adapterSessionId - External adapter session ID being evaluated
+   * @returns Promise resolving to true when the session is Makaio-managed and should be skipped
+   */
+  protected isSessionSkipped(adapterSessionId: string): Promise<boolean>;
+  /**
+   * Queue a normalized event and return its delivery promise.
+   * @param event - Normalized event to emit
+   * @returns Promise that resolves after delivery or rejects on emit failure
+   */
+  protected queueEvent(event: NormalizedEvent): Promise<void>;
+  /**
+   * Enqueue a cursor write as a PQueue task so it executes after all previously
+   * queued events for the same batch have been emitted.
+   *
+   * PQueue runs tasks with concurrency=1 in FIFO order, so placing the cursor
+   * write at the back of the queue after all `queueEvent` calls guarantees that
+   * the cursor advances only once every preceding event in the batch has been
+   * delivered. This prevents the race where a process exit after `queueEvent`
+   * but before queue drain would leave events lost yet the cursor advanced.
+   * @param filePath - Path to the log file
+   * @param bytesRead - Total bytes read at the new cursor position
+   * @param startOffset - Byte offset this read started from
+   * @param mtime - File modification time
+   * @param isJsonFormat - Whether the file uses JSON (mtime-based) format
+   * @param sessionContext - Serialized session context for the cursor
+   * @param precedingEventPromises - Emission promises queued before this cursor write
+   * @returns Promise that resolves when the cursor write has completed
+   */
+  protected queueCursorUpdate(filePath: string, bytesRead: number, startOffset: number, mtime: Date, isJsonFormat: boolean, sessionContext?: ImportCursorPosition['sessionContext'], precedingEventPromises?: Promise<void>[]): Promise<void>;
+}
+//#endregion
+export { LogImporterConfig as _, CompactionMetadata as a, StorageMessagePayload as b, ExternalToolIdentifiers as c, ImportMetadata as d, ImportSegment as f, LogImporter as g, LogImportTestConfig as h, LogFileChangeEvent as i, ExternalToolMeta as l, LogImportSessionContext as m, LogOrchestratorConfig as n, DiscoveryMetadata as o, ImportSegmentLineage as p, ParseFileResult as r, ExternalToolIdentifier as s, BaseLogOrchestrator as t, ImportCursorPosition as u, NormalizedEvent as v, toImportSegment as x, ProcessLogFileResult as y };