@agent-realm/harness-session-adapters
v1.1.0
Published
Session adapters: one reader per agent harness, speaking sessions v1.3 (describe, list, read, derive) over sessions-model v1.3 records
Readme
@agent-realm/harness-session-adapters
Status: 1.0.0. Twelve harnesses: Claude Code, Codex, Copilot CLI, Gemini CLI, VS Code, Goose, OpenCode, Antigravity (agy), Cursor IDE, cursor-agent, Zed and Devin Local.
What it is
The session adapters are one reader per agent harness: Claude Code, Codex, Copilot CLI, Cursor, Zed and the rest. Each reads that harness's own conversation store and gives back the same records: sessions, messages and their parts, usage, links and lifecycle events. Two contracts define them:
- sessions-model v1.4, for what the records are and how they are keyed;
- sessions v1.4, for the four operations every adapter speaks.
| Operation | Takes | Gives |
|---|---|---|
| describe() | nothing | the adapter's sources, versions, redaction paths and facets |
| list(store) | {host, harness, harness_path} | every session with its sources and an updated_hint |
| read(store, session, source_key, from, known) | a position, or none | the new raw units, continuity, a new position |
| derive(session, input, state) | units and the last state | the records that changed, the complete live keys, a new state |
read never writes into a harness store. derive is pure.
For a file source whose raw bytes a consumer archived, unitsFromBytes(harness, source_key, bytes,
{start}) returns the units read would have returned from those bytes, with no file system:
import { unitsFromBytes } from '@agent-realm/harness-session-adapters';
const { units, held_back } = unitsFromBytes('claude-code', sourceKey, archivedBytes);A database source has no file bytes, so it is a bad_request. The package loads from CommonJS
too, with require('@agent-realm/harness-session-adapters').
Why
Every harness keeps its conversations differently, and changes the format often. memhouse
captures them, hs (harness-skeleton) exposes them, and harness-sessions-sql loaders store them. Each of
them needs the same readers. This package is the single copy: one place to fix a reader, with one
conformance suite proving it against fixtures.
How
Node.js 22.15 or later (node:sqlite, and zstd in node:zlib for Zed). The package has no dependencies.
Install it from npm with npm install @agent-realm/harness-session-adapters. The examples, the fixtures
and the conformance suite stay in the repository: use a checkout of
harness-skeleton for them
(AGENTS.md, Install and deploy).
import { adapterFor, host, harnessPath } from '@agent-realm/harness-session-adapters';
const adapter = adapterFor('claude-code');
const store = { host: host().host, harness: 'claude-code', harness_path: harnessPath('/home/user/.claude') };
for (const s of adapter.list(store)) {
const session = { ...store, session_id: s.session_id, incarnation: s.incarnation };
const input = s.sources.map((src) => {
const r = adapter.read(store, session, src.source_key, null, null);
return { source_key: src.source_key, generation: 1, complete: true, units: r.units, gone: [] };
});
const { changed } = adapter.derive(session, input, null);
// `changed` holds every record of the session on a first derive.
}A consumer keeps each source's position and generation, and the derive state, between passes.
conformance/engine.js is a minimal consumer that shows how.
validateSession checks one session's records against the contract's record shapes
(sessions-model §2) and returns its findings, none when the records are valid. The conformance
suite runs it over every golden; a writer can run it before it writes:
import { validateSession } from '@agent-realm/harness-session-adapters/validate';
const findings = validateSession(records, { harness: 'claude-code', sessionId });
// [{at, problem}]: valid when every finding is a warning (`warning: true`, an unknown
// registry value such as a new harness or ts_source, which a v1 reader accepts)docs/conformance-matrix.md says, for each of the 32 adapter-side
conformance items of sessions-model and sessions and each of the twelve harnesses, what proves it:
a generic check run over every fixture case, a named test, or the reason the item does not apply.
It is generated from conformance/matrix.js, and npm test fails when it is stale.
npm test # unit tests and the conformance suite, against the fixtures
node conformance/golden.js claude-code # rewrite one harness's goldens, for review
node conformance/matrix.js --write # regenerate docs/conformance-matrix.mdWhere next
docs/: the guides (read a store, add a harness, run the conformance matrix), the adapter interface and the live check.examples/: fromdescribeto a full pass over every harness, each runnable against the fixtures.docs/conformance-matrix.md: what proves each conformance item, per harness.CHANGELOG.md: what changed, with a migration note for every key change.AGENTS.md: rules for anyone changing this package, and how to install and deploy it.
