acpcore

README

acp-go-core

The shared module and contract of the acp-go-* family: Go packages that give local coding-agent harnesses an ACP interface. This repository holds the code every sibling has in common, the family contract, the per-sibling registry, the lifecycle fixture battery, and the checks that keep the siblings aligned.

The Family

Repo	Package	Vendor key	Native surface	Store format
acp-go-claude	claudeacp	claude	Claude Code stream-json and control protocol	claude-transcript-jsonl-v2
acp-go-codex	codexacp	codex	codex app-server stdio protocol	codex-rollout-jsonl-v2
acp-go-hermes	hermesacp	hermes	hermes serve WebSocket JSON-RPC and HTTP persistence	hermes-session-json-v2
acp-go-opencode	opencodeacp	opencode	opencode serve HTTP and SSE	opencode-sync-events-v2
acp-go-opencodev2	opencodeacp	opencode	OpenCode v2 opencode serve HTTP and SSE	opencode-session-export-v2
acp-go-pi	piacp	pi	pi --mode rpc JSONL protocol	pi-session-jsonl-v2
acp-go-amp	ampacp	amp	amp threads continue stream-json with a native lifecycle plugin	amp-thread-json-v1
acp-go-nanocodex	nanocodexacp	nanocodex	Bundled Rust helper embedding the Nanocodex library over JSONL	nanocodex-rollout-jsonl-v3

The registry records each sibling's capabilities, options, and deviations.

Packages

The package list and what each owns is in docs/01.

import (
    acpcore "github.com/savid/acp-go-core"
    "github.com/savid/acp-go-core/lifecycle"
    "github.com/savid/acp-go-core/process"
)

A sibling imports what it needs and re-exports nothing. A host imports the root package for the store types it implements and lifecycle for the reducer.

Shared Versions

Every sibling moves together on the ACP SDK (github.com/coder/acp-go-sdk), the Go directive, and this module. Versions live only in go.mod files: this module's go.mod sets the family's ACP SDK version and Go directive, and every sibling matches it. The Go directive is the language version the module needs, without a patch component or a toolchain line.

Every sibling MUST require one shared version of this module, a commit on its master, without a replace directive for it; make drift-check compares the siblings. Local development may use an untracked Go workspace.

A shared-version change covers every sibling and reruns each conformance suite. Shared direct dependencies such as OpenTelemetry and testify also move together; make drift-check requires one version of every module across the family's go.mod files.

Protocol Posture

• The family implements published ACP v1. Adopting v2 is one coordinated cutover across the family and its hosts.
• Protocol claims come from the published spec and schema. The required Go SDK version is evidence for its own generated types and transport bounds only.
• The reserved family literals are defined in docs/00.
• Current upstream status and adoption triggers live in the watchlist.

Checks

make test          # race, shuffled
make audit         # fmt-check lint build coverage-check tidy vuln modernize-check, then go mod verify
make check         # links, skill metadata, fixture structure, script syntax
make drift-check   # family structural contract across sibling checkouts

make check validates this repo's local links and anchors, skill metadata and symlinks, lifecycle fixture structure and violation coverage, and script syntax. It runs without sibling checkouts and needs Bash, Make, and Python 3 with PyYAML.

make drift-check verifies the enumerable structural rules in docs/06 against the sibling checkouts beside this repo. It needs Bash, Git, Python 3, and rg. Missing checkouts are reported and skipped. A pass proves the enumerated structure, not behavior.

Core Principles

The family principles are stated once, in docs/00.

Documentation

Page	Scope
00 · Overview	Ownership, identity, reserved literals, error vocabulary
01 · Public API	This module, agent surface, options, builders
02 · Wire contract	Capabilities, methods, metadata, envelopes
03 · Sessions and store	Persistence, commit ordering, restore, identity
04 · Behavior	Config, models, images, usage, permissions, commands, delete
05 · Lifecycle	Process model, cancellation, shutdown, concurrency
06 · Repository standards	Layout, tooling, CI, docs
07 · Testing	Unit, conformance, fixtures, integration
Registry	Current per-sibling facts and deviations

The lifecycle manifest is the canonical reducer battery, embedded as lifecycle.Fixtures and run by go test ./lifecycle. Siblings validate their emitters through the reducer.

Documentation

Overview

Package acpcore holds the behavior every acp-go-* sibling shares: the session store contract and its in-memory implementation at the root, and the sessionlog, observer, storetest, lifecycle, process, wire, and image packages beneath it.

Index

