Repository navigation
Tool or plugin to accept AI session recordings (append-only JSONL, schema-free) #1853
Description
Relocated from dezren39/darwin-nix#292 on 2026-10-28 (placement audit): The session-recording tooling idea (a tool/plugin to accept AI session recordings, append-only JSONL) is agent/fleet infrastructure, not nix configuration. Original body below; issue references inside it are historical (dezren39/nix numbering).
Today an agent session produced roughly a dozen observations worth keeping and every one would have died with the session. They are now hand-appended to ~/git/ai_recordings.jsonl, and instructions/recordings.md asks agents to keep doing that (wired into opencode.jsonc). This issue is for the tooling that should eventually replace the hand-append.
What gets recorded
The moments an agent already stops to explain to the user. That framing is the whole trick — it needs no new judgement call, just a second destination for something already being written:
- a significant discovery
- a mistake the agent made, including miscounted or stale numbers
- a subagent that ignored its brief, or followed it too rigidly
- a review finding that was wrong, or right for the wrong reason
- a fix that made things worse
- a tool that lied — reported success while the thing it checked was broken
- anything producing surprise, guilt, irritation or relief
Real examples from the first session:
- "Adding a 120s ceiling without an outstanding-worker guard made pool exhaustion faster than the bug it fixed — before the ceiling, a user hammering retry was throttled by the hang itself."
- "The test was shaped like the assumption under test." (An httpx float
timeout=30is four independent inactivity limits, not a total deadline; the stub modelled it as one budget, so the test certified the same misunderstanding as the code.) - "I told the agent
__proto__was the same family ashasOwnProperty. It measured, and it is the only name with that divergence — a transport hazard, not a runtime one. My framing would have sent the fix to the wrong layer." - "The verifier had five independent soundness bugs, and the entire cutover proof rested on it."
Schema — deliberately almost none
sentiment is any. A dict of arrays ({"positive": [...], "negative": [...]}), a bare "good", a tag list, {"fixed": true} — whatever expresses it. Do not make agents flatten a feeling to fit a shape; the flattening is where the signal goes.
A starting shape, all fields optional, unknown keys allowed:
{"ts":"2026-09-30T22:41:00Z","pwd":"/where/it/happened","repo":"operations-portal","origin":"git@github.com:org/repo.git","kind":"short-slug","sentiment":{"positive":["measured instead of trusting the brief"],"negative":["my framing sent it to the wrong layer"]},"note":"What happened, with evidence.","lesson":"What to do differently."}Three submission styles should all be accepted, because all three beat silence:
- Copy the segment sent to the user, plus a sentiment tail. Lowest effort, still useful.
- Loosely structured, would fail a parser.
category=bad judgement | finding: ... | result: ... {grade: F, ...}. Normalise later. - Fully populated schema with the real request/response objects embedded. Ideal.
Only hard rule: append, never edit or rewrite. Reading is allowed but not required.
What the tool should do
- Accept a line over some cheap interface — a CLI (
record '<json>'), an opencode plugin hook, or an MCP tool. Cheapest possible call site; an agent mid-task will not stop for ceremony. - Never reject. A malformed line costs one normalisation pass later; a rejected line costs the observation permanently, and the observation is the scarce part. Quarantine unparseable input to a sibling file rather than erroring.
- Stamp what the agent would otherwise have to gather: timestamp,
pwd, repo common dir, origin URL, session id, model, maybe git HEAD. - Rotate by size, like the JSONL journals elsewhere in this config.
- Be a no-op when the target is unwritable — recording must never fail a task.
Later, a dedicated agent extracts these into a database. That is why detail now is cheap and absence is permanent.
Open questions
- Should the plugin capture automatically (on subagent completion, on a failed gate) or stay agent-initiated? Automatic capture gets volume; agent-initiated gets judgement. Probably both, tagged by origin.
- Per-repo files or one global? Currently global at
~/git/ai_recordings.jsonlwithrepo/originfields, which keeps cross-repo patterns visible. - Is there a privacy boundary? Recordings quote real failure text and file paths, and a leak like
DETAIL: Key (secret)=(...)was found in a log path today. Probably worth reusing whatever redaction the host repo already has. - A
schema.mdwith all-optional fields, common value types, and notes on when each is used — useful without becoming a gate.
Related: instructions/recordings.md, opencode.jsonc (instructions array).
Acceptance criteria
- A tool (CLI or plugin) appends a recording entry to the recordings file in the documented JSONL shape, replacing the hand-append workflow described in the issue.
- All schema fields are optional and unknown keys are preserved;
sentimentaccepts any shape (string, list, or dict of arrays) without flattening or validation loss. - Appends are append-only and safe under concurrent agent sessions (no truncation or interleaved partial lines).
instructions/recordings.md/opencode.jsoncwiring points agents at the tool instead of the manual file edit.- A round-trip test shows an entry written by the tool reads back byte-identical in the fields the agent supplied.
Activity
developing-today commentedon Oct 28, 2026
CODE-781
dezren39 commentedon Oct 28, 2026
History carried over from dezren39/darwin-nix#292 (verbatim, oldest first):
@dezren39 · 2026-10-27T14:50:42Z
Intake review
Fleet-monitor intake pass (2026-10-27). No related open issue covers this tooling (the recordings practice itself lives in
instructions/recordings.mdand~/git/ai_recordings.jsonl, per the issue). I appended acceptance criteria and normalized labels (kind/enhancement, priority/low, effort/m).Notes / risks: the deliberately-almost-none schema is the feature — any implementation that grows validation will destroy the signal the issue is designed to capture. Suggested approach: a tiny append-only writer (lock + single-line append) plus the instructions wiring; keep parsing permissive on the read side.
@dezren39 · 2026-10-28T19:19:22Z
Triage verdict (task 2316): CONFIRMED — still unimplemented; the hand-append workflow this issue replaces is still the live workflow.
Verified at dezren39/nix main
efd3161:instructions/recordings.mdstill instructs agents to hand-append JSON lines to~/git/ai_recordings.jsonl, and its closing line points at this issue as the future tool: 'Future: see dezren39/nix for the tracking issue on a tool or plugin to accept these directly.'instructions/recordings.mditself. Code search forai_recordingshits only docs (instructions/recordings.md,ARCHITECTURE.md,instructions/work-strategies.md).opencode-global.jsoncwiring still loads the instruction (the 'wired into opencode.jsonc' premise holds).Routing: first-slice implementation enqueued as task 2643 (queue
repo-health-nix-pilot, deduperepo-health:v1:fix:dezren39/nix:issue:292) — arecordCLI in the repo's script+test pattern covering the acceptance criteria (never-reject + quarantine, stamping, atomic append under concurrency, size rotation, no-op when unwritable, byte-identical round-trip of supplied fields / anysentimentshape), plus pointinginstructions/recordings.mdat the tool with hand-append as fallback. The open questions (plugin/MCP interface, automatic capture, redaction boundary, per-repo files) stay open here for later slices — the packet does not decide them.dezren39 commentedon Oct 28, 2026
🤖 Agent note · picked up
dezren39 commentedon Oct 28, 2026
🤖 Agent note · done
Premise check (fresh reads, 2026-10-28):
instructions/recordings.mdin dezren39/nix (present on the laptop clone) prescribes appending JSON lines to~/git/ai_recordings.jsonl, all-optional schema,sentimentis any shape, append-never-edit — and its own footer points at the tracking issue for "a tool or plugin to accept these directly." That tracking issue is this one (relocated from Tool or plugin to accept AI session recordings (append-only JSONL, schema-free) dezren39/darwin-nix#292).ai_recordingsreference and no recordings tooling (only an unrelated world-fixtures doc mentions the word); a recursive tree search finds no recording path.ai_recordings.jsonlwas found on the sandbox (home, depth 3) or the laptop (home, depth 4) at triage time. Either it lives somewhere else now or the practice currently writes nowhere — in both cases the tool must create the target file on first append, and the fix packet says so.Route: v1 is the CLI — the cheapest interface the issue names — with the issue's open questions (plugin auto-capture, per-repo vs global, redaction, schema.md) explicitly deferred, since none of them block the CLI. Fix follow-up enqueued as queue task 2767 (dedupe
repo-health:v1:fix:developing-today/code:issue:1853, packethidden_files/packet-1853-record-cli.json):recordCLI in this repo'sbin/style — stamps ts/pwd/repo/origin/HEAD/session/model, single O_APPEND write per entry (concurrency-safe), never rejects (malformed input quarantined verbatim to a sibling file, exit 0), silent no-op when unwritable, round-trip test. As a cross-repo set under this single issue, the same change carries a companion dezren39/nix PR updatinginstructions/recordings.mdto point at the tool — no separate nix issue. This issue stays open atpriority/low; this triage task completes astriaged.14 remaining items
Merge pull request #1934 from developing-today/queue/2767-1853-record…
Merge pull request #1057 from dezren39/queue/2767-1853-recordings-tool
dezren39 commentedon Oct 29, 2026
🤖 Agent note · done
recordCLI set is merged as one set: code PR feat(recordings):recordCLI — append-only session-recording ingestion (#1853) #1934 (merge commit 38f1f00; CI all green — Nix flake evaluation, treefmt, run) and companion nix PR recordings: point agents at the record tool (developing-today/code#1853) dezren39/darwin-nix#1057 (merge commit 8489a6779; docs-only instructions/recordings.md pointing agents at the tool, MERGEABLE/CLEAN, no CI checks reported on that repo). Tool or plugin to accept AI session recordings (append-only JSONL, schema-free) #1853 closed by the code PR.recordCLI — append-only session-recording ingestion (#1853) #1934 · recordings: point agents at the record tool (developing-today/code#1853) dezren39/darwin-nix#1057