sessionio

package module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 26, 2026 License: MPL-2.0 Imports: 11 Imported by: 0

README

agent-session-io

ci release

Harness-neutral access to local coding-agent sessions.

agent-session-io is a Go library and a single sessionio CLI for discovering, reading, exporting, and inspecting current sessions from coding-agent harnesses. Codex and Claude Code are the first full-fidelity targets. Catalog and search commands are planned but are not in the current reader release.

The core reader stays usable without SQLite, embeddings, a model provider, or a background service.

Install

macOS or Linux:

curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/nikitatsym/agent-session-io/main/scripts/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/nikitatsym/agent-session-io/main/scripts/install.ps1 | iex

With a Go toolchain:

go install github.com/nikitatsym/agent-session-io/cmd/sessionio@latest

The release installers select the current operating system and architecture, download the latest GitHub Release archive, verify its SHA-256 checksum, install into a user-owned directory, and connect shell completion. Restart the shell after installation. Set SESSIONIO_VERSION to install a specific tag, SESSIONIO_INSTALL_DIR to choose another directory, SESSIONIO_COMPLETION_SHELL to override shell detection, or SESSIONIO_NO_COMPLETION=1 to skip completion setup.

Release archives are available for macOS, Linux, and Windows on amd64 and arm64. GitHub build provenance can be verified with:

gh attestation verify sessionio_darwin_arm64.tar.gz \
  --repo nikitatsym/agent-session-io

CLI

Fang and Cobra provide styled help, shell completion, and manpage generation:

sessionio --help
sessionio --version
sessionio version --json
sessionio completion zsh
sessionio completion install
sessionio update
sessionio sources
sessionio list --harness codex --since 7d
sessionio list --current
sessionio list --current=exact --format json
sessionio show SESSION_ID
sessionio export SESSION_ID

sessionio completion install generates a static completion script and connects it through a managed block in the detected shell profile. It is safe to run repeatedly. PowerShell users can override the profile with --profile.

sessionio update selects the latest release for the current platform, verifies it against the published SHA-256 checksum file, and replaces the current executable with rollback on failure. Public release redirects and asset URLs are used directly, so checking for an update does not require a GitHub API token or consume the GitHub REST API rate limit.

sources and list default to human-readable tables. Both accept --format human|json|ndjson, and --harness codex|claude can be repeated. list also accepts inclusive --since and --until bounds as RFC3339 or elapsed durations such as 30m, 7d, or 2w. list --current reports sessions tied to live Codex or Claude processes; --current=exact excludes probable evidence before matching and regrouping. Runtime presence cannot be combined with --since or --until.

show and export take the session ID printed by list; a unique prefix of the ID or of its digest part is enough, and an ambiguous prefix fails with the matching candidates. show provides --detail normalized|native|provenance. export is the lossless machine interface: it defaults to streaming, self-describing NDJSON and accepts --format json for a single buffered document. Scripts and agents should always pass their desired format explicitly.

Machine output and the Go reader API are current drafts until an explicit contract-freeze decision. Before that decision, the project updates them in place without compatibility shims.

The durable reader semantics are documented in the reader contract.

Development

The repository requires Go, Python 3, and uv.

python3 dev.py check
uvx pre-commit install

dev.py is the single development entry point:

  • python3 dev.py lint
  • python3 dev.py test
  • python3 dev.py e2e
  • python3 dev.py check

Lint includes project-owned Go checks and uvx tackbox@latest lint .. Pre-commit and CI run the same complete dev.py check.

Release

Pushing a semantic version tag runs the complete check, builds cross-platform archives with GoReleaser, publishes checksums, and records GitHub build provenance:

git tag v0.1.0
git push origin v0.1.0

License

Mozilla Public License 2.0. See LICENSE.

Documentation

Overview

Package sessionio provides harness-neutral access to coding-agent sessions.

Index

Constants

View Source 
const PresenceSchema = "sessionio.presence/v1"

PresenceSchema identifies the runtime-presence machine-output schema.

View Source 
const ReaderSchema = "sessionio.reader/v1"

ReaderSchema identifies the initial reader machine-output schema.

Variables

View Source 
var ErrStreamClosed = errors.New("sessionio: stream closed")

ErrStreamClosed is returned when Next is called after Close.

Functions

func ValidatePresenceSnapshot 

func ValidatePresenceSnapshot(snapshot PresenceSnapshot) error

ValidatePresenceSnapshot validates a runtime-presence snapshot before use or encoding.

func WriteJSON 

func WriteJSON(writer io.Writer, producer Producer, records []Record) error

WriteJSON writes one validated reader document followed by a newline.

func WritePresenceJSON 

