Repository navigation
oars 0.3.0
·
2091 commits
to main
since this release
Changes since 0.2.0. Four command groups are new (keys, sessions, gate, pool); login and logout keep their flags.
- The hosted-agent commands of 0.2.0 (
deploy,status, andtemplates) are not in this release; a script that calls one gets the unknown-command exit (2). oars keys create|list|revokemanages your API keys.keys create --workload <id>mints a key limited to one workload (authoritiesAGENT_OPERATEandAGENT_READonly), so a scheduled agent can change its own schedule without being able to reach another workload.oars sessionskeeps a local, deterministic memory of your own Claude Code sessions:deposit,recall(with--mcpto serve the same query to a running agent),lineage,read,books,measure,verify,exclusions, andhook, plusgold sample,gold arms, andgold score. It makes no model call and no network call, exceptgold arms, which sends redacted text through your own Claude subscription.deposit --allowalso reads Cursor, Codex, Copilot CLI, Gemini CLI, Grok Build, and VS Code Copilot Chat sessions (Stable, Insiders, and OSS builds), each opt-in by name; the VS Code source is written from VS Code's public source and synthetic fixtures and has never run against a live store, and its sessions carry no per-model input figure, soinput0 there means not known.- Every deposited transcript is also hard-linked (copied across volumes) into
<config>/oars/sessions/raw/, on by default, so it outlives Claude Code's own cleanup. These are raw transcripts on your machine, and the files themselves are not uploaded. oars sessions hook installwrites four fail-open hooks (SessionStart,PreToolUse,PostToolUseFailure,SessionEnd) into a Claude Code settings file;PreToolUsehas no matcher, so it starts node on every tool call, and for a call shape the store has seen fail it adds counts as context, with 10 percent of those held back (they are recorded and nothing is injected);hook statuslists them andhook uninstallremoves only the entries install wrote. Install is idempotent, and raisescleanupPeriodDaysin that file to at least 365 (uninstall leaves it raised).--schedule nightlyregisters a daily deposit task on Windows. A session-end deposit that finds the store locked records its session inpending/in the store and exits; the next deposit of any kind deposits the pending sessions first. The step log shows that as adepositrow with statusdeferred, whichmeasureprints asdeposit@<ev> deferred (store locked).- What a deposit captures (capture version 17): per session, the setup it ran with (permission mode, plugins, hook count, instruction bytes), the tool funnel (tools offered, loaded, removed), the trust shape (interrupts, rejections, policy denials, minutes the agent ran between human turns), the
errorCodeclass of each failed call, the packages an install or runner call resolves and the dependency names a manifest shows, and stack strata (language, repo-file bucket, framework, countedexplore). A call the user refused is a failed call witherrorCodeuser-rejectedfor Claude Code, Cursor, Codex, and Gemini. A Gemini session that ran on Windows stores its shell calls asPowerShell, and Gemini sessions under~/.cache/.geminiare read. A rotated Copilot log (events.N.jsonlbesideevents.jsonl) is read oldest first as one session. The MCP tool name aftermcp__is redacted wherever it is stored. Recall floors a step's token count to its bucket, so no local cell holds an exact number, and cells are weekly (keyed on the Monday of the UTC week), with day cells for the reads of days. A language share on the wire may nameother, the name a touched file with an extension off the pinned list gets, so a session that touched a.mdfile is not refused; the frame'slanguageslist stays closed to the pinned names. The store is at extractor version 12 (a derived prompt carries its strata), and an older store re-derives from its log with no transcript read. A Copilot session's reasoning tokens are shared over the responses of its model in proportion to their output, no line above its own output, so a healthy session passes the thinking invariant ofoars sessions verify --strict. - On a large store (a test store whose log holds superseded records), a deposit that skips unchanged files needs a 104 MB heap and
verify248 MB; a store too large for node's default heap still needsNODE_OPTIONS=--max-old-space-size=<MB>(docs/sessions-store.md). A deposit whose read of its ownstore.lockis refused at the end (an antivirus share violation on Windows) removes the lock instead of leaving it for 10 minutes, a store lock whose holder hangs is refreshed for at most an hour and, once it has aged 10 more minutes, the next deposit breaks it and prints one line naming the holder's pid, and a Codex thread that a crash tore stays readable. A deposit that loses its store lock (held past the hour cap, then broken by a waiter that a second deposit followed) checks that the lock file still carries its own token before it writesstate.json, replaces the log, or compacts, and stops withThis run lost the store lock to another deposit(exit 1) when it does not, before any further capture, raw archive, pending, derived, or hook index write. It never overwrites the second deposit's--allowand--redact-domainentries, so no domain stops being masked. oars sessions verifyaudits each session against its raw file (raw-file match, Merkle root, count bindings), reports every session on its own, and scores each against your own other weeks on its harness (selfBaseline).verifyandbooksname the project folders that hold transcripts but are not on the saved allowlist, which are never read (scopein--json); that list never failsverify --strict.oars sessions exclusionsscans your sessions against a local term file (OARS_EXCLUSION_TERMS) and writes the excluded ones to a list, printing counts only.gold samplerefuses a draw with no term file, and--exclude-termonly adds to that file's terms.oars sessionsships a pinned public vocabulary (VOCAB_VERSION1, snapshot of 2026-11-04,packages/cli/vocab/, about 6 MB raw in the package) and the functions that project the fields a pool would carry; they compute from the store and write nothing to disk. A shell call projects toprogram,subcommand, andflagsfrom that program's list, sogrep AcmeWidgetMergerisgrepalone; a program, package, tool, or skill outside the vocabulary isprivate,custom, or only a count. A client more than 30 days past its snapshot builds no pool batch (vocabulary_expired).oars gate installandoars gate uninstallwire one fail-openPreToolUsehook into Claude Code's user settings (rerunning changes nothing, andinstallsets the file's mode after writing and follows a symlink that points at nothing yet), andoars gate hookrecords each package, MCP server, and skill pick as it happens intocrossings.jsonl, in under a second.oars gate replayfinds the same crossings in session logs already on disk, andoars gate reportcounts that one file once per crossing, by who recorded it. Names are read exactly: annpx <name>whose folder holdsnode_modules/.bin/<name>islocal-bin-run, notfetch-and-run; a name is not sent to a registry whenHOME,sudo, a sourced file, or a package-manager config setting could change its configuration; a version with a character such as#,&,?,;, or%counts asunreadable-name; and a resumed transcript counts a call once.oars gate hookadds a note about a name first published within 30 days or not found, with no policy file needed.gate-policy.json(in the sessions store, written by you) sets each class (young-name,not-found) towarn,block, oroff, with a day count and a holdback share (default 10 percent, which withholds notes at random and never a block). A note states a registry fact; a block is a labeled deny that exists only fornot-found(an npm name; a Python name never readsnot-found) and only when you writeblock. Each row records itsarm, thelineShown, thelineHeld, and thepolicyit ran under, andoars gate policyprints the policy in force. A registry ask the hook has to cut is finished by a detached helper that fills the cache; a call starts at most three helpers. The hook makes the lock for a helper in the same step that starts it, and takes the lock back before the process can end when the helper cannot start (the start throws, or the child reports an error), so no lock outlives its helper and keeps a name unasked for five minutes. A hook the deadline ends stops its own ask and writes one not-read row, written before the stop so a slow stop (ataskkillon Windows) cannot cost it; the deadline writes nothing when the hook's own append has already put the record on disk and then stalled, and another hook's row in the same file never makes it skip its own. One name twice in a call is one note and one counted row, and a block label prints once (the call is still denied). A kept registry answer is read only in the folder that asked. A crossing goes nowhere unless you opt in, and no opt-in exists yet.- The pool's ledger has no expiry: migration
0009_ledger_no_delete.sqlmakes the database abort anyDELETEof adepositsrow or acontributorsrecord. A counting batch turns an account frompendingtostandingafter 90 days and stays on the ledger. The pool counts two strata of their own beside the single ones, (language, share) and (repo size, explore bucket), each held to five accounts and served only in the bundle'sstrata; provider errors inliveare not built yet. The pool's bundle serves tool-day reads from day cells (a tool's failure rate and its share of the day's steps, with the floor counted within its day) and a version-free (name,platform,shell) fit cell, stored asenv:<platform>:<shell>, served only when no cell of that motif, week, and exposure is under the floor, so a total beside its parts never shows a sub-floor part by subtraction. Recovery and fit's call-shape method are not served. The bundle'sETaghashes the list of served families. A local store holds theenv:<platform>:<shell>rows incells.jsonlbeside its other cells. oars pooltalks to a pool server you name with--serverorOARS_POOL_URL(there is no default server):oars pool loginruns the provider's device flow (RFC 8628, Google or GitHub) itself and sends the provider's token to the pool once; every request prints (request line, every header, and body) before it is sent, with the device code, the provider's token, and the credential shown only as<credential: n bytes>. The client ID and Google's client secret come fromOARS_GITHUB_CLIENT_ID,OARS_GOOGLE_CLIENT_ID, andOARS_GOOGLE_CLIENT_SECRET; an unset one stops the command before it sends anything and names the variable.oars pool depositwrites batches to an outbox and stops: nothing is sent. It sends each stack language with its share bucket (languageShares, one of0,under-10,10-50,over-50; a share outside the list is dropped and its language still goes) and each prompt'sexploreas acallsbucket (thecountedges, then doubling to over 4,096); the exact count never leaves.--send <hash>sends no request: a batch that was shown and is unchanged stops withsending_disabled(exit 5), and any other hash stops with its own refusal. It builds one batch per main session, once the session and its subagents have all been quiet for 6 hours, in skeleton format 2: a shell step holds the projected program, subcommand, and flags, usage and step costs are buckets, a name off the public lists goes asprivate, and nothing carries a session id, root path, date, or exact value. Each session passes the folder allowlist and the exclusion check before any projection runs; one that fails either is counted by reason and never built, and a session that later fails a gate has its earlier batch removed. The batch also carries your own before and after windows asdeltas(a plugin added or removed asprivate, apermissionModeoreffortchanged by field name alone, or a public package removed; 7 days each, at least 5 sessions a side, marked once indeltas-sent.log). A batch built under an older vocabulary or field list is rebuilt, and the older file removed.oars pool outboxprints each batch exactly as it would be sent, then its SHA-256, and records that it was shown;--explainadds each field's rule.--jsoncarriesbatched,excluded.folder,withdrawn, anddiscarded.oars pool fetch --harness-version <version>fetches that version's signed bundle for one harness (--harness <name>; with no flag, the harness your local store holds the most sessions of, claude-code when none leads, and it prints which it chose and how to change it; only counts are read, and none leave the machine), verifies it against the key pinned at login, and keeps it per harness (pool-replica/<server>/<harness>/<version>.json). It checks the sign-in before it reads the local store, prints every request line and header before sending (credential shown only as<credential: n bytes>), keeps the bundle'sETagand sendsIf-None-Matchso an unchanged bundle is a 304 that keeps the file, and on the weekly cap (429) keeps the bundle, says when to try again, and exits 10 (CAPPED). A bundle of another vocabulary version, or made for another harness, is refused even when its signature holds (bundle_unverified).oars loginwith the built-in issuer not answering discovery (no answer, an error status, or a body that is not discovery JSON) exits 2 with the not-launched message instead of exit 8 or 1; a failure on--issuer-urlorOARS_ISSUER_URLis still reported as that failure, with its own exit code. A request the network refuses (exit 8) now names the server and the network's reason (Cannot reach the server at https://api.manyoars.com: getaddrinfo ENOTFOUND api.manyoars.com) in place ofCannot reach the server: fetch failed; anOAUTH_TIMEOUTdoes not name the server.