agentsession

package module
v0.0.21 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 3, 2026 License: MIT Imports: 33 Imported by: 6

README

agentsession

Go Reference CI

The reference Go implementation of the Agent Session Format: an append-only, tree-structured JSONL record of one agent session whose conversation payloads are Open Responses items. One file holds what the model was sent, what it returned, what tools did, how the configuration changed, where the conversation branched, and what happened afterwards.

  • Lossless. Items are stored as the wire carried them, reasoning and extension types included. Anything a reader does not understand is written back byte for byte.
  • Replayable. Every model call can be rebuilt from the path to its entry: settings, items, compaction. A recorded request_hash (RFC 8785 canonical JSON, SHA-256) lets a reader check its work.
  • Resumable. Run, dispatch and decision entries record what happened around the conversation. For every call without an output, the path says whether it was never started, was in flight when the record stopped, or is waiting on an answer, in any file whose header promises those entries are written.
  • Append-only and crash-tolerant. A session file is always a valid prefix of the run; a line cut short by a crash is reported and skipped.
  • Content-addressed. An entry's id is the hash of its envelope over the hash of its body, and parent is a hash, so a file verifies itself line by line, a leaf commits to its whole path, and two sessions that share history share the same entries. A session that continues from a point in another names that point as its base and opens with the path to it.
  • Tree-shaped context, DAG-shaped provenance. Branching creates children of an earlier entry in the same file, and a context is built by walking one parent. Abandoned branches stay, because they are preference data. Convergence — a subagent's result coming back, a branch merged in — is recorded beside that tree in parents, which says where work came from and never widens the walk.
  • Exportable. One ATIF v1.8 document per root-to-leaf path, with the raw items in the extras, redaction at export and media spilled beside the documents.

The root module depends on openresponses and the standard library alone. Requires Go 1.25. The library is pre-1.0: minor versions may change the API, and CHANGELOG.md records every break.

Install

go get github.com/ChristopherDavenport/agentsession

Recording a session

store, err := jsonl.Open(filepath.Join(home, ".agent", "sessions"))
sess, err := store.Create(ctx, agentsession.Header{
    CWD:     cwd,
    Harness: &agentsession.Harness{Name: "my-agent", Version: "1.0"},
})
id := sess.ID()

// The first entry on a root is a config with the full settings.
cfg, err := agentsession.ConfigFromRequest(openresponses.Request{
    Model: "gpt-5", Instructions: "Be brief.", Tools: tools,
})
store.Append(ctx, id, cfg)
store.Append(ctx, id, agentsession.NewItemEntry(openresponses.UserText("What is 2+2?")))

// Build the request from the tree, send it, record what came back.
c, err := sess.Context()
req, err := c.Request()                 // store: false, no previous_response_id
start := time.Now()
resp, err := client.Create(ctx, req)
_, err = agentsession.RecordResponse(ctx, store, id, req, resp, time.Since(start))

RecordResponse appends the output items and the response entry with the hash of the request it was given. Every append becomes the leaf. sess.Branch(entryID) moves the leaf so the next append forks in place, and appending sess.MarkLeaf() makes that choice durable, so a reopened session resumes from it rather than from the last line; sess.ResetLeaf() starts a new root. sess.Compact(firstKept, summary) and sess.SummarizeBranch(from, summary) build the entries that fold context down or carry it across a branch switch; a caller that split the request input at an index, or kept its last n items, uses sess.CompactFrom(i, summary) or sess.CompactKeeping(n, summary) instead of mapping the index to an entry ID itself. Context.ItemEntries is the mapping, aligned with Context.Items. sess.Verify(responseEntryID) rebuilds the request and checks the hash; it returns ErrNoHash when the response recorded none, so nil means the request was checked and not that there was nothing to check. A fold that keeps an item verbatim from before first_kept records it on the compaction's Pinned, and the context algorithm places those items immediately after the summary, which is where the request that was sent had them.

agentsession.OutputEntries(path, resp) is the rule for finding a response's own output items, over a path the caller already holds. It is what RequestContext removes; a reader that instead serves those items — replaying a recorded call, say — calls the same function, so the two cannot drift into rebuilding different requests from one file.

A harness that composes its instructions from several layers records them as parts, so a change to one layer costs that layer and not the whole prompt:

parts := []agentsession.InstructionPart{
    {ID: "product", Source: "product", Text: productPrompt},
    {ID: "agentsmd", Source: "agentsmd", Text: agentsmd.Render(res.Files)},
    {ID: "agentmemory", Source: "agentmemory", Text: block},
}
cfg, err := agentsession.ConfigFromRequestParts(req, parts...) // the first entry on a root
// ... later, when a layer re-renders ...
if delta := c.Settings.InstructionsDelta(parts); delta != nil {
    delta.InstructionsOmitted = omitted   // what was considered and left out
    store.Append(ctx, id, delta)
}

InstructionsDelta writes the whole ordered list of IDs with the text of the parts that moved and a hash for the parts that did not, and returns nil when nothing moved. Settings.Instructions is always the parts joined with a blank line, so a reader that does not care about the composition sees the string it always saw. agentsession.Continue(ctx, store, id, summary) rolls a session that has outgrown its file into a successor that starts from the old leaf's settings, and marks the old one superseded so a Current listing shows only the successor.

A harness that runs the loop records the lifecycle around it. The header's Records lists the record entry types the writer promises to write whenever their event occurs, so a reader may take their absence as the event not having happened; a converter over a native log that has no such record leaves it empty.

sess, err := store.Create(ctx, agentsession.Header{Records: agentsession.AllRecords})
store.Append(ctx, id, agentsession.NewRunStart("run-1", agentsession.SourceInput, "cron:nightly"))
// ... the request, the response with its function calls ...
store.Append(ctx, id, agentsession.NewDecision("call_1", callEntryID, agentsession.VerdictHold, agentsession.ByPolicy).
    WithReason("destructive; needs approval"))
store.Append(ctx, id, agentsession.NewDispatch("call_2", otherCallEntryID)) // synced before the tool runs
end, err := sess.EndRun(agentsession.ReasonInputRequired, "")           // pending computed from the path
store.Append(ctx, id, end)

An input a harness accepts while a run is in flight, a steer or a follow-up, is recorded before it is acted on:

q := agentsession.NewQueued(item, agentsession.ModeSteer).
    WithTrigger("human", "slack:1758412800.0002", "gateway")
store.Append(ctx, id, q)                 // the gateway can answer 202
// ... when the loop can take it ...
store.Append(ctx, id, q.Drain())         // the item, its source and queued_from

sess.PendingQueued(leaf) lists the inputs that have neither been appended nor been closed by the end of the run they were queued into, which is the inbox a restarted harness drains.

On resume, sess.PendingCalls(leaf) lists the calls without an output and Call.State(header) says what the path knows about each. A run's end reason is a shape of its segment and of the path the segment ends: ComputeReason recomputes it and Run.Verify checks a written one against it. A run that answers a held call and ends without calling the model again, which is what a refusal and a terminating resume are, reads as stopped.

Both file stores guard a session against a second writing process and report agentsession.ErrSessionLocked, the one sentinel for that condition, so a host written against the Store interface tells a session another process holds from a store that is broken without knowing which store it was given. jsonl.WithReadOnly and sqlite.WithReadOnly open a store that takes no lock and refuses every write with agentsession.ErrReadOnly, which is how a session is read while an agent is writing it.

Reading one

f, _ := os.Open("session.jsonl")
sess, err := agentsession.Read(f)
if t := sess.Truncated(); t != nil {
    log.Printf("last line was cut short: %v", t) // the prefix loaded
}
for _, e := range sess.Entries() {
    switch v := e.(type) {
    case *agentsession.ItemEntry:
        fmt.Println(v.Item.ItemType())
    case *agentsession.UnknownEntry:
        fmt.Println("extension", v.Type) // re-emitted verbatim by Write
    }
}

Exporting to ATIF

docs := func(yield func(*atif.Trajectory) bool) {
    for tr, err := range export.Trajectories(sess) {
        if err != nil {
            continue
        }
        doc, err := export.ToATIF(tr, export.Options{
            Redactors: []export.Redactor{
                export.Secrets(os.Getenv("OPENAI_API_KEY")),
                export.HomePaths(home),
            },
        })
        if err != nil || !yield(doc) {
            return
        }
    }
}
err := export.WriteATIF("out/", docs)

export.At(s, entryID) builds the document of the path that ends at one entry, which is what a consumer holding a score needs once the outcomes a judge appended have moved the leaf; Trajectories is that over each leaf. A document's steps are the context after compaction and its final_metrics are the whole path, so a run that folded reports what it spent; total_steps counts the path's model calls, and a line in notes says so where that is not the number of steps, and what the steps leave out. export.WriteDocument writes one document under a name of the caller's, agent/trajectory.json for a Harbor trial, with its media spilled beside it as WriteATIF does. export.Options.ModelName overrides the model name the document reports, for a consumer that derives a provider from it, without changing the name the request was sent with.

Each document is one root-to-leaf path with compaction applied. The session's current path is written as <session-id>.json, the others as <session-id>_<leaf>.json. A branch that was continued lists the leaves it was preferred over in extra.preferred_over; an abandoned one names the fork in extra.abandoned_at. By default the continued branch is the one appended to last; pass export.PreferCurrentLeaf, export.PreferLabel("kept") or export.PreferScore to Trajectories to decide otherwise. export.Items(doc) reads the raw items back out, and export.ItemsFrom(doc) rebuilds them, lossily, from the declared fields of a document any producer wrote. export.NoPassthrough() strips the raw items for a document a judge will read.

Inspecting from a shell

cmd/agentsession reads session files without taking their lock, and opens a store with jsonl.WithReadOnly or cas.WithReadOnly, so every command but repair and migrate is safe to run beside a harness that is writing. Where a command takes a file it also takes a cas store's root and a session id, and reads the session as the file it projects to; a path inside a cas session's directory, its one-line header file included, is read as that session.

go install github.com/ChristopherDavenport/agentsession/cmd/agentsession@latest

agentsession show session.jsonl            # entries in file order, then the context at the leaf
agentsession show session.jsonl -leaf ID   # the context at another entry
agentsession show session.jsonl -v         # with the data of custom and extension entries
agentsession verify session.jsonl          # rebuild every request and check its hash
agentsession export session.jsonl -out dir -secret "$OPENAI_API_KEY" -redact-home
agentsession list ~/.agent/sessions        # a jsonl store's sessions, newest first
agentsession list ~/.agent/sessions -current   # leave out sessions continued in a successor
agentsession list ~/.agent/cas             # a cas store's sessions, the same columns
agentsession show ~/.agent/cas ID          # any command, on a session a cas store holds
agentsession verify ~/.agent/cas           # the whole store, as git fsck: journal, objects, sessions
agentsession repair ~/.agent/cas ID -dry-run   # what a repair of a damaged session log would keep
agentsession repair ~/.agent/cas ID        # rewrite it from the records that read, keeping the old log
agentsession migrate ~/.agent/cas          # migrate a cas store v0.0.15 or earlier wrote

verify exits 1 on a file with a header and no entries, since nothing was checked, and on a mismatch, a truncated final line, a run end that disagrees with its segment, a dispatch after a reject or an answer, or a call that ran without the dispatch the header promised. On a session a cas store holds it also exits 1 on a subsession link whose session's header names another parent or another call, which is what a line moved to a fork after a call ID collision leaves when a level of its subsessions was not re-derived; a file names no store to find the child in, so a file's links go unchecked, and a child the store lacks is one that never started. export writes one ATIF document per leaf and embeds a linked subsession when its file is beside the exported one or in the same store. repair takes the session's lock and writes: it rewrites a cas session whose log has a record that fails its checksum, as cas.Store.Repair does. migrate opens a cas store for writing, which migrates a store v0.0.15 or earlier wrote; no read-only open reads a session of such a store until one has, and no release before v0.0.16 reads it after. On such a store, stop every writer, take a copy, run migrate, then upgrade the readers and the writers together. A migrated store's journal is a dangling symbolic link by design, which keeps a writer of v0.0.15 or earlier from writing to it; a copy that follows links (cp -L, rsync without -l) reports or skips it, and the next writing open puts it back.

Tracing

The otel module is the RFC's OpenTelemetry projection. otel.Export replays a session's path into any tracer with the entries' own timestamps: a session span, a span per run carrying its source and end reason, a chat <model> span per model call that links the previous turn's, and an execute_tool <name> span per call that links the inference that produced it and carries each decision as an event and the call's state when the record stopped. otel.Wrap decorates a store so a live harness emits the same spans as it appends, and a session reopened in a new process picks up the calls the last one left pending.

store := otel.Wrap(jsonlStore, otel.Tracer("my-agent"))
// ... record as usual; call store.Close(sessionID) when done ...

_, err := otel.Export(ctx, tracer, sess, sess.Leaf()) // a stored session, after the fact

Packages

package purpose
agentsession header, entries, tree, context algorithm, request hash, Store interface, in-memory store
cas the content-addressed store RFC 0002 describes, laid out like a git repository: bodies and envelopes as objects under their hashes, held once however many sessions share them; a session as a ref with a header, a base, a HEAD and a log; a journal as the commit point, replayed on open; a head compare-and-swap; a record or mirror mark; projection to a JSONL file with the synthetic leaf marker, import held to a push's checks, push and fetch between stores, packs and a sweep that repacks as git's gc does, a sync policy, a read-only open, and a verify that walks the store as git fsck does
jsonl the file store: one JSONL file per session with a sync policy, crash recovery and a per-session lock against a second writing process, reporting a dead holder's lock when it takes one over, or read-only and taking no lock
sqlite a SQLite store, as a nested module so its driver stays out of the library, holding each open session against a second process, or read-only and taking no hold
otel the OpenTelemetry projection, as a nested module: replay a session as spans, or wrap a store so a live run emits them
atif Go types for ATIF v1.8 with unknown-member passthrough and validation
export trajectories, ATIF conversion, redactors, writer
storetest the conformance suite every store runs
cmd/agentsession the command: show, verify, export and list session files and the sessions of a jsonl or cas store

Interoperating

Three things a writer built elsewhere must agree on are written in the RFC rather than shared as code: the request hash, the link entry for subsessions, and the subsession ID, a UUIDv5 under the nil namespace over <parent session id>/<call_id> that SubsessionID derives. testdata/hash/vectors.json holds request documents and their hashes so another implementation can test itself against the same inputs. The Python one-liner json.dumps(obj, sort_keys=True, separators=(",", ":"), ensure_ascii=False) reproduces the canonical form for requests whose numbers are integers.

Development

make check   # gofmt, vet, deps, staticcheck, govulncheck, race tests

See CONTRIBUTING.md. The format is specified in docs/rfcs/0001-agent-session-format.md and the library design in docs/plans/session-layer.md.

Documentation

Overview

Package agentsession implements the Agent Session Format: an append-only, tree-structured JSONL record of one agent session whose conversation payloads are Open Responses items. The format is specified in docs/rfcs/0001-agent-session-format.md; this package is its reference implementation.

Shape

A session file is a header line followed by entries, one JSON object per line. An entry's id is the hash of its envelope over the hash of its body, and parent names a parent by hash, so a file verifies itself and a leaf commits to its whole path; Session.Append computes both. Entries form a tree through those members, so a branch is a child of an earlier entry, in place, and an abandoned branch stays in the file. A session made with Fork continues from an entry of another, its base, and opens with the path to it. An entry may also name further predecessors in EntryBase.Parents — a subagent's result, a branch merged back — which record where converged work came from and are never walked when building a context. Header and Entry are the two line shapes; the concrete entry types are ItemEntry (one Open Responses item, verbatim), ResponseEntry (the envelope of one model call), ConfigEntry (a delta to request settings), CompactionEntry and BranchSummaryEntry (summaries that enter context), and the out-of-context LabelEntry, InfoEntry, EnvEntry, OutcomeEntry, LinkEntry and CustomEntry. Namespaced types decode to UnknownEntry and are written back byte for byte, as are namespaced items inside an item entry.

Sessions

Session is the tree in memory: Read loads one, Write emits one, and Session.Append adds an entry as a child of the current leaf. Session.Branch moves the leaf so the next append forks; a fresh root follows Session.ResetLeaf. A file cut short by a crash still loads, and Session.Truncated reports the broken line.

Context

Session.ContextAt runs the format's context algorithm: it walks the path to an entry, replays config entries into Settings, applies the last compaction and returns the item list a model call there would receive. Settings.Request turns that into the canonical openresponses.Request, and RequestHash hashes it as the format defines (RFC 8785 canonical JSON, SHA-256). Session.Verify checks a stored response's hash against the rebuilt request, and reports ErrNoHash rather than nil when the response recorded none.

Stores

Store is the persistence interface; MemoryStore is the in-memory one and the jsonl subpackage is the file store. The storetest subpackage is the conformance suite every store runs.

Export

The export subpackage turns a session's root-to-leaf paths into ATIF documents, using the types in the atif subpackage, with the raw items carried in the extras so nothing is lost.

Index

Constants

View Source 
const (
	TypeItem          = "item"
	TypeResponse      = "response"
	TypeConfig        = "config"
	TypeCompaction    = "compaction"
	TypeBranchSummary = "branch_summary"
	TypeLabel         = "label"
	TypeInfo          = "info"
	TypeEnv           = "env"
	TypeOutcome       = "outcome"
	TypeLink          = "link"
	TypeCustom        = "custom"
)

Entry types defined by the format. Any other type of the form "ns:name" is an extension and decodes to UnknownEntry.

View Source 
const (
	RelSubsession  = "subsession"
	RelForkOf      = "fork_of"
	RelContinuedIn = "continued_in"
	// RelJudgedBy is written into a judged session and names the
	// session of its judge; see [NewJudgedByLink] and [Judges].
	RelJudgedBy = "judged_by"
)

Relations a LinkEntry may carry.

View Source 
const (
	OutcomeFeedback  = "feedback"
	OutcomeTest      = "test"
	OutcomeTask      = "task"
	OutcomeToolError = "tool_error"
	OutcomeEval      = "eval"
	OutcomeCustom    = "custom"
)

Kinds an OutcomeEntry may carry.

View Source 
const (
	MediaInline  = "inline"
	MediaSidecar = "sidecar"
)

Media storage modes named by the header.

View Source 
const (
	TypeRun      = "run"
	TypeDispatch = "dispatch"
	TypeDecision = "decision"
	TypeQueued   = "queued"
)

Record entry types added in format 0.2, and queued in 0.3. They are never in context.

View Source 
const (
	ModeSteer    = "steer"
	ModeFollowUp = "followup"
)

Modes a QueuedEntry may carry: an input that joins the run in flight, and one that waits for it to end.

View Source 
const (
	RunStart = "start"
	RunEnd   = "end"
)

Phases of a RunEntry.

View Source 
const (
	SourceInput  = "input"
	SourceResume = "resume"
)

Sources of a run, on its start entry. Both are shapes of the path: a resume's first function call output, decision or dispatch takes up a call that was pending when the run began, whatever messages come before it; an input is everything else, a retry after an error included.

View Source 
const (
	ReasonDone          = "done"
	ReasonStopped       = "stopped"
	ReasonInterrupted   = "interrupted"
	ReasonInputRequired = "input_required"
	ReasonAborted       = "aborted"
	ReasonError         = "error"
)

Reasons a run ended, on its end entry. The first five are computable from the run's segment and the path it ends by ComputeReason; ReasonError and ReasonInterrupted are the two a writer adds where the segment cannot show them, and a written one stands over any segment.

View Source 
const (
	VerdictProceed = "proceed"
	VerdictReject  = "reject"
	VerdictHold    = "hold"
	// VerdictAnswer ends a call that may already have run, one in
	// flight when the record stopped or one the file cannot say about,
	// with an output the harness wrote rather than one its tool
	// returned: the call is not handed to its tool again. By says who
	// answered and Reason why.
	VerdictAnswer = "answer"
)

Verdicts a DecisionEntry may carry, each defined by what follows the decision on the path: a dispatch, an output carrying the reason, nothing, or an output the harness wrote for a call that may already have run.

View Source 
const (
	ByHuman  = "human"
	ByPolicy = "policy"
	ByAgent  = "agent"
)

Deciders a DecisionEntry may name.

View Source 
const (
	WorkspaceLocal     = "local"
	WorkspaceContainer = "container"
	WorkspaceRemote    = "remote"
)

Workspace kinds an EnvEntry may name.

View Source 
const Format = "agentsession/0.11"

Format is the session format version this package writes.

View Source 
const FormatMajor = 0

FormatMajor is the major version of the format this package reads. Any minor version of it is accepted; files are migrated in memory.

View Source 
const FormatMinor = 11

FormatMinor is the minor version this package writes. A file of an earlier minor is migrated in memory on read: from 0.5 an entry's id is its envelope hash, so every earlier entry is rehashed and keeps its old id in legacy_id. A 0.5 to 0.9 file reads as it stands, since 0.6 to 0.9 only add optional members and elements and 0.10 lets a dispatch elsewhere in the session stand for one on the path, for the answer rule and against the call having never started, which reads a 0.9 file's rebased call differently too; and for two rules 0.8 reads differently: instructions_omitted stays in force until a later config changes it, and a run whose pending call is held after its dispatch ends input_required, not aborted. 0.9 lets instructions_omitted name a run of the list in force by keep, which no 0.8 omitted part could be. 0.10 also marks a file written under 0.9's rules as they stood when they stopped changing. 0.11 accepts a run written resume over a segment that holds nothing, in a 0.9 or 0.10 file too, and adds the of member of an omitted keep, the omit setting, the judged_by link relation and the target member of a link; its writer names an instructions part out of force by its hash.

View Source 
const HashPrefix = "sha256:"

HashPrefix precedes the hexadecimal digest in a request hash.

View Source 
const LeafLabel = "leaf"

LeafLabel is the reserved label that makes the leaf durable. A label entry carrying it names the branch the next append should continue, not a fixed entry to pin the leaf at: Session.Append keeps the leaf at the label's target rather than moving it to the label entry, and Read resolves the leaf to the newest entry appended under that target after the label, so a branch marked and then written on resumes where it was written to rather than rewinding to the mark. A mark nothing followed resolves to itself. A null label on the same target clears it. The format holds this as a library convention; see the RFC's open questions.

View Source 
const MaxOriginDepth = 64

MaxOriginDepth bounds the chain of forks OriginDispatches walks: a fork of a fork of a fork, each made at an entry of the prefix the one before carried. The header's parent_session is provenance the format does not validate, so a chain may fail to end where a store is damaged, and a walk that reaches the bound reports it rather than going on.

View Source 
const MaxRefName = 200

MaxRefName is the longest ref name, in bytes.

View Source 
const OmitItems = "items"

OmitItems is the reason a Context reports for an item left out because Omit.Items lists its entry.

View Source 
const OmitOtherModels = "other_models"

OmitOtherModels is the one value of Omit.Reasoning the format defines: a request leaves out each item entry holding a reasoning item that carries a response and was written while a model other than the request's was in force. It is also the reason a Context reports for an item left out by that rule.

View Source 
const PartSeparator = "\n\n"

PartSeparator joins the instruction parts into the instructions string. The rule is the format's, so a writer that records parts and a reader that rebuilds the string produce the same bytes and the request hash verifies.

View Source 
const Payload = "openresponses/" + openresponses.SpecVersion

Payload is the payload profile this package writes: Open Responses items at the specification version openresponses targets.

Variables

View Source 
var AllRecords = []string{TypeRun, TypeDispatch, TypeDecision}

AllRecords are the three record entry types a harness that runs the loop itself can promise: run, dispatch and decision. A harness that also accepts inputs while a run is in flight adds TypeQueued, which promises that every such input is recorded as a queued entry before it is acted on, so a reader may take the absence of one as nothing having been queued.

View Source 
var ErrAnswerNotDispatched = errors.New("agentsession: answer for a call the record shows never started")

ErrAnswerNotDispatched is returned when an answer decision is appended for a call with no dispatch in a session whose header promises dispatch records: the record says that call never started, so it did not run, and a writer that ends it without running it writes a reject.

View Source 
var ErrBadConvergence = errors.New("agentsession: bad convergence reference")

ErrBadConvergence is returned for an entry whose Parents break the format's rules: a reference naming no entry, the same entry named twice, a reference to the entry's own parent, or a reference into this session naming an entry that does not already exist.

View Source 
var ErrBadID = errors.New("agentsession: entry id does not match its hash")

ErrBadID is returned by Append for an entry whose ID was set by the caller and does not match the hash the format defines, and by Read for a line whose id does not verify.

View Source 
var ErrBadNormalisation = errors.New("agentsession: normalised entry is malformed")

ErrBadNormalisation is returned for a Normalisation a caller set that the format cannot carry: no pointer, or not exactly one of Was and Raw.

View Source 
var ErrBadTarget = errors.New("agentsession: target does not name the call")

ErrBadTarget is returned when a decision or dispatch is appended whose target is not the entry of a function call on the path with the decision's call ID: a target names the call, and its call ID must agree.

View Source 
var ErrBaseRule = errors.New("agentsession: entry breaks the base rule")

ErrBaseRule is returned for an entry that breaks the rule a base imposes on a session: the entries before the base are the path to it, one root and each the child of the one before, and every entry after it hangs from the base or from an entry after it, never from null, since a session with a base has one root, and never from the prefix above the base, since the prefix is another session's record and branching above the base is a new session with a lower base. Read and Scan hold a file's lines to it and Append the entry it is given, so a file that reads is one Append can continue. An error reporting it is also ErrNoEntry under errors.Is, which Append returned for it before this sentinel existed.

View Source 
var ErrCallAnswered = errors.New("agentsession: call was answered")

ErrCallAnswered is returned when a dispatch or a decision is appended for a call that an answer decision on the path already ended: what follows an answer is the call's output and nothing else.

View Source 
var ErrCallCompleted = errors.New("agentsession: call has its output")

ErrCallCompleted is returned when an answer, a reject or a dispatch is appended for a call whose output is already on the path: the output ends the call, and an answer or reject is for a call that has none.

View Source 
var ErrCallIDEmpty = errors.New("agentsession: function call has no call ID")

ErrCallIDEmpty is returned when a function call is appended with no call ID, and by Session.VerifyRecords for a session that holds one: nothing could name the call, not its output, a decision or a pending list.

View Source 
var ErrCallIDRepeated = errors.New("agentsession: call ID repeated")

ErrCallIDRepeated is returned when a function call is appended whose call ID another function call in the session has, on any branch, and by Session.VerifyRecords for a session that holds two: a call ID names one call in a session.

View Source 
var ErrCallRejected = errors.New("agentsession: call was rejected")

ErrCallRejected is returned when a dispatch or a decision is appended for a call that a decision on the path already rejected: what follows a reject is the call's refusal output and nothing else.

View Source 
var ErrHashMismatch = errors.New("agentsession: request hash mismatch")

ErrHashMismatch is returned by Session.Verify when the rebuilt request does not hash to the recorded value.

View Source 
var ErrLinkMismatch = errors.New("agentsession: subsession link disagrees with its target's header")

ErrLinkMismatch is returned by Session.VerifyLinks for a subsession link whose target's header names another session as its parent, or another call as the one that spawned it. The link and the header are two records of one spawn, written by the parent and by the child, and RFC 0001 has them agree. The disagreement is what a line moved to a fork after a call ID collision leaves behind when its links were not pointed at the subsessions re-derived under the fork's ID: two stores derive one ID for the subsession of one call, so the link names the other store's subagent, and only that session's header says so.

View Source 
var ErrNoEntry = errors.New("agentsession: no such entry")

ErrNoEntry is returned when an entry ID is not in the session.

View Source 
var ErrNoHash = errors.New("agentsession: no request hash recorded")

ErrNoHash is returned by Session.Verify for a response entry that recorded no request hash. The response is not verified and not mismatched: there was nothing to check. A writer records no hash when it cannot stand behind one, which is what a layer that edits the request outside the transcript leaves behind, so a caller that accepts unverified requests opts in with errors.Is rather than by reading err == nil.

View Source 
var ErrNoRef = errors.New("agentsession: no such ref")

ErrNoRef is returned by ResolveRef when the store holds no ref of the name.

View Source 
var ErrNoRefs = errors.New("agentsession: store does not keep refs")

ErrNoRefs is returned by the helpers that need refs when the store does not keep them.

View Source 
var ErrNoSession = errors.New("agentsession: no such session")

ErrNoSession is returned when a session ID is not in the store.

View Source 
var ErrNotGit = errors.New("agentsession: not a git checkout")

ErrNotGit is returned by GitRevision when dir is not inside a git checkout.

View Source 
var ErrOmitDivergence = errors.New("agentsession: the recorded hash is the request without the omit setting applied")

ErrOmitDivergence is wrapped, beside ErrHashMismatch, by the error that Session.Verify returns when the response's recorded hash is the request built with the items the omit in force leaves out: the writer sent, or hashed, what the record says a request leaves out. It is a divergence between the record and its own rule, and not a response that recorded no hash.

View Source 
var ErrOriginChain = errors.New("agentsession: the chain of forks does not end")

ErrOriginChain is returned by OriginDispatches when the sessions a fork was made from do not end: parent_session names a session already on the walk, or the walk reaches MaxOriginDepth.

View Source 
var ErrReadOnly = errors.New("agentsession: store is read-only")

ErrReadOnly is returned by a store opened read-only when a caller tries to write: such a store takes no hold on the sessions it opens, so it must not append to them either. Reading a session while a harness writes it is what it is for.

View Source 
var ErrReasonMismatch = errors.New("agentsession: run end disagrees with its segment")

ErrReasonMismatch is returned by Run.Verify when a run's written end reason or pending list disagrees with its segment.

View Source 
var ErrRecordMissing = errors.New("agentsession: promised record entry missing")

ErrRecordMissing is returned by Session.VerifyRecords when the header promises a record entry type and the path lacks one where the event plainly happened.

View Source 
var ErrRefMoved = errors.New("agentsession: ref moved")

ErrRefMoved is returned by UpdateRef when the ref does not hold the expected target. The error wraps it as a RefMovedError, which carries the target the ref holds.

View Source 
var ErrRefName = errors.New("agentsession: invalid ref name")

ErrRefName is returned for a name or prefix RFC 0002 does not allow, and for a name that conflicts with a ref the store holds.

View Source 
var ErrRejectDispatched = errors.New("agentsession: reject for a call that was dispatched")

ErrRejectDispatched is returned when a reject is appended for a call that has a dispatch on the path: a reject says the call did not run, and one that may have run is ended by an answer.

View Source 
var ErrReservedMember = errors.New("agentsession: body carries a reserved envelope name")

ErrReservedMember is returned for a body carrying a top-level member by one of the envelope's names.

View Source 
var ErrScanMigrated = errors.New("agentsession: a file before 0.5 has no hashed ids to scan; read it")

ErrScanMigrated is returned by Scan for a file of a minor before 0.5, whose entries carry no hashes to verify: Read migrates one.

View Source 
var ErrSessionExists = errors.New("agentsession: session already exists")

ErrSessionExists is returned when Create is given an ID already in the store.

View Source 
var ErrSessionLocked = errors.New("agentsession: session is open in another process")

ErrSessionLocked is returned by a store whose session is held by another process. It is the one sentinel for that condition: each store wraps it, so a host written against the Store interface can tell "another process has this session", which means leave the conversation alone, from a store that is broken, which means the daemon is unhealthy, without knowing which store it was given.

View Source 
var ErrSourceMismatch = errors.New("agentsession: run source disagrees with its segment")

ErrSourceMismatch is returned by Session.VerifyRecords for a run start whose source is not the shape of its segment; see ComputeSource. A run written resume over a segment that holds nothing is not one, as Run.Empty says.

View Source 
var ErrSuperseded = errors.New("agentsession: session was continued in a successor")

ErrSuperseded is returned by a store that refuses to append to a session a continued_in link has retired. No store in this module refuses; the error is here for one that wants to.

View Source 
var ErrUnresolvedMigration = errors.New("agentsession: migrated session holds entries that could not be rewritten")

ErrUnresolvedMigration is returned by Write for a session migrated from an earlier minor version that holds an entry the migration could not rewrite.

View Source 
var ErrUnsupportedFormat = errors.New("agentsession: unsupported format")

ErrUnsupportedFormat is returned when a header names a format this package cannot read.

Functions

func CanonicalRequest added in v0.0.19 

func CanonicalRequest(req openresponses.Request) (openresponses.Request, error)

CanonicalRequest returns req as its canonical JSON (RFC 8785) decodes: every member inside opaque JSON, such as a tool's parameter schema, in canonical order and spelling. A request rebuilt from a session equals the one sent under canonical JSON, not in bytes: a cas store holds bodies in canonical form, while a jsonl file gives members as they were written. A renderer that turns a request into tokens passes the live request and the rebuilt one through CanonicalRequest alike, and then renders the same bytes from either. It does not change the request hash.

func CanonicalTime added in v0.0.8 

func CanonicalTime(t time.Time) string

CanonicalTime renders t in the one form the format admits for ts: UTC, uppercase T and Z, a fractional part only when non-zero, with no trailing zeros and at most nine digits. It is what Go's RFC3339Nano layout produces for a UTC time, so a time.Time round trips unchanged, which is the property the rule was chosen for.

func ComputeReason added in v0.0.5 

func ComputeReason(path, segment []Entry) string

ComputeReason recomputes a run's end reason from its segment and the root-first path the segment ends, as the format defines it: the first of error, input_required, aborted, done and stopped whose shape they match, with aborted again as the value for anything left. A nil path means the segment stands for the path. It never returns ReasonInterrupted, and returns ReasonError only for a response that carries an error; both are values a writer adds where the segment cannot show them.

A pending call is one of the run's calls, as Run.Calls has them, with no output: a call made before the segment counts once the segment holds a decision, dispatch or output for it, so a resume that holds such a call before any model call ends input_required.

The stopped step reads the path because a run that answers a call and ends without calling the model again, which is what a resume whose tool asks to terminate and a refusal both are, holds no response of its own: the response that made the calls is on the path before the segment.

func ComputeSource added in v0.0.17 

func ComputeSource(r *Run) string

ComputeSource returns the source a run's start names, by the format's rule: SourceResume when the segment's first function call output, decision or dispatch takes up a call that was on the path with no output when the run began, whatever messages come before it, and SourceInput otherwise, a run that takes up nothing included. A run built by hand with no Path has nothing before its segment, so it is an input.

It is the shape the segment shows, which is not always what the writer meant: a run started to take up a call and ended before it did has an empty segment, which computes as an input. Format 0.11 accepts such a run written SourceResume as it is written, and Session.VerifyRecords does not report it; a writer still computes the source it writes at start from what it knows then, and need not change.

func EntryHashes added in v0.0.8 

func EntryHashes(data []byte) (id, content string, err error)

EntryHashes computes an entry's two hashes from its encoded form, a JSON object with the envelope members in it: the content hash over the body, the members outside the envelope, and the id over the envelope object — type, parent, parents when present and non-empty, ts, and content holding the content hash. The id member in data, if any, is ignored; ts is taken as the string it is. Both are "sha256:" plus lowercase hex over the canonical bytes.

func GitRevision 

func GitRevision(dir string) (string, error)

GitRevision returns the commit HEAD points at for the checkout containing dir, reading .git directly so no git binary is needed. It follows symbolic refs through loose refs and packed-refs and handles worktrees and submodules whose .git is a file.

func HashBytes 

func HashBytes(data []byte) string

HashBytes returns the content hash of data in the env entry's form.

func HashFile 

func HashFile(path string) (string, error)

HashFile returns the content hash of a file in the form the env entry uses: "sha256:" followed by lowercase hex.

func HashFiles 

func HashFiles(dir string, paths ...string) (map[string]string, error)

HashFiles hashes each path, keyed as given. Paths are hashed as they are; callers that want keys relative to a directory pass them that way and resolve against dir.

func HashRequestJSON 

func HashRequestJSON(data []byte) (string, error)

HashRequestJSON computes the request hash of an already-encoded request. Member order and whitespace in data do not matter.

func HashText added in v0.0.6 

func HashText(s string) string

HashText returns the hash of a string in the format's notation, which is HashBytes over its UTF-8 bytes: HashPrefix and the lowercase hexadecimal SHA-256. It is how a config delta names the text of an instructions part it does not repeat, so a reader can tell the part it already has from one that changed.

func HeaderIdent added in v0.0.21 

func HeaderIdent(h Header) (string, error)

HeaderIdent names a session's incarnation: the hash of its header without `format`, which is all a writer's rewrite of a session changes, as a follower tells one session from another created again under its ID. A store records it with each ref it sets and compares it at resolution, so a ref to a deleted session never reaches a session created later under that ID. It is the store's, and no RefTarget carries it.

func InContext 

func InContext(e Entry) bool

InContext reports whether an entry contributes an item to the model context: item, branch_summary and compaction entries do. Whether a compaction is actually selected depends on the path; see Session.ContextAt.

func IsExtension 

func IsExtension(typ string) bool

IsExtension reports whether typ is a namespaced extension type.

func JoinInstructions added in v0.0.6 

func JoinInstructions(parts []InstructionPart) string

JoinInstructions returns the instructions the parts compose: their texts joined with PartSeparator, in order.

func MarshalEntry 

func MarshalEntry(e Entry) ([]byte, error)

MarshalEntry encodes one entry as a single JSON line without the trailing newline. The envelope members come first in a fixed order, then the type's members, then any unknown members in key order.

func NewBaseRuleError added in v0.0.20 

func NewBaseRuleError(detail string) error

NewBaseRuleError returns an error reporting that an entry breaks the base rule, with detail saying how: ErrBaseRule and ErrNoEntry both under errors.Is, as the session reports it. A store that meets the rule before the session does, as one recording a reset leaf on a session with a base, reports it the same way.

func NewEntryID 

func NewEntryID() string

NewEntryID returns a short random entry ID: eight hexadecimal characters. Session.Append regenerates on the rare collision within a file, so callers need not check.

func NewSessionID 

func NewSessionID() string

NewSessionID returns a UUIDv7 in its canonical text form. The leading 48 bits are the current Unix time in milliseconds, so IDs sort by creation time; the rest is random.

func OriginDispatches added in v0.0.20 

func OriginDispatches(ctx context.Context, r Reader, s *Session, callEntry string) (*Session, []*DispatchEntry, error)

OriginDispatches returns the dispatches for the call whose function call is the entry callEntry, and the session holding them. They are s's own, as Session.Dispatches has them, when s holds any. A call in a fork's prefix has its dispatches, if any, in the session the fork was made from, which the fork's file does not carry: for such a call with none in s, the session the header's ParentSession names is read through r and asked the same, and so up a chain of forks, each made at an entry on the prefix the one before carried, to MaxOriginDepth. A dispatch found there is read as one off the path, which a rebase above a dispatch leaves: the call may have run, under that dispatch's key and with the arguments it handed over, and its output, when the origin holds one, is on that origin's branch. It returns nil, nil and no error when no session on the walk holds one, when the walk reaches a session that names no parent, when r does not hold the session named (ErrNoSession), or when r is nil, which reads s alone. Any other error reading an origin is returned, wrapping the store's, and so is ErrOriginChain for a chain that does not end.

The store is passed, not read behind the caller's back: an Open or a Read of a fork does not go and read other sessions, so a reader that wants a prefix call's dispatches asks for them here, with the store it holds. Call.State reads a prefix call with no dispatch on its path as CallUnknown either way; what this adds is the dispatch itself.

func ParseCanonicalTime added in v0.0.8 

func ParseCanonicalTime(s string) (time.Time, bool)

ParseCanonicalTime parses s and reports whether it is spelled in the canonical form: a spelling the format admits renders back to itself.

func ParseFormat 

func ParseFormat(format string) (major, minor int, err error)

ParseFormat splits a format string such as "agentsession/0.1" into its major and minor versions.

func RecordResponse 

func RecordResponse(ctx context.Context, store Store, sessionID string, req openresponses.Request, resp *openresponses.Response, latency time.Duration) (string, error)

RecordResponse writes one model call to a session: every output item of resp as an item entry carrying resp.ID, then the response entry with the response's model, status, usage, incomplete details, error, the hash of req and the latency. req must be the request as it was sent, so the recorded hash is the one a reader rebuilds from the path; pass a zero latency to leave latency_ms out. It returns the ID of the response entry.

The caller records the user items and function call outputs that precede the request before calling this, as the format requires.

func RefConflict added in v0.0.21 

func RefConflict(name string, existing []string) error

RefConflict reports whether creating name beside the refs in existing breaks RFC 0002's rules on names: name is an existing ref's name, or a prefix of one, or has one as a prefix, at a segment boundary (a ref under a ref), or some prefix of it at a segment boundary differs only in ASCII case from the same-length prefix of an existing name. It returns nil for a name that is itself in existing and spelled the same, which creates nothing new.

func RequestHash 

func RequestHash(req openresponses.Request) (string, error)

RequestHash computes the request hash the format defines: the request serialised with the JSON Canonicalization Scheme (RFC 8785) and digested with SHA-256, rendered as "sha256:" plus lowercase hex. The input must be the request as it was sent, passthrough members included, because those reached the model.

func ResolveCurrent added in v0.0.21 

func ResolveCurrent(ctx context.Context, st Store, name string) (id string, moved bool, err error)

ResolveCurrent returns the session that is current for name: the ref's target, followed along continued_in links to the end of the chain. moved reports that it followed at least one, which says the ref is behind, as after a writer that continued the session and stopped before it moved the ref. It stops at a cycle with an error. The store's ResolveRef stays literal; this is the caller's choice.

It reads sessions through Reader when the store is one, and otherwise with Open.

func SameWorkspace added in v0.0.10 

func SameWorkspace(a, b *Workspace) bool

SameWorkspace reports whether two workspace members are the same under the format's substitution rule: compared member by member in their canonical form, the ones the format does not define included, and an absent one equal only to another absent one. An empty kind or ref is the same as an absent one, as the format says. An env entry whose workspace is not the same as the one in force before it on the path is a substitution.

func SubsessionID added in v0.0.5 

func SubsessionID(parentSessionID, callID string) string

SubsessionID derives the session ID the format recommends for a subsession: a UUIDv5 under the nil namespace over "<parent session id>/<call_id>", so a reader can compute the child's ID from the parent's link or function call alone, before or after the child exists. A second child for the same call appends a new root to the existing child session rather than minting a second ID.

func ToolName 

func ToolName(t openresponses.Tool) string

ToolName returns the name of a tool: the function name for a function tool, the "name" member of an extension tool when it has one, else "".

func ValidHash added in v0.0.8 

func ValidHash(s string) bool

ValidHash reports whether s is a hash in the format's notation: "sha256:" followed by exactly 64 lowercase hexadecimal characters. Anything a store puts on a filesystem as a hash is checked with it.

func ValidRefName added in v0.0.21 

func ValidRefName(name string) error

ValidRefName reports whether name is a ref name by RFC 0002's rules, which are about the name alone: segments of [A-Za-z0-9._-] joined by "/", none empty, "." or "..", ending in a dot or naming a Windows device, at most MaxRefName bytes. A store checks what depends on the refs it holds with RefConflict.

func ValidRefPrefix added in v0.0.21 

func ValidRefPrefix(prefix string) error

ValidRefPrefix reports whether prefix can begin a ref name: the empty prefix, or characters a name allows and "/". It need not end at a segment boundary.

func Write 

func Write(w io.Writer, s *Session) error

Write encodes the session as JSONL: the header, then every entry in file order, one per line, each in its canonical form. Preservation is of members and not bytes, and the hashes are over canonical forms, so a canonical line is what a reader verifies most directly. A session migrated from an earlier minor version that holds an entry the migration could not rewrite is refused, since the format forbids re-emitting such a file as 0.5.

Types

type BranchSummaryEntry 

type BranchSummaryEntry struct {
	EntryBase `json:"-"`
	From      string               `json:"from"`
	Summary   openresponses.Item   `json:"summary"`
	Usage     *openresponses.Usage `json:"usage,omitempty"`
}

BranchSummaryEntry carries context across a branch switch. Its parent is where the new branch continues; From is the leaf that was left. It is in context through its summary.

func (*BranchSummaryEntry) EntryType 

func (*BranchSummaryEntry) EntryType() string

EntryType returns "branch_summary".

func (*BranchSummaryEntry) MarshalJSON 

func (e *BranchSummaryEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits the entry as one JSON object.

func (*BranchSummaryEntry) UnmarshalJSON 

func (e *BranchSummaryEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the entry.

type Call added in v0.0.5 

type Call struct {
	// Entry is the item entry holding the function call.
	Entry *ItemEntry
	// Call is the function call item.
	Call *openresponses.FunctionCall
	// Decisions are the decisions on the call, in path order.
	Decisions []*DecisionEntry
	// Dispatch is the first dispatch entry, or nil when none is on the
	// path.
	Dispatch *DispatchEntry
	// Dispatches are the dispatch entries, in path order: one for each
	// time the call was handed to its tool, so a call run again after a
	// restart has two. Dispatch is the first of them.
	Dispatches []*DispatchEntry
	// Output is the item entry holding the function call output, or nil
	// when the call is pending.
	Output *ItemEntry
	// contains filtered or unexported fields
}

Call is one function call on a path and everything that happened to it there: the decisions made about it, its dispatches and its output.

func Calls added in v0.0.5 

func Calls(path []Entry) []*Call

Calls collects the function calls on a root-first path, in the order their items appear, with the decisions, dispatch and output the path holds for each. A decision or dispatch belongs to the call its target names, an output to the latest call before it with its call ID, as the format has it; one whose call is not on the path is ignored.

func (*Call) Answered added in v0.0.11 

func (c *Call) Answered() bool

Answered reports whether a decision ended the call with an output the harness wrote rather than one its tool returned: a call that may have run, answered without being handed to its tool again.

func (*Call) Args added in v0.0.5 

func (c *Call) Args() string

Args returns the arguments the tool runs with: those of the last decision that rewrote them, else the call's own. An answer's args are passed over: no tool ran with them, the format says they name nothing, and reading them here would show an output the harness wrote as a rewrite of what the tool runs with. They are read from the decision itself.

func (*Call) DispatchedArgs added in v0.0.11 

func (c *Call) DispatchedArgs() string

DispatchedArgs returns the arguments the call's last dispatch handed its tool: those of the last decision before it that rewrote them, else the call's own. It is "" when the call has no dispatch. A replay rule deciding whether that hand-off may run again reads these beside Call.IdempotencyKey; Call.Args are the arguments a new hand-off would run with, which a later decision may have changed.

func (*Call) From added in v0.0.8 

func (c *Call) From() []EntryRef

From returns the predecessors the call's output converges: for a call a subagent answered, the leaf of the child session the answer was taken from, which the format says the output entry SHOULD name and which is the first moment the parent knows it. It is nil for a pending call, and for an output whose writer recorded no provenance.

A LinkEntry names the child session and is written when the call is dispatched, before the child has a point to name; this is the other half of that round trip. Without it, a child that branched leaves no record of which of its leaves answered, and a projection has to choose.

func (*Call) Held added in v0.0.5 

func (c *Call) Held() bool

Held reports whether the call is waiting on an answer: its latest decision is a hold and no dispatch follows it. A hold after a dispatch is a call that may have run and waits on someone to say whether it runs again; it is held, and its Dispatches say it may have run.

func (*Call) ID added in v0.0.5 

func (c *Call) ID() string

ID returns the call ID.

func (*Call) IdempotencyKey added in v0.0.11 

func (c *Call) IdempotencyKey() string

IdempotencyKey returns the key the call's last dispatch handed its tool, or "" when it has no dispatch or the dispatch no key. It is the key a further run of that hand-off repeats, and it pairs with Call.DispatchedArgs: a harness that ran the call again under a new key, which it does for new arguments, made a new operation, and the key of an earlier dispatch describes the earlier arguments.

func (*Call) InFlight added in v0.0.11 

func (c *Call) InFlight() bool

InFlight reports whether the call was handed to its tool when the record stopped: it has a dispatch and no output, and no decision after its last dispatch holds it or answers it. Its side effect may have happened.

func (*Call) Pending added in v0.0.5 

func (c *Call) Pending() bool

Pending reports whether the call has no output on the path.

func (*Call) Rejected added in v0.0.5 

func (c *Call) Rejected() bool

Rejected reports whether a decision ended the call without running it.

func (*Call) State added in v0.0.5 

func (c *Call) State(h Header) CallState

State returns what the path says happened to the call, reading the header's records to decide whether a missing dispatch means the call never started or means the file does not say. A held call with dispatches is held, and may have run. The promise covers a call the session made, after its base: one in a fork's prefix, from a call Session.Calls or Session.PendingCalls returns, is unknown, since its origin may have promised nothing. So is one with no dispatch on the path and one on another branch of the session, which a rebase above the dispatch leaves. A call from Calls over a bare path is taken to be the session's own, with nothing beside the path. A prefix call's dispatches, when its origin holds any, are what OriginDispatches reads through a store; they do not change the state, which is unknown either way, but say under which key and with which arguments the call may have run.

type CallState added in v0.0.5 

type CallState int

CallState is what the path says happened to a call. 

const (
	// CallCompleted: the call has an output.
	CallCompleted CallState = iota
	// CallHeld: the call waits on an answer to a hold.
	CallHeld
	// CallInFlight: the call was dispatched and no output arrived, so
	// its side effect may have happened.
	CallInFlight
	// CallNeverStarted: no dispatch and no output, for a call the
	// session made under a header that promises dispatches are recorded
	// before the tool runs, so the tool never ran.
	// A call in a fork's prefix was made under its origin's promise,
	// which this header does not vouch for, and is CallUnknown.
	CallNeverStarted
	// CallUnknown: no dispatch and no output, where no promise covers
	// the call, so the file does not say whether the tool ran.
	CallUnknown
	// CallAnswered: an answer decision ended the call and its output is
	// not on the path yet, since the record stopped between the two.
	// The harness that continues the path writes the output and
	// nothing else for the call; no dispatch may follow.
	CallAnswered
	// CallRejected: a reject decision ended the call and its refusal
	// output is not on the path yet, since the record stopped between
	// the two. The call did not run and does not: the harness that
	// continues the path writes the output, carrying the reject's
	// reason, and nothing else for the call.
	CallRejected
)

func (CallState) String added in v0.0.5 

func (s CallState) String() string

String names the state.

type Change added in v0.0.21 

type Change struct {
	Kind ChangeKind
	// Session is the follower's own session after this change, which
	// the next step extends in place: Path, ContextAt and Verify work on
	// it as on any read session. It is never the writer's, and a caller
	// never appends to it.
	Session *Session
	// ID and Entry are the entry an Appended change adds.
	ID    string
	Entry Entry
	// Leaf is the leaf a Head change records.
	Leaf string
	// Cursor is the position after this change, to resume from.
	Cursor Cursor
}

Change is one step of a follow.

type ChangeKind added in v0.0.21 

type ChangeKind int

ChangeKind says what a Change is. 

const (
	// Snapshot: Session is the session as it was read.
	Snapshot ChangeKind = iota
	// Appended: Entry was appended and Session includes it.
	Appended
	// Head: the store recorded Leaf as the session's head. A leaf a
	// writer moved with Session.Branch and did not record is not seen.
	Head
	// Reset: the log was replaced. Session is the session read again,
	// and a consumer drops what it derived from before. It may lack an
	// entry that was yielded earlier.
	Reset
)

func (ChangeKind) String added in v0.0.21 

func (k ChangeKind) String() string

String names the kind.

type CompactionEntry 

type CompactionEntry struct {
	EntryBase `json:"-"`
	// FirstKept names the earliest entry on the path that stays in
	// context.
	FirstKept string `json:"first_kept"`
	// Summary is an item: the server's compaction item verbatim, or a
	// message for a local summary.
	Summary openresponses.Item `json:"summary"`
	// Pinned are items kept verbatim from before FirstKept. They are in
	// context immediately after Summary and before the entries from
	// FirstKept.
	Pinned openresponses.Items `json:"pinned,omitempty"`
	// Config is a full settings checkpoint so a reader need not replay
	// config entries from before the compaction.
	Config       Settings             `json:"config"`
	TokensBefore int                  `json:"tokens_before,omitempty"`
	Usage        *openresponses.Usage `json:"usage,omitempty"`
}

CompactionEntry replaces the context before FirstKept with a summary. It is in context through its summary and its pinned items.

func (*CompactionEntry) EntryType 

func (*CompactionEntry) EntryType() string

EntryType returns "compaction".

func (*CompactionEntry) MarshalJSON 

func (e *CompactionEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits the entry as one JSON object.

func (*CompactionEntry) UnmarshalJSON 

func (e *CompactionEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the entry.

type ConfigEntry 

type ConfigEntry struct {
	EntryBase    `json:"-"`
	Model        string                         `json:"model,omitempty"`
	Instructions *string                        `json:"instructions,omitempty"`
	Reasoning    *openresponses.ReasoningConfig `json:"reasoning,omitempty"`
	Text         *openresponses.TextConfig      `json:"text,omitempty"`
	// InstructionsParts names the parts the instructions are composed
	// of, in the order they are joined. A delta carries the whole
	// ordered list: a part whose text changed carries its text, a part
	// whose text is unchanged carries its Hash alone, and a part left
	// out of the list is removed. Set it through
	// [Settings.InstructionsDelta] rather than by hand, which computes
	// exactly that from the parts in force. When Instructions is set
	// beside it the two must agree, since Instructions is the parts
	// joined with "\n\n".
	InstructionsParts []InstructionPart `json:"instructions_parts,omitempty"`
	// InstructionsOmitted records the parts the writer considered and
	// left out, so a session says what the model was not given as well
	// as what it was. Nothing in it reaches the request, but it stays
	// in force until a later config entry carries it: nil leaves the
	// list in force as it was, and an empty, non-nil list, written as
	// [], clears it. A writer sets it only when the list changed, and
	// through [Settings.OmittedDelta], which names each run of parts
	// that stay omitted by a keep, and, in a session of format 0.11, a
	// run of the list an earlier entry wrote by a keep carrying of.
	InstructionsOmitted []OmittedPart       `json:"instructions_omitted,omitzero"`
	ToolsAdded          openresponses.Tools `json:"tools_added,omitempty"`
	ToolsRemoved        []string            `json:"tools_removed,omitempty"`
	// Extra carries request members beyond the named ones, such as
	// temperature or provider passthrough keys. A null value removes
	// the key from the settings.
	Extra   map[string]json.RawMessage `json:"extra,omitempty"`
	Replace bool                       `json:"replace,omitempty"`
	// Omit records the items a request leaves out of the context, in
	// format 0.11: a rule that leaves out a reasoning item written under
	// another model, and a list of entries whose items contribute
	// nothing. It is in force as a setting is: nil leaves the object in
	// force as it was, an empty, non-nil one, written as {}, clears it,
	// and any other sets the reasoning rule it names and adds its items
	// to those in force. See [Omit] and [Settings.OmitDelta]. An omit
	// member that does not decode as the object, which a file from before
	// the member was defined may hold, is kept as written in Unknown and
	// Omit is nil.
	Omit *Omit `json:"-" member:"omit"`
}

ConfigEntry is a delta to request settings. Fields left at their zero value are unchanged; Replace discards all earlier config on the path before this one applies. The first entry on a root should be a config carrying full settings.

func ConfigFromRequest 

func ConfigFromRequest(req openresponses.Request) (*ConfigEntry, error)

ConfigFromRequest builds the full config entry for the settings a request was sent with: its model, instructions, reasoning, text and tools, with every other request member that is not about the one call (temperature, tool_choice, metadata, provider passthrough keys and so on) in Extra under its wire name. Replay of the result over empty settings followed by Settings.Request over the same input hashes to the same value as the request, which is what the first entry on a root should establish. Replace is set so the entry stands alone wherever it is placed.

func ConfigFromRequestParts added in v0.0.6 

func ConfigFromRequestParts(req openresponses.Request, parts ...InstructionPart) (*ConfigEntry, error)

ConfigFromRequestParts is ConfigFromRequest for a caller that composed the instructions from named parts: the entry carries the parts instead of the joined string, so every delta after it names the one part that moved rather than repeating the whole prompt. The parts' texts joined with PartSeparator must equal the request's instructions, since that is what the model received and what the request hash covers.

func UnresolvedOf added in v0.0.20 

func UnresolvedOf(path []Entry) []*ConfigEntry

UnresolvedOf returns the config entries on a root-first path that carry a keep with an of the path cannot resolve, in path order: the of names no entry on the path whose list is still in force to name, since a replace or a compaction's checkpoint, or the keep runs past that list or takes a part the delta names elsewhere. The format keeps such an element as written and it reaches no request, so nothing but a tool that checks a file reports it; this is that check, replaying the path as the context algorithm does.

func (*ConfigEntry) ClearExtra added in v0.0.3 

func (c *ConfigEntry) ClearExtra(key string)

ClearExtra records the removal of a passthrough member: the delta carries a null for key, which deletes it from the settings on replay.

func (*ConfigEntry) EntryType 

func (*ConfigEntry) EntryType() string

EntryType returns "config".

func (*ConfigEntry) MarshalJSON 

func (e *ConfigEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits the entry as one JSON object.

func (*ConfigEntry) SetExtra added in v0.0.3 

func (c *ConfigEntry) SetExtra(key string, v any) error

SetExtra records a passthrough request member on the delta: v is marshalled and stored under key, replacing any earlier value.

func (*ConfigEntry) UnmarshalJSON 

func (e *ConfigEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the entry.

type Context 

type Context struct {
	Settings Settings
	Items    openresponses.Items
	// Entries are the entries selected by the context algorithm, in
	// order: after a compaction, the compaction itself, then the kept
	// entries from FirstKept up to it, then everything after. Entries
	// that contribute no item are included so a renderer can show them.
	Entries []Entry
	// ItemEntries is aligned with Items: ItemEntries[i] is the entry
	// that contributed Items[i], so an index into the request input
	// maps back to the entry that produced it. After a compaction the
	// compaction entry fills one slot for its summary and one for each
	// of its pinned items, so it repeats as many times as it
	// contributed: Items[0] is its summary and the next len(Pinned)
	// items are its pins.
	ItemEntries []Entry
	// OmittedItems are the item entries on the path that the request
	// leaves out, each with the reason, in path order: the entries the
	// context algorithm selected whose items [Settings.Omit] excludes.
	// They are in Entries, so a renderer can show them as omitted and
	// not as absent, and in neither Items nor ItemEntries, so Request
	// is what the model was sent. It is empty for a path with no omit
	// in force.
	OmittedItems []OmittedItem
}

Context is what a model call at a point on a path receives: the replayed settings, the item list ready to be the request input and the entries the list was built from, for renderers.

func BuildContext 

func BuildContext(path []Entry) (Context, error)

BuildContext runs the context algorithm over a root-first path. Only the last compaction on the path is applied. FirstKept must name an entry on the path before the compaction. An item entry that the omit in force at the end of the path excludes contributes nothing and is reported in Context.OmittedItems.

func (Context) InstructionsOmitted added in v0.0.6 

func (c Context) InstructionsOmitted() []OmittedPart

InstructionsOmitted returns the parts left out of the instructions in force: Settings.InstructionsOmitted. The list stays in force until a later config entry carries the member, so a writer writes it only when it changed, and a compaction checkpoint carries it.

func (Context) Request 

func (c Context) Request() (openresponses.Request, error)

Request returns the canonical request for the context. It equals the request the model was sent under canonical JSON (RFC 8785), not in bytes: member order inside opaque JSON, such as a tool's parameter schema, is what the store gives back. A jsonl file gives members as they were written and a cas store gives them in canonical order, so the same session rebuilds different bytes from each, with one request hash. A renderer that turns the request into tokens passes it, and the live request it compares with, through CanonicalRequest first.

type Cursor added in v0.0.21 

type Cursor string

Cursor is a position in one session's log, opaque and the store's own. The zero Cursor is the start: Follow begins with a snapshot. A cursor from one store is meaningless to another, and a cursor the current log no longer holds, because the log was replaced since, is answered with a Reset, never with a silent skip.

type CustomEntry 

type CustomEntry struct {
	EntryBase `json:"-"`
	NS        string          `json:"ns"`
	Data      json.RawMessage `json:"data,omitempty"`
	// CallID names the function call the record belongs to, when the
	// writer knows it: a record a tool writes while it runs. A record's
	// position cannot say which call of a batch in flight it belongs to;
	// this can. A reader may use it and must not require it. A call_id
	// member that is not a non-empty string, which a file from before
	// the member was defined may hold, is kept as written in Unknown and
	// CallID is empty.
	CallID string `json:"-" member:"call_id"`
}

CustomEntry is application state that is not in context. State that the model should see is an ItemEntry holding a namespaced item.

func (*CustomEntry) EntryType 

func (*CustomEntry) EntryType() string

EntryType returns "custom".

func (*CustomEntry) MarshalJSON 

func (e *CustomEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits the entry as one JSON object.

func (*CustomEntry) UnmarshalJSON 

func (e *CustomEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the entry.

type DecisionEntry added in v0.0.5 

type DecisionEntry struct {
	EntryBase `json:"-"`
	CallID    string          `json:"call_id"`
	Target    string          `json:"target"`
	Verdict   string          `json:"verdict"`
	By        string          `json:"by,omitempty"`
	Reason    string          `json:"reason,omitempty"`
	Args      json.RawMessage `json:"args,omitempty"`
}

DecisionEntry records that a call's fate was decided outside the tool. Target is the item entry holding the function call. Reason is required when Verdict is VerdictReject, since it is what the model saw as the output. Args, when present, are the arguments the tool ran with after the decision rewrote them; the function call item stays as the model produced it. An answer, VerdictAnswer, ran nothing, so Args on one names nothing.

func NewDecision added in v0.0.5 

func NewDecision(callID, target, verdict, by string) *DecisionEntry

NewDecision builds a decision on the call callID held by the item entry target. by may be "".

func (*DecisionEntry) EntryType added in v0.0.5 

func (*DecisionEntry) EntryType() string

EntryType returns "decision".

func (*DecisionEntry) MarshalJSON added in v0.0.5 

func (e *DecisionEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits the entry as one JSON object.

func (*DecisionEntry) UnmarshalJSON added in v0.0.5 

func (e *DecisionEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the entry.

func (*DecisionEntry) WithArgs added in v0.0.5 

func (e *DecisionEntry) WithArgs(args json.RawMessage) *DecisionEntry

WithArgs records the arguments the tool ran with and returns the entry, for chaining. args must be a JSON value.

func (*DecisionEntry) WithReason added in v0.0.5 

func (e *DecisionEntry) WithReason(reason string) *DecisionEntry

WithReason sets the decider's text and returns the entry, for chaining.

type DispatchEntry added in v0.0.5 

type DispatchEntry struct {
	EntryBase `json:"-"`
	CallID    string `json:"call_id"`
	Target    string `json:"target"`
	// IdempotencyKey is the key the harness gave the tool for this
	// hand-off. A dispatch that repeats an earlier hand-off carries that
	// hand-off's key, and a new key is a new operation; the last
	// dispatch's key is what [Call.IdempotencyKey] returns. An
	// idempotency_key member
	// that is not a non-empty string, which a file from before the
	// member was defined may hold, is kept as written in Unknown and
	// IdempotencyKey is empty.
	IdempotencyKey string `json:"-" member:"idempotency_key"`
}

DispatchEntry records that a call was handed to its tool. Target is the item entry holding the function call. A writer that names "dispatch" in the header's records writes it, durably, before the tool runs. Each dispatch for a call is one hand-off, so a call run again after a restart has a second.

func NewDispatch added in v0.0.5 

func NewDispatch(callID, target string) *DispatchEntry

NewDispatch builds a dispatch for the call callID held by the item entry target.

func (*DispatchEntry) EntryType added in v0.0.5 

func (*DispatchEntry) EntryType() string

EntryType returns "dispatch".

func (*DispatchEntry) MarshalJSON added in v0.0.5 

func (e *DispatchEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits the entry as one JSON object.

func (*DispatchEntry) UnmarshalJSON added in v0.0.5 

func (e *DispatchEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the entry.

func (*DispatchEntry) WithIdempotencyKey added in v0.0.11 

func (e *DispatchEntry) WithIdempotencyKey(key string) *DispatchEntry

WithIdempotencyKey records the key the tool is handed and returns the entry, for chaining.

type Entry 

type Entry interface {
	Base() *EntryBase
	EntryType() string
}

Entry is one line of a session after the header. Concrete types are ItemEntry, ResponseEntry, ConfigEntry, CompactionEntry, BranchSummaryEntry, RunEntry, DispatchEntry, DecisionEntry, QueuedEntry, LabelEntry, InfoEntry, EnvEntry, OutcomeEntry, LinkEntry, CustomEntry and UnknownEntry. Decoded values are always pointers, so switch on *ItemEntry and so on. An entry must not be modified once it has been appended to a session; corrections are new entries.

func UnmarshalEntry 

func UnmarshalEntry(data []byte) (Entry, error)

UnmarshalEntry decodes one line, dispatching on its type. Types this package does not define decode to *UnknownEntry.

type EntryBase 

type EntryBase struct {
	// ID is unique within the session. Session.Append assigns one when
	// it is empty.
	ID string
	// Parent is the ID of the parent entry, or "" for a root. It is the
	// entry's line of descent: exactly one, in this session, and the
	// only edge a context is built from.
	Parent string
	// Parents records further predecessors this entry converges: the
	// result of a subagent session, a branch merged back, several
	// workers joined at once. It is provenance. Nothing it names
	// contributes to any context by virtue of being named — whatever
	// crossed the boundary is in this entry's own payload, materialised
	// — so [Session.Path] and every context the library builds follow
	// Parent alone. Session.Append sorts it.
	Parents []EntryRef
	// Timestamp is when the entry was written. The format admits one
	// spelling, UTC with at most nine fractional digits, so Append
	// converts a caller's time to UTC.
	Timestamp time.Time
	// LegacyID is the id an entry had before its file was migrated to
	// 0.5, when its id became the envelope hash. It is a body member,
	// so it is hashed; a projection may emit it beside the new id so
	// output made from the earlier file still resolves.
	LegacyID string
	// Normalised records what a writer changed in the body before
	// writing so that it passed the I-JSON test: a lone surrogate to
	// U+FFFD, an integer outside binary64 to a string or to its rounded
	// value. It is sorted by At as UTF-16 code units.
	Normalised []Normalisation
	// Unknown holds body members this package does not define,
	// preserved so a later minor version's optional fields survive a
	// rewrite. It is nil when there are none.
	Unknown map[string]json.RawMessage
	// contains filtered or unexported fields
}

EntryBase is the envelope every entry carries.

func (*EntryBase) Base 

func (b *EntryBase) Base() *EntryBase

Base returns the envelope.

func (*EntryBase) ContentHash added in v0.0.8 

func (b *EntryBase) ContentHash() string

ContentHash returns the hash of the entry's body, the members outside the envelope, as computed when the entry was appended or read. It is empty for an entry that has been neither.

type EntryRef added in v0.0.8 

type EntryRef struct {
	// Session names the session Entry is in. It is empty when the entry
	// is in this session, which is the only case a reader can resolve
	// without a store.
	Session string `json:"session,omitempty"`
	// Entry is the ID of the entry referred to.
	Entry string `json:"entry"`
}

EntryRef names one entry, here or in another session. It is what EntryBase.Parents holds.

func (*EntryRef) UnmarshalJSON added in v0.0.18 

func (r *EntryRef) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a reference by its members' exact names, as the format names them: a key in another case is a member the format does not define. An entry member that is missing or not a string decodes as no entry, which the convergence rules refuse.

type EnvEntry 

type EnvEntry struct {
	EntryBase `json:"-"`
	CWD       string            `json:"cwd,omitempty"`
	VCS       *VCS              `json:"vcs,omitempty"`
	Files     *FileHashes       `json:"files,omitempty"`
	Tools     map[string]string `json:"tools,omitempty"`
	// Workspace says which file system CWD is a path in. A local run
	// may leave it nil.
	Workspace *Workspace `json:"workspace,omitempty"`
}

EnvEntry is a snapshot of the environment for replay: where the tools ran and what they saw. It applies from its position on the path until the next one, and its CWD takes precedence over the header's.

What a harness records beyond these members, such as the identity of a working tree's contents, goes in a namespaced member: one of the entry, kept in Unknown (EntryBase), or one inside vcs, set with VCS.SetMember. Only workspace is compared for a substitution, so a change to any other member, those the format does not define included, is not one: see SameWorkspace.

func NewEnvEntry 

func NewEnvEntry(cwd string) *EnvEntry

NewEnvEntry starts an env entry for a working directory. Use EnvEntry.SetGit, EnvEntry.AddRead and EnvEntry.AddWritten to fill it in.

func (*EnvEntry) AddRead 

func (e *EnvEntry) AddRead(path, hash string)

AddRead records the hash of a file the session read.

func (*EnvEntry) AddTool 

func (e *EnvEntry) AddTool(name, version string)

AddTool records the version of a tool available to the session.

func (*EnvEntry) AddWritten 

func (e *EnvEntry) AddWritten(path, hash string)

AddWritten records the hash of a file the session wrote.

func (*EnvEntry) EntryType 

func (*EnvEntry) EntryType() string

EntryType returns "env".

func (*EnvEntry) MarshalJSON 

func (e *EnvEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits the entry as one JSON object.

func (*EnvEntry) SetGit 

func (e *EnvEntry) SetGit(dir string, dirty bool) error

SetGit records the git revision of dir, read from its .git directory without running git, and whether the tree is known to be dirty. A directory that is not a git checkout leaves VCS unset and returns nil; other errors are returned. Members of an existing VCS the format does not define, set with VCS.SetMember or read from a file, are kept.

func (*EnvEntry) SetWorkspace added in v0.0.5 

func (e *EnvEntry) SetWorkspace(kind, ref string) *Workspace

SetWorkspace records which file system CWD is a path in: kind is WorkspaceLocal, WorkspaceContainer or WorkspaceRemote, and ref is what the harness resolves to it (an image digest, a host, an instance ID). A container on a remote host is a container, with the host a member of the workspace: set it, and anything else that tells one file system from another, with Workspace.SetMember on the result, and not as an unknown member of the entry, which the substitution rule does not compare.

func (*EnvEntry) UnmarshalJSON 

func (e *EnvEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the entry.

type FileHashes 

type FileHashes struct {
	Read    map[string]string `json:"read,omitempty"`
	Written map[string]string `json:"written,omitempty"`
}

FileHashes maps paths to content hashes ("sha256:...") for files read and written.

type Follower added in v0.0.21 

type Follower interface {
	Follow(ctx context.Context, id string, from Cursor) iter.Seq2[Change, error]
}

Follower is implemented by a store that can follow a session: read it, then receive each change the store accepts, without holding it.

Follow takes no hold and writes nothing, recovery included, as Reader does, so a store opened read-only can follow, and so can one that is not while another process holds the session. The iterator yields a Snapshot first, or with a cursor the changes after it, and then each change as the store accepts it. It ends without an error when ctx is done, and with ErrNoSession when the session is deleted; a session created again under the same ID is another session, and the follower never continues into it. Breaking out of the range stops the follower and releases what it held.

Everything a follower yields is visible, never promised durable, as Reader says of a read: a crash, or an append that failed after another process saw it, can take back an entry a follower yielded, and the follower then yields Reset. Appends arrive in the order the store accepted them, on every branch, never in the order of a path.

type Harness 

type Harness struct {
	Name    string `json:"name"`
	Version string `json:"version,omitempty"`
}

Harness names the writer of a session. 

type Header struct {
	Format    string    `json:"format"`
	ID        string    `json:"id"`
	CreatedAt time.Time `json:"created_at"`
	Payload   string    `json:"payload"`
	Harness   *Harness  `json:"harness,omitempty"`
	// Records lists the record entry types this writer writes whenever
	// their event occurs, so a reader may take their absence on a path
	// as the event not having happened. Empty means no such promise,
	// which is what a converter over a native log without them sets.
	Records       []string `json:"records,omitempty"`
	CWD           string   `json:"cwd,omitempty"`
	ParentSession string   `json:"parent_session,omitempty"`
	// SpawnedBy is, for a subsession, the call_id of the parent's
	// function call that spawned it.
	SpawnedBy string `json:"spawned_by,omitempty"`
	// Base is the hash of the entry this session continues from, in
	// the session ParentSession names, or empty for a session that
	// starts fresh. A file with a base opens with the path to it, the
	// prefix, before any entry the session appended itself, and every
	// own entry hangs from the base. A base is never a leaf label.
	Base  string `json:"base,omitempty"`
	Media string `json:"media,omitempty"`
	// Redacted is true when bodies were changed after they were written,
	// as export redaction does. The redactor recomputes every hash and
	// reference over the redacted bodies, so the file walks and
	// verifies against itself and not against the original.
	Redacted bool `json:"redacted,omitempty"`

	// Extra holds header fields this package does not define.
	Extra map[string]json.RawMessage `json:"-"`
}

Header is the first line of a session file. It is not part of the tree. Unknown fields decode into Extra and are written back, as the format requires of any tool that rewrites a file.

func Scan added in v0.0.18 

func Scan(r io.Reader) (Header, iter.Seq2[RawEntry, error], error)

Scan reads a session file and verifies it as Read does, decoding no entry: every line passes the I-JSON test, every entry's id is the hash of its line's canonical bytes, its ts has the one spelling the format admits, its parent is null or an entry earlier in the file, its parents keep the convergence rules, in a file whose header names a base it keeps the base rule (ErrBaseRule), and the legacy_id and normalised any entry may carry have their types. The header is read and checked first and returned as the file declares it. A line met a second time is yielded with Repeat set. A last line cut short, as a crash mid-append leaves, ends the sequence with a *TruncatedLine error; any other failure ends it with its error, and the header's base not being in the file is reported once the file ends. Lines are numbered, and empty ones skipped, as Read numbers and skips them.

Scan checks no more of an entry than that: what a core entry type requires of its own members is Decode's to check, as it is Read's. The sequence reads r as it goes, so it ranges once; a second range yields an error.

func (Header) HasRecord added in v0.0.5 

func (h Header) HasRecord(typ string) bool

HasRecord reports whether the header promises that entries of type typ are written whenever their event occurs, so their absence means the event did not happen.

func (Header) MarshalJSON 

func (h Header) MarshalJSON() ([]byte, error)

MarshalJSON emits the header with its type discriminator first and Extra flattened into the object.

func (*Header) UnmarshalJSON 

func (h *Header) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the header, keeping unknown fields in Extra.

func (Header) Validate 

func (h Header) Validate() error

Validate checks the required header fields and that the format is one this package reads.

type InfoEntry 

type InfoEntry struct {
	EntryBase `json:"-"`
	Name      string `json:"name,omitempty"`
}

InfoEntry carries display metadata such as a session name. Further members are kept in Unknown.

func (*InfoEntry) EntryType 

func (*InfoEntry) EntryType() string

EntryType returns "info".

func (*InfoEntry) MarshalJSON 

func (e *InfoEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits the entry as one JSON object.

func (*InfoEntry) UnmarshalJSON 

func (e *InfoEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the entry.

type InstructionPart added in v0.0.6 

type InstructionPart struct {
	// ID is the part's stable name, chosen by the harness: the same
	// string across the session, so a delta can name a part it does
	// not repeat. It is empty on a keep, and on a part in force that
	// an element naming nothing left unresolved.
	ID string `json:"id,omitempty"`
	// Text is the part's text. On a delta it is absent for a part
	// whose text is unchanged, which carries Hash instead.
	Text string `json:"text,omitempty"`
	// Source names the layer that produced the part, in the harness's
	// own terms.
	Source string `json:"source,omitempty"`
	// Hash is the hash of the text a delta does not repeat, in the
	// format's notation: [HashPrefix] and the SHA-256 of the text.
	// [HashText] computes it. It is set on a delta's unchanged part
	// and empty on a part that carries its text.
	Hash string `json:"hash,omitempty"`
	// Keep, on a delta, stands for the next Keep parts in force,
	// unchanged, and is the element's only member: see
	// [Settings.InstructionsDelta]. A keep member that is not a
	// positive integer, which a file from before the member was defined
	// may hold, is kept as written and Keep is zero; on an element that
	// names an ID it means nothing.
	Keep int `json:"keep,omitempty"`
	// contains filtered or unexported fields
}

InstructionPart is one named part of the instructions. A harness that composes the instructions from several layers, a product prompt, an AGENTS.md chain, a skill catalogue, a memory block, gives each layer a part, so a change to one is recorded as a change to one and a reader can say which layer an instruction came from.

func (*InstructionPart) UnmarshalJSON added in v0.0.10 

func (p *InstructionPart) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the part, taking keep only when it is a positive integer written as digits, so an earlier file's keep in any other form stays a member this package does not define.

func (InstructionPart) Unresolved added in v0.0.10 

func (p InstructionPart) Unresolved() bool

Unresolved reports whether the path could not rebuild the part's text: it was named by a hash or a keep the path could not resolve, or by an element that names nothing.

type ItemEntry 

type ItemEntry struct {
	EntryBase `json:"-"`
	// Item is the Open Responses item, verbatim. Extension items decode
	// to *openresponses.UnknownItem and re-encode byte for byte.
	Item openresponses.Item `json:"item"`
	// ResponseID names the response this item belongs to when the item
	// was model output; it matches ResponseEntry.ResponseID.
	ResponseID string `json:"response,omitempty"`
	// Visible is false for an item that is in context but that a
	// renderer should hide. Nil means visible.
	Visible *bool `json:"visible,omitempty"`
	// Source says how the input arrived, for an item a person or
	// another system sent rather than the model or the loop. It is the
	// trigger a [QueuedEntry] carried, so two people steering one run
	// are told apart.
	Source *Trigger `json:"source,omitempty"`
	// QueuedFrom names the [QueuedEntry] this item was accepted as,
	// for an input that waited before it could be appended.
	QueuedFrom string `json:"queued_from,omitempty"`
}

ItemEntry is one conversation item in the payload profile. It is in model context.

func NewItemEntry 

func NewItemEntry(item openresponses.Item) *ItemEntry

NewItemEntry builds an item entry.

func OutputEntries added in v0.0.6 

func OutputEntries(path []Entry, resp *ResponseEntry) []*ItemEntry

OutputEntries returns the item entries on path that hold the output of resp, in path order. It is the format's rule for finding a response's own output items, stated in RFC 0001 under "Request context of a response", and it is the one implementation: a reader that needs those items, and one that needs to exclude them, must agree or the same file rebuilds two different requests.

Walking back from the end of path: an entry that is not an item entry is skipped, an item entry whose Response names resp is one of its output items, and the walk stops at the first item entry that names another response or none. A response with no ResponseID has no output items.

path is resp's path with resp itself at the end, or that path without it; either gives the same answer, since an entry that is not an item entry is skipped. It MUST NOT run past resp: a path that continues beyond the response ends in the next call's items, the walk stops on the first of them, and the result is an empty slice rather than an error. Only the matching item entries are returned, never the entries skipped between them: those are on the path for their own reasons and stay there.

The returned entries are the session's own, not copies. A caller that serves their items to something that records must clone them; a caller that only reads the path need not.

func (*ItemEntry) EntryType 

func (*ItemEntry) EntryType() string

EntryType returns "item".

func (*ItemEntry) IsVisible 

func (e *ItemEntry) IsVisible() bool

IsVisible reports whether a renderer should show the item.

func (*ItemEntry) MarshalJSON 

func (e *ItemEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits the entry as one JSON object.

func (*ItemEntry) UnmarshalJSON 

func (e *ItemEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the entry, dispatching the item through the openresponses item registry.

type LabelEntry 

type LabelEntry struct {
	EntryBase `json:"-"`
	Target    string  `json:"target"`
	Label     *string `json:"label"`
}

LabelEntry bookmarks another entry. A nil Label clears an earlier label on the same target.

func NewLabelEntry 

func NewLabelEntry(target, label string) *LabelEntry

NewLabelEntry builds a label on target; an empty label clears.

func (*LabelEntry) EntryType 

func (*LabelEntry) EntryType() string

EntryType returns "label".

func (*LabelEntry) MarshalJSON 

func (e *LabelEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits the entry as one JSON object.

func (*LabelEntry) UnmarshalJSON 

func (e *LabelEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the entry.

type LinkEntry 

type LinkEntry struct {
	EntryBase `json:"-"`
	Rel       string `json:"rel"`
	Session   string `json:"session"`
	// CallID ties a subsession to the function call that spawned it.
	CallID string `json:"call_id,omitempty"`
	// Target, on a [RelJudgedBy] link, names the entry of the judged
	// session the judgement is about: the entry the judge's outcome
	// names. It is a member of that relation alone: a target member on
	// a link of another relation, or one that is not a non-empty
	// string, which a file from before the member was defined may hold,
	// is kept as written in Unknown and Target is empty.
	Target string `json:"-" member:"target"`
}

LinkEntry references another session, for subagents and forks.

func Judges added in v0.0.20 

func Judges(path []Entry) []*LinkEntry

Judges returns the judged_by links on a root-first path, in path order: the sessions that judged what the path holds, each with the entry it judged in its Target when the writer named one. A link is a record entry and contributes nothing to a context, so a reader selecting the judges of a run reads them here and filters by Target for the judgements of one entry; the header of a judge's session cannot say it is one, since a subagent and a fork carry the same parent_session. 

func NewJudgedByLink(judge, target string) *LinkEntry

NewJudgedByLink builds the link entry a judged session records for the session of its judge: judge is the judge's session ID, and target, when it is not empty, the entry of the judged session the judgement is about, the one the judge's outcome names. The judge is a session of its own whose header names the judged one as its parent_session, which a subagent's and a fork's header does too, so the link is what says which it is. Judges reads these links back.

func NewLinkEntry 

func NewLinkEntry(rel, session string) *LinkEntry

NewLinkEntry builds a link to another session. 

func NewSubsessionLink(session, callID string) *LinkEntry

NewSubsessionLink builds the link entry the format prescribes for a subagent session spawned by the function call callID.

func (*LinkEntry) EntryType 

func (*LinkEntry) EntryType() string

EntryType returns "link".

func (*LinkEntry) MarshalJSON 

func (e *LinkEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits the entry as one JSON object.

func (*LinkEntry) UnmarshalJSON 

func (e *LinkEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the entry.

type LinkError added in v0.0.20 

type LinkError struct {
	// Entry is the link entry's id.
	Entry string
	// Session is the session the link names.
	Session string
	// Err says what is wrong with the link.
	Err error
}

LinkError is the error Session.VerifyLinks returns for a link it could not pass: the link entry, the session it names, and what went wrong, which is ErrLinkMismatch naming the member that disagrees, or the error the resolver returned for the target.

func (*LinkError) Error added in v0.0.20 

func (e *LinkError) Error() string

Error implements error.

func (*LinkError) Unwrap added in v0.0.20 

func (e *LinkError) Unwrap() error

Unwrap returns the error the link failed on.

type ListFilter 

type ListFilter struct {
	// CWD matches the header's working directory exactly.
	CWD string
	// ParentSession matches sessions forked or spawned from the given
	// one. A header cannot say which: a judge, a subagent and a fork
	// all carry the session they came from, so they are listed
	// together. The link entries of the parent say which each is, as
	// [Judges] reads for judges.
	ParentSession string
	// Harness matches the name of the header's harness exactly; a
	// header naming no harness matches nothing when it is set. A
	// scheduled routine finds its own sessions by it without an index
	// of its own beside the store.
	Harness string
	// Extra matches the header's extra members: each member named here
	// must be in the header with the same value, compared in canonical
	// form so key order and spacing do not matter; members the header
	// has beyond these do not count. A harness that writes its user or
	// platform into the header selects by them here.
	Extra map[string]json.RawMessage
	// TopLevel keeps only sessions with no spawned_by: those a person or
	// a schedule started, and not the subsessions a call spawned.
	TopLevel bool
	// After and Before bound created_at, exclusive.
	After, Before time.Time
	// Limit caps the number of results; zero means no cap.
	Limit int
	// WithNames asks for Summary.Name. A store that keeps names
	// indexed fills it regardless; a file store must scan each
	// session's entries to find it, so it does so only when asked.
	WithNames bool
	// Current excludes sessions a continued_in link has retired, so a
	// listing shows the successor and not the session it replaced.
	// A file store scans each session's entries to know, as for
	// WithNames.
	Current bool
}

ListFilter narrows a List. Zero fields do not filter, so the zero filter lists every session. The header fields cost no scan: every store reads the header to list a session, and Matches decides on it alone; WithNames and Current read the session's entries.

func (ListFilter) Keep added in v0.0.5 

func (f ListFilter) Keep(sum Summary) bool

Keep reports whether a summary passes the filter: the header checks of Matches, and Current against Summary.SupersededBy.

func (ListFilter) Matches 

func (f ListFilter) Matches(h Header) bool

Matches reports whether a header passes the filter: the fields of the filter that read the header alone, which is every one but WithNames and Current.

type MemoryStore 

type MemoryStore struct {
	// contains filtered or unexported fields
}

MemoryStore keeps sessions in memory. It is the reference store for tests and for sessions that are never persisted.

func NewMemoryStore 

func NewMemoryStore() *MemoryStore

NewMemoryStore returns an empty store.

func (*MemoryStore) Append 

func (m *MemoryStore) Append(ctx context.Context, sessionID string, e Entry) (string, error)

Append implements Store.

func (*MemoryStore) Create 

func (m *MemoryStore) Create(_ context.Context, h Header) (*Session, error)

Create implements Store. A header whose Base is set makes a fork of the session holding the base, as Fork does.

func (*MemoryStore) Delete 

func (m *MemoryStore) Delete(_ context.Context, id string) error

Delete implements Store.

func (*MemoryStore) Follow added in v0.0.21 

func (m *MemoryStore) Follow(ctx context.Context, id string, from Cursor) iter.Seq2[Change, error]

Follow implements Follower. A cursor is good for the session as it was created, so a session deleted and created again under its ID answers a cursor from before with a Reset. Appends through the store wake the follower directly; one made through the session returned by Open is found by a slow look, since nothing rings.

func (*MemoryStore) List 

func (m *MemoryStore) List(_ context.Context, f ListFilter) iter.Seq2[Summary, error]

List implements Store.

func (*MemoryStore) ListRefs added in v0.0.21 

func (m *MemoryStore) ListRefs(_ context.Context, prefix string) iter.Seq2[Ref, error]

ListRefs implements RefStore.

func (*MemoryStore) Open 

func (m *MemoryStore) Open(_ context.Context, id string) (*Session, error)

Open implements Store.

func (*MemoryStore) Read added in v0.0.19 

func (m *MemoryStore) Read(ctx context.Context, id string) (*Session, error)

Read implements Reader: a copy of the session, rebuilt from its encoding. Its leaf is the one the entries record, as a store reading a file finds it: a leaf moved through Session.Branch and not recorded is not there.

func (*MemoryStore) RefLog added in v0.0.21 

func (m *MemoryStore) RefLog(_ context.Context, name string) iter.Seq2[RefUpdate, error]

RefLog implements RefStore.

func (*MemoryStore) ResolveRef added in v0.0.21 

func (m *MemoryStore) ResolveRef(_ context.Context, name string) (RefTarget, error)

ResolveRef implements RefStore.

func (*MemoryStore) UpdateRef added in v0.0.21 

func (m *MemoryStore) UpdateRef(_ context.Context, name string, expected, next RefTarget, reason string) error

UpdateRef implements RefStore.

type Normalisation added in v0.0.8 

type Normalisation struct {
	// At is an RFC 6901 JSON Pointer relative to the body.
	At string `json:"at"`
	// Was is the member's original JSON source text, escapes included,
	// so it is I-JSON whatever it describes. It is empty when the
	// output was not valid UTF-8 and had no JSON text to record.
	Was string `json:"was,omitempty"`
	// Raw carries the original bytes, base64 under RFC 4648 §4 with
	// padding, when Was cannot: output that was not valid UTF-8.
	Raw string `json:"raw,omitempty"`
}

Normalisation is one change a writer made to a body before writing it, recorded in EntryBase.Normalised.

func NormaliseJSON added in v0.0.8 

func NormaliseJSON(data []byte) ([]byte, []Normalisation, error)

NormaliseJSON rewrites a JSON document so that every value passes the I-JSON test the format hashes under, and reports each change the way the format has a writer record it. A whole number outside binary64 is rounded to binary64 and written canonically, so 9007199254740993 becomes 9007199254740992 however it was spelled and a 64-bit id such as 1234567890123456789 becomes 1234567890123456800; a lone surrogate escape becomes U+FFFD; in a string that is not valid UTF-8 each maximal subpart of an ill-formed sequence (Unicode §3.9) becomes one U+FFFD, as the WHATWG decoder does. Each change carries the RFC 6901 pointer of the value relative to data and the value's original JSON source text, a string's quotes included, or its original bytes in base64 when there was no valid text to record. The changes are sorted by pointer as UTF-16 code units, the order the format fixes so two writers normalising one output agree.

Session.Append runs this over an entry's body, and repairs a Go string that is not valid UTF-8 the same way, so a harness that hands the library a body straight from a provider need do nothing. It is exported for the case Go's decoder hides: a lone surrogate in provider bytes is replaced on the way into a struct, and the record that it happened is lost unless the harness normalises the bytes first and keeps the changes, prefixing each pointer with that of the member the bytes become (for an item, "/item") before setting them on EntryBase.Normalised.

What cannot be normalised is an error: a number that is not finite in binary64, a repeated member name, a member name that itself fails the test.

type Omit added in v0.0.20 

type Omit struct {
	// Reasoning is a rule over the reasoning items on the path. It is
	// closed: [OmitOtherModels] is the one value defined, and a value
	// this package does not define has no effect, leaving the rule in
	// force as it was.
	Reasoning string `json:"reasoning,omitempty"`
	// Items are entry IDs. An item entry on the path whose ID is listed
	// contributes nothing, whatever it holds; an ID that names no item
	// entry on the path names nothing, and a writer writes no empty one.
	// The set in force is the union of every list since the last replace
	// or compaction's checkpoint.
	Items []string `json:"items,omitempty"`
}

Omit is the omit setting: what a request leaves out of the context though it is on the path, as format 0.11 records it. Settings carry the object in force, which a config entry's Omit extends: its Reasoning replaces the rule in force when it names one, its Items are added to the set in force, and an object naming neither clears both.

func (Omit) IsZero added in v0.0.20 

func (o Omit) IsZero() bool

IsZero reports whether the object names no rule and no entry, which is the object a config entry writes to clear the one in force, and the settings of a path that left nothing out. An empty id names no entry, so a list of them names none.

type OmittedItem added in v0.0.20 

type OmittedItem struct {
	// Entry is the item entry whose item contributes nothing.
	Entry *ItemEntry
	// Reason is [OmitOtherModels] when the entry holds a reasoning item
	// written under another model than the request's, and [OmitItems]
	// when the omit in force lists it. An entry both rules reach is
	// reported as listed.
	Reason string
}

OmittedItem is an item entry a request leaves out of the context, and why.

type OmittedPart added in v0.0.6 

type OmittedPart struct {
	// ID names the part. It is empty on a keep, and on an element in
	// force that names no part: see [OmittedPart.Unresolved].
	ID     string `json:"id,omitempty"`
	Reason string `json:"reason,omitempty"`
	Size   int    `json:"size,omitempty"`
	Source string `json:"source,omitempty"`
	// Keep, on a config delta, stands for the next Keep parts of the
	// list in force, unchanged, and is the element's only member: see
	// [Settings.OmittedDelta]. A keep member that is not a positive
	// integer, which a file from before the member was defined may
	// hold, is kept as written and Keep is zero; on an element that
	// names an ID it means nothing.
	Keep int `json:"keep,omitempty"`
	// Of, on a keep, names a config entry earlier on the path: the keep
	// counts over the list that entry put in force instead of the list
	// in force before this entry, as format 0.11 lets a writer name the
	// list an earlier entry wrote. It is the id of that entry. It means
	// nothing beside an ID or without a Keep, and an of member that is
	// not a non-empty string, which a file from before the member was
	// defined may hold, is kept as written and Of is empty. See
	// [Settings.OmittedDelta].
	Of string `json:"of,omitempty"`
}

OmittedPart is a part the writer considered for the instructions and left out: a file the budget did not reach, a memory entry that did not fit, a skill out of scope. Reason is the writer's own word for why, Size the bytes the part would have added.

func (*OmittedPart) UnmarshalJSON added in v0.0.12 

func (p *OmittedPart) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the part, taking keep only when it is a positive integer written as digits and of only when it is a non-empty string, so an earlier file's member in any other form stays a member this package does not define.

func (OmittedPart) Unresolved added in v0.0.12 

func (p OmittedPart) Unresolved() bool

Unresolved reports whether the element names no part: a keep the path could not satisfy, left in the list in force as written, or an element with neither an ID nor a keep.

type Outcome added in v0.0.8 

type Outcome int

Outcome is what an append did, which the format has a store report. 

const (
	// Continued: the entry was added under the leaf and is the leaf.
	Continued Outcome = iota
	// Branched: the entry was added elsewhere and the leaf did not move.
	Branched
	// Held: the session already held the entry; nothing changed.
	Held
	// LeafMoved: a leaf label moved the leaf to its target.
	LeafMoved
	// LeafNotMoved: a leaf label named a target the leaf may not rest
	// on, and was added without moving it.
	LeafNotMoved
)

func (Outcome) String added in v0.0.8 

func (o Outcome) String() string

String names the outcome.

type OutcomeEntry 

type OutcomeEntry struct {
	EntryBase `json:"-"`
	Kind      string          `json:"kind"`
	Target    string          `json:"target,omitempty"`
	Score     *float64        `json:"score,omitempty"`
	Pass      *bool           `json:"pass,omitempty"`
	Label     string          `json:"label,omitempty"`
	Details   json.RawMessage `json:"details,omitempty"`
}

OutcomeEntry is a judgement of how the session, or a range of it, went. Target names an entry in this session, usually the last entry of the range judged; a task or test name belongs in Details. Score is any finite number on the judge's own scale, named by Label; Pass is the judge's verdict when it has one.

func NewOutcomeEntry 

func NewOutcomeEntry(kind, target string) *OutcomeEntry

NewOutcomeEntry builds an outcome entry of the given kind about target, which may be "" for the session as a whole.

func (*OutcomeEntry) EntryType 

func (*OutcomeEntry) EntryType() string

EntryType returns "outcome".

func (*OutcomeEntry) MarshalJSON 

func (e *OutcomeEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits the entry as one JSON object.

func (*OutcomeEntry) UnmarshalJSON 

func (e *OutcomeEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the entry.

func (*OutcomeEntry) WithDetails 

func (e *OutcomeEntry) WithDetails(v any) *OutcomeEntry

WithDetails encodes v as the details and returns the entry, for chaining. An encoding failure leaves Details unset and is returned by the next Session.Append through MarshalEntry only if v cannot be marshalled at all, so callers should pass plain data.

func (*OutcomeEntry) WithLabel 

func (e *OutcomeEntry) WithLabel(label string) *OutcomeEntry

WithLabel sets the label and returns the entry, for chaining.

func (*OutcomeEntry) WithPass added in v0.0.5 

func (e *OutcomeEntry) WithPass(pass bool) *OutcomeEntry

WithPass sets the judge's verdict and returns the entry, for chaining.

func (*OutcomeEntry) WithScore 

func (e *OutcomeEntry) WithScore(score float64) *OutcomeEntry

WithScore sets the score and returns the entry, for chaining.

type QueuedEntry added in v0.0.6 

type QueuedEntry struct {
	EntryBase `json:"-"`
	// Item is the input as it will be appended.
	Item openresponses.Item `json:"item"`
	// Mode is ModeSteer or ModeFollowUp.
	Mode string `json:"mode"`
	// Trigger is what brought the input in.
	Trigger *Trigger `json:"trigger,omitempty"`
	// Ref names the queued input in the harness's own terms, for a
	// caller that holds a handle to it.
	Ref string `json:"ref,omitempty"`
}

QueuedEntry records an input a harness accepted before it could be appended to the conversation: a steer typed while the model is running, or a follow-up that waits for the run to end. It is a record entry, so the context algorithm ignores it and the item it holds reaches no request until it is appended as an ItemEntry.

A queued entry with no item entry naming it and no run end after it on the path is an input the harness still owes the conversation; Session.PendingQueued lists them, which is what a gateway that answered 202 drains on resume. The entry is where the trigger of that input lives, since the run entry names the trigger of the run and an input that joins a run in flight has a different one.

func NewQueued added in v0.0.6 

func NewQueued(item openresponses.Item, mode string) *QueuedEntry

NewQueued builds a queued entry for an input accepted in mode ModeSteer or ModeFollowUp.

func Queued added in v0.0.6 

func Queued(path []Entry) []*QueuedEntry

Queued returns the queued entries on a root-first path that are still waiting: no item entry on the path names them in QueuedFrom, and no run end follows them. They are the inputs a harness accepted and has not yet appended to the conversation, the durable inbox a resume drains. A run end after a queued entry closes it, since the run it was queued into has ended: a harness that still wants the input queues it again.

func (*QueuedEntry) Drain added in v0.0.6 

func (e *QueuedEntry) Drain() *ItemEntry

Drain returns the item entry that appends this queued input to the conversation: the item, the trigger as its source and QueuedFrom naming this entry, so the record says why the item is there. The entry must already have an ID, which it has once it is appended. The trigger is copied whole, the members the format does not define included, so the two entries do not share one once both are appended and neither may be modified.

func (*QueuedEntry) EntryType added in v0.0.6 

func (*QueuedEntry) EntryType() string

EntryType returns "queued".

func (*QueuedEntry) MarshalJSON added in v0.0.6 

func (e *QueuedEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits the entry as one JSON object.

func (*QueuedEntry) UnmarshalJSON added in v0.0.6 

func (e *QueuedEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the entry, dispatching the item through the openresponses item registry.

func (*QueuedEntry) WithTrigger added in v0.0.6 

func (e *QueuedEntry) WithTrigger(kind, ref, source string) *QueuedEntry

WithTrigger records what brought the input in and returns the entry, for chaining.

type RawEntry added in v0.0.18 

type RawEntry struct {
	ID, Parent, Type string
	// Line is the line as read, without its terminator.
	Line []byte
	// Repeat is set for a line whose id an earlier line had, which a
	// reader treats as that same entry.
	Repeat bool
}

RawEntry is one entry line as Scan met it: its envelope, read from the line's own bytes, and the line, which Decode turns into an entry when asked.

func (RawEntry) Decode added in v0.0.18 

func (r RawEntry) Decode() (Entry, error)

Decode decodes the entry, as Read decodes each line. Its id is the one Scan verified.

type Reader added in v0.0.19 

type Reader interface {
	Read(ctx context.Context, id string) (*Session, error)
}

Reader is implemented by a store that can read a session without holding it. Read takes no hold, writes nothing, the recovery an Open would write included, and keeps nothing: it returns a session of its own, read from what the store holds, which no later append reaches and whose leaf moves move no other session's. A session this store or another process is writing is read as a store opened read-only would read it, and stays the writer's. A missing session is ErrNoSession.

What Read sees of a session being written is what the store held when it read: an append in flight may not be there yet, and a leaf a writer moved through Session.Branch and has not recorded is not. Nor need what it sees be durable: Read can show an append its writer has not yet made durable, under a lazy sync policy or while its fsync runs, which a crash can take back. Each store says what, if anything, reads only what is durable.

type Ref added in v0.0.21 

type Ref struct {
	Name   string
	Target RefTarget
}

Ref is a name and the target it holds.

type RefMovedError added in v0.0.21 

type RefMovedError struct {
	Name string
	// Current is the target the ref holds, the zero RefTarget when it
	// holds none.
	Current RefTarget
}

RefMovedError is the error UpdateRef returns when the ref holds another target than the one expected. errors.Is(err, ErrRefMoved) holds, and errors.As finds the holder's target.

func (*RefMovedError) Error added in v0.0.21 

func (e *RefMovedError) Error() string

Error implements error.

func (*RefMovedError) Unwrap added in v0.0.21 

func (e *RefMovedError) Unwrap() error

Unwrap returns ErrRefMoved.

type RefStore added in v0.0.21 

type RefStore interface {
	// ResolveRef returns the ref's target, or [ErrNoRef]. A ref whose
	// session is gone is dangling: ResolveRef returns its target
	// together with an error wrapping [ErrNoSession], so a caller can
	// tell which session it was and move the ref.
	ResolveRef(ctx context.Context, name string) (RefTarget, error)
	// UpdateRef moves the ref from expected to next, the zero RefTarget
	// meaning none: none as expected creates the ref if it is absent,
	// none as next deletes it. On a mismatch it returns [ErrRefMoved]
	// as a [*RefMovedError] carrying the target the ref holds. A next
	// whose session the store does not hold is [ErrNoSession], and one
	// whose entry that session does not hold is [ErrNoEntry]. An update
	// that changes nothing is not logged. reason is recorded in the ref
	// log and may be empty.
	UpdateRef(ctx context.Context, name string, expected, next RefTarget, reason string) error
	// ListRefs lists the refs whose name begins with prefix, in name
	// order. It does not check that the sessions exist.
	ListRefs(ctx context.Context, prefix string) iter.Seq2[Ref, error]
	// RefLog lists the ref's updates, newest first, and nothing for a
	// name never updated. It outlives the ref's deletion.
	RefLog(ctx context.Context, name string) iter.Seq2[RefUpdate, error]
}

RefStore is implemented by a store that keeps refs, as RFC 0002's refs section defines them. A store opened read-only resolves and lists, and reports ErrReadOnly from UpdateRef.

type RefTarget added in v0.0.21 

type RefTarget struct {
	Session string
	// Entry is the entry the ref pins, or "". It must be an entry the
	// session holds: its base, one of its own, or one on its prefix.
	Entry string
}

RefTarget is what a ref points to: a session, and optionally an entry of it that the ref pins. The zero RefTarget is "no ref", as an expected value and as a next one.

func (RefTarget) IsZero added in v0.0.21 

func (t RefTarget) IsZero() bool

IsZero reports whether t names nothing.

func (RefTarget) String added in v0.0.21 

func (t RefTarget) String() string

String renders the target as the session, then @ and the entry when one is pinned.

type RefUpdate added in v0.0.21 

type RefUpdate struct {
	Name     string
	Old, New RefTarget
	Time     time.Time
	Reason   string
}

RefUpdate is one accepted update, as the ref log records it. Old is the zero RefTarget for a creation and New is for a deletion.

type ResponseEntry 

type ResponseEntry struct {
	EntryBase   `json:"-"`
	ResponseID  string                           `json:"response_id"`
	Model       string                           `json:"model,omitempty"`
	Status      openresponses.ResponseStatus     `json:"status"`
	Usage       *openresponses.Usage             `json:"usage,omitempty"`
	Incomplete  *openresponses.IncompleteDetails `json:"incomplete,omitempty"`
	Error       *openresponses.ErrorPayload      `json:"error,omitempty"`
	RequestHash string                           `json:"request_hash,omitempty"`
	LatencyMS   int64                            `json:"latency_ms,omitempty"`
	// Attempts is the number of calls to the model this response took,
	// itself included, when the harness retried calls that failed and
	// recorded none of them as a response entry of its own. Zero means
	// one. An attempts member that is not a positive integer, which a
	// file from before the member was defined may hold, is kept as
	// written in Unknown and Attempts is zero.
	Attempts int `json:"-" member:"attempts"`
}

ResponseEntry is the envelope of one model call, written after its output items. It is not in context.

func (*ResponseEntry) Calls added in v0.0.10 

func (e *ResponseEntry) Calls() int

Calls returns the number of calls to the model the response took: Attempts, or one when it is not set.

func (*ResponseEntry) EntryType 

func (*ResponseEntry) EntryType() string

EntryType returns "response".

func (*ResponseEntry) MarshalJSON 

func (e *ResponseEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits the entry as one JSON object.

func (*ResponseEntry) UnmarshalJSON 

func (e *ResponseEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the entry.

type Result added in v0.0.8 

type Result struct {
	ID      string
	Outcome Outcome
	// Unresolved lists references in the entry a store could not
	// resolve — a sidecar blob it does not hold, a convergence into a
	// session it does not have — which the format lets a store report
	// rather than refuse. A session in memory sets nothing here.
	Unresolved []string
	// Reopen is set by a store when the append is durable but the
	// caller's session could not be brought in step with it, so the
	// caller opens the session again before using it further.
	Reopen bool
	// Durable is set by a store that says whether it acknowledged the
	// append once it was durable, as RFC 0002 asks of a store that
	// may acknowledge one before. A session in memory, and a store
	// that does not report it, leaves it false.
	Durable bool
}

Result is what Commit reports: the entry's ID and what appending it did. A store adds what it alone can know.

type Run added in v0.0.5 

type Run struct {
	Start *RunEntry
	// End is nil when no end entry for the run is on the segment.
	End     *RunEntry
	Segment []Entry
	// Path is the root-first path up to the last entry of the segment,
	// of which Segment is the tail. The end reason of a run that
	// answers a call an earlier run's model call made is a shape of
	// the path, not of the segment alone; see [ComputeReason]. It is
	// nil in a Run built by hand, and then the segment stands for the
	// path.
	Path []Entry
}

Run is one run's segment of a path: the entries from its start entry to its end entry, or to the end of the path when the run was cut off or closed by a branch.

func Runs added in v0.0.5 

func Runs(path []Entry) []*Run

Runs partitions a root-first path into its runs. Entries before the first start entry belong to no run and are dropped; a start entry closes any run still open, as a branch does. Only an end entry whose run_id matches the open run closes it.

func (*Run) Calls added in v0.0.5 

func (r *Run) Calls() []*Call

Calls returns the run's calls: those on its segment, and those made before it that the segment holds a decision, a dispatch or an output for, since the run took them up. Each carries what the path holds for it; see Calls.

func (*Run) Empty added in v0.0.19 

func (r *Run) Empty() bool

Empty reports whether the run's segment holds no entry but its start and its end, or, for a run that was cut, none after its start: a run refused, or killed, before it did anything. Such a run written SourceResume is the shape of SourceInput, and format 0.11 accepts it as written, since all it shows is that its writer meant to take up a call and took up nothing: Session.VerifyRecords does not report it with ErrSourceMismatch. Empty tells it from a resume that adds a message or an output and takes up nothing, which is still reported.

func (*Run) Pending added in v0.0.5 

func (r *Run) Pending() []string

Pending returns the IDs of the run's calls with no output on the path, a call made before the segment that the run took up among them; see Run.Calls.

func (*Run) RunID added in v0.0.5 

func (r *Run) RunID() string

RunID returns the run's ID.

func (*Run) Verify added in v0.0.5 

func (r *Run) Verify() error

Verify checks the run's end entry against its segment. A written error or interrupted stands over any segment; any other reason must match ComputeReason, and the pending list must match Run.Pending. A run without an end verifies trivially.

type RunEntry added in v0.0.5 

type RunEntry struct {
	EntryBase `json:"-"`
	RunID     string `json:"run_id"`
	Phase     string `json:"phase"`
	// Source is set on a start entry.
	Source string `json:"source,omitempty"`
	// Reason is set on an end entry.
	Reason string `json:"reason,omitempty"`
	// Ref names the trigger of a start or the cause of an end in the
	// harness's own terms. Readers treat it as opaque.
	Ref string `json:"ref,omitempty"`
	// Trigger, on a start entry, says how the input that started the run
	// arrived, in parts, beside Ref and changing nothing about it. A
	// harness's richer facts about the firing, such as when it was due
	// or which attempt it is, go in [Trigger.Unknown]; members of the
	// run entry this package does not define, where format 0.6 put
	// them, are kept in [EntryBase.Unknown]. A trigger member this type
	// cannot hold exactly, one written before the member was defined,
	// is kept there as written and Trigger is nil.
	Trigger *Trigger `json:"-" member:"trigger"`
	// Pending lists, on an end entry, the IDs of the calls left without
	// an output. It is written even when empty.
	Pending []string `json:"pending"`
}

RunEntry marks the start or the end of one pass of the harness's loop. Two entries per run share a RunID. A start carries Source and an optional Ref naming what triggered the input in the harness's own terms; an end carries Reason, the IDs of the calls left pending and an optional Ref naming the cause.

func NewRunEnd added in v0.0.5 

func NewRunEnd(runID, reason, ref string, pending []string) *RunEntry

NewRunEnd builds the entry that closes a run. pending lists the IDs of the calls left without an output; Session.EndRun computes it from the path. ref may be "".

func NewRunStart added in v0.0.5 

func NewRunStart(runID, source, ref string) *RunEntry

NewRunStart builds the entry that opens a run. ref may be "".

func (*RunEntry) EntryType added in v0.0.5 

func (*RunEntry) EntryType() string

EntryType returns "run".

func (*RunEntry) IsEnd added in v0.0.5 

func (e *RunEntry) IsEnd() bool

IsEnd reports whether the entry closes a run.

func (*RunEntry) IsStart added in v0.0.5 

func (e *RunEntry) IsStart() bool

IsStart reports whether the entry opens a run.

func (*RunEntry) MarshalJSON added in v0.0.5 

func (e *RunEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits the entry as one JSON object. Which members are written depends on the phase: a start carries source, an end carries reason and always carries pending, even when empty, since a run that ended owing nothing is a fact a reader relies on.

The other phase's members are written when they are set rather than dropped. Nothing this library builds sets them, and validateLifecycle asks only for the phase's own, so a well-formed entry is written exactly as it was before. A file from elsewhere that carries one is the case that matters: the envelope rule is that a reader preserves what it does not itself need, and rewriting such a file to drop a member it declared breaks that promise silently. Rejecting the shape on the way in would be the alternative, and a larger decision than an encoder.

func (*RunEntry) UnmarshalJSON added in v0.0.5 

func (e *RunEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes the entry.

type Session 

type Session struct {
	// contains filtered or unexported fields
}

Session is one session in memory: the header, the entries in file order, the tree they form and the current leaf. It is safe for concurrent use. Entries are shared, not copied, and must not be modified after they are appended.

func Continue added in v0.0.5 

func Continue(ctx context.Context, store Store, id string, summary openresponses.Item) (*Session, error)

Continue rolls a session over into a successor, for a conversation that has outgrown its file: a months-long unattended session, or one whose compaction has folded the context many times over while the file kept growing. It does the four steps in the order the format wants them: the successor is created with parent_session naming id and the old header's harness, working directory, records and media mode; its first entry is a full config carrying the settings in force at the old leaf, so the first request on the new root rebuilds and a recorder finds a config on the path; summary, when not nil, is appended as the item that carries the conversation across; the old session's display name is carried over; and the old session gets a continued_in link naming the successor, which is what a store reads to mark it superseded. It returns the successor.

func ContinueRef added in v0.0.21 

func ContinueRef(ctx context.Context, st Store, name string, summary openresponses.Item) (*Session, error)

ContinueRef continues the session ref name points to, as Continue does, and moves the ref from the old session to the successor by compare-and-swap, so a named conversation that rolls over keeps its name. The ref's pinned entry, which names an entry of the old session, is not carried.

When the ref moved while the continuation ran, the error is ErrRefMoved and the successor is returned with it: it exists, the old session is retired, and the caller decides where the name goes.

func Fork added in v0.0.8 

func Fork(origin *Session, at string, h Header) (*Session, error)

Fork creates a session that continues from entry at of origin: a session with a base, in the format's terms. The new session's header is h with Base set to at and, when h names none, ParentSession set to origin's ID; its entries open with origin's path to at, the prefix, which the new session shares with origin rather than copies, and its leaf is the base. Every entry it appends hangs from the base or from an entry it appended itself, and its file opens with the prefix so it stands alone. The base may not be a leaf label, since it is the fork's first leaf and the leaf never rests on one, and h's media, when set, must be origin's, since the prefix was written in that form. Fork refuses a prefix that could not stand alone: one holding an entry that converges an entry of origin off the path (ErrBadConvergence), or an entry of a migrated origin that the migration could not rewrite (ErrUnresolvedMigration).

A store's Create does the same for a header whose Base is set, so Fork is the in-memory form and a store's Create the persistent one.

func New 

func New(h Header) *Session

New creates an empty session. Header fields left empty are filled: a UUIDv7 ID, the current time, this package's format and payload. Times the session assigns are in UTC so a file carries one offset however the writer's clock is configured; times the caller supplies are kept as given.

func Read 

func Read(r io.Reader) (*Session, error)

Read decodes a session from its JSONL form. A final line that does not parse is tolerated and reported through Session.Truncated; any other malformed line, a missing parent, a convergence reference that names no entry yet in this file, a line that breaks the base rule (ErrBaseRule) in a file whose header names one, or a repeated ID is an error. The leaf is the last entry in the file unless a LeafLabel is in force, in which case it is the entry that label names.

func SessionFor added in v0.0.21 

func SessionFor(ctx context.Context, st Store, name string, h Header) (s *Session, err error)

SessionFor returns the session ref name points to, creating one from h and setting the ref when there is none. It is the answer to two harnesses that each create a session for one name: the ref is created by compare-and-swap, so one caller's session wins, and the other opens the winner's and deletes its own, which nothing else has seen. A dangling ref, whose session is gone, is replaced the same way.

The session comes from Open, so a store that guards sessions against a second writing process reports ErrSessionLocked to a caller whose winner is held by another process.

func (*Session) Append 

func (s *Session) Append(e Entry) (string, error)

Append adds e to the tree. Its ID is the hash of its envelope over the hash of its body, as the format defines, and is computed here; an ID the caller set must match or the append is refused. An empty Parent is set to the current leaf, so an explicit Parent branches in place; a zero Timestamp is set to now, and any timestamp is taken to UTC, the one spelling the format admits. In a session with a base, the parent must be the base or an own entry.

An append under the leaf makes the entry the leaf; an append elsewhere is a branch and the leaf does not move. A leaf label makes its target the leaf, wherever the label's own parent sits, when the target is the base or an own entry and not itself a label; otherwise nothing moves. The leaf never rests on a leaf label. An entry the session already holds — same type, body, parent, parents and timestamp — is a no-op that returns the existing ID.

Parents, when the caller set any, is sorted into the order the format requires and checked against the convergence rules; it does not move the leaf and does not reach any context. On success e is owned by the session and must not be modified.

func (*Session) Branch 

func (s *Session) Branch(id string) error

Branch moves the leaf to id, so the next append becomes a child of that entry. When id is inside a run, the run is open on the new path; see Session.EndRun for who closes it.

func (*Session) Calls added in v0.0.5 

func (s *Session) Calls(leaf string) ([]*Call, error)

Calls returns the calls on the path to leaf; see Calls. A call made in a fork's prefix is known as one, so its State reads the header's promise as not covering it.

func (*Session) Children 

func (s *Session) Children(id string) []string

Children returns the IDs of the entries whose parent is id, in file order. Pass "" for the roots.

func (*Session) Commit added in v0.0.8 

func (s *Session) Commit(e Entry) (Result, error)

Commit is Append with its outcome reported.

func (*Session) Compact 

func (s *Session) Compact(firstKept string, summary openresponses.Item) (*CompactionEntry, error)

Compact builds the compaction entry for the current leaf: FirstKept names the earliest entry on the path that stays in context, summary is the item that replaces everything before it, and the settings checkpoint is taken from the context at the leaf. The entry is not appended; set TokensBefore, Usage or Pinned if they apply, then append it through the store. A caller that knows an item index rather than an entry ID uses Session.CompactFrom or Session.CompactKeeping.

func (*Session) CompactFrom added in v0.0.4 

func (s *Session) CompactFrom(first int, summary openresponses.Item) (*CompactionEntry, error)

CompactFrom is Session.Compact for a caller that split the request input at an index: FirstKept is the entry that contributed item first of the context at the leaf, and the items before it are what summary replaces. The index counts the items the context algorithm produces, Context.Items, so entries that contribute no item do not shift it. The item at first cannot be an earlier compaction's summary or one of its pinned items: the format keeps entries, and what a compaction contributes is kept only while it is the last compaction on the path.

func (*Session) CompactKeeping added in v0.0.4 

func (s *Session) CompactKeeping(kept int, summary openresponses.Item) (*CompactionEntry, error)

CompactKeeping is Session.Compact for a caller that knows how many items of the request input it kept: the last kept items of the context at the leaf stay, and summary replaces the rest. kept must be at least 1, because FirstKept names an entry, and at most the number of items in the context.

func (*Session) Context 

func (s *Session) Context() (Context, error)

Context builds the context at the current leaf. With no leaf it is empty.

func (*Session) ContextAt 

func (s *Session) ContextAt(id string) (Context, error)

ContextAt builds the context at entry id, the request a model call appended after that entry would receive. An empty id yields an empty context.

func (*Session) ContextHash added in v0.0.8 

func (s *Session) ContextHash(id string) (string, error)

ContextHash computes the context hash at entry id, as RFC 0002 defines it: the key a store can compute as it appends and a router can key a provider's cached prefix on. It is defined over the path ending at the entry by the entry's type and not by any later leaf. An item, config, compaction or branch_summary contributes; a response, a record entry and an extension entry do not. The value before any contributing entry is the hash of the canonical null; a non-contributing entry takes its parent's; a contributing entry hashes the three-element array of its parent's context hash, its type and its content hash as the section defines, with the per-run provenance members removed from the body first and a compaction's first_kept replaced by the context hash and type of the entry it names.

It excludes ts and parents, it is incremental, and two sessions whose contributing entries are byte-identical share it. It is not request_hash: on a path with no compaction the two identify the same request, and after a fold they part.

func (*Session) DeclaredFormat added in v0.0.18 

func (s *Session) DeclaredFormat() string

DeclaredFormat returns the format the session's file named in its header when it was read, before Read brought the header up to the format this package writes; for a session made here, the format it writes. A reader that hedges on a rule a minor gained says so of the minor the file declared. A store that raises the header before an append leaves this as read; the session read again declares the raised format.

func (*Session) Dispatches added in v0.0.18 

func (s *Session) Dispatches(target string) []*DispatchEntry

Dispatches returns the dispatches for the call whose function call is the entry target, anywhere in the session, in the order they were added, each naming the call by its call ID. A call with none on its path may have one elsewhere, which a rebase above it leaves, and may then have run. A call in a fork's prefix has its dispatches, if any, in the session the fork was made from, which the fork does not hold; OriginDispatches reads them through a store.

func (*Session) EndRun added in v0.0.5 

func (s *Session) EndRun(reason, ref string) (*RunEntry, error)

EndRun builds the end entry for the run open at the current leaf: its pending list is Run.Pending. reason is one of the Reason constants and ref may be "". The entry is not appended.

A writer that continues a path on which a run is open that it is not running owns that run and closes it before appending anything else, as the format has it: after Session.Branch into a run, with ReasonInterrupted and a ref naming the rewind; on resuming a run a crash cut off, with ReasonError and a ref naming the cut. Session.OpenRun at the leaf says whether there is one.

func (*Session) Entries 

func (s *Session) Entries() []Entry

Entries returns the entries in file order. The slice is a copy; the entries are shared.

func (*Session) Entry 

func (s *Session) Entry(id string) (Entry, bool)

Entry returns the entry with the given ID.

func (*Session) Extend added in v0.0.21 

func (s *Session) Extend(e Entry) (Result, error)

Extend adds e, an entry a store already holds, to a session read from that store, and places the leaf as Read would had e been in what it read: the newest entry under the durable leaf mark that was appended after it, the mark itself when none was, and the newest entry when no mark is in force. Session.Commit applies the live rule instead, under which an entry whose parent is not the leaf is a branch and moves nothing; a session read from a file has no live leaf to follow, so the two differ after a writer's Session.Branch. A follower of a store whose sessions Read builds keeps its session up to date with Extend.

func (*Session) Header 

func (s *Session) Header() Header

Header returns a copy of the header.

func (*Session) ID 

func (s *Session) ID() string

ID returns the session ID.

func (*Session) Judges added in v0.0.20 

func (s *Session) Judges(leaf string) ([]*LinkEntry, error)

Judges returns the judged_by links on the path to leaf; see Judges.

func (*Session) Labels 

func (s *Session) Labels() map[string]string

Labels returns the current label of every labelled entry: the last label entry per target wins, and a null label clears.

func (*Session) Leaf 

func (s *Session) Leaf() string

Leaf returns the ID of the entry the next append will name as its parent, or "" when the next append starts a new root.

func (*Session) Leaves 

func (s *Session) Leaves() []string

Leaves returns the IDs of the entries that have no children, in file order.

func (*Session) Len 

func (s *Session) Len() int

Len returns the number of entries.

func (*Session) MarkLeaf added in v0.0.5 

func (s *Session) MarkLeaf() (*LabelEntry, error)

MarkLeaf builds the label entry that makes the current leaf durable, so a reopened session resumes on this branch rather than on whichever one the last line happens to be under. Append it through the store after Branch; the leaf stays where it is, and appending past the mark moves the resumed leaf with it. It returns an error when there is no leaf.

A mark records which branch is live, so a host that moves to another branch marks again; nothing under an abandoned mark follows it, and the abandoned mark is what a reopen honours.

func (*Session) Migrated added in v0.0.8 

func (s *Session) Migrated() (bool, []string)

Migrated reports whether the session was read from a file of an earlier minor version and rewritten in memory, so its entries carry LegacyID, and returns the IDs of entries the migration could not rewrite: extension entries, whose members may name entries the reader cannot recognise. A migrated session with unresolved entries cannot be written as 0.5.

func (*Session) Name 

func (s *Session) Name() string

Name returns the display name from the last info entry that set one.

func (*Session) OpenRun added in v0.0.5 

func (s *Session) OpenRun(leaf string) (*Run, error)

OpenRun returns the run on the path to leaf that has no end entry, or nil when every run is closed or there is none.

func (*Session) Path 

func (s *Session) Path(id string) []Entry

Path returns the entries from the root to id, root first, or nil when id is not in the session.

func (*Session) PendingCalls added in v0.0.5 

func (s *Session) PendingCalls(leaf string) ([]*Call, error)

PendingCalls returns the calls on the path to leaf that have no output, which is what a resume answers.

func (*Session) PendingQueued added in v0.0.6 

func (s *Session) PendingQueued(leaf string) ([]*QueuedEntry, error)

PendingQueued returns the inputs queued on the path to leaf that have not been appended; see Queued.

func (*Session) Prefix added in v0.0.8 

func (s *Session) Prefix(id string) bool

Prefix reports whether id is on the path to the session's base: an entry another session wrote, carried so the file stands alone.

func (*Session) Prepare added in v0.0.8 

func (s *Session) Prepare(e Entry) (Result, error)

Prepare does everything Append does short of adding the entry: it fills the parent and the timestamp, sorts and checks the references, applies the parent rule, and computes the hashes, setting the ID on the entry. It reports the outcome Commit would have. A store uses it to know the entry's hashes before anything is written, so that nothing is visible in memory before the store's commit point; a Commit of the same entry afterwards recomputes the same values.

func (*Session) Repeated added in v0.0.8 

func (s *Session) Repeated() []string

Repeated returns the IDs Read met a second time in the file, each treated as the same entry as the first, in file order.

func (*Session) RequestContext 

func (s *Session) RequestContext(id string) (Context, error)

RequestContext rebuilds the context of the request that produced the response entry id: the path to the entry with the response's own output items removed, as OutputEntries finds them. Only those item entries are removed; everything else on the path stays, so an entry another layer wrote between two output items of one response, which contributes nothing to context, leaves the rebuilt request and its hash alone.

func (*Session) ResetLeaf 

func (s *Session) ResetLeaf()

ResetLeaf clears the leaf, so the next append starts a new root.

func (*Session) Resolve added in v0.0.9 

func (s *Session) Resolve(id string) (string, bool)

Resolve returns the ID of the entry id names: id itself when it is an entry's ID, else the ID of the entry a migration rewrote from id, whose LegacyID it is, in the session as read or in a 0.5 file that kept the member. Everything written about a session before its file was migrated names entries by their old IDs; Resolve is how a reader holding one finds the entry, since Entry, Path and the rest take the current ID alone.

func (*Session) Roots 

func (s *Session) Roots() []string

Roots returns the IDs of the root entries in file order.

func (*Session) Runs added in v0.0.5 

func (s *Session) Runs(leaf string) ([]*Run, error)

Runs returns the runs on the path to leaf; see Runs.

func (*Session) SummarizeBranch 

func (s *Session) SummarizeBranch(from string, summary openresponses.Item) (*BranchSummaryEntry, error)

SummarizeBranch builds the branch summary that carries context from the abandoned leaf from to the current leaf, where the new branch continues. Move the leaf with Branch first, then append the result through the store; its parent is set on append. When the new leaf is inside a run, that run is open on the new path and the writer closes it first: append Session.EndRun with ReasonInterrupted before the summary, so the path does not read as a run a crash cut off.

func (*Session) SupersededBy added in v0.0.5 

func (s *Session) SupersededBy() string

SupersededBy returns the successor named by the last continued_in link in the session, or "".

func (*Session) Truncated 

func (s *Session) Truncated() *TruncatedLine

Truncated reports the final line of the file this session was read from when that line did not parse, or nil. A truncated line is what a crash mid-append leaves behind; the entries before it are intact.

func (*Session) UnresolvedOf added in v0.0.20 

func (s *Session) UnresolvedOf(leaf string) ([]*ConfigEntry, error)

UnresolvedOf returns the config entries on the path to leaf that carry a keep with an of the path cannot resolve; see UnresolvedOf.

func (*Session) Verify 

func (s *Session) Verify(id string) error

Verify rebuilds the request for the response entry id and checks that it hashes to the entry's RequestHash. A response that recorded no hash returns ErrNoHash: nil means the request was checked. 

func (s *Session) VerifyLinks(resolve func(id string) (*Session, error)) error

VerifyLinks checks every subsession link the session wrote against the header of the session it names, read through resolve: the target's parent_session is this session's id and its spawned_by is the link's call_id, as RFC 0001 says of a subsession. A target resolve does not find, returned as (nil, nil), is a child that never started, which a link written at dispatch records by design, and passes; an error from resolve is reported for that link. A link on a fork's prefix is the origin's, to be checked there against the origin's id, since the child it names was spawned by the origin; it is passed over, as are links of other relations, which name no spawn. It returns the first problem found, a *LinkError, and with a nil resolve checks nothing.

func (*Session) VerifyRecords added in v0.0.5 

func (s *Session) VerifyRecords(leaf string) error

VerifyRecords checks the record entries on the path to leaf against the format's rules: every function call has a call ID and none repeats in the session, every decision and dispatch names its call by target, every run start's source and every run end agree with the segment, no dispatch or decision follows a reject or an answer on the same call, no answer, reject or dispatch follows an output and no reject a dispatch, and, when the header names dispatch in records, no answer ends a call with no dispatch and every call that ran has a dispatch. A run written resume over a segment that holds nothing agrees with it, as format 0.11 has it, in a file of any minor. The rules that rest on records apply to what the session wrote, the entries after its base: a fork's prefix is another session's record, kept to that session's promise. It returns the first problem found.

type Settings 

type Settings struct {
	Model        string                        `json:"model,omitempty"`
	Instructions string                        `json:"instructions,omitempty"`
	Reasoning    openresponses.ReasoningConfig `json:"reasoning,omitzero"`
	Text         openresponses.TextConfig      `json:"text,omitzero"`
	// InstructionsParts are the parts the instructions are composed
	// of, in order, when the path named them, each carrying its text.
	// Instructions is always their texts joined with [PartSeparator],
	// so a reader that does not care about the composition reads the
	// string as before. It is empty for a path that set the
	// instructions as one string.
	InstructionsParts []InstructionPart `json:"instructions_parts,omitempty"`
	// InstructionsOmitted are the parts left out of the instructions
	// that are in force: the list the last config entry carrying one
	// wrote, each keep in it resolved against the list before it,
	// cleared by an empty list or a replace without one. A keep the
	// path could not satisfy stays in the list as written: see
	// [OmittedPart.Unresolved]. It
	// reaches no request, so [Settings.Request] leaves it out and the
	// request hash does not cover it; a compaction checkpoint carries
	// it so the list survives the fold. A checkpoint member that does
	// not decode as a list of parts, which a file from before 0.8 may
	// hold, is kept as written and InstructionsOmitted is nil.
	InstructionsOmitted []OmittedPart `json:"instructions_omitted,omitempty"`
	// Omit is what a request leaves out of the context, in force as the
	// path's config entries set it: see [Omit]. The checkpoint of a
	// compaction carries it. A checkpoint member that does not decode as
	// the object, which a file from before 0.11 may hold, is kept as
	// written and Omit is zero.
	Omit  Omit                `json:"omit,omitzero"`
	Tools openresponses.Tools `json:"tools,omitempty"`
	// Extra carries request members beyond the named ones, keyed by
	// their wire name.
	Extra map[string]json.RawMessage `json:"extra,omitempty"`
	// contains filtered or unexported fields
}

Settings are the request settings in force at a point on a path: the result of replaying config entries. The JSON form is the full-config checkpoint a compaction entry carries.

func (Settings) Apply 

func (s Settings) Apply(c *ConfigEntry) Settings

Apply returns the settings after the delta c. The receiver is not modified.

func (Settings) ExtraValue added in v0.0.3 

func (s Settings) ExtraValue(key string, v any) (bool, error)

ExtraValue decodes the passthrough member key into v. It reports false, and leaves v alone, when the settings carry no such member.

func (Settings) InstructionsDelta added in v0.0.6 

func (s Settings) InstructionsDelta(parts []InstructionPart) *ConfigEntry

InstructionsDelta returns the config delta that takes the instructions from these settings to parts: the whole ordered list, with the text of every part that is new or whose text or source changed, a keep for every run of unchanged parts in the order they are in force, and the hash alone of an unchanged part out of that order, so a change to one layer costs that layer and not the whole prompt, however many parts it has. A part in force that parts leaves out is removed by its absence. parts names each ID once.

A part that is not in force, or is in force with other resolved text, is named by its hash alone when the path has given its ID that text and source and the part has since left force, as format 0.11 lets a writer: an agent handed the session back after another replaced its parts costs the parts that changed, and not its whole prompt. A part in force with its text and another source, and one in force the path could not resolve, carry their text, since a hash resolves against the part in force first, and so does a part the path never had under its ID. A replace and a compaction's checkpoint start the path's parts afresh, so a part that left force before one carries its text again. A delta written this way is read by a reader of 0.11, which resolves a hash against the parts that have left force; the library writes 0.11 headers, so a reader of 0.10 that cannot has refused the file.

It returns nil when parts are exactly the ones in force, so a harness that re-renders its layers every turn writes nothing when nothing moved.

func (Settings) OmitDelta added in v0.0.20 

func (s Settings) OmitDelta(want Omit) (*Omit, bool)

OmitDelta returns the omit member that takes the omit in force in these settings to want, for ConfigEntry.Omit, and whether one does. It is nil, and true, when want is what is in force, so a recorder that states its rule at every model switch writes it once; the rule and the entries not yet in force when want only adds to what is, a rule other than the one in force included, which a delta replaces; and an empty, non-nil object, which clears, when want is empty and something is in force. A want that drops the rule or an entry in force and keeps something is no single member: a delta only adds, and clears both with {}, so it returns nil and false, and the writer clears in one entry and writes what it keeps in the next. So does a want whose rule is not one the format defines, which no delta sets.

A config entry with Replace set discards the omit in force with the rest of the settings, so the member it carries is want itself, not this delta: a replace that wrote nothing, because the rule was in force, would clear it.

func (Settings) OmittedDelta added in v0.0.12 

func (s Settings) OmittedDelta(omitted []OmittedPart) []OmittedPart

OmittedDelta returns the instructions_omitted member that takes the omitted parts in force in these settings to omitted, for ConfigEntry.InstructionsOmitted: nil when omitted is the list in force, so a writer that renders its omissions every turn writes nothing when nothing moved; an empty, non-nil list, written as [], when omitted is empty and a list is in force; and otherwise the shortest of three, as encoded: omitted whole; omitted with every run of parts in force, unchanged and in the order they are in force, named by a keep, so a part moving across a budget costs that part and not the whole list; and omitted with every run of parts that an earlier entry on the path put in force, unchanged and in that list's order, named by a keep carrying of, so a hand-back to an agent whose list another agent replaced costs one element and not the list. Each of the sixteen lists put in force most recently before the one in force is tried, newest first, and one is used only when it is shorter than the best so far, so a list in force that the keeps already cover is never named by of. A part that changed, is new or is out of the order of the list a delta counts over is written whole. omitted names each ID once; when it does not, omitted is returned whole, and a list a delta would count over that names an ID twice is not counted over.

The lists an of can name are those the settings recorded as they were replayed, so settings from Session.Context or BuildContext have them, back to the last replace or compaction; settings built by hand have none, and the result is the first two. An of is the ID of the config entry, so a recorder writes the delta for the entry it is about to append and nothing else.

A delta with Replace set discards the lists in force and earlier ones, so its keeps would resolve against nothing: such a delta carries omitted itself.

func (Settings) Request 

func (s Settings) Request(items openresponses.Items) (openresponses.Request, error)

Request builds the canonical request for these settings over items: store false and no previous_response_id, as the context algorithm requires. Extra members ride in Request.Extra and are flattened on encode.

func (*Settings) UnmarshalJSON added in v0.0.11 

func (s *Settings) UnmarshalJSON(data []byte) error

UnmarshalJSON decodes a checkpoint, taking instructions_omitted only when the member is spelled exactly and holds a list of parts that encodes back to what the line holds, extra members aside, as a member promoted into a typed field is taken. Anything else, such as a part whose id is spelled "ID", is left for the rewrite to keep as written.

type Store 

type Store interface {
	// Create starts a new session from h, filling empty header fields.
	// A header whose Base is set makes a fork, as [Fork] does: the
	// session opens with the path to the base, taken from the session
	// ParentSession names when that session holds it and otherwise from
	// any session the store holds it in. Create refuses a base the store
	// does not hold with ErrNoEntry, and a base that is a leaf label or a
	// media form other than the origin's, rather than letting the first
	// append fail.
	Create(ctx context.Context, h Header) (*Session, error)
	// Open loads the session with the given ID. A store that guards
	// sessions against a second writing process takes the session's
	// hold here and keeps it until the store lets it go, at its Release
	// or Close: one hold per session per store, which a Release frees
	// whoever opened it. A process that reads sessions it does not
	// write, such as a search across a history beside the harness
	// writing it, reads them through [Reader] or through a second store
	// opened read-only, never by Open and Release on the writing store,
	// which would keep each session from other processes or free one
	// its own writer is using.
	Open(ctx context.Context, id string) (*Session, error)
	// Append adds e to the session and returns its ID.
	Append(ctx context.Context, sessionID string, e Entry) (string, error)
	// List enumerates sessions matching f, newest first.
	List(ctx context.Context, f ListFilter) iter.Seq2[Summary, error]
	// Delete removes the session.
	Delete(ctx context.Context, id string) error
}

Store persists sessions. Append is the only write to a session's content; the entry is added to the in-memory tree of the open session and made durable according to the store's policy. Sessions returned by Create and Open are shared with the store, so leaf moves through Session.Branch and Session.ResetLeaf are seen by later appends.

A store that guards a session against a second writing process reports ErrSessionLocked from the calls that need the hold, and a store opened read-only reports ErrReadOnly from the calls that write.

type Summary 

type Summary struct {
	Header Header
	// Name is the session's display name, from the last info entry
	// that set one, when the store provides it: see
	// ListFilter.WithNames.
	Name string
	// SupersededBy names the successor the session was continued in,
	// from its last continued_in link, when the store provides it: a
	// store that indexes links fills it always, a file store when
	// ListFilter.WithNames or Current asks it to scan.
	SupersededBy string
	// Path is where the session lives, for file-backed stores.
	Path string
	// Size is the stored size in bytes, when known.
	Size int64
	// Modified is when the session last changed, when known.
	Modified time.Time
}

Summary describes a stored session without loading it.

type Trigger added in v0.0.6 

type Trigger struct {
	Kind   string `json:"kind,omitempty"`
	Ref    string `json:"ref,omitempty"`
	Source string `json:"source,omitempty"`
	// Unknown holds the members of the trigger the format does not
	// define, the harness's own facts about the arrival such as when a
	// scheduled firing was due and which attempt it is, encoded inline
	// beside kind, ref and source. It is nil when there are none.
	Unknown map[string]json.RawMessage `json:"-"`
}

Trigger says how an input arrived, in the harness's own terms: Kind is the sort of thing it came from (a person, a channel, a schedule, another agent), Ref names the thing itself (a message ID, a cron name) and Source names the layer that took it. A reader treats all three as opaque; what the format fixes is where they are written, so two people steering one run are two triggers and not one.

func (*Trigger) Clone added in v0.0.11 

func (t *Trigger) Clone() *Trigger

Clone returns a copy of the trigger that shares no map with it, or nil for nil.

func (*Trigger) Equal added in v0.0.11 

func (t *Trigger) Equal(u *Trigger) bool

Equal reports whether two triggers are the same: kind, ref, source and every member the format does not define, compared in canonical form, so the order and spacing a line gave them do not count. Two nil triggers are equal. A Trigger holds a map, so == does not compile on it.

func (Trigger) MarshalJSON added in v0.0.11 

func (t Trigger) MarshalJSON() ([]byte, error)

MarshalJSON emits kind, ref, source and the unknown members as one object.

func (*Trigger) SetMember added in v0.0.11 

func (t *Trigger) SetMember(key string, v any) error

SetMember sets a member of the trigger the format does not define, such as when a scheduled firing was due or which attempt it is.

func (*Trigger) UnmarshalJSON added in v0.0.11 

func (t *Trigger) UnmarshalJSON(data []byte) error

UnmarshalJSON takes kind, ref and source, spelled exactly, and keeps every other member in Unknown.

type TruncatedLine 

type TruncatedLine struct {
	// Line is the 1-based line number in the file.
	Line int
	// Data is the line as read, without its terminator.
	Data []byte
	// Err is the decode error.
	Err error
}

TruncatedLine describes a final line that did not parse.

func (*TruncatedLine) Error 

func (t *TruncatedLine) Error() string

Error implements error.

func (*TruncatedLine) Unwrap 

func (t *TruncatedLine) Unwrap() error

Unwrap returns the decode error.

type UnknownEntry 

type UnknownEntry struct {
	EntryBase
	Type string
	Raw  json.RawMessage
}

UnknownEntry is an entry whose type this package does not define, typically a namespaced extension. Raw holds the original line and is re-emitted verbatim. It is not in context.

func (*UnknownEntry) EntryType 

func (e *UnknownEntry) EntryType() string

EntryType returns the wire type.

func (*UnknownEntry) MarshalJSON 

func (e *UnknownEntry) MarshalJSON() ([]byte, error)

MarshalJSON emits the original bytes.

func (*UnknownEntry) UnmarshalJSON 

func (e *UnknownEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON records the envelope and the raw bytes.

type VCS 

type VCS struct {
	System   string `json:"system"`
	Revision string `json:"revision,omitempty"`
	Dirty    bool   `json:"dirty,omitempty"`
	// Unknown holds the members of vcs the format does not define,
	// encoded inline beside system, revision and dirty. It is nil when
	// there are none.
	Unknown map[string]json.RawMessage `json:"-"`
}

VCS is the version-control state of the working directory. Revision and Dirty cannot tell two dirty trees on one revision apart; a harness that needs to, as one that restores files to a checkpoint does, records the tree's identity in a namespaced member, such as "cline:tree", with VCS.SetMember. A change to it is not a substitution, since only workspace is compared. Replacing an entry's VCS whole drops such members; a caller changing a field edits the VCS it has, or a copy of it, which keeps them.

func (VCS) MarshalJSON added in v0.0.19 

func (v VCS) MarshalJSON() ([]byte, error)

MarshalJSON emits the defined members and the unknown ones as one object.

func (*VCS) SetMember added in v0.0.19 

func (v *VCS) SetMember(key string, val any) error

SetMember sets a member of vcs the format does not define, which should be namespaced, such as "cline:tree".

func (*VCS) UnmarshalJSON added in v0.0.19 

func (v *VCS) UnmarshalJSON(data []byte) error

UnmarshalJSON takes system, revision and dirty, spelled exactly, and keeps every other member in Unknown.

type Workspace added in v0.0.5 

type Workspace struct {
	Kind string `json:"kind,omitempty"`
	Ref  string `json:"ref,omitempty"`
	// Unknown holds the members of workspace the format does not
	// define, such as host or instance, encoded inline beside kind and
	// ref. It is nil when there are none.
	Unknown map[string]json.RawMessage `json:"-"`
}

Workspace says which file system an env entry's cwd is a path in. Ref is one string the harness can resolve to it: an image digest, a host, an instance ID. A container's Ref should be a digest rather than a tag, because a tag moves. Anything else that tells one file system from another, the host a container runs on or its instance, goes in Unknown, inside workspace and not beside it, since the format's substitution rule compares workspace alone: see SameWorkspace.

func (Workspace) MarshalJSON added in v0.0.10 

func (w Workspace) MarshalJSON() ([]byte, error)

MarshalJSON emits kind, ref and the unknown members as one object.

func (*Workspace) SetMember added in v0.0.10 

func (w *Workspace) SetMember(key string, v any) error

SetMember sets a member of the workspace the format does not define, such as the host a container runs on or its instance.

func (*Workspace) UnmarshalJSON added in v0.0.10 

func (w *Workspace) UnmarshalJSON(data []byte) error

UnmarshalJSON takes kind and ref, spelled exactly, and keeps every other member in Unknown.

Source Files

View all Source files

Directories

Path Synopsis
Package atif holds Go types for the Agent Trajectory Interchange Format (ATIF) v1.8, Harbor's interchange format for agent trajectories, as defined by its RFC and the Pydantic models in harbor.models.trajectories.
 Package atif holds Go types for the Agent Trajectory Interchange Format (ATIF) v1.8, Harbor's interchange format for agent trajectories, as defined by its RFC and the Pydantic models in harbor.models.trajectories.
Package cas is the content-addressed session store RFC 0002 describes, laid out on a filesystem the way git lays out a repository:
 Package cas is the content-addressed session store RFC 0002 describes, laid out on a filesystem the way git lays out a repository:
cmd
agentsession command
Command agentsession inspects, verifies, exports and lists Agent Session Format files, and the sessions of a cas store, from a shell, repairs a cas session whose log is damaged, and migrates a cas store from before per-session logs.
 Command agentsession inspects, verifies, exports and lists Agent Session Format files, and the sessions of a cas store, from a shell, repairs a cas session whose log is damaged, and migrates a cas store from before per-session logs.
Package export turns session trees into linear trajectories and ATIF documents.
 Package export turns session trees into linear trajectories and ATIF documents.
internal
follow
Package follow is the loop the file and database stores share to implement agentsession.Follower: a store says how to read a session up to a cursor and what has been written beyond one, and Run turns that into the iterator, keeping the follower's own session, yielding the changes in order and waiting between them.
 Package follow is the loop the file and database stores share to implement agentsession.Follower: a store says how to read a session up to a cursor and what has been written beyond one, and Run turns that into the iterator, keeping the follower's own session, yielding the changes in order and waiting between them.
followtest
Package followtest is the helper the Follow tests of every store share: a follow ranged over in a goroutine, so a case can wait for the next change with a timeout and check that nothing else comes.
 Package followtest is the helper the Follow tests of every store share: a follow ranged over in a goroutine, so a case can wait for the next change with a timeout and check that nothing else comes.
ijson
Package ijson checks that a JSON document is I-JSON (RFC 7493) by the test the session format states: every number is finite once rounded to binary64, a number whose exact value is a whole number is exactly representable in binary64 or is the exact value of the canonical rendering of the nearest double, no object repeats a member name, and no string holds a lone surrogate.
 Package ijson checks that a JSON document is I-JSON (RFC 7493) by the test the session format states: every number is finite once rounded to binary64, a number whose exact value is a whole number is exactly representable in binary64 or is the exact value of the canonical rendering of the nearest double, no object repeats a member name, and no string holds a lone surrogate.
jcs
Package jcs implements the JSON Canonicalization Scheme (RFC 8785): members sorted by UTF-16 code units, no insignificant whitespace, strings with the minimal escapes the scheme prescribes and numbers in the ECMAScript Number.prototype.toString form.
 Package jcs implements the JSON Canonicalization Scheme (RFC 8785): members sorted by UTF-16 code units, no insignificant whitespace, strings with the minimal escapes the scheme prescribes and numbers in the ECMAScript Number.prototype.toString form.
jsonx
Package jsonx holds the encoding/json helpers the agentsession packages share: escape-free marshalling, member joining for objects with unknown members, and struct key discovery.
 Package jsonx holds the encoding/json helpers the agentsession packages share: escape-free marshalling, member joining for objects with unknown members, and struct key discovery.
procs
Package procs answers one question for the stores' session locks: does a process with this ID still exist on this host.
 Package procs answers one question for the stores' session locks: does a process with this ID still exist on this host.
wake
Package wake carries the two pieces of waiting a follower shares across stores: a per-session broadcast a writer in the same process rings, and the interval a follower polls at when nothing rings.
 Package wake carries the two pieces of waiting a follower shares across stores: a per-session broadcast a writer in the same process rings, and the interval a follower polls at when nothing rings.
Package jsonl is the default session store: one append-only JSONL file per session under a root directory, laid out as
 Package jsonl is the default session store: one append-only JSONL file per session under a root directory, laid out as
otel module
sqlite module
Package storetest is the conformance suite for agentsession.Store implementations.
 Package storetest is the conformance suite for agentsession.Store implementations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.