func WritePresenceJSON(writer io.Writer, producer Producer, snapshot PresenceSnapshot) error

WritePresenceJSON writes one validated presence snapshot followed by a newline.

Types

type Adapter 

type Adapter interface {
	Descriptor() AdapterDescriptor
	Sources(context.Context) (Stream[Source], error)
	Sessions(context.Context, SessionRequest) (Stream[SessionRef], error)
	Read(context.Context, SessionRef) (Stream[ReadItem], error)
}

Adapter discovers and reads sessions for one harness.

type AdapterDescriptor 

type AdapterDescriptor struct {
	Harness      Harness            `json:"harness"`
	Version      string             `json:"version"`
	Capabilities []CapabilityStatus `json:"capabilities"`
}

AdapterDescriptor declares an adapter's identity and capabilities.

type ByteRange 

type ByteRange struct {
	Start int64 `json:"start"`
	End   int64 `json:"end"`
}

ByteRange is a half-open source byte range.

type Capability 

type Capability string

Capability identifies a reader feature exposed by a source or adapter. 

const (
	CapabilityDiscovery          Capability = "discovery"
	CapabilityMessages           Capability = "messages"
	CapabilityRichContent        Capability = "rich_content"
	CapabilityTools              Capability = "tools"
	CapabilityReasoning          Capability = "reasoning"
	CapabilityBranches           Capability = "branches"
	CapabilityUsage              Capability = "usage"
	CapabilityEnvironment        Capability = "environment"
	CapabilityRepository         Capability = "repository"
	CapabilityIncrementalReading Capability = "incremental_reading"
)

type CapabilityStatus 

type CapabilityStatus struct {
	Capability Capability   `json:"capability"`
	Support    SupportLevel `json:"support"`
	Detail     string       `json:"detail,omitempty"`
}

CapabilityStatus describes one capability.

type CaptureKind 

type CaptureKind string

CaptureKind distinguishes exact bytes from a logical structured snapshot. 

const (
	CaptureKindByteExact          CaptureKind = "byte_exact"
	CaptureKindStructuredSnapshot CaptureKind = "structured_snapshot"
	CaptureKindDecodedStream      CaptureKind = "decoded_stream"
)

type ContentAvailability 

type ContentAvailability string

ContentAvailability describes why content is or is not directly readable. 

const (
	ContentAvailabilityAvailable   ContentAvailability = "available"
	ContentAvailabilityEncrypted   ContentAvailability = "encrypted"
	ContentAvailabilityRedacted    ContentAvailability = "redacted"
	ContentAvailabilityExternal    ContentAvailability = "external"
	ContentAvailabilityUnavailable ContentAvailability = "unavailable"
)

type ContentBlock 

type ContentBlock struct {
	ID           ContentID           `json:"id"`
	Kind         ContentKind         `json:"kind"`
	Availability ContentAvailability `json:"availability"`
	Text         *TextContent        `json:"text,omitempty"`
	Media        *MediaContent       `json:"media,omitempty"`
	Opaque       *OpaqueContent      `json:"opaque,omitempty"`
}

ContentBlock is one typed message or reasoning content block.

type ContentID 

type ContentID string

ContentID is an opaque content-block identifier.

type ContentKind 

type ContentKind string

ContentKind selects the active ContentBlock variant. 

const (
	ContentKindText   ContentKind = "text"
	ContentKindMedia  ContentKind = "media"
	ContentKindOpaque ContentKind = "opaque"
)

type DatabaseKey 

type DatabaseKey struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

DatabaseKey is one native database key component.

type DatabaseLocator 

type DatabaseLocator struct {
	Path  string        `json:"path"`
	Table string        `json:"table"`
	Keys  []DatabaseKey `json:"keys,omitempty"`
}

DatabaseLocator identifies a row or event within a database.

type Diagnostic 

type Diagnostic struct {
	Code     string             `json:"code"`
	Severity DiagnosticSeverity `json:"severity"`
	Message  string             `json:"message"`
	Locator  *SourceLocator     `json:"locator,omitempty"`
	Cause    error              `json:"-"`
}

Diagnostic reports a non-fatal source or capability condition.

type DiagnosticSeverity 

type DiagnosticSeverity string

DiagnosticSeverity identifies the impact of a reader diagnostic. 

const (
	DiagnosticSeverityInfo    DiagnosticSeverity = "info"
	DiagnosticSeverityWarning DiagnosticSeverity = "warning"
	DiagnosticSeverityError   DiagnosticSeverity = "error"
)

type DiscoveryRevision 

type DiscoveryRevision string

DiscoveryRevision is an opaque, non-authoritative discovery change token.

type Event 

