Interface: ModelDriver

Defined in: ports/model-driver.ts:14

Runtime port for LLM provider protocol drivers (@paraharness/claude, @paraharness/openai, @paraharness/gemini).

Manages wire-accurate turn invocation, KV-cache-preserving fork preparation, and in-place synchronization note injection on tool and user frames.

Methods

appendToolResultNotes()

appendToolResultNotes(
   frame, 
   notes, 
   targetCallId?, 
   opts?
): Promise<WireFrameRecord>;

Defined in: ports/model-driver.ts:57

Appends synchronization or recovery notes to a role: 'tool' or role: 'user' frame in-place.

Updates both rawWireFrame and frame.canonical so subsequent turns see the appended notes without breaking role alternation.

Parameters

Parameter	Type	Description
frame	WireFrameRecord	Existing tool or user wire frame record.
notes	readonly string[]	Synchronization note strings to append.
targetCallId?	string	Optional tool callId to target on a multi-tool frame.
opts?	AppendToolResultNotesOptions	Optional error status override.

Returns

Promise<WireFrameRecord>

Updated wire frame record to persist via LedgerStore.replaceMessageFrame().

---

invokeTurn()

invokeTurn(req): Promise<ModelTurnResponse>;

Defined in: ports/model-driver.ts:29

Invokes a single model turn over req.history and returns the raw wire frame and canonical projection.

Transmits the pinned wire prefix and conversation history to the provider and extracts tool calls or structured output.

Parameters

Parameter	Type	Description
req	ModelTurnRequest	Turn request payload and wire prefix configuration.

Returns

Promise<ModelTurnResponse>

Raw wire response, canonical message, structured output, and usage.

---

prepareFork()

prepareFork(ctx, target): Promise<readonly WireFrameRecord[]>;

Defined in: ports/model-driver.ts:42

Synthesizes the initial WireFrameRecord[] chain for a downward fork or cross-model escalation.

Preserves byte-identical parent wire frames on same-model forks and re-encodes from CanonicalMessage (substituting compacted skill tombstones) when escalating across distinct models.

Parameters

Parameter	Type	Description
ctx	ForkContext	Fork lineage, history mode, and turn-batch pairing metadata.
target	PrepareForkTarget	Target model configuration and tombstone substitution flag.

Returns

Promise<readonly WireFrameRecord[]>

Synthesized wire frame chain to persist in LedgerStore.

Properties

Property	Modifier	Type	Description	Defined in
vendor?	readonly	string	Optional alias matching vendorId.	ports/model-driver.ts:18
vendorId	readonly	string	Primary vendor identifier ('anthropic' | 'openai' | 'google' | string).	ports/model-driver.ts:16