Documentation
¶
Index ¶
- Variables
- func BridgeTerminalStream(stream net.Conn, p *ClaudeCodePTY)
- func CleanupSession(session *Session)
- func DefaultCredentialsPath() string
- func DefaultRegistryDir() string
- func DefaultRegistryPath() string
- func DefaultSessionsDir() string
- func EnsureValidToken(serverURL string) (string, error)
- func IsSessionActive(s *Session) bool
- func RegisterDefaultCard(serverURL, proxyToken, displayName string) error
- func RunClaudeCode(opts ClaudeCodeOptions)
- func RunConnect(opts ConnectOptions)
- func RunLogin(opts LoginOptions) error
- func RunTaskWorker(ctx context.Context, opts TaskWorkerOptions)
- func SaveCredentials(path string, creds *Credentials) error
- func SaveRegistry(path string, reg *Registry) error
- func SaveSession(session *Session) error
- type AgentInfoData
- type ClaudeCodeOptions
- type ClaudeCodePTY
- type Client
- type ConnectOptions
- type Credentials
- type DeviceAuthResponse
- type LockedRegistryFile
- type LoginOptions
- type OpencodeProcess
- type RegisterResponse
- type Registry
- type RegistryEntry
- type Session
- type TaskWorker
- type TaskWorkerOptions
- type TokenResponse
Constants ¶
This section is empty.
Variables ¶
var ErrNeedReLogin = errors.New("all tokens expired, please run 'agentserver login' again")
ErrNeedReLogin indicates all tokens have expired and interactive re-auth is needed.
var Version = "dev"
Version is set at build time via -ldflags.
Functions ¶
func BridgeTerminalStream ¶ added in v0.27.0
func BridgeTerminalStream(stream net.Conn, p *ClaudeCodePTY)
BridgeTerminalStream bridges a yamux terminal stream to a PTY.
Protocol on the stream:
- Prefix 0x00 + data: terminal I/O bytes
- Prefix 0x01 + JSON: control commands (resize, etc.)
func CleanupSession ¶ added in v0.35.0
func CleanupSession(session *Session)
CleanupSession clears the PID from the session file.
func DefaultCredentialsPath ¶ added in v0.33.0
func DefaultCredentialsPath() string
DefaultCredentialsPath returns ~/.agentserver/.credentials.json.
func DefaultRegistryDir ¶ added in v0.20.0
func DefaultRegistryDir() string
DefaultRegistryDir returns the default directory for agentserver config.
func DefaultRegistryPath ¶ added in v0.20.0
func DefaultRegistryPath() string
DefaultRegistryPath returns the default path for the registry file.
func DefaultSessionsDir ¶ added in v0.35.0
func DefaultSessionsDir() string
DefaultSessionsDir returns ~/.agentserver/sessions.
func EnsureValidToken ¶ added in v0.35.0
EnsureValidToken checks for a valid OAuth access token, refreshing if needed. Returns the access token or ErrNeedReLogin if interactive auth is required.
func IsSessionActive ¶ added in v0.35.0
IsSessionActive checks if a session's process is still running.
func RegisterDefaultCard ¶ added in v0.30.1
RegisterDefaultCard registers a default agent card for a claudecode agent.
func RunClaudeCode ¶ added in v0.27.0
func RunClaudeCode(opts ClaudeCodeOptions)
RunClaudeCode executes the Claude Code agent connect workflow. Each invocation registers a new sandbox (or resumes an existing one), then establishes a tunnel and bridges terminal streams to a local Claude Code PTY.
func RunConnect ¶ added in v0.6.1
func RunConnect(opts ConnectOptions)
RunConnect executes the agent connect workflow. Each invocation registers a new sandbox (or resumes an existing one).
func RunLogin ¶ added in v0.33.0
func RunLogin(opts LoginOptions) error
RunLogin executes the OAuth Device Flow login and agent registration.
func RunTaskWorker ¶ added in v0.30.0
func RunTaskWorker(ctx context.Context, opts TaskWorkerOptions)
RunTaskWorker starts the task worker that polls for tasks. Blocks until ctx is cancelled.
func SaveCredentials ¶ added in v0.33.0
func SaveCredentials(path string, creds *Credentials) error
SaveCredentials writes credentials to disk with 0600 permissions.
func SaveRegistry ¶ added in v0.20.0
SaveRegistry writes the registry to disk.
func SaveSession ¶ added in v0.35.0
SaveSession writes a session file and records the current PID.
Types ¶
type AgentInfoData ¶ added in v0.16.0
type AgentInfoData struct {
Hostname string `json:"hostname"`
OS string `json:"os"`
Platform string `json:"platform"`
PlatformVersion string `json:"platform_version"`
KernelArch string `json:"kernel_arch"`
CPUModelName string `json:"cpu_model_name"`
CPUCountLogical int `json:"cpu_count_logical"`
MemoryTotal uint64 `json:"memory_total"`
DiskTotal uint64 `json:"disk_total"`
DiskFree uint64 `json:"disk_free"`
AgentVersion string `json:"agent_version"`
OpencodeVersion string `json:"opencode_version"`
Workdir string `json:"workdir"`
HostInfo *host.InfoStat `json:"host_info,omitempty"`
CPUInfo *cpuInfoDetail `json:"cpu_info,omitempty"`
MemoryInfo *mem.VirtualMemoryStat `json:"memory_info,omitempty"`
DiskInfo *disk.UsageStat `json:"disk_info,omitempty"`
}
AgentInfoData is the system info payload sent from agent to server.
type ClaudeCodeOptions ¶ added in v0.27.0
type ClaudeCodeOptions struct {
Server string
Name string
SkipOpenBrowser bool
ClaudeBin string
WorkDir string
Resume string // sandbox ID to resume
Continue bool // resume most recent session
}
ClaudeCodeOptions holds all flags for the claudecode command.
type ClaudeCodePTY ¶ added in v0.27.0
type ClaudeCodePTY struct {
// contains filtered or unexported fields
}
ClaudeCodePTY manages a Claude Code process running inside a pseudo-terminal.
func NewClaudeCodePTY ¶ added in v0.27.0
func NewClaudeCodePTY(claudeBin, workDir string, cols, rows uint16) (*ClaudeCodePTY, error)
NewClaudeCodePTY starts a Claude Code process in a PTY.
func (*ClaudeCodePTY) Close ¶ added in v0.27.0
func (p *ClaudeCodePTY) Close() error
Close terminates the process and closes the PTY.
func (*ClaudeCodePTY) IsAlive ¶ added in v0.27.0
func (p *ClaudeCodePTY) IsAlive() bool
IsAlive reports whether the underlying process is still running.
func (*ClaudeCodePTY) Resize ¶ added in v0.27.0
func (p *ClaudeCodePTY) Resize(cols, rows uint16) error
Resize changes the PTY window size.
type Client ¶
type Client struct {
ServerURL string
SandboxID string
TunnelToken string
OpencodeURL string // local HTTP service URL (e.g. http://localhost:4096)
OpencodeToken string // optional Basic Auth password for opencode
Workdir string
BackendType string // "opencode" or "claudecode"
// OnTerminalStream is called when the server opens a terminal stream.
// Implementations should bridge the stream to a PTY.
// If nil, terminal streams are rejected.
OnTerminalStream func(stream net.Conn)
// contains filtered or unexported fields
}
Client is the cli-agent tunnel client that connects to the server and forwards HTTP/terminal requests to a local service.
type ConnectOptions ¶ added in v0.6.1
type ConnectOptions struct {
Server string
Name string
SkipOpenBrowser bool
Resume string // sandbox ID to resume
Continue bool // resume most recent session
OpencodeURL string
OpencodeURLSet bool // true if --opencode-url was explicitly provided
OpencodeToken string
AutoStart bool
OpencodeBin string
OpencodePort int // 0 = auto-assign
OpencodePortSet bool // true if --opencode-port was explicitly provided
}
ConnectOptions holds all flags for the connect command.
type Credentials ¶ added in v0.33.0
type Credentials struct {
ServerURL string `json:"serverUrl,omitempty"`
AccessToken string `json:"accessToken"`
RefreshToken string `json:"refreshToken"`
ExpiresAt time.Time `json:"expiresAt"`
Scopes []string `json:"scopes,omitempty"`
}
Credentials holds OAuth tokens for the authenticated user.
func LoadCredentials ¶ added in v0.33.0
func LoadCredentials(path string) (*Credentials, error)
LoadCredentials reads credentials from disk. Returns nil if the file does not exist.
type DeviceAuthResponse ¶ added in v0.33.0
type DeviceAuthResponse struct {
DeviceCode string `json:"device_code"`
UserCode string `json:"user_code"`
VerificationURI string `json:"verification_uri"`
VerificationURIComplete string `json:"verification_uri_complete"`
ExpiresIn int `json:"expires_in"`
Interval int `json:"interval"`
}
DeviceAuthResponse is the response from Hydra's device authorization endpoint.
type LockedRegistryFile ¶ added in v0.20.0
type LockedRegistryFile struct {
Path string
Reg *Registry
// contains filtered or unexported fields
}
LockedRegistryFile holds an exclusive lock on the registry for safe read-modify-write operations. Call Close() when done.
func LockRegistry ¶ added in v0.20.0
func LockRegistry(path string) (*LockedRegistryFile, error)
LockRegistry acquires an exclusive file lock and loads the registry. The caller must call Close() when done to release the lock and optionally save changes via Save() before Close().
func (*LockedRegistryFile) Close ¶ added in v0.20.0
func (l *LockedRegistryFile) Close()
Close releases the file lock.
func (*LockedRegistryFile) Save ¶ added in v0.20.0
func (l *LockedRegistryFile) Save() error
Save writes the registry to disk while the lock is held.
type LoginOptions ¶ added in v0.33.0
LoginOptions holds flags for the login command.
type OpencodeProcess ¶
type OpencodeProcess struct {
Port int
// contains filtered or unexported fields
}
OpencodeProcess manages a local opencode serve subprocess.
func StartOpencode ¶
func StartOpencode(bin string, port int, password string) (*OpencodeProcess, error)
StartOpencode starts "opencode serve --hostname 127.0.0.1 --port {port}" as a child process. It returns immediately after starting the process.
func (*OpencodeProcess) Stop ¶
func (p *OpencodeProcess) Stop()
Stop sends SIGTERM to the child process, waits briefly, then sends SIGKILL if needed.
func (*OpencodeProcess) WaitReady ¶
WaitReady polls http://localhost:{port}/ every 500ms until a response is received or the timeout expires.
type RegisterResponse ¶ added in v0.33.0
type RegisterResponse struct {
SandboxID string `json:"sandbox_id"`
TunnelToken string `json:"tunnel_token"`
ProxyToken string `json:"proxy_token"`
WorkspaceID string `json:"workspace_id"`
ShortID string `json:"short_id"`
}
RegisterResponse is the response from the agent registration endpoint.
type Registry ¶ added in v0.20.0
type Registry struct {
Entries []*RegistryEntry `json:"entries"`
}
Registry holds all agent registrations on this machine.
func LoadRegistry ¶ added in v0.20.0
LoadRegistry reads the registry from disk. Returns an empty registry if the file does not exist.
func (*Registry) Find ¶ added in v0.20.0
func (r *Registry) Find(dir, workspaceID string) *RegistryEntry
Find returns the entry matching (dir, workspaceID), or nil if not found.
func (*Registry) FindByDir ¶ added in v0.20.0
func (r *Registry) FindByDir(dir string) []*RegistryEntry
FindByDir returns all entries for the given directory.
func (*Registry) NextPort ¶ added in v0.20.0
NextPort returns the lowest available port starting from basePort. It finds the first gap in the used port range to reuse freed ports.
func (*Registry) Put ¶ added in v0.20.0
func (r *Registry) Put(entry *RegistryEntry)
Put adds or replaces an entry keyed by (Dir, WorkspaceID).
type RegistryEntry ¶ added in v0.20.0
type RegistryEntry struct {
Dir string `json:"dir"`
Server string `json:"server"`
SandboxID string `json:"sandbox_id"`
TunnelToken string `json:"tunnel_token"`
WorkspaceID string `json:"workspace_id"`
Name string `json:"name"`
Type string `json:"type,omitempty"` // "opencode" or "claudecode"
OpencodePort int `json:"opencode_port,omitempty"`
}
RegistryEntry represents a single agent registration keyed by (Dir, WorkspaceID).
type Session ¶ added in v0.35.0
type Session struct {
SandboxID string `json:"sandboxId"`
TunnelToken string `json:"tunnelToken"`
ProxyToken string `json:"proxyToken"`
WorkspaceID string `json:"workspaceId"`
Name string `json:"name"`
Type string `json:"type"` // "opencode" or "claudecode"
ServerURL string `json:"serverUrl"`
Dir string `json:"dir"`
CreatedAt time.Time `json:"createdAt"`
PID int `json:"pid,omitempty"`
}
Session represents a sandbox session created by a single agent process. Stored in ~/.agentserver/sessions/{sandbox-id}.json.
func FindLatestSession ¶ added in v0.35.0
FindLatestSession finds the most recent inactive session for the given directory and type. If dir is empty, matches any directory. If sessionType is empty, matches any type.
func ListSessions ¶ added in v0.35.0
ListSessions reads all session files.
func LoadSession ¶ added in v0.35.0
LoadSession reads a session by sandbox ID.
type TaskWorker ¶ added in v0.30.0
type TaskWorker struct {
// contains filtered or unexported fields
}
TaskWorker receives and executes delegated tasks using the Go Agent SDK.
func NewTaskWorker ¶ added in v0.30.0
func NewTaskWorker(opts TaskWorkerOptions) *TaskWorker
func (*TaskWorker) ExecuteTask ¶ added in v0.30.0
func (w *TaskWorker) ExecuteTask(ctx context.Context, taskID, sessionID, prompt, systemContext string, maxTurns int, maxBudgetUSD float64) error
ExecuteTask runs a single task: connects bridge, executes via Agent SDK.
type TaskWorkerOptions ¶ added in v0.30.0
type TaskWorkerOptions struct {
ServerURL string // agentserver base URL (e.g. https://agentserver.example.com)
ProxyToken string // sandbox proxy_token for auth
SandboxID string // this agent's sandbox ID
Workdir string // working directory for claude CLI
CLIPath string // path to claude binary (default: "claude")
}
TaskWorkerOptions configures the task worker.
type TokenResponse ¶ added in v0.33.0
type TokenResponse struct {
AccessToken string `json:"access_token"`
RefreshToken string `json:"refresh_token"`
TokenType string `json:"token_type"`
ExpiresIn int `json:"expires_in"`
Scope string `json:"scope"`
}
TokenResponse is the response from the token endpoint.