Documentation
¶
Overview ¶
Package usage is the ledger `logos usage` reads: what each context pack cost against what it drew from, and each time a recorded dead end was handed back to an agent about to retry it.
Every number here is a receipt, never an estimate of something Logos cannot see. It cannot see a host's API usage, so "tokens saved" is a pack's size against its own uncut candidates, both measured by contextpack on the same estimate. It cannot tell whether an agent heeded a dead end, so the count is of dead ends returned, not of mistakes avoided.
JSONL in the vault, one file per month, for the reasons internal/activity gives: a person can read it with grep, and it survives the index being deleted. Totals kept only in SQLite would be the fifth time a durable record silently lived in the cache. Unlike the activity log it holds no prompt and no tool output — a timestamp, a project name and counts — so it is kept, not aged out: a running total that forgets its first month is not a total.
Index ¶
- Constants
- func Handoff(e Event) bool
- func ProcedureRefs(hits []procedure.Hit) []string
- func Record(vault string, e Event) error
- func RecordPack(vault, via, project string, pack contextpack.Pack, session string) error
- func Recording(vault string) bool
- func Ref(text string) string
- func RulingRefs(hits []deadend.Ruling) []string
- func SameProject(a, b string) bool
- func SetRecording(vault string, on bool) error
- func Tallies(events []Event) map[string]Tally
- type Event
- type Tally
- type Totals
Constants ¶
const ( KindPack = "pack" // a context pack was handed to an agent KindDeadEnd = "dead-end" // a recorded dead end was handed back before a retry KindAtEdit = "at-edit" // a ruling naming a file was shown as that file was edited KindAvoided = "avoided" // a session ended without touching what a ruling it was shown names // A procedure's evidence is earned here, not in its text: the text is // what its uid is derived from, so rewriting "evidence: once" would make // it a different memory, and the ledger is already the vault's record of // what was shown to whom. KindProcedure = "procedure" // procedures known to work were handed back before a try KindProven = "proven" // a procedure's verify passed in the session after it was shown )
Event kinds.
const Dir = "usage"
Dir is the vault subdirectory holding the ledger.
const Week = 7 * 24 * time.Hour
Week is how far back `logos usage --week` reads.
Variables ¶
This section is empty.
Functions ¶
func Handoff ¶ added in v0.5.3
Handoff reports whether e is a resume that handed one agent's checkpoint to another. Both names must be known: "cli" is what a shell gets when nothing said who is asking, and counting it as different from every agent would make each person's own resume a handoff — on either side, since a checkpoint written from a shell is signed "cli" too.
func ProcedureRefs ¶ added in v0.5.5
ProcedureRefs are the refs of procedures a check handed back.
func Record ¶
Record appends one event.
Errors are returned, and a caller reports rather than swallows them: a ledger that silently stopped being written would show a total that looks complete and is not. They must not fail the pack or the check being recorded, which already did its job.
func RecordPack ¶
func RecordPack(vault, via, project string, pack contextpack.Pack, session string) error
RecordPack records a rendered pack. Its headings and footer are counted on both sides, so the saving is exactly what the budget left out. session is the host's session id when the caller has one, "" otherwise.
The refs are the handed-over checkpoint's own ruled-out approaches, the ones a pack always shows under "Already tried". Earlier checkpoints' rulings are left out: the budget may cut them, and a receipt claiming a ruling was shown when it was cut would overstate what Logos did.
func Recording ¶
Recording reports whether this vault's ledger takes new events. On unless someone said otherwise — it holds counts, never prompts or content — but everything Logos writes on its own has a switch, with `logos usage off` for the vault and LOGOS_USAGE=off for one process.
func Ref ¶ added in v0.5.3
Ref is the ledger's name for a ruling: a fingerprint of its whole recorded text (Record.Raw, not the route alone, which two rulings can share), spacing and case aside, so the same ruling read from two places has one name.
func RulingRefs ¶ added in v0.5.3
RulingRefs are the refs of rulings a dead-end check handed back.
func SameProject ¶ added in v0.5.3
projectKey is the one name an event is filed and summed under. The callers spell a project three ways — the bare name a pack is built for, the worktree scope a dead-end check runs in, the path someone typed after --project — and recording each as given split one project's total across three keys, with `logos usage kestrel` counting only one of them. A path is its project's name, and a worktree's work is its project's: the total is per project. Applied on read as well, so a ledger written before this still sums right. SameProject reports whether two spellings of a project are filed under one name — a worktree scope and its project, a path and its name.
func SetRecording ¶
SetRecording turns the ledger on or off for this vault. What is already recorded is left alone either way; the files are the user's to delete.
Types ¶
type Event ¶
type Event struct {
TS int64 `json:"ts"`
Kind string `json:"kind"`
Project string `json:"project,omitempty"`
// Via is where it happened, "mcp:resume" or "cli:tried", so a total can be
// traced back to the path that produced it.
Via string `json:"via"`
// Sent and Full are a pack's tokens as sent and as its candidates came to
// uncut, the same headings and footer counted in both.
Sent int `json:"sent,omitempty"`
Full int `json:"full,omitempty"`
// Rulings is how many recorded dead ends a dead-end event returned, or an
// avoided event counts.
Rulings int `json:"rulings,omitempty"`
// Reader is who a pack was built for and From who wrote the checkpoint it
// handed over — the two names a handoff is counted from. Agent names, as
// the checkpoint already records them.
Reader string `json:"reader,omitempty"`
From string `json:"from,omitempty"`
// Session is the host's session the event happened in, when the caller
// knows it, so the session-end receipt can find what was shown to it.
Session string `json:"session,omitempty"`
// Refs name the rulings handed back, as Ref of their text: an opaque
// fingerprint, not the text, so the ledger still holds no content. The
// receipt resolves them against the vault at session end.
Refs []string `json:"refs,omitempty"`
}
Event is one line of the ledger.
type Tally ¶ added in v0.5.5
Tally is what the ledger says about one procedure: how many times it was handed back, and in how many sessions its verify then passed.
type Totals ¶
type Totals struct {
Packs int
Sent int
Full int
// DeadEndChecks is the number of checks that returned at least one recorded
// dead end, and Rulings the dead ends they returned between them.
DeadEndChecks int
Rulings int
// AtEdit is how many rulings an edit hook put in front of an agent as it
// opened a file they name — kept apart from Rulings, which an agent asked for.
AtEdit int
// Restores is how many packs were a resume, and Handoffs how many of those
// handed over a checkpoint another agent wrote — see Handoff.
Restores int
Handoffs int
// Avoided is how many rulings sessions were shown and then never touched
// what they name: "may have avoided", never "avoided".
Avoided int
// Procedures is how many procedures before_you_try handed back, and Proven
// how many a session then ran the verify of, and saw pass, after it.
Procedures int
Proven int
Since int64
}
Totals is the ledger summed.
Source Files