@rivus/agent-kit/sessions
listSessions, sessionAdapterHome, isSessionHead, SessionAdapter — anywhere, with a platform
Functions
isSessionHead()
function isSessionHead(item: SessionHead | SessionListFailure): item is SessionHead;Parameters
item
SessionHead | SessionListFailure
Returns
item is SessionHead
listSessions()
function listSessions(platform: SessionPlatform & Pick<Platform, "env" | "home">, options?: ListSessionsOptions): AsyncGenerator<SessionHead | SessionListFailure>;Lists the sessions of each agent from its homes' roots, one head per session file, reading at most 64 KB from
each end of a file. A missing root or an unreadable file is a failure item and listing goes on. Throws
capability-unsupported when a requested agent has no adapter; leaving the loop stops the reads.
Parameters
platform
SessionPlatform & Pick<Platform, "env" | "home">
options?
Returns
AsyncGenerator<SessionHead | SessionListFailure>
readOriginal()
function readOriginal(
platform: SessionPlatform,
source: SourcePointer,
options?: ReadOriginalOptions
): Promise<Result<unknown, ReadOriginalError>>;Parameters
platform
source
options?
Returns
Promise<Result<unknown, ReadOriginalError>>
sessionAdapterHome()
function sessionAdapterHome(
adapter: Pick<SessionAdapter, "home" | "agent">,
context: HomeContext,
options?: SessionAdapterHomeOptions
): AgentHome;The home whose roots an adapter lists: the adapter's own home rule, else the catalog's rule for a built-in agent.
Throws capability-unsupported when there is neither. For a caller that walks an adapter's roots itself, for
example to report progress per root, instead of through listSessions.
Parameters
adapter
Pick<SessionAdapter, "home" | "agent">
context
options?
Returns
Interfaces
ListSessionsOptions
Properties
agents?
readonly agents?: readonly string[];Agents to list, by id or alias; defaults to every agent in providers.sessions.
onTotal?
readonly onTotal?: (files: number) => void;Called with the running total of session files each time another root has been listed.
Parameters
files
number
Returns
void
providers?
readonly providers?: readonly Provider[];signal?
readonly signal?: AbortSignal;ReadOriginalOptions
Reads an event's record back from its source pointer and parses it. SourceChanged means those bytes are no
longer one JSON value, because the file changed after the transcript was loaded. An abort rejects with
signal.reason; only defects throw.
Properties
progress?
readonly progress?: ReadProgress;signal?
readonly signal?: AbortSignal;SessionAdapter
How one CodingAgent stores its sessions and how to read them. The shell supplies built-in adapters;
a shell caller passes its own as a sessions service in the providers option, and /testing has the checks an
adapter must pass. Every read goes through the platform passed to the call.
Properties
agent
readonly agent: string;capabilities
readonly capabilities: readonly Capability[];Everything this agent's transcripts can list; each transcript lists the subset its files show.
displayName
readonly displayName: string;home?
readonly home?: HomeRule;This agent's home rule, used instead of catalog's; required for an agent catalog has no rule for.
specificationVersion
readonly specificationVersion: "sessions-v1";Methods
detect()
detect(platform: SessionPlatform, ref: SessionRef): Promise<boolean>;Whether ref.path is a session of this agent; cheap, for refs whose agent is unknown.
Parameters
platform
ref
Returns
Promise<boolean>
discover()
discover(
platform: SessionPlatform,
root: string,
options?: DiscoverOptions
): AsyncIterable<SessionHead | SessionListFailure>;Lists the sessions under root, reading at most 64 KB from each end of each file.
Parameters
platform
root
string
options?
DiscoverOptions
Returns
AsyncIterable<SessionHead | SessionListFailure>
load()
load(
platform: SessionPlatform,
ref: SessionRef,
options?: LoadOptions
): Promise<Result<Transcript, SessionReadError>>;Reads every file of the session. Expected failures are values: a file that disappeared, an IO error, or a format
generation this adapter does not know; single unreadable lines are skipped records. An abort rejects with
signal.reason, and only defects throw.
Parameters
platform
ref
options?
LoadOptions
Returns
Promise<Result<Transcript, SessionReadError>>
roots()
roots(home: AgentHome): string[];Directories that hold this agent's sessions, such as <home>/projects.
Parameters
home
Returns
string[]
summarize()?
summarize?(
platform: SessionPlatform,
ref: SessionRef,
options?: object
): Promise<Result<SessionSummaryWithPrompts, SessionReadError>>;A faster pass than folding the loaded transcript, with the same result: no transcript or event payload is kept,
and the state it holds grows with the session's requests, lanes and tool calls, never with its bytes. With
prompts, the summary also carries the main lane's user prompts under the given caps, by the same rule
sessionPrompts applies to the loaded transcript — an implementation that leaves them out fails the conformance
suite. The equality covers the summary's numbers and prompts, not the failure modes: the pass may read fewer
files than load (side files the summary's numbers never read) and in its own order, so an IO error on one of
those can fail load while summarize succeeds, or the reverse.
Parameters
platform
ref
options?
prompts?
SessionPromptsOptions
signal?
AbortSignal
Returns
Promise<Result<SessionSummaryWithPrompts, SessionReadError>>
SessionAdapterHomeOptions
Properties
providers?
readonly providers?: readonly Provider[];SessionHead
What listing learns about a Session from the head and tail of its main file, without reading it fully.
Properties
cwd?
cwd?: string;firstPrompt?
firstPrompt?: string;The first real user prompt, cut to 500 characters.
lastActiveAt
lastActiveAt: number;The last record time seen at either end of the file, else the file's modification time.
ref
ref: SessionRef;sizeBytes
sizeBytes: number;startedAt?
startedAt?: number;title?
title?: string;The agent's own title, else the first real prompt, cut to 80 characters.
SessionPlatform
The part of Platform that reading sessions uses: listing, stat and reads, never writes. A whole Platform satisfies it, and so does a read-only file system such as a browser's.
Properties
decompress?
readonly decompress?: Decompress;Present when the host can decode a compressed session file.
fs
readonly fs: Pick<PlatformFs, "stat" | "list" | "read">;sqlite?
readonly sqlite?: PlatformSqlite;Present when the host has SQLite, for an agent whose sessions live in a database.
SessionRef
The reference to a Session. It carries the CodingAgentId, so later calls reach the right adapter.
Properties
agent
readonly agent: string;path
readonly path: string;The session's main file; an adapter may read other files next to it.
sessionId?
readonly sessionId?: string;Type Aliases
ReadOriginalError
type ReadOriginalError = SourceChanged | SessionNotFound | ReadFailed;SessionAdapters
type SessionAdapters = ServiceTable<SessionAdapter>;Session adapters by agent id; supplied by the caller.
SessionListError
type SessionListError =
| {
_tag: "RootMissing";
path: string;
}
| ReadFailed;Why one root or file could not be listed. Listing continues with the next one.