type Event struct {
	ID         EventID          `json:"id"`
	Kind       EventKind        `json:"kind"`
	Timestamp  *time.Time       `json:"timestamp,omitempty"`
	Evidence   []EvidenceRef    `json:"evidence"`
	Message    *MessageEvent    `json:"message,omitempty"`
	Reasoning  *ReasoningEvent  `json:"reasoning,omitempty"`
	ToolCall   *ToolCallEvent   `json:"tool_call,omitempty"`
	ToolResult *ToolResultEvent `json:"tool_result,omitempty"`
	Usage      *UsageEvent      `json:"usage,omitempty"`
	Facts      *FactEvent       `json:"facts,omitempty"`
	Marker     *MarkerEvent     `json:"marker,omitempty"`
	Unknown    *UnknownEvent    `json:"unknown,omitempty"`
}

Event is one normalized event backed by native evidence.

type EventID 

type EventID string

EventID is an opaque normalized-event identifier.

type EventKind 

type EventKind string

EventKind selects the active Event variant. 

const (
	EventKindMessage    EventKind = "message"
	EventKindReasoning  EventKind = "reasoning"
	EventKindToolCall   EventKind = "tool_call"
	EventKindToolResult EventKind = "tool_result"
	EventKindUsage      EventKind = "usage"
	EventKindFacts      EventKind = "facts"
	EventKindMarker     EventKind = "marker"
	EventKindUnknown    EventKind = "unknown"
)

type EvidenceRef 

type EvidenceRef struct {
	Observation ObservationID `json:"observation"`
	Locator     SourceLocator `json:"locator"`
}

EvidenceRef points from normalized data to a native observation.

type Fact 

type Fact struct {
	Kind  FactKind `json:"kind"`
	Value string   `json:"value"`
}

Fact is one typed normalized fact.

type FactEvent 

type FactEvent struct {
	Facts []Fact `json:"facts"`
}

FactEvent contains normalized session facts.

type FactKind 

type FactKind string

FactKind identifies a normalized session fact. 

const (
	FactKindLaunchDirectory  FactKind = "launch_directory"
	FactKindWorkingDirectory FactKind = "working_directory"
	FactKindModel            FactKind = "model"
	FactKindProvider         FactKind = "provider"
	FactKindEffort           FactKind = "effort"
	FactKindGitRoot          FactKind = "git_root"
	FactKindGitRemote        FactKind = "git_remote"
	FactKindGitBranch        FactKind = "git_branch"
	FactKindGitCommit        FactKind = "git_commit"
	FactKindApprovalPolicy   FactKind = "approval_policy"
	FactKindSandboxPolicy    FactKind = "sandbox_policy"
	FactKindTimezone         FactKind = "timezone"
	FactKindCurrentDate      FactKind = "current_date"
)

type FileLocator 

type FileLocator struct {
	Root      string     `json:"root"`
	Path      string     `json:"path"`
	Record    *uint64    `json:"record,omitempty"`
	Line      *uint64    `json:"line,omitempty"`
	ByteRange *ByteRange `json:"byte_range,omitempty"`
}

FileLocator identifies a record or byte range within a root-relative file.

type Harness 

type Harness string

Harness identifies a coding-agent harness. 

const (
	HarnessCodex    Harness = "codex"
	HarnessClaude   Harness = "claude"
	HarnessOMP      Harness = "omp"
	HarnessOpenCode Harness = "opencode"
)

type LimitationKind 

type LimitationKind string

LimitationKind identifies missing fidelity in the upstream source. 

const (
	LimitationKindUpstreamTruncation     LimitationKind = "upstream_truncation"
	LimitationKindExternalPayload        LimitationKind = "external_payload"
	LimitationKindMissingExternalPayload LimitationKind = "missing_external_payload"
	LimitationKindMutableMaterialization LimitationKind = "mutable_materialization"
)

type LocatorKind 

type LocatorKind string

LocatorKind selects the active SourceLocator variant. 

const (
	LocatorKindFile     LocatorKind = "file"
	LocatorKindDatabase LocatorKind = "database"
	LocatorKindOpaque   LocatorKind = "opaque"
)

type MarkerEvent 

type MarkerEvent struct {
	Name  string `json:"name"`
	State string `json:"state,omitempty"`
}

MarkerEvent preserves an operational or structural native marker.

type MediaContent 

type MediaContent struct {
	MediaType string `json:"media_type,omitempty"`
	Data      []byte `json:"data,omitempty"`
	Reference string `json:"reference,omitempty"`
}

MediaContent contains inline or externally referenced media.

type MessageEvent 

type MessageEvent struct {
	Role    MessageRole    `json:"role"`
	Content []ContentBlock `json:"content,omitempty"`
}

