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. If dir is empty, matches any directory.
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.