client

Documentation

Overview

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

A Client uses the local realtime broker when it is available and falls back to the durable registry for one-shot operations. Use Client.Watch when a program needs an initial snapshot followed by live state revisions.

Index

• Variables
• func IsUnavailable(err error) bool
• type Client
  • func New(config Config) *Client
  • func (c *Client) GC(ctx context.Context, deleteAfter time.Duration) (registry.GCResult, error)
  • func (c *Client) Get(ctx context.Context, id string) (registry.Session, error)
  • func (c *Client) List(ctx context.Context, filter registry.Filter) ([]registry.Session, error)
  • func (c *Client) Observe(ctx context.Context, observation registry.Observation) (registry.Session, error)
  • func (c *Client) ObserveBatch(ctx context.Context, observations []registry.Observation) ([]registry.Session, error)
  • func (c *Client) Ping(ctx context.Context) error
  • func (c *Client) SocketPath() string
  • func (c *Client) StorePath() string
  • func (c *Client) Summary(ctx context.Context, filter registry.Filter) ([]registry.Summary, error)
  • func (c *Client) SummaryByTmuxSession(ctx context.Context, filter registry.Filter) ([]registry.Summary, error)
  • func (c *Client) SummaryByTmuxSessionWithOptions(ctx context.Context, options registry.SummaryOptions) ([]registry.Summary, error)
  • func (c *Client) Watch(ctx context.Context, filter registry.Filter, ...) error
• type Config
• type OperationError
  • func (e *OperationError) Error() string

Examples

• Client.List

Variables

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")
)

Functions

func IsUnavailable

func IsUnavailable(err error) bool

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

Types

type Client

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

Client reads and updates agent-harness state through the local AHT broker. One-shot operations fall back to the durable registry when the broker is not running. Watch requires a running broker.

func New

func New(config Config) *Client

New returns a client for the configured local AHT instance.

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(),
		registry.Filter{Presence: registry.PresenceLive},
	)
	if err != nil {
		panic(err)
	}

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

Output:
codex: running

func (*Client) Observe

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

Observe records one agent-harness observation. When the broker is not running, the client records the observation directly in the durable registry.

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) 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) 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) SummaryByTmuxSessionWithOptions

func (c *Client) SummaryByTmuxSessionWithOptions(ctx context.Context, options registry.SummaryOptions) ([]registry.Summary, error)

SummaryByTmuxSessionWithOptions 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
}

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 OperationError

type OperationError struct {
	Code    string
	Message string
}

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

func (*OperationError) Error

func (e *OperationError) Error() string