README
¶
agentsessions
A neutral, open contract — and working reference implementation — for durable agent sessions. Create, run, suspend, resume, fork, and replay an agent session, with a Bring-Your-Own-Harness SPI on top and a pluggable compute backend underneath.
Docs site · Quickstart · Concepts · Specification · Releases
What it is
The narrow waist for agent runtimes: producers plug in on top (an issue tracker, a chat platform, a custom app), compute plugs in underneath (pod, Kata, Cloud Hypervisor, agent-substrate), and the core knows about neither. Build an agent once; run it managed, self-hosted, or in CI, with the same identity, provenance, and suspend / resume / fork, and no rewrite when it moves.
Kubernetes has no durable-session primitive, and most agent runtimes bind you to one framework, one
compute model, or one vendor. agentsessions makes this layer an open, vendor-neutral contract
anyone can implement and target, plus a reference implementation that proves the contract holds.
Quickstart
go install github.com/agent-primitives/sessions/cmd/agentctl@v0.3.0
go install github.com/agent-primitives/sessions/cmd/agentsessionsd@v0.3.0
Signed archives for linux/darwin on amd64/arm64, with checksums and SBOMs, are on the latest release. Container images:
ghcr.io/agent-primitives/sessions/agentsessionsd:v0.3.0
ghcr.io/agent-primitives/sessions/harnessnode:v0.3.0
Then follow docs/quickstart.md: exec a turn, replay it with zero model
calls, fork it, suspend and resume it, and verify its provenance chain with a non-Go verifier. No
Kubernetes, cloud, or model key required.
The three contracts
- Sessions (
api/session.proto): the client-facing lifecycle: create / list / exec / suspend / resume / fork / replay / approve. Producers attach context throughOriginandannotations, with no producer-specific fields in the core; identity is OIDC-neutral (issuer/subject/principal). - Harness (
api/harness.proto): Bring-Your-Own-Harness. The host drives one execution; the harness streams typed events over theHarness.ConnectgRPC stream. Implement it directly, or adapt an agent framework with a thin shim. - Runtime (
api/runtime.go): compute / sandbox: create / snapshot / restore / stop on any backend that implements the SPI; no kernel-isolation technology is assumed. Sessions resume by replay by default, so they run even on a plain pod;CanPlaceplaces a harness that needs memory snapshots only on a runtime that has them.
See docs/architecture.md for how they fit together.
What's proven
The load-bearing claims are demonstrated end to end, and a replay-conformance suite
(conformance/) exercises the determinism guarantees:
- Survives pod death, resumes by replay. A different incarnation reconstructs the session byte-identically from the durable journal, invoking the model zero times (quickstart).
- Tamper-evident, language-neutral provenance. Every event is hash-chained over an RFC 8785 canonical form, and a non-Go verifier reproduces the Go hash (quickstart).
- Bring-your-own-harness, out of process. The host mediates the model over
Harness.Connect, so the determinism guarantees hold across the process boundary (harness authoring). - Both capability tiers on real agent-substrate, in CI. Byte-identical replay, and memory
snapshot suspend / restore with in-RAM state continuing, against a real
ate-systemon a micro-VM (substrate conformance).
Documentation
The docs are published, rendered and searchable, at sessions.agent-primitives.dev, along with a walkthrough of how a turn runs and a recording of the full lifecycle on a real cluster. Start with:
- Concepts: sessions, typed events, the log, fences, resumability.
- Quickstart: exec, replay, fork, suspend, resume, and verify, locally.
- Writing a harness: plug your agent into the
api.HarnessSPI. - Architecture: how the neutral core is built, and the repository layout.
- API reference and the draft specification.
Every doc, indexed by goal: docs/README.md.
Status
Working reference implementation (Go 1.26). The Sessions API, the single-writer event-sourced
controller, the durable hash-chained log, BYOH over Harness.Connect, the Runtime SPI with local
and substrate backends, the replay-conformance suite, and real-substrate conformance across both
capability tiers all run today. See the
verification boundary for what the live tests
cover, and how it behaves for approvals, recovery, and known limits.
The reference daemon has no authentication, authorization, or transport security. Custom Go hosts
can opt into caller authentication and
RPC authorization, not complete required-mode
isolation.
A managed control plane, enterprise identity and provenance, and confidential or GPU snapshots are
not built. Read docs/security.md before exposing a host.
API stability
agentsessions.v1 is a proto namespace, not a stability promise. The Go module is pre-1.0 and makes
no backward-compatibility guarantee; pin a commit if you need stability today. Breaking changes
are called out in CHANGELOG.md, and CI gates the schema against the most recent
release tag, so the contract cannot break silently
(stability).
Ecosystem
agentsessions composes with existing OSS at its seams: MCP, A2A, CloudEvents, Durable Task / Dapr,
and OpenTelemetry GenAI. See what it composes with.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package api defines the agentsessions contracts: the Sessions control-plane API, the Harness BYOH SPI, and the Runtime compute SPI.
|
Package api defines the agentsessions contracts: the Sessions control-plane API, the Harness BYOH SPI, and the Runtime compute SPI. |
|
Package authn provides opt-in gRPC caller authentication, not authorization.
|
Package authn provides opt-in gRPC caller authentication, not authorization. |
|
Package canon defines the language-neutral canonical serialization for the event log's tamper-evident hash-chain.
|
Package canon defines the language-neutral canonical serialization for the event log's tamper-evident hash-chain. |
|
Package client is the Go client for the Sessions API.
|
Package client is the Go client for the Sessions API. |
|
cmd
|
|
|
agentctl
command
Command agentctl is the client-facing CLI for agentsessions — the top seam a user or GitHub drives.
|
Command agentctl is the client-facing CLI for agentsessions — the top seam a user or GitHub drives. |
|
agentnode
command
Command agentnode is the co-located agentsessions node used for the pod resume demo: one binary running the controller + the echo harness + the durable sqlite journal.
|
Command agentnode is the co-located agentsessions node used for the pod resume demo: one binary running the controller + the echo harness + the durable sqlite journal. |
|
agentsessionsd
command
Command agentsessionsd serves the Sessions API over TCP.
|
Command agentsessionsd serves the Sessions API over TCP. |
|
harnessnode
command
Command harnessnode is the harness packaged to run INSIDE a compute sandbox (a substrate actor, or any runtime).
|
Command harnessnode is the harness packaged to run INSIDE a compute sandbox (a substrate actor, or any runtime). |
|
Package conformance is the replay-conformance suite: the CSI/CRI-style neutral checks that any host/backend/harness combination must pass, run here against the REAL stack (the persistent sqlitelog backend + the controller + the echo harness).
|
Package conformance is the replay-conformance suite: the CSI/CRI-style neutral checks that any host/backend/harness combination must pass, run here against the REAL stack (the persistent sqlitelog backend + the controller + the echo harness). |
|
Package controller is the single-writer, event-sourced core of agentsessions.
|
Package controller is the single-writer, event-sourced core of agentsessions. |
|
Package eventlog is the reference in-memory event log for the agentsessions walking skeleton.
|
Package eventlog is the reference in-memory event log for the agentsessions walking skeleton. |
|
hack
|
|
|
doccheck
command
Command doccheck type-checks the Go code blocks in the repository's Markdown against the current module, so a doc example cannot drift from the API it shows.
|
Command doccheck type-checks the Go code blocks in the repository's Markdown against the current module, so a doc example cannot drift from the API it shows. |
|
harness
|
|
|
chatagent
Package chatagent provides a text-only conversational reference harness.
|
Package chatagent provides a text-only conversational reference harness. |
|
counteragent
Package counteragent is a REQUIRES_MEMORY_SNAPSHOT api.Harness: it holds an in-RAM counter whose state is, by design, NOT reconstructable from the event log.
|
Package counteragent is a REQUIRES_MEMORY_SNAPSHOT api.Harness: it holds an in-RAM counter whose state is, by design, NOT reconstructable from the event log. |
|
echoagent
Package echoagent is a trivial STATELESS_REPLAY api.Harness: it feeds the last input to the model through the host-mediated sink and lets the recorded completion be the output.
|
Package echoagent is a trivial STATELESS_REPLAY api.Harness: it feeds the last input to the model through the host-mediated sink and lets the recorded completion be the output. |
|
toolagent
Package toolagent provides a reference harness that lets the model call tools, each one gated on a human decision.
|
Package toolagent provides a reference harness that lets the model call tools, each one gated on a human decision. |
|
Package harnesswire bridges the in-process api.Harness SPI and the out-of-process Harness.Connect gRPC stream, in both directions:
|
Package harnesswire bridges the in-process api.Harness SPI and the out-of-process Harness.Connect gRPC stream, in both directions: |
|
integrations
|
|
|
substrate
module
|
|
|
internal
|
|
|
agentsessionsd
Package agentsessionsd is the agentsessionsd server: it serves the Sessions API over TCP.
|
Package agentsessionsd is the agentsessionsd server: it serves the Sessions API over TCP. |
|
ctxlock
Package ctxlock provides cancellation-aware serialization for invocation sinks.
|
Package ctxlock provides cancellation-aware serialization for invocation sinks. |
|
fuzzcheck
Package fuzzcheck holds the checks the decoding fuzz targets share.
|
Package fuzzcheck holds the checks the decoding fuzz targets share. |
|
modelcall
Package modelcall carries host-owned dispatch metadata without changing model requests or their durable representation.
|
Package modelcall carries host-owned dispatch metadata without changing model requests or their durable representation. |
|
modelconfig
Package modelconfig constructs the OpenAI-compatible client shared by repository-owned hosts.
|
Package modelconfig constructs the OpenAI-compatible client shared by repository-owned hosts. |
|
version
Package version reports the build's identity.
|
Package version reports the build's identity. |
|
model
|
|
|
openai
Package openai provides OpenAI-compatible Chat Completions and Responses protocol clients.
|
Package openai provides OpenAI-compatible Chat Completions and Responses protocol clients. |
|
Package observability provides structured operation logging and gRPC request correlation.
|
Package observability provides structured operation logging and gRPC request correlation. |
|
Package placement wires the Sessions layer to the Runtime compute SPI.
|
Package placement wires the Sessions layer to the Runtime compute SPI. |
|
runtime
|
|
|
local
Package local implements the agentsessions api.Runtime compute SPI as a filesystem-only backend — the honest "plain pod" counterpart to runtime/substrate.
|
Package local implements the agentsessions api.Runtime compute SPI as a filesystem-only backend — the honest "plain pod" counterpart to runtime/substrate. |
|
remote
Package remote is a Runtime backend for a harness somebody else is already running.
|
Package remote is a Runtime backend for a harness somebody else is already running. |
|
substrate
Package substrate implements the agentsessions api.Runtime compute SPI on top of agent-substrate (the "actors on pre-warmed workers" runtime that memory-snapshots RAM+disk).
|
Package substrate implements the agentsessions api.Runtime compute SPI on top of agent-substrate (the "actors on pre-warmed workers" runtime that memory-snapshots RAM+disk). |
|
Package session implements the client-facing Sessions gRPC service, backed by the durable sqlitelog journal and the event-sourced controller.
|
Package session implements the client-facing Sessions gRPC service, backed by the durable sqlitelog journal and the event-sourced controller. |
|
Package sqlitelog is the persistent, single-writer event log backing agentsessions on durable storage.
|
Package sqlitelog is the persistent, single-writer event log backing agentsessions on durable storage. |
|
Package wire converts between the hand-written api domain types (the SPI programmed against internally) and the generated protobuf wire types in api/genpb.
|
Package wire converts between the hand-written api domain types (the SPI programmed against internally) and the generated protobuf wire types in api/genpb. |