MessageEvent contains ordered native message content.

type MessageRole 

type MessageRole string

MessageRole identifies the native conversational role. 

const (
	MessageRoleUser      MessageRole = "user"
	MessageRoleAssistant MessageRole = "assistant"
	MessageRoleDeveloper MessageRole = "developer"
	MessageRoleSystem    MessageRole = "system"
	MessageRoleTool      MessageRole = "tool"
	MessageRoleUnknown   MessageRole = "unknown"
)

type NDJSONEncoder 

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

NDJSONEncoder writes independently decodable reader records.

func NewNDJSONEncoder 

func NewNDJSONEncoder(writer io.Writer, producer Producer) (*NDJSONEncoder, error)

NewNDJSONEncoder creates a validated NDJSON encoder.

func (*NDJSONEncoder) Encode 

func (encoder *NDJSONEncoder) Encode(record Record) error

Encode validates and writes one self-describing NDJSON record.

type NativeAgentMetadata 

type NativeAgentMetadata struct {
	Nickname string `json:"nickname,omitempty"`
	Role     string `json:"role,omitempty"`
	Path     string `json:"path,omitempty"`
}

type NativeHistoryMetadata 

type NativeHistoryMetadata struct {
	BaseNativeID        string  `json:"base_native_id,omitempty"`
	EndOrdinalExclusive *uint64 `json:"end_ordinal_exclusive,omitempty"`
	EndByteOffset       *uint64 `json:"end_byte_offset,omitempty"`
	OwnStartOrdinal     *uint64 `json:"own_start_ordinal,omitempty"`
}

type NativeIdentity 

type NativeIdentity struct {
	Kind  NativeIdentityKind `json:"kind"`
	Value string             `json:"value"`
}

type NativeIdentityKind 

type NativeIdentityKind string

NativeIdentityKind identifies one native session identity. 

const NativeIdentityKindSession NativeIdentityKind = "session"

type NativeObservation 

type NativeObservation struct {
	ID             ObservationID        `json:"id"`
	NativeKind     string               `json:"native_kind"`
	NativeVersion  string               `json:"native_version,omitempty"`
	Timestamp      *time.Time           `json:"timestamp,omitempty"`
	Locator        SourceLocator        `json:"locator"`
	Revision       Revision             `json:"revision"`
	Representation NativeRepresentation `json:"representation"`
	Limitations    []SourceLimitation   `json:"limitations,omitempty"`
}

NativeObservation is the smallest independently locatable native unit.

type NativeRelationshipHint 

type NativeRelationshipHint struct {
	Kind           NativeRelationshipKind `json:"kind"`
	TargetNativeID string                 `json:"target_native_id"`
}

type NativeRelationshipKind 

type NativeRelationshipKind string

NativeRelationshipKind identifies a native session relationship hint. 

const (
	NativeRelationshipKindForkParent    NativeRelationshipKind = "fork_parent"
	NativeRelationshipKindControlParent NativeRelationshipKind = "control_parent"
)

type NativeRepresentation 

type NativeRepresentation struct {
	Capture   CaptureKind `json:"capture"`
	Codec     string      `json:"codec,omitempty"`
	MediaType string      `json:"media_type"`
	Data      []byte      `json:"data"`
	Framing   []byte      `json:"framing,omitempty"`
}

NativeRepresentation preserves a source-native observation.

type NativeSessionMetadata 

type NativeSessionMetadata struct {
	Identities    []NativeIdentity         `json:"identities,omitempty"`
	Relationships []NativeRelationshipHint `json:"relationships,omitempty"`
	Agent         *NativeAgentMetadata     `json:"agent,omitempty"`
	History       *NativeHistoryMetadata   `json:"history,omitempty"`
}

NativeSessionMetadata preserves native identities and session topology.

type NextFunc 

type NextFunc[T any] func(context.Context) (T, error)

NextFunc produces the next stream value.

type NodeKind 

type NodeKind string

NodeKind identifies the object addressed by a relation endpoint. 

const (
	NodeKindSession     NodeKind = "session"
	NodeKindObservation NodeKind = "observation"
	NodeKindEvent       NodeKind = "event"
	NodeKindContent     NodeKind = "content"
)

type NodeRef 

type NodeRef struct {
	Kind NodeKind `json:"kind"`
	ID   string   `json:"id"`
}

NodeRef identifies one relation endpoint.

type ObservationID 

type ObservationID string

ObservationID is an opaque source-native observation identifier.

type OccurrenceID 

type OccurrenceID string

OccurrenceID is an opaque source-occurrence identifier.

type OpaqueContent 

