agentsession

Overview ¶

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.

agentsession show <file> | <cas-root> <id> [-leaf id] [-v] [-f]
agentsession verify <file> | <cas-root> [id]
agentsession export <file> | <cas-root> <id> -out dir [-redact-home] [-redact-env] [-secret VALUE]...
agentsession list <root> [-cwd path] [-parent id] [-limit n]
agentsession refs <root> [prefix]
agentsession ref <root> <name> [-log]
agentsession repair <cas-root> <id> [-dry-run]
agentsession repair <cas-root> -ref <name> [-dry-run]
agentsession migrate <cas-root>

show -f prints the session and then each entry as the store accepts it, until interrupted: a session a harness is writing, watched from beside it, in a cas store or in a jsonl store's layout, with nothing held and nothing written.

Every command but repair and migrate opens what it reads read-only. show, verify and export read a file directly and never take its lock; given a cas store and a session id, they open the store read-only and read the session as the file its projection is. A path inside a cas store's sessions/<id> directory, its one-line header file included, is read as that session through the store. verify of a session a cas store holds also checks each subsession link against the header of the session it names, which the store can find and a file alone cannot. verify of a cas root with no id checks the whole store as git fsck does, and then each session's request hashes, records and links as verify of that session would, printing only what fails. list opens a jsonl or cas store root read-only and prints its sessions, newest first. All four are safe to run beside a harness that is writing, which is when an operator most wants them.

refs lists the refs of a cas or jsonl store, names that point to sessions, and ref prints one, with -log every update that moved it, newest first. Both open the store read-only. Where a command takes a session in a cas store, an id of the form ref:<name> names the session that ref points to.

repair rewrites a cas session whose log has a record that fails its checksum, which keeps the session from opening and the store from sweeping, from the records that still read: it keeps the entries whose objects are whole and whose parents are kept, prints what it dropped and where the head went, and keeps the damaged log in the session's directory, which verify reports until it is removed. It takes the session's lock, so it fails on a session a harness holds. With -dry-run it opens the store read-only and writes nothing. repair -ref <name> restarts a ref's damaged log from the ref's target, keeping the damaged log beside it, which verify reports until it is removed.

migrate opens a cas store for writing and closes it, which is what migrates a store v0.0.15 or earlier wrote; a read-only open, as every other command makes, reads no session of such a store. It refuses while a writer of the earlier release holds a session. On such a store, stop every writer, take a copy of the store, run migrate, then start the readers and writers of this release together: once it has run, no release before v0.0.16 reads the store.