@rivus/agent-kit/transcript
loadTranscript, summarizeSession, Transcript, TranscriptEvent — anywhere, with a platform
Functions
loadTranscript()
function loadTranscript(
platform: SessionPlatform,
target: SessionTarget,
options?: LoadTranscriptOptions
): Promise<Result<Transcript, LoadTranscriptError>>;Reads every file of a session into one Transcript. Expected failures are values: SessionNotFound,
CapabilityUnsupported (the named agent has no adapter), NoAdapterAccepted (detection found none),
UnknownFormatGeneration and ReadFailed. An abort rejects with signal.reason; only defects throw.
Parameters
platform
target
options?
Returns
Promise<Result<Transcript, LoadTranscriptError>>
summarizeSession()
function summarizeSession(
platform: SessionPlatform,
target: SessionTarget,
options?: SummarizeSessionOptions
): Promise<Result<SessionSummaryWithPrompts, LoadTranscriptError>>;The adapter's own summary pass when it has one, else foldTranscript of the loaded transcript — the same numbers
either way, so a cache of summaries cannot tell them apart. With prompts, the summary also carries the main
lane's user prompts: from the pass for an adapter that implements one, else from the loaded transcript, always by
the kit's prompt rule (sessionPrompts).
Parameters
platform
target
options?
Returns
Promise<Result<SessionSummaryWithPrompts, LoadTranscriptError>>
Interfaces
Lane
One agent's execution line in a Session. The main agent has no parentId; a subagent names its parent lane.
Properties
id
id: string;parentId?
parentId?: string;spawnEventId?
spawnEventId?: string;The tool_call or system event on the parent lane that started this subagent, when the log records it.
systemPrompt?
systemPrompt?: string;This lane's own system prompt, when the agent records one per lane.
title?
title?: string;LoadTranscriptOptions
Properties
onProgress?
readonly onProgress?: (bytes: number) => void;Called with the running total of bytes read across the session's files.
Parameters
bytes
number
Returns
void
providers?
readonly providers?: readonly Provider[];signal?
readonly signal?: AbortSignal;PromptSnapshotPayload
A system event with type: 'prompt_snapshot': the system prompt and tool definitions the agent recorded at
that point on the event's lane. A later snapshot on the same lane replaces an earlier one; a field left out was
not recorded by that snapshot. promptSnapshot returns it for such an event.
Extends
SystemPayload
Indexable
[field: string]: unknownProperties
durationMs?
durationMs?: number;Inherited from
SystemPayload.durationMs
systemPrompt?
systemPrompt?: string;Inherited from
SystemPayload.systemPrompt
text?
text?: string;Inherited from
SystemPayload.text
tools?
tools?: unknown[];Inherited from
SystemPayload.tools
type
type: "prompt_snapshot";Overrides
SystemPayload.type
SessionSummary
Numbers about one Session. A number whose capability the transcript does not list is absent; failedTools and
turns are always counted.
Properties
compactions?
compactions?: number;contextShape?
contextShape?: number[];Input tokens of each request in order, downsampled to at most 120 points.
durationMs?
durationMs?: number;failedTools?
failedTools?: number;inputTokens?
inputTokens?: number;outputTokens?
outputTokens?: number;requests?
requests?: number;subagents?
subagents?: number;turns?
turns?: number;SessionTarget
A session to read. Without an agent (or with an id that does not parse), every adapter's detect decides.
Properties
agent?
readonly agent?: string;path
readonly path: string;sessionId?
readonly sessionId?: string;SourcePointer
Where an event's original record is: reading length bytes at offset of file returns it. A compressed file
counts decompressed bytes, and a session kept in SQLite names its row instead of a byte range.
Properties
codec?
codec?: "zstd";The file is compressed, and offset/length index its decompressed stream.
file
file: string;length
length: number;line
line: number;1-based.
offset
offset: number;sqlite?
sqlite?: SqliteSourcePointer;The original is one SQLite row of file, not the bytes at offset.
SummarizeSessionOptions
Properties
prompts?
readonly prompts?: SessionPromptsOptions;providers?
readonly providers?: readonly Provider[];signal?
readonly signal?: AbortSignal;Transcript
The ordered events of a Session, merged from all its files, with the records that became no event.
Properties
agent
agent: string;agents
agents: Lane[];agentVersion?
agentVersion?: string;The agent version the log records.
capabilities
capabilities: Capability[];What these files record: a subset of the adapter's capabilities.
events
events: TranscriptEvent[];session
session: TranscriptSession;skipped
skipped: SkippedRecord[];TranscriptEventPayloads
The payload type of each event kind. Code generic over the kind, such as a function that builds a
TranscriptEventOf<K>, types its payload as TranscriptEventPayloads[K]: while K is a type parameter, TypeScript
does not resolve TranscriptEventOf<K>['payload'], so an event built from such a payload does not check as a
TranscriptEventOf<K>.
Properties
assistant
assistant: MessagePayload;compaction
compaction: CompactionPayload;hook
hook: HookPayload;reasoning
reasoning: ReasoningPayload;request
request: RequestPayload;system
system: SystemPayload;tool_call
tool_call: ToolCallPayload;tool_result
tool_result: ToolResultPayload;unknown
unknown: UnknownPayload;user
user: MessagePayload;TranscriptSession
Properties
cwd?
cwd?: string;endedAt?
endedAt?: number;id
id: string;startedAt?
startedAt?: number;systemPrompt?
systemPrompt?: string;The main lane's latest recorded system prompt.
title?
title?: string;tools?
tools?: unknown;The main lane's latest recorded tool definitions.
Type Aliases
Capability
type Capability =
| "requests"
| "usage"
| "durations"
| "reasoning"
| "compaction"
| "compactionTokens"
| "subagents"
| "systemPrompt"
| "toolSchemas"
| "hooks";What an agent's logs can record. A count whose capability a transcript does not list is absent, never 0.
LoadTranscriptError
type LoadTranscriptError = SessionReadError | NoAdapterAccepted | CapabilityUnsupported;The expected failures of loadTranscript and summarizeSession.
TranscriptEvent
type TranscriptEvent = TranscriptEventOf<TranscriptEventKind>;One event of a Transcript. Events form a flat list and reference each other by id: agentId names a lane in
Transcript.agents, parentId the event this one follows in the agent's own record chain, requestId the
request event of the model request that produced it, payload.callId pairs a tool_result with its
tool_call, and shadowedBy names the compaction that removed it from the model's context. The union is
discriminated by kind: narrowing on it types payload as that kind's *Payload. An agent may add fields of its
own to a payload, which read as unknown.
TranscriptEventKind
type TranscriptEventKind =
| "user"
| "assistant"
| "reasoning"
| "tool_call"
| "tool_result"
| "request"
| "system"
| "compaction"
| "hook"
| "unknown";TranscriptEventOf
type TranscriptEventOf<K extends TranscriptEventKind> = { [Kind in K]: TranscriptEventBase<Kind> }[K];The events of the kinds in K, such as TranscriptEventOf<'tool_call'>; a union of kinds gives a union of
events, each with its own payload type.
Type Parameters
K
K extends TranscriptEventKind
Variables
SESSION_SUMMARY_VERSION
const SESSION_SUMMARY_VERSION: 2 = 2;Version of the summary numbers. It changes when a number changes meaning or value for the same files, so that a cache of summaries knows to recompute them.