type OpaqueContent struct {
	NativeType string `json:"native_type"`
	MediaType  string `json:"media_type,omitempty"`
	Data       []byte `json:"data,omitempty"`
}

OpaqueContent preserves a harness-specific content block.

type OpaqueLocator 

type OpaqueLocator struct {
	Scheme string `json:"scheme"`
	Value  string `json:"value"`
}

OpaqueLocator identifies a unit through an adapter-defined scheme.

type Payload 

type Payload struct {
	MediaType string `json:"media_type"`
	Data      []byte `json:"data"`
}

Payload preserves a typed tool payload without interpreting its bytes.

type PresenceCapability 

type PresenceCapability string

PresenceCapability identifies a runtime-presence signal a provider can inspect. 

const (
	PresenceCapabilityExactMatch    PresenceCapability = "exact_match"
	PresenceCapabilityProbableMatch PresenceCapability = "probable_match"
)

type PresenceCapabilityStatus 

type PresenceCapabilityStatus struct {
	Capability PresenceCapability `json:"capability"`
	Support    PresenceSupport    `json:"support"`
	Reason     *PresenceReason    `json:"reason,omitempty"`
	Detail     string             `json:"detail,omitempty"`
}

PresenceCapabilityStatus reports one provider capability for one harness.

type PresenceCertainty 

type PresenceCertainty string

PresenceCertainty describes the strength of a runtime-to-session match. 

const (
	PresenceCertaintyExact    PresenceCertainty = "exact"
	PresenceCertaintyProbable PresenceCertainty = "probable"
)

type PresenceEvidence 

type PresenceEvidence struct {
	Kind      PresenceEvidenceKind `json:"kind"`
	Certainty PresenceCertainty    `json:"certainty"`
	Detail    string               `json:"detail,omitempty"`
}

PresenceEvidence is a typed, non-secret observation supporting a presence result.

type PresenceEvidenceKind 

type PresenceEvidenceKind string

PresenceEvidenceKind identifies a non-secret runtime-presence observation. 

const (
	PresenceEvidenceProcessIdentity       PresenceEvidenceKind = "process_identity"
	PresenceEvidenceNativeSessionRegistry PresenceEvidenceKind = "native_session_registry"
	PresenceEvidenceOpenSessionFile       PresenceEvidenceKind = "open_session_file"
	PresenceEvidenceTerminalIdentity      PresenceEvidenceKind = "terminal_identity"
	PresenceEvidenceTerminalBreadcrumb    PresenceEvidenceKind = "terminal_breadcrumb"
	PresenceEvidenceLoopbackListener      PresenceEvidenceKind = "loopback_listener"
	PresenceEvidenceHealthEndpoint        PresenceEvidenceKind = "health_endpoint"
	PresenceEvidenceSessionStatus         PresenceEvidenceKind = "session_status"
)

type PresenceMatch 

type PresenceMatch struct {
	Harness         Harness              `json:"harness"`
	NativeSessionID string               `json:"native_session_id"`
	Certainty       PresenceCertainty    `json:"certainty"`
	Occurrences     []PresenceOccurrence `json:"occurrences"`
	Selection       PresenceSelection    `json:"selection"`
	Processes       []ProcessInstance    `json:"processes"`
	Evidence        []PresenceEvidence   `json:"evidence"`
}

PresenceMatch groups runtime observations by harness and native session ID.

type PresenceNDJSONEncoder 

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

PresenceNDJSONEncoder writes independently decodable presence snapshots.

func NewPresenceNDJSONEncoder 

func NewPresenceNDJSONEncoder(writer io.Writer, producer Producer) (*PresenceNDJSONEncoder, error)

NewPresenceNDJSONEncoder creates a validated presence NDJSON encoder.

func (*PresenceNDJSONEncoder) Encode 

func (encoder *PresenceNDJSONEncoder) Encode(snapshot PresenceSnapshot) error

Encode validates and writes one self-describing presence snapshot.

type PresenceOccurrence 

type PresenceOccurrence struct {
	Session  SessionRef                 `json:"session"`
	Relation PresenceOccurrenceRelation `json:"relation"`
}

PresenceOccurrence attaches one persisted session occurrence to a native session match.

type PresenceOccurrenceRelation 

type PresenceOccurrenceRelation string

PresenceOccurrenceRelation describes how a persisted occurrence matches a native session. 

const (
	PresenceOccurrenceRelationExactLocator   PresenceOccurrenceRelation = "exact_locator"
	PresenceOccurrenceRelationNativeIdentity PresenceOccurrenceRelation = "native_identity"
)

type PresenceProviderStatus 

