Documentation
¶
Overview ¶
Package transcript reads other coding agents' on-disk session logs and normalises them into a common shape.
It is the front half of `logos ingest`. The thesis is "read transcripts, never replay them": a raw transcript resumed as context hands the next agent every abandoned approach as a live option, which is the stale-answer failure the continuity benchmark measures. So this package's job stops at reading — no model, no vault writes, no network. Distillation into a checkpoint candidate happens in distil.go and the queue in internal/session.
Everything a reader returns is untrusted. A transcript is other agents' full text including whatever they read off the web, and it is the most hostile input this codebase accepts. Callers that put a Session in front of a model must frame it as evidence, never instructions (see internal/untrusted).
Reading is strictly read-only: no function here opens a source file for write, ever. TestIngestNeverWritesToTheSourceTranscript asserts the mtimes.
Index ¶
Constants ¶
const LogosClaudeProjectsEnv = "LOGOS_CLAUDE_PROJECTS"
LogosClaudeProjectsEnv overrides the Claude Code projects directory, so a test points at a fixture tree instead of the real one. Same pattern as LOGOS_VAULT.
const LogosCodexSessionsEnv = "LOGOS_CODEX_SESSIONS"
LogosCodexSessionsEnv overrides the Codex sessions directory for tests.
const LogosCursorStorageEnv = "LOGOS_CURSOR_STORAGE"
LogosCursorStorageEnv overrides the Cursor globalStorage directory, so a test points at a fixture instead of the developer's real chat history.
Variables ¶
This section is empty.
Functions ¶
func Harnesses ¶
func Harnesses() []string
Harnesses lists every harness name ingest knows how to try, for help text and error messages.
func Sessions ¶
Sessions lists discoverable session file paths for one harness. An unknown harness, or one whose format needs txcript when txcript is absent, returns a SkipReason error naming the fix rather than an empty slice.
func SourceFile ¶ added in v0.4.5
SourceFile returns the file on disk that a recorded source path names.
Cursor addresses a session as <storage file>#<chat id>, so a caller asking the plain question "is this transcript still there?" cannot just stat the string: every Cursor session would read as deleted while its database sat untouched. The addressing scheme was invented here, so the answer lives here too, rather than in each caller reinventing the split.
Types ¶
type Availability ¶
type Availability struct {
Harness string
Root string
Found bool
Reason string // when !Found: why it was skipped, per invariant 3
Sessions int // discoverable session files, best effort
}
Availability describes one harness and whether ingest can read it here.
func Available ¶
func Available() []Availability
Available reports every known harness and its status on this machine, sorted by name. A harness with a reader but no session directory, and a harness with no native reader and no txcript, both say why rather than vanishing from the list.
type Session ¶
type Session struct {
Harness string // "claude-code", "codex", "cursor", ...
ID string // harness-native session id
Path string // absolute path to the source file
Project string // best-effort repo/dir the session ran in
Started int64
Ended int64
Turns []Turn
Hash string // content hash of the source, for idempotence
// Skipped counts lines the reader could not parse but stepped over rather
// than failing the whole session on. Surfaced, never swallowed (invariant
// 3): a session with Skipped > 0 is reported as partially read.
Skipped int
}
Session is one agent session, normalised across harnesses.
type SkipReason ¶
SkipReason is the "named and skipped, not silently dropped" error (invariant 3). It carries the harness and a sentence a user can act on.
func (*SkipReason) Error ¶
func (e *SkipReason) Error() string
type Turn ¶
type Turn struct {
Role string // "user" | "assistant" | "tool"
Text string
Tool string // tool name, when Role == "tool"
Status string // "ok" | "error", when known
// Input is the tool invocation — the shell command, the file path — carried
// on the tool turn so a harvest can list commands run and files touched
// without a model. Empty when the harness did not record it.
Input string
}
Turn is one exchange in a session, in wall-clock order.
Source Files