agentlib

Documentation

Overview

Package agentlib exposes Tokitoki's local usage sync engine for native front-ends.

Index

• Constants
• Variables
• func BaseURL() string
• func DefaultDataDir() (string, error)
• func DefaultProviderDirs() map[Provider][]string
• type Client
  • func New(options Options) (*Client, error)
  • func (c *Client) DashboardURL(ctx context.Context) (string, error)
  • func (c *Client) DataDir() string
  • func (c *Client) GetAPIKey() (string, error)
  • func (c *Client) Scan(options SyncOptions) error
  • func (c *Client) SendHeartbeat(ctx context.Context, heartbeat Heartbeat) error
  • func (c *Client) SetAPIKey(apiKey string) error
  • func (c *Client) Sync(ctx context.Context, options SyncOptions) error
  • func (c *Client) Upload(ctx context.Context) error
  • func (c *Client) VerifyAPIKey(ctx context.Context) (bool, error)
  • func (c *Client) VerifyAPIKeyValue(ctx context.Context, apiKey string) (bool, error)
• type Heartbeat
• type Options
• type Provider
• type SyncOptions

Constants

const (
	// DefaultUploadTimeout is the maximum duration for one scan and upload run.
	DefaultUploadTimeout = 2 * time.Minute

	// DefaultLockTimeout is the maximum duration to wait for another Tokitoki
	// command to release the shared local data lock.
	DefaultLockTimeout = DefaultUploadTimeout + 10*time.Second
)

Variables

var (
	// ErrMissingAPIKey is returned when the shared data directory does not have
	// a configured API key. It aliases the inner package's sentinel so a key
	// error raised anywhere in the stack compares equal here.
	ErrMissingAPIKey = cli.ErrNoAPIKey

	// ErrNoScanDirectories is returned when a sync call has no provider
	// directory to scan.
	ErrNoScanDirectories = errors.New("nothing to scan; pass at least one provider directory")
)

Functions

func BaseURL

func BaseURL() string

BaseURL returns the Tokitoki server every subsystem talks to — usage uploads, update checks, and the web dashboard alike. Front-ends open it when they need a plain link to the server (for example as the fallback when DashboardURL cannot mint a signed login link).

func DefaultDataDir

func DefaultDataDir() (string, error)

DefaultDataDir returns the shared Tokitoki data directory.

func DefaultProviderDirs

func DefaultProviderDirs() map[Provider][]string

DefaultProviderDirs returns the built-in provider data directories.

Types

type Client

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

Client provides local settings and usage sync operations for native clients.

func New

func New(options Options) (*Client, error)

New creates a Client and ensures its data directory exists.

func (*Client) DashboardURL

func (c *Client) DashboardURL(ctx context.Context) (string, error)

DashboardURL exchanges the stored API key for a one-time browser login URL. Opening it signs the user straight into their web dashboard — no password.

func (*Client) DataDir

func (c *Client) DataDir() string

DataDir returns the directory used for shared agent state.

func (*Client) GetAPIKey

func (c *Client) GetAPIKey() (string, error)

GetAPIKey returns the configured API key.

func (*Client) Scan

func (c *Client) Scan(options SyncOptions) error

Scan ingests provider directories into the local queue without uploading. It is the other half of Sync, for callers running the two on separate schedules.

func (*Client) SendHeartbeat

func (c *Client) SendHeartbeat(ctx context.Context, heartbeat Heartbeat) error

SendHeartbeat persists an IDE activity event before attempting upload. If the network is unavailable the event stays queued in the shared local database and a later heartbeat or normal sync retries it with backoff.

func (*Client) SetAPIKey

func (c *Client) SetAPIKey(apiKey string) error

SetAPIKey saves apiKey in the shared local agent store.

func (*Client) Sync

func (c *Client) Sync(ctx context.Context, options SyncOptions) error

Sync scans selected provider directories and uploads newly discovered events. Scanning is local and always runs; without a configured API key the events simply stay queued and upload resumes once a key is saved.

The two halves run at the same time. A scan queues each file's events as it finishes that file, so the upload half has work to send long before the scan is done — on a first run over a large history that is the difference between uploading throughout the scan and sitting idle until it ends. They share no state but the queue: the scan writes to it, the drain reads from it.