type PresenceProviderStatus struct {
	Harness      Harness                    `json:"harness"`
	Version      string                     `json:"version"`
	Support      PresenceSupport            `json:"support"`
	Reason       *PresenceReason            `json:"reason,omitempty"`
	Detail       string                     `json:"detail,omitempty"`
	Capabilities []PresenceCapabilityStatus `json:"capabilities"`
}

PresenceProviderStatus reports a versioned runtime-presence provider for one harness.

type PresenceReason 

type PresenceReason string

PresenceReason explains a non-match or unavailable runtime-presence signal. 

const (
	PresenceReasonAccessDenied            PresenceReason = "access_denied"
	PresenceReasonAuthenticationRequired  PresenceReason = "authentication_required"
	PresenceReasonCrossEnvironment        PresenceReason = "cross_environment"
	PresenceReasonInspectionFailed        PresenceReason = "inspection_failed"
	PresenceReasonNoSessionIdentity       PresenceReason = "no_session_identity"
	PresenceReasonPrerequisiteMissing     PresenceReason = "prerequisite_missing"
	PresenceReasonProcessExited           PresenceReason = "process_exited"
	PresenceReasonProviderUnavailable     PresenceReason = "provider_unavailable"
	PresenceReasonProviderUnsupported     PresenceReason = "provider_unsupported"
	PresenceReasonStaleProcessIdentity    PresenceReason = "stale_process_identity"
	PresenceReasonUnmatchedNativeIdentity PresenceReason = "unmatched_native_identity"
)

type PresenceSelection 

type PresenceSelection struct {
	Status    PresenceSelectionStatus `json:"status"`
	SessionID SessionID               `json:"session_id,omitempty"`
}

PresenceSelection records the selected persisted occurrence, if resolution was possible.

type PresenceSelectionStatus 

type PresenceSelectionStatus string

PresenceSelectionStatus describes whether one persisted occurrence was selected. 

const (
	PresenceSelectionResolved  PresenceSelectionStatus = "resolved"
	PresenceSelectionAmbiguous PresenceSelectionStatus = "ambiguous"
)

type PresenceSnapshot 

type PresenceSnapshot struct {
	ObservedAt         time.Time                `json:"observed_at"`
	ExpiresAt          time.Time                `json:"expires_at"`
	Providers          []PresenceProviderStatus `json:"providers"`
	Matches            []PresenceMatch          `json:"matches"`
	UnmatchedProcesses []UnmatchedProcess       `json:"unmatched_processes"`
}

PresenceSnapshot is one ephemeral, time-bounded runtime-presence observation.

type PresenceSupport 

type PresenceSupport string

PresenceSupport describes whether a runtime-presence signal is available. 

const (
	PresenceSupportSupported   PresenceSupport = "supported"
	PresenceSupportUnavailable PresenceSupport = "unavailable"
	PresenceSupportUnsupported PresenceSupport = "unsupported"
)

type ProcessInstance 

type ProcessInstance struct {
	PID       uint64             `json:"pid"`
	StartedAt time.Time          `json:"started_at"`
	Evidence  []PresenceEvidence `json:"evidence"`
}

ProcessInstance is a live process identity sampled with its start time.

type Producer 

type Producer struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

Producer identifies the program that emitted machine output.

type ReadItem 

type ReadItem struct {
	Session     SessionRef        `json:"session"`
	Observation NativeObservation `json:"observation"`
	Events      []Event           `json:"events,omitempty"`
	Relations   []Relation        `json:"relations,omitempty"`
	Diagnostics []Diagnostic      `json:"diagnostics,omitempty"`
}

ReadItem contains one native observation and its normalized projections.

type ReaderError 

type ReaderError struct {
	Operation      string
	Harness        Harness
	AdapterVersion string
	SessionID      SessionID
	Locator        *SourceLocator
	Err            error
}

ReaderError adds reader context while preserving the underlying error.

func (*ReaderError) Error 

func (readerError *ReaderError) Error() string

func (*ReaderError) Unwrap 

func (readerError *ReaderError) Unwrap() error

Unwrap returns the underlying reader failure.

type ReasoningEvent 

type ReasoningEvent struct {
	Content []ContentBlock `json:"content,omitempty"`
	Summary []ContentBlock `json:"summary,omitempty"`
}

ReasoningEvent contains reasoning and any separately exposed summary.

type Record 

type Record struct {
	Kind       RecordKind  `json:"kind"`
	Source     *Source     `json:"source,omitempty"`
	Session    *SessionRef `json:"session,omitempty"`
	ReadItem   *ReadItem   `json:"read_item,omitempty"`
	Diagnostic *Diagnostic `json:"diagnostic,omitempty"`
}

Record is one validated reader machine-output record.

