Skip to content

oars 0.3.0

Choose a tag to compare

@github-actions github-actions released this 10 Nov 14:22
· 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, and templates) are not in this release; a script that calls one gets the unknown-command exit (2).
  • oars keys create|list|revoke manages your API keys. keys create --workload <id> mints a key limited to one workload (authorities AGENT_OPERATE and AGENT_READ only), so a scheduled agent can change its own schedule without being able to reach another workload.
  • oars sessions keeps a local, deterministic memory of your own Claude Code sessions: deposit, recall (with --mcp to serve the same query to a running agent), lineage, read, books, measure, verify, exclusions, and hook, plus gold sample, gold arms, and gold score. It makes no model call and no network call, except gold arms, which sends redacted text through your own Claude subscription. deposit --allow also 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, so input 0 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 install writes four fail-open hooks (SessionStart, PreToolUse, PostToolUseFailure, SessionEnd) into a Claude Code settings file; PreToolUse has 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 status lists them and hook uninstall removes only the entries install wrote. Install is idempotent, and raises cleanupPeriodDays in that file to at least 365 (uninstall leaves it raised). --schedule nightly registers a daily deposit task on Windows. A session-end deposit that finds the store locked records its session in pending/ in the store and exits; the next deposit of any kind deposits the pending sessions first. The step log shows that as a deposit row with status deferred, which measure prints as deposit@<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 errorCode class 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, counted explore). A call the user refused is a failed call with errorCode user-rejected for Claude Code, Cursor, Codex, and Gemini. A Gemini session that ran on Windows stores its shell calls as PowerShell, and Gemini sessions under ~/.cache/.gemini are read. A rotated Copilot log (events.N.jsonl beside events.jsonl) is read oldest first as one session. The MCP tool name after mcp__ 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 name other, the name a touched file with an extension off the pinned list gets, so a session that touched a .md file is not refused; the frame's languages list 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 of oars 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 verify 248 MB; a store too large for node's default heap still needs NODE_OPTIONS=--max-old-space-size=<MB> (docs/sessions-store.md). A deposit whose read of its own store.lock is 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 writes state.json, replaces the log, or compacts, and stops with This 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 --allow and --redact-domain entries, so no domain stops being masked.
  • oars sessions verify audits 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). verify and books name the project folders that hold transcripts but are not on the saved allowlist, which are never read (scope in --json); that list never fails verify --strict.
  • oars sessions exclusions scans your sessions against a local term file (OARS_EXCLUSION_TERMS) and writes the excluded ones to a list, printing counts only. gold sample refuses a draw with no term file, and --exclude-term only adds to that file's terms.
  • oars sessions ships a pinned public vocabulary (VOCAB_VERSION 1, 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 to program, subcommand, and flags from that program's list, so grep AcmeWidgetMerger is grep alone; a program, package, tool, or skill outside the vocabulary is private, custom, or only a count. A client more than 30 days past its snapshot builds no pool batch (vocabulary_expired).
  • oars gate install and oars gate uninstall wire one fail-open PreToolUse hook into Claude Code's user settings (rerunning changes nothing, and install sets the file's mode after writing and follows a symlink that points at nothing yet), and oars gate hook records each package, MCP server, and skill pick as it happens into crossings.jsonl, in under a second. oars gate replay finds the same crossings in session logs already on disk, and oars gate report counts that one file once per crossing, by who recorded it. Names are read exactly: an npx <name> whose folder holds node_modules/.bin/<name> is local-bin-run, not fetch-and-run; a name is not sent to a registry when HOME, sudo, a sourced file, or a package-manager config setting could change its configuration; a version with a character such as #, &, ?, ;, or % counts as unreadable-name; and a resumed transcript counts a call once.
  • oars gate hook adds 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) to warn, block, or off, 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 for not-found (an npm name; a Python name never reads not-found) and only when you write block. Each row records its arm, the lineShown, the lineHeld, and the policy it ran under, and oars gate policy prints 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 (a taskkill on 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.sql makes the database abort any DELETE of a deposits row or a contributors record. A counting batch turns an account from pending to standing after 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's strata; provider errors in live are 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 as env:<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's ETag hashes the list of served families. A local store holds the env:<platform>:<shell> rows in cells.jsonl beside its other cells.
  • oars pool talks to a pool server you name with --server or OARS_POOL_URL (there is no default server): oars pool login runs 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 from OARS_GITHUB_CLIENT_ID, OARS_GOOGLE_CLIENT_ID, and OARS_GOOGLE_CLIENT_SECRET; an unset one stops the command before it sends anything and names the variable.
  • oars pool deposit writes batches to an outbox and stops: nothing is sent. It sends each stack language with its share bucket (languageShares, one of 0, under-10, 10-50, over-50; a share outside the list is dropped and its language still goes) and each prompt's explore as a calls bucket (the count edges, 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 with sending_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 as private, 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 as deltas (a plugin added or removed as private, a permissionMode or effort changed by field name alone, or a public package removed; 7 days each, at least 5 sessions a side, marked once in deltas-sent.log). A batch built under an older vocabulary or field list is rebuilt, and the older file removed. oars pool outbox prints each batch exactly as it would be sent, then its SHA-256, and records that it was shown; --explain adds each field's rule. --json carries batched, excluded.folder, withdrawn, and discarded.
  • 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's ETag and sends If-None-Match so 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 login with 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-url or OARS_ISSUER_URL is 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 of Cannot reach the server: fetch failed; an OAUTH_TIMEOUT does not name the server.