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 ¶
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 )
Event kinds.
const Dir = "usage"
Dir is the vault subdirectory holding the ledger.
Variables ¶
This section is empty.
Functions ¶
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, b contextpack.Budget) 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.
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 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.
Rulings int `json:"rulings,omitempty"`
}
Event is one line of the ledger.
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
Since int64
}
Totals is the ledger summed.
Source Files