type RecordKind 

type RecordKind string

RecordKind selects the active Record variant. 

const (
	RecordKindSource     RecordKind = "source"
	RecordKindSession    RecordKind = "session"
	RecordKindReadItem   RecordKind = "read_item"
	RecordKindDiagnostic RecordKind = "diagnostic"
)

type Registry 

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

Registry stores one validated adapter per harness.

func NewRegistry 

func NewRegistry(adapters ...Adapter) (*Registry, error)

NewRegistry creates a registry and validates every supplied adapter.

func (*Registry) Adapter 

func (registry *Registry) Adapter(harness Harness) (Adapter, bool)

Adapter returns the adapter registered for a harness.

func (*Registry) Descriptors 

func (registry *Registry) Descriptors() []AdapterDescriptor

Descriptors returns descriptors ordered lexically by harness.

func (*Registry) Register 

func (registry *Registry) Register(adapter Adapter) error

Register adds an adapter after validating its descriptor.

type Relation 

type Relation struct {
	ID       RelationID     `json:"id"`
	Kind     RelationKind   `json:"kind"`
	From     NodeRef        `json:"from"`
	To       NodeRef        `json:"to"`
	Origin   RelationOrigin `json:"origin"`
	Evidence []EvidenceRef  `json:"evidence"`
}

Relation links two typed nodes using native evidence.

type RelationID 

type RelationID string

RelationID is an opaque structural-relation identifier.

type RelationKind 

type RelationKind string

RelationKind identifies a structural relation. 

const (
	RelationKindPrevious     RelationKind = "previous"
	RelationKindNext         RelationKind = "next"
	RelationKindReplyTo      RelationKind = "reply_to"
	RelationKindBranchParent RelationKind = "branch_parent"
	RelationKindContains     RelationKind = "contains"
	RelationKindToolPair     RelationKind = "tool_pair"
	RelationKindMaterializes RelationKind = "materializes"
	RelationKindUpdates      RelationKind = "updates"
	// RelationKindActiveLeaf identifies the source-selected leaf of a persisted branch tree.
	RelationKindActiveLeaf RelationKind = "active_leaf"
)

type RelationOrigin 

type RelationOrigin string

RelationOrigin distinguishes native relations from deterministic projections. 

const (
	RelationOriginNative        RelationOrigin = "native"
	RelationOriginDeterministic RelationOrigin = "deterministic"
)

type Revision 

type Revision struct {
	Kind  RevisionKind `json:"kind"`
	Value string       `json:"value"`
}

Revision identifies the immutable source state used for a read.

type RevisionKind 

type RevisionKind string

RevisionKind identifies the source revision mechanism. 

const (
	RevisionKindFileSnapshot        RevisionKind = "file_snapshot"
	RevisionKindDatabaseTransaction RevisionKind = "database_transaction"
	RevisionKindEventSequence       RevisionKind = "event_sequence"
	RevisionKindOpaque              RevisionKind = "opaque"
)

type SessionID 

type SessionID string

SessionID is an opaque occurrence-scoped session identifier.

type SessionRef 

type SessionRef struct {
	ID                SessionID             `json:"id"`
	NativeID          string                `json:"native_id"`
	Title             string                `json:"title,omitempty"`
	DiscoveryRevision DiscoveryRevision     `json:"discovery_revision"`
	Native            NativeSessionMetadata `json:"native"`
	Occurrence        SourceOccurrence      `json:"occurrence"`
	StartedAt         *time.Time            `json:"started_at,omitempty"`
	UpdatedAt         *time.Time            `json:"updated_at,omitempty"`
	Diagnostics       []Diagnostic          `json:"diagnostics,omitempty"`
}

SessionRef identifies one native session within one source occurrence.

type SessionRequest 

type SessionRequest struct {
	Sources []SourceID
}

SessionRequest filters session discovery by source.

type Source 

type Source struct {
	ID           SourceID           `json:"id"`
	Harness      Harness            `json:"harness"`
	Kind         SourceKind         `json:"kind"`
	Status       SourceStatus       `json:"status"`
	Locator      SourceLocator      `json:"locator"`
	Capabilities []CapabilityStatus `json:"capabilities,omitempty"`
	Diagnostics  []Diagnostic       `json:"diagnostics,omitempty"`
}

Source describes one discovered native source.

type SourceID 

type SourceID string

SourceID is an opaque discovered-source identifier.

type SourceKind 

type SourceKind string

SourceKind distinguishes canonical transcripts from auxiliary stores. 

const (
	SourceKindCanonical SourceKind = "canonical"
	SourceKindAuxiliary SourceKind = "auxiliary"
)

type SourceLimitation 

