Documentation
¶
Overview ¶
Package herdr is the binary's door to Herdr, the terminal multiplexer f10 opens task worktrees in. Every call goes through the herdr CLI as JSON, and the ids the next call needs are read from the answer rather than predicted.
Index ¶
- Constants
- Variables
- func AgentExists(ctx context.Context, dir, target string) (bool, error)
- func Available() error
- func CloseWorkspace(ctx context.Context, dir, id string) error
- func FocusWorkspace(ctx context.Context, dir, id string) error
- func IsCode(err error, code string) bool
- func PaneIdleShell(ctx context.Context, dir, pane string) (bool, error)
- func Prompt(ctx context.Context, dir, name, text string) error
- func Screen(ctx context.Context, dir, name string) (string, error)
- func SendKeys(ctx context.Context, dir, name string, keys ...string) error
- func StartAgent(ctx context.Context, dir, name, kind, pane string, args []string, ...) error
- type Backend
- func (Backend) Available() error
- func (b Backend) Close(ctx context.Context, id string) error
- func (b Backend) Focus(ctx context.Context, id string) error
- func (Backend) Name() string
- func (b Backend) Occupancy(ctx context.Context, ws agentctl.Opened) (agentctl.Occupancy, error)
- func (b Backend) Open(ctx context.Context, path, label string) (agentctl.Opened, []string, error)
- func (b Backend) Prompt(ctx context.Context, name, text string) error
- func (b Backend) Screen(ctx context.Context, name string) (string, error)
- func (b Backend) SendEnter(ctx context.Context, name string) error
- func (b Backend) StartAgent(ctx context.Context, ws agentctl.Opened, name, kind string, args []string, ...) error
- func (b Backend) Workspaces(ctx context.Context) ([]agentctl.Workspace, error)
- type Error
- type Listed
- type Pane
- type Workspace
Constants ¶
const ( CodePaneBusy = "agent_pane_busy" CodeAgentNotFound = "agent_not_found" )
The error codes this package acts on. Herdr answers agent_pane_busy while the pane runs anything but an idle shell, its rc files included.
Variables ¶
var ( StartDeadline = 5 * time.Second StartPoll = 200 * time.Millisecond StartReport = time.Second )
How long StartAgent waits for a pane whose shell is still starting, how often it asks, and the longest gap between two progress reports. Variables so tests need not wait.
var ErrNotInside = errors.New("f10 start, forward, drive and finish run inside a Herdr session: " +
"open a pane there, or install it from https://herdr.dev")
ErrNotInside is the one refusal: start, forward, drive and finish run inside a Herdr session and nowhere else, with no fallback by design.
Functions ¶
func AgentExists ¶ added in v0.27.0
AgentExists reports whether a live agent answers to target: its name, or the id of the pane hosting it.
func Available ¶
func Available() error
Available reports whether this process can reach Herdr: the session marks itself in the environment, and the CLI has to be on PATH.
func CloseWorkspace ¶
CloseWorkspace closes the workspace, its tabs and panes, and whatever agent ran in them.
func FocusWorkspace ¶
FocusWorkspace brings the workspace to the front.
func PaneIdleShell ¶ added in v0.27.0
PaneIdleShell reports whether pane sits at its shell's prompt: the shell owns the terminal's foreground process group. Anything the shell runs, an rc child or a program, owns a group of its own.
func Prompt ¶
Prompt submits text to the named agent and returns as soon as it is submitted. Never --wait: the caller may itself be an agent in Herdr.
func Screen ¶ added in v0.55.0
Screen is the named agent's visible screen, as text: `agent read` prints the terminal itself, not a JSON envelope.
func SendKeys ¶ added in v0.55.0
SendKeys presses keys in the named agent's terminal, by herdr's key names.
func StartAgent ¶
func StartAgent( ctx context.Context, dir, name, kind, pane string, args []string, waiting func(waited time.Duration), ) error
StartAgent launches an agent of kind in pane under name, args on its own command line. A pane still running its shell's rc files answers busy, so that refusal alone is retried until StartDeadline; waiting (when not nil) hears how long it has, on the first busy answer then within StartReport.
Types ¶
type Backend ¶ added in v0.46.0
type Backend struct {
Dir string
}
Backend is Herdr as an agentctl.Backend: a workspace's agent slot is its pane, and every call runs the herdr CLI from Dir.
func (Backend) Occupancy ¶ added in v0.46.0
Occupancy asks Herdr for an agent in the pane, by the pane's id since its name is unknown here, then whether the pane sits at an idle shell.
func (Backend) Open ¶ added in v0.46.0
Open adopts a workspace Herdr already shows on the checkout (one with an agent in a pane, else the first), since `worktree open` can answer with a second one; others are noted, not closed: their panes may be the user's.
func (Backend) StartAgent ¶ added in v0.46.0
type Error ¶ added in v0.27.0
An Error is herdr's own refusal: the error envelope it printed on stderr.
type Listed ¶
type Listed struct {
ID string
Label string
Path string
Focused bool
Agent string // herdr's agent_status: idle, working, done, unknown
}
A Listed is one workspace as `workspace list` reports it. Path is the checkout the workspace shows, or "" for a workspace with no worktree.
type Pane ¶ added in v0.27.0
A Pane is one pane of a workspace as `pane list` reports it. Agent is the kind of agent the pane hosts, or "" for none.
type Workspace ¶
type Workspace struct {
ID string
RootPane string
AlreadyOpen bool // Herdr was showing this checkout before the call
}
A Workspace is what opening a worktree yields: the ids the agent calls are addressed by.
func OpenWorktree ¶
OpenWorktree turns the checkout at path into a workspace labelled label, or returns the one already showing it. The main checkout goes as --cwd: without it Herdr takes the repo from the focused workspace and refuses when that one shows a linked worktree.
Source Files