Abstract Class: BaseLogImporter<TRecord, TState>

Makaio Framework / ai-adapters-core / BaseLogImporter

Abstract Class: BaseLogImporter<TRecord, TState>

Defined in: ../../../adapters/core/src/log-importer/base-importer.ts:27

Abstract base class for log importers.

Provides default processLogFile() implementation that composes extractSessionContext() + processRecords(). Adapters implement the abstract methods for their specific log format.

Type Parameters

TRecord

TRecord

The tool’s native log record type

TState

TState = unknown

The resumable state type

Implements

LogImporter<TRecord, TState>

Constructors

Constructor

new BaseLogImporter<TRecord, TState>(): BaseLogImporter<TRecord, TState>

Returns

BaseLogImporter<TRecord, TState>

Methods

canHandle()

abstract canHandle(sample): boolean | { confidence: number; }

Defined in: ../../../adapters/core/src/log-importer/base-importer.ts:29

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.

Parameters

sample

string | JsonObject

Sample log content (JSONL line or parsed JSON object)

Returns

boolean | { confidence: number; }

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.

Implementation of

LogImporter.canHandle

deserializeState()

abstract deserializeState(raw): TState

Defined in: ../../../adapters/core/src/log-importer/base-importer.ts:48

Restore adapter state from cursor.

Converts the serialized state back to the adapter’s typed state when resuming from a persisted cursor.

Parameters

raw

JsonObject

Serialized state from cursor storage

Returns

TState

Restored adapter-specific state

Implementation of

LogImporter.deserializeState

extractDiscoveryMetadata()

abstract extractDiscoveryMetadata(filePath): Promise<DiscoveryMetadata>

Defined in: ../../../adapters/core/src/log-importer/base-importer.ts:44

Extract discovery metadata from a log file without importing full message history.

Parameters

filePath

string

Absolute path to the source log file

Returns

Promise<DiscoveryMetadata>

Discovery metadata when parsing succeeds; rejects on unrecoverable read/parse errors

Implementation of

LogImporter.extractDiscoveryMetadata

extractSessionContext()

abstract extractSessionContext(records): LogImportSessionContext<TState>

Defined in: ../../../adapters/core/src/log-importer/base-importer.ts:45

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).

Parameters

records

TRecord[]

Initial batch of parsed records from the file

Returns

LogImportSessionContext<TState>

Session context with events and initial state

Remarks

The returned context is persisted in the cursor and restored on subsequent reads via deserializeState.

Implementation of

LogImporter.extractSessionContext

getLogDirectory()

abstract getLogDirectory(): string

Defined in: ../../../adapters/core/src/log-importer/base-importer.ts:30

Get the root directory containing this tool’s log files.

Returns

string

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)

Implementation of

LogImporter.getLogDirectory

isMakaioManaged()

abstract isMakaioManaged(sessionId): Promise<boolean>

Defined in: ../../../adapters/core/src/log-importer/base-importer.ts:38

Check if a session is managed by Makaio (should be skipped during import).

Parameters

sessionId

string

The external tool’s session identifier

Returns

Promise<boolean>

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.

Implementation of

LogImporter.isMakaioManaged

parseRecord()

abstract parseRecord(line, sourceFilePath?): TRecord | null

Defined in: ../../../adapters/core/src/log-importer/base-importer.ts:37

Parse a single log record from raw input.

Parameters

line

string | JsonObject

Raw log line or parsed JSON object to parse

sourceFilePath?

string

Optional source file path for format-specific context

Returns

TRecord | null

Parsed record or null when the input does not match the adapter format

Implementation of

LogImporter.parseRecord

processLogFile()

processLogFile(records): ProcessLogFileResult

Defined in: ../../../adapters/core/src/log-importer/base-importer.ts:59

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.

Parameters

records

TRecord | TRecord[]

All parsed records from the log file

Returns

ProcessLogFileResult

Combined session metadata, events, and message payloads

Implementation of

LogImporter.processLogFile

processRecords()

abstract processRecords(records, context): NormalizedEvent[]

Defined in: ../../../adapters/core/src/log-importer/base-importer.ts:46

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).

Parameters

records

TRecord[]

Batch of parsed records to process

context

LogImportSessionContext<TState>

Session context (from extractSessionContext or restored)

Returns

NormalizedEvent[]

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 ImportMetadata to payloads under the _import key for provenance tracking.

Implementation of

LogImporter.processRecords

serializeState()

abstract serializeState(state): JsonObject

Defined in: ../../../adapters/core/src/log-importer/base-importer.ts:47

Serialize adapter state for cursor persistence.

Converts the adapter’s typed state to a JSON-serializable object for storage in the cursor.

Parameters

state

TState

Adapter-specific state to serialize

Returns

JsonObject

JSON-serializable representation of the state

Implementation of

LogImporter.serializeState