type SourceLimitation struct {
	Kind   LimitationKind `json:"kind"`
	Detail string         `json:"detail,omitempty"`
}

SourceLimitation records a native-source fidelity limitation.

type SourceLocator 

type SourceLocator struct {
	Kind     LocatorKind      `json:"kind"`
	File     *FileLocator     `json:"file,omitempty"`
	Database *DatabaseLocator `json:"database,omitempty"`
	Opaque   *OpaqueLocator   `json:"opaque,omitempty"`
}

SourceLocator locates a source-native unit.

type SourceOccurrence 

type SourceOccurrence struct {
	ID       OccurrenceID  `json:"id"`
	SourceID SourceID      `json:"source_id"`
	Harness  Harness       `json:"harness"`
	Locator  SourceLocator `json:"locator"`
}

SourceOccurrence identifies one observed instance of a source.

type SourceStatus 

type SourceStatus string

SourceStatus describes whether a discovered source can be read. 

const (
	SourceStatusAvailable   SourceStatus = "available"
	SourceStatusMissing     SourceStatus = "missing"
	SourceStatusDisabled    SourceStatus = "disabled"
	SourceStatusUnsupported SourceStatus = "unsupported"
)

type Stream 

type Stream[T any] interface {
	Next(context.Context) (T, error)
	Close() error
}

Stream is a pull-based sequence with explicit resource ownership.

func NewStream 

func NewStream[T any](next NextFunc[T], close func() error) (Stream[T], error)

NewStream wraps callbacks in the Stream lifecycle contract.

type SupportLevel 

type SupportLevel string

SupportLevel describes how completely a capability is implemented. 

const (
	SupportFull         SupportLevel = "full"
	SupportPartial      SupportLevel = "partial"
	SupportExperimental SupportLevel = "experimental"
	SupportUnavailable  SupportLevel = "unavailable"
)

type TextContent 

type TextContent struct {
	Text string `json:"text"`
}

TextContent contains a native text block.

type ToolCallEvent 

type ToolCallEvent struct {
	CallID string  `json:"call_id"`
	Name   string  `json:"name"`
	Input  Payload `json:"input"`
}

ToolCallEvent contains one native tool invocation.

type ToolResultEvent 

type ToolResultEvent struct {
	CallID string           `json:"call_id"`
	Status ToolResultStatus `json:"status"`
	Output Payload          `json:"output"`
}

ToolResultEvent contains one native tool result or state transition.

type ToolResultStatus 

type ToolResultStatus string

ToolResultStatus describes the state represented by a tool result. 

const (
	ToolResultStatusSuccess ToolResultStatus = "success"
	ToolResultStatusError   ToolResultStatus = "error"
	ToolResultStatusPending ToolResultStatus = "pending"
	ToolResultStatusRunning ToolResultStatus = "running"
	ToolResultStatusUnknown ToolResultStatus = "unknown"
)

type UnknownEvent 

type UnknownEvent struct {
	NativeType string `json:"native_type"`
}

UnknownEvent preserves the type of an otherwise unknown native record.

type UnmatchedProcess 

type UnmatchedProcess struct {
	Harness          Harness            `json:"harness"`
	Process          ProcessInstance    `json:"process"`
	ClaimedNativeIDs []string           `json:"claimed_native_ids,omitempty"`
	Reason           PresenceReason     `json:"reason"`
	Evidence         []PresenceEvidence `json:"evidence"`
}

UnmatchedProcess is a live harness process that was not assigned to a persisted session.

type UsageEvent 

type UsageEvent struct {
	InputTokens      *int64 `json:"input_tokens,omitempty"`
	OutputTokens     *int64 `json:"output_tokens,omitempty"`
	ReasoningTokens  *int64 `json:"reasoning_tokens,omitempty"`
	CacheReadTokens  *int64 `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens *int64 `json:"cache_write_tokens,omitempty"`
	TotalTokens      *int64 `json:"total_tokens,omitempty"`
}

UsageEvent contains normalized optional token counters.

Source Files

View all Source files

Directories

Path Synopsis
adapters
claude
Package claude reads Claude Code transcript JSONL files.
 Package claude reads Claude Code transcript JSONL files.
codex
Package codex reads Codex rollout JSONL files.
 Package codex reads Codex rollout JSONL files.
cmd
sessionio command
internal
buildinfo
catalog
Package catalog owns the PostgreSQL search catalog and its typed failures.
 Package catalog owns the PostgreSQL search catalog and its typed failures.
cli
completion
config
Package config loads the versioned strict TOML configuration file.
 Package config loads the versioned strict TOML configuration file.
presence
runtimeprobe
sourceio
updater

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.