npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@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.md

Where next