Sync returns only once both halves are finished, because callers are one-shot processes that exit when it returns. The drain therefore keeps polling until the scan has stopped producing and the queue is empty.

func (*Client) Upload

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

Upload drains queued events to the server without scanning first.

Scanning and uploading share no state but the local queue: a scan writes events into it and an upload drains them. Nothing about the drain depends on a scan having just run, so a caller that wants the two to proceed at their own pace runs Scan and Upload on separate schedules — an upload no longer waits for a scan to finish before sending what is already queued, and a slow or failing scan cannot hold back events that were queued minutes ago.

A missing API key is not an error here. Events stay queued until a key exists, which is the same thing Sync does.

func (*Client) VerifyAPIKey

func (c *Client) VerifyAPIKey(ctx context.Context) (bool, error)

VerifyAPIKey checks the stored API key against the server. A definite answer returns (true, nil) or (false, nil); network or server trouble is an error so callers can tell "invalid" apart from "could not check".

func (*Client) VerifyAPIKeyValue

func (c *Client) VerifyAPIKeyValue(ctx context.Context, apiKey string) (bool, error)

VerifyAPIKeyValue checks the given key against the server without touching the stored one — front-ends verify a candidate key before saving it. Same answer semantics as VerifyAPIKey.

type Heartbeat

type Heartbeat struct {
	Entity         string
	Timestamp      time.Time
	Project        string
	ProjectPath    string
	Language       string
	Branch         string
	Editor         string
	Plugin         string
	Category       string
	IsWrite        bool
	LineNumber     int
	CursorPosition int
	LinesInFile    int
}

Heartbeat describes one IDE activity sample.

type Options

type Options struct {
	// DataDir is the directory used for shared agent state. When empty, the
	// default is ~/.tokitoki.
	DataDir string

	// LockTimeout controls how long calls that mutate shared state wait for the
	// local data lock. When zero, DefaultLockTimeout is used.
	LockTimeout time.Duration

	// Logger receives warnings from lower-level agent components. When nil,
	// logs are discarded.
	Logger *slog.Logger
}

Options configures a Client.

type Provider

type Provider string

Provider identifies a local AI usage source.

const (
	// ProviderClaude identifies Claude usage files.
	ProviderClaude Provider = "claude"

	// ProviderCodex identifies Codex usage files.
	ProviderCodex Provider = "codex"

	// ProviderCopilot identifies GitHub Copilot CLI usage files.
	ProviderCopilot Provider = "copilot"

	// ProviderGemini identifies Gemini CLI usage files.
	ProviderGemini Provider = "gemini"

	// ProviderKimi identifies Kimi usage files.
	ProviderKimi Provider = "kimi"

	// ProviderQwen identifies Qwen usage files.
	ProviderQwen Provider = "qwen"

	// ProviderOpenClaw identifies OpenClaw usage files.
	ProviderOpenClaw Provider = "openclaw"

	// ProviderPi identifies pi-agent usage files.
	ProviderPi Provider = "pi"

	// ProviderAmp identifies Amp usage files.
	ProviderAmp Provider = "amp"

	// ProviderDroid identifies Droid usage files.
	ProviderDroid Provider = "droid"

	// ProviderKilo identifies Kilo usage files.
	ProviderKilo Provider = "kilo"

	// ProviderHermes identifies Hermes Agent usage files.
	ProviderHermes Provider = "hermes"

	// ProviderCodebuff identifies Codebuff usage files.
	ProviderCodebuff Provider = "codebuff"

	// ProviderOpenCode identifies OpenCode usage files.
	ProviderOpenCode Provider = "opencode"

	// ProviderGoose identifies Goose usage files.
	ProviderGoose Provider = "goose"

	// ProviderWorkbuddy identifies WorkBuddy usage files.
	ProviderWorkbuddy Provider = "workbuddy"
)

type SyncOptions

type SyncOptions struct {
	// ProviderDirs selects data directories by provider. This is the extension
	// point for new local AI agents.
	ProviderDirs map[Provider][]string
}

SyncOptions selects provider data directories for one sync run.