• Constants
• Variables
• type InMemorySessionStore
  • func NewInMemorySessionStore() *InMemorySessionStore
  • func (s *InMemorySessionStore) Append(ctx context.Context, main SessionKey, base int, entries []SessionStoreEntry, ...) error
  • func (s *InMemorySessionStore) Delete(ctx context.Context, key SessionKey) error
  • func (s *InMemorySessionStore) ListSessions(ctx context.Context) ([]SessionSummary, error)
  • func (s *InMemorySessionStore) Load(ctx context.Context, sessionID string) (map[string][]SessionStoreEntry, error)
  • func (s *InMemorySessionStore) Replace(ctx context.Context, main SessionKey, replacements []SessionStoreReplacement) error
• type SessionKey
• type SessionStore
• type SessionStoreEntry
• type SessionStoreReplacement
• type SessionSummary

Constants

const SessionStoreMainSubpath = ""

SessionStoreMainSubpath addresses a session's main record.

const SessionStoreTimeout = 10 * time.Second

SessionStoreTimeout bounds one store call a sibling makes on a host's behalf.

Variables

var ErrSessionIDRequired = errors.New("session id is required")

ErrSessionIDRequired reports a write addressed to an empty session id.

Types

type InMemorySessionStore

type InMemorySessionStore struct {
	// contains filtered or unexported fields
}

InMemorySessionStore is the default store when a host provides none, and the reference implementation the store contract battery is written against. It holds its own copy of every entry, and Load returns another copy.

func NewInMemorySessionStore

func NewInMemorySessionStore() *InMemorySessionStore

NewInMemorySessionStore creates an empty process-local store.

func (*InMemorySessionStore) Append

func (s *InMemorySessionStore) Append(ctx context.Context, main SessionKey, base int, entries []SessionStoreEntry, replacements []SessionStoreReplacement) error

Append extends the main record of the session's committed generation and replaces the listed subpaths.

func (*InMemorySessionStore) Delete

func (s *InMemorySessionStore) Delete(ctx context.Context, key SessionKey) error

Delete removes one subrecord, or the whole session when the main key is named; a deleted session stays deleted. Deleting a key with an empty SessionID is a no-op.

func (*InMemorySessionStore) ListSessions

func (s *InMemorySessionStore) ListSessions(ctx context.Context) ([]SessionSummary, error)

ListSessions lists committed sessions, newest first.

func (*InMemorySessionStore) Load

func (s *InMemorySessionStore) Load(ctx context.Context, sessionID string) (map[string][]SessionStoreEntry, error)

Load returns one complete session generation keyed by subpath. A live empty main record is present under the empty key; a missing session returns nil.

func (*InMemorySessionStore) Replace

func (s *InMemorySessionStore) Replace(ctx context.Context, main SessionKey, replacements []SessionStoreReplacement) error

Replace atomically publishes one session's complete generation.

type SessionKey

type SessionKey struct {
	// SessionID is the ACP-visible session ID being stored.
	SessionID string
	// Subpath is empty for the main record or names a session-owned subrecord.
	Subpath string
}

SessionKey addresses one session-store record.

type SessionStore

type SessionStore interface {
	Load(ctx context.Context, sessionID string) (map[string][]SessionStoreEntry, error)
	Replace(ctx context.Context, main SessionKey, replacements []SessionStoreReplacement) error
	Append(ctx context.Context, main SessionKey, base int, entries []SessionStoreEntry, replacements []SessionStoreReplacement) error
	Delete(ctx context.Context, key SessionKey) error
	ListSessions(ctx context.Context) ([]SessionSummary, error)
}

SessionStore is the durability boundary a host provides. Replace publishes one complete generation and is durable before it returns; it copies the entries it receives, so the caller keeps them. Append extends the committed generation: it atomically appends entries to the main record and replaces each listed subpath, keeping every unlisted subpath. base is the number of main entries the caller expects the generation to hold, compared by count only; when it holds another number, or the session has no committed generation, Append fails without writing. Append to a deleted session writes nothing and succeeds; it is durable before it returns, copies what it receives, and on failure preserves the previous generation. Load atomically reads every live subpath of one session; the returned map, slices, and bytes belong to the caller.

type SessionStoreEntry

type SessionStoreEntry = json.RawMessage

SessionStoreEntry is one JSON object in a session's main record or one of its subrecords. Implementations preserve the raw bytes; the sibling validates entries before publishing them.

type SessionStoreReplacement

type SessionStoreReplacement struct {
	Key     SessionKey
	Entries []SessionStoreEntry
}

SessionStoreReplacement is one record written during an atomic replace.

type SessionSummary

type SessionSummary struct {
	SessionID          string
	UpdatedAtUnixMilli int64
}

SessionSummary is a lightweight entry returned by session-store listers.