client

package
v1.4.0 Latest Latest
Warning

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

 Go to latest Published: Sep 13, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package client provides access to the current user's AHT agent-session state.

By default, a Client uses the local realtime broker when it is available and falls back to the durable registry for one-shot operations. Config.Mode can instead require realtime or durable storage; invalid modes make operations fail with ErrInvalidMode. Use Client.Watch when a program needs an initial snapshot followed by live state revisions.

Index

Examples

Constants

View Source 
const (
	// ModeAuto routes operations through the realtime broker and falls back to
	// the durable registry on disk when the broker is offline.
	// This is the default mode.
	ModeAuto Mode = "auto"

	// ModeRealtimeOnly directs all operations strictly to the realtime broker socket.
	// When the broker is offline, operations fail immediately with [ErrUnavailable]
	// without reading disk or taking filesystem locks.
	ModeRealtimeOnly Mode = "realtime"

	// ModeDurableOnly directs all operations directly to the on-disk registry file,
	// bypassing the realtime broker entirely.
	ModeDurableOnly Mode = "durable"

	PresenceLive    Presence = registry.PresenceLive
	PresenceGone    Presence = registry.PresenceGone
	PresenceUnknown Presence = registry.PresenceUnknown

	ActivityRunning     Activity = registry.ActivityRunning
	ActivityWaiting     Activity = registry.ActivityWaiting
	ActivityIdle        Activity = registry.ActivityIdle
	ActivityFailed      Activity = registry.ActivityFailed
	ActivityInterrupted Activity = registry.ActivityInterrupted
	ActivityUnknown     Activity = registry.ActivityUnknown

	HarnessClaude   Harness = registry.HarnessClaude
	HarnessCodex    Harness = registry.HarnessCodex
	HarnessCursor   Harness = registry.HarnessCursor
	HarnessCopilot  Harness = registry.HarnessCopilot
	HarnessCline    Harness = registry.HarnessCline
	HarnessKimiCode Harness = registry.HarnessKimiCode
	HarnessGrok     Harness = registry.HarnessGrok
	HarnessGoose    Harness = registry.HarnessGoose
	HarnessPi       Harness = registry.HarnessPi
	HarnessOmp      Harness = registry.HarnessOmp
	HarnessOpenCode Harness = registry.HarnessOpenCode
	HarnessAgy      Harness = registry.HarnessAgy
	HarnessKilo     Harness = registry.HarnessKilo
	HarnessDroid    Harness = registry.HarnessDroid
	HarnessOpenClaw Harness = registry.HarnessOpenClaw
	HarnessHermes   Harness = registry.HarnessHermes
)

Variables

View Source 
var (
	// ErrUnavailable means no realtime AHT broker accepted the local connection.
	ErrUnavailable = errors.New("aht broker unavailable")
	// ErrProtocol means the broker returned an invalid or incompatible response.
	ErrProtocol = errors.New("aht broker protocol error")

	ErrRealtimeRequired = errors.New("operation requires a realtime broker connection")
	// ErrInvalidMode means a client was configured with an unsupported Mode.
	ErrInvalidMode = errors.New("invalid aht client mode")
)

Functions

func IsUnavailable 

func IsUnavailable(err error) bool

IsUnavailable reports whether err means that no realtime broker accepted the connection.

Types

type Activity added in v1.3.0 

type Activity = registry.Activity

Activity indicates what an agent is currently doing.

type Client 

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

Client reads and updates agent-harness state through the local AHT broker. Depending on Mode, operations route to the realtime broker socket, durable disk storage, or auto-fallback between the two.

func New 

func New(config Config) *Client

New returns a client for the configured local AHT instance. An unsupported Mode makes all operations return ErrInvalidMode without performing I/O.

func (*Client) GC 

func (c *Client) GC(ctx context.Context, deleteAfter time.Duration) (registry.GCResult, error)

GC removes gone-session tombstones at least deleteAfter old.

func (*Client) Get 

func (c *Client) Get(ctx context.Context, id string) (registry.Session, error)

Get returns the session identified by id.

func (*Client) List 

func (c *Client) List(ctx context.Context, filter registry.Filter) ([]registry.Session, error)

List returns all sessions matching filter.

Example 
package main

import (
	"context"
	"fmt"
	"os"
	"path/filepath"
	"time"

	"github.com/zigai/aht/pkg/client"
	"github.com/zigai/aht/pkg/registry"
)

func main() {
	directory, err := os.MkdirTemp("", "aht-client-example")
	if err != nil {
		panic(err)
	}
	defer func() { _ = os.RemoveAll(directory) }()

	storePath := filepath.Join(directory, "sessions.json")
	presence := registry.PresenceLive
	activity := registry.ActivityRunning
	if _, err := registry.NewFileStore(storePath).Observe(context.Background(), registry.Observation{
		Source:     registry.ObservationSourceNative,
		Evidence:   registry.ObservationEvidenceNativeEvent,
		Harness:    registry.HarnessCodex,
		Identity:   registry.ObservationIdentity{SessionID: "example"},
		Presence:   &presence,
		Activity:   &activity,
		ObservedAt: time.Now().UTC(),
	}); err != nil {
		panic(err)
	}

	aht := client.New(client.Config{
		StorePath:  storePath,
		SocketPath: filepath.Join(directory, "offline.sock"),
	})
	sessions, err := aht.List(
		context.Background(),
		client.Filter{Presence: client.PresenceLive},
	)
	if err != nil {
		panic(err)
	}

	fmt.Printf("%s: %s\n", sessions[0].Harness, *sessions[0].Activity)
}

Output:
codex: running

func (*Client) Mode added in v1.3.0 

func (c *Client) Mode() Mode

Mode returns the configured operating mode.

func (*Client) Observe 

func (c *Client) Observe(ctx context.Context, observation registry.Observation) (registry.Session, error)

Observe records one agent-harness observation using the configured Mode. Only ModeAuto falls back to durable storage when the broker is unavailable.

func (*Client) ObserveBatch 

func (c *Client) ObserveBatch(ctx context.Context, observations []registry.Observation) ([]registry.Session, error)

ObserveBatch atomically records a group of agent-harness observations.

func (*Client) Ping 

func (c *Client) Ping(ctx context.Context) error

Ping verifies that the realtime broker is accepting requests.

func (*Client) Realtime added in v1.3.0 

func (c *Client) Realtime() *broker.Client

Realtime returns the underlying realtime broker socket client.

func (*Client) SocketPath 

func (c *Client) SocketPath() string

SocketPath returns the broker endpoint used by the client.

func (*Client) StorePath 

func (c *Client) StorePath() string

StorePath returns the durable registry path used for broker fallback.

func (*Client) Subscribe added in v1.3.0 

func (c *Client) Subscribe(ctx context.Context, filter registry.Filter) (*broker.Subscription, error)

Subscribe returns an active subscription streaming state snapshots from the broker. Subscribe requires a running broker and is not supported in ModeDurableOnly.

func (*Client) Summary 

func (c *Client) Summary(ctx context.Context, filter registry.Filter) ([]registry.Summary, error)

Summary returns aggregate session counts grouped by terminal-multiplexer session.

func (*Client) SummaryByTmuxSession 

func (c *Client) SummaryByTmuxSession(ctx context.Context, filter registry.Filter) ([]registry.Summary, error)

SummaryByTmuxSession implements registry.Store.

func (*Client) Watch 

func (c *Client) Watch(
	ctx context.Context,
	filter registry.Filter,
	yield func(registry.StateSnapshot) error,
) error

Watch calls yield with the initial filtered snapshot and each strictly newer revision until ctx is canceled. Watch returns nil after cancellation.

type Config 

type Config struct {
	StorePath  string
	SocketPath string
	Mode       Mode
}

Config identifies the local AHT instance used by a Client. Empty fields use the current user's default registry and its associated broker socket.

type Filter added in v1.3.0 

type Filter = registry.Filter

Filter specifies matching criteria when querying or watching sessions.

type Harness added in v1.3.0 

type Harness = registry.Harness

Harness identifies a supported AI coding agent.

type Mode added in v1.3.0 

type Mode string

Mode controls how a Client routes operations between the realtime broker and the durable registry file on disk.

type MultiplexerContext added in v1.3.0 

type MultiplexerContext = registry.MultiplexerContext

MultiplexerContext represents the unified multiplexer location of a session.

type Observation added in v1.3.0 

type Observation = registry.Observation

Observation represents an observation recorded for a session.

type OperationError 

type OperationError struct {
	Code    string
	Message string
	// contains filtered or unexported fields
}

OperationError is a machine-readable failure returned by the AHT broker.

func (*OperationError) Error 

func (e *OperationError) Error() string

func (*OperationError) Unwrap added in v1.4.0 

func (e *OperationError) Unwrap() error

Unwrap preserves the broker failure and its registry error classification.

type Presence added in v1.3.0 

type Presence = registry.Presence

Presence indicates whether an agent session is live, gone, or unknown.

type Session added in v1.3.0 

type Session = registry.Session

Session represents an agent-harness session tracked by AHT.

type StateSnapshot added in v1.3.0 

type StateSnapshot = registry.StateSnapshot

StateSnapshot is a revisioned collection of tracked sessions.

type Subscription added in v1.3.0 

type Subscription = broker.Subscription

Subscription streams independently owned snapshots from the realtime broker.

type Summary added in v1.3.0 

type Summary = registry.Summary

Summary represents aggregate session counts for a terminal session.

type TmuxContext added in v1.3.0 

type TmuxContext = registry.TmuxContext

TmuxContext represents the tmux multiplexer location of a session.

Source Files

View all Source files

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.