Interface: LogImporter<TRecord, TState>

Makaio Framework / ai-adapters-core / LogImporter

Interface: LogImporter<TRecord, TState>

Defined in: ../../../adapters/core/src/log-importer/types.ts:349

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

See

NormalizedEvent - Output format for normalized events
ImportMetadata - Provenance metadata added to events
ImportCursorPosition - Cursor tracking for incremental import
LogImportSessionContext - Session context for incremental imports

Type Parameters

TRecord

TRecord

The tool’s native log record type

TState

TState = unknown

The resumable state type (defaults to unknown)

Methods

canHandle()

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

Defined in: ../../../adapters/core/src/log-importer/types.ts:369

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.

deserializeState()

deserializeState(raw): TState

Defined in: ../../../adapters/core/src/log-importer/types.ts:471

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

extractDiscoveryMetadata()

extractDiscoveryMetadata(filePath): Promise<DiscoveryMetadata>

Defined in: ../../../adapters/core/src/log-importer/types.ts:418

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.

Parameters

filePath

string

Absolute path to the log file

Returns

Promise<DiscoveryMetadata>

Discovery metadata with session ID, model, cwd, and title

extractSessionContext()

extractSessionContext(records): LogImportSessionContext<TState>

Defined in: ../../../adapters/core/src/log-importer/types.ts:432

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.

getLogDirectory()

getLogDirectory(): string

Defined in: ../../../adapters/core/src/log-importer/types.ts:380

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)

isMakaioManaged()

isMakaioManaged(sessionId): Promise<boolean>

Defined in: ../../../adapters/core/src/log-importer/types.ts:407

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.

parseRecord()

parseRecord(content, sourceFilePath?): TRecord | null

Defined in: ../../../adapters/core/src/log-importer/types.ts:394

Parse a single line/record from log file content.

Parameters

content

string | JsonObject

Raw line content from the log file (JSONL) or full file (JSON)

sourceFilePath?

string

Optional path to the source file (for importers that need path context)

Returns

TRecord | null

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

processLogFile()

processLogFile(records): ProcessLogFileResult

Defined in: ../../../adapters/core/src/log-importer/types.ts:482

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

processRecords()

processRecords(records, context): NormalizedEvent[]

Defined in: ../../../adapters/core/src/log-importer/types.ts:451

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.

serializeState()

serializeState(state): JsonObject

Defined in: ../../../adapters/core/src/log-importer/types.ts:461

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