Documentation
¶
Overview ¶
Package statefile reads and writes the append-only files that hold an agent session. A record is one JSON header line, a body of exactly len bytes, and a newline. The body is never escaped.
Index ¶
- Variables
- func ContextUsed(chain []Record) int
- func Copy(src, dst string, n int) error
- func Encode(r Record) ([]byte, error)
- func NewID() string
- func ValidID(id string) bool
- type Conf
- type File
- type Header
- type Kind
- type Record
- type Sessions
- func (s Sessions) Copy(from, id string, n int) error
- func (s Sessions) List() ([]string, error)
- func (s Sessions) Load(id string) ([]Record, error)
- func (s Sessions) Open(id string) (*File, error)
- func (s Sessions) Path(id string) string
- func (s Sessions) Start(id string, config []byte) (*File, error)
- type Status
- type Usage
- type Worker
Constants ¶
This section is empty.
Variables ¶
var ErrTorn = errors.New("torn record")
Functions ¶
func ContextUsed ¶ added in v0.4.0
ContextUsed is the size of the last step's prompt in tokens: what the context costs now. Input excludes cache reads and writes on every provider.
func Copy ¶
Copy makes dst from records 1 through n-1 of src, byte for byte. The prefix of an append-only file never changes, so the copy is the same value under a new name.
Types ¶
type Conf ¶
type Conf struct {
Model string `json:"model"`
Tools string `json:"tools"`
Workers []Worker `json:"workers"`
ContextLimit int `json:"context_limit"`
Input []string `json:"input,omitempty"`
Params map[string]json.RawMessage `json:"params,omitempty"`
Preset string `json:"preset,omitempty"` // the catalog preset a connector began from; display only
}
Conf is the body of the config record. Record 2 is the first; a later one changes only the workers, and the newest one is the session's. Model is one provider/model string. ContextLimit is the token limit past which the harness refuses to step. Input is the media types read hands to the model as media; text is always text, and any other file is read as text. Params are fields for the model's vendor, set on every request as its envelope decides.
type File ¶
type File struct {
Path string
// contains filtered or unexported fields
}
File is a state file open for appending. One writer per file.
type Header ¶
type Header struct {
N int `json:"n"`
Kind Kind `json:"kind"`
ID string `json:"id"`
Time time.Time `json:"time"`
Len int `json:"len"`
Type string `json:"type,omitempty"`
Step string `json:"step,omitempty"` // text, thinking, call: the step that closes it
Provider string `json:"provider,omitempty"` // thinking: who signed it. step: who served it
For string `json:"for,omitempty"` // result, error: the record it answers
Exit *int `json:"exit,omitempty"` // result of run
Truncated bool `json:"truncated,omitempty"` // result
FullOutput string `json:"full_output,omitempty"` // result: path in worker scratch
Via string `json:"via,omitempty"` // message: connector name. error: who stopped the session. config: who changed it
IdempotencyKey string `json:"idempotency_key,omitempty"` // message: the poster's key; a repost with it appends nothing
Source string `json:"source,omitempty"` // system: where the text came from
Upto int `json:"upto,omitempty"` // step: last record in its context
Model string `json:"model,omitempty"` // step
Harness string `json:"harness,omitempty"` // step: version that built the request
Request string `json:"request,omitempty"` // step: sha256 of the request bytes
Sent time.Time `json:"sent,omitzero"` // step: when the request that served it went out; cache ttls count from here
Usage *Usage `json:"usage,omitempty"` // step
Stop string `json:"stop,omitempty"` // step: why the provider ended the output, in its own words
Cache json.RawMessage `json:"cache,omitempty"` // step: provider cache markers
}
Header is the JSON line before every body. Fields beyond the first six belong to particular kinds and are omitted otherwise.
type Kind ¶
type Kind string
const ( Start Kind = "start" Config Kind = "config" System Kind = "system" Message Kind = "message" Text Kind = "text" Thinking Kind = "thinking" Call Kind = "call" Step Kind = "step" Result Kind = "result" Error Kind = "error" Name Kind = "name" // the session's name, newest wins; empty removes it. Never in the context )
type Record ¶
type Record struct {
Header
Body []byte
Note string // result: text the build renders after the body, derived from the file, never written
}
func Build ¶
Build reorders a file into context order and returns it with the index the next step's upto must carry. File order is time order; the API wants each step's results directly after it. So for each step: the results it saw, then the messages it saw as one user turn, then its blocks, then the step record itself. Blocks no step closed are dropped. Start and config never enter.
func Decode ¶
Decode reads one record. io.EOF at a record boundary is returned as is. EOF anywhere inside a record is ErrTorn.
type Sessions ¶
type Sessions struct {
Dir string
}
Sessions is the directory that holds one state file per session, named by its id. The filesystem is the registry.
func (Sessions) Copy ¶
Copy creates session id from records 1 through n-1 of session from. Fork and revert are both this call.
func (Sessions) Load ¶
Load returns a session's records. A file with none is a create that died before its first write, not a session.
type Status ¶
type Status string
const ( StatusOpen Status = "open" // a message or result is unaddressed. needs a step StatusClosed Status = "closed" // the last step addressed everything and made no calls StatusInterrupted Status = "interrupted" // a closed call has no result and nobody holds the lock StatusFailed Status = "failed" // the last record is an error StatusStepping Status = "stepping" // the harness holds the session. Never derived from the file )
type Usage ¶
type Usage struct {
Input int `json:"input"`
Output int `json:"output"`
CacheRead int `json:"cache_read,omitempty"`
CacheWrite int `json:"cache_write,omitempty"`
}
Usage counts tokens. Input excludes cache reads and writes on every provider, so Input + CacheRead + CacheWrite is the prompt.
Source Files