Documentation
¶
Overview ¶
Package herdr is the binary's door to Herdr, the terminal multiplexer `f10 start` opens a task's worktree in, `f10 forward` reaches its agent through and `f10 finish` closes it from. 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 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) 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 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, with args on the agent's own command line. A pane whose shell is still running its rc files answers busy, so that one refusal is retried until StartDeadline; past it, herdr's error stands. While it waits, waiting (when not nil) hears how long it has waited: on the first busy answer, then within StartReport of the last. Once started, waiting for the agent to be ready for input is herdr's wait, not ours.
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 rather than opening another, since `worktree open` can answer with a second one beside it: the first with an agent in a pane wins, else the first. Any other is named in a note, never closed, since its panes may hold the user's own work.
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. dir is the main checkout, passed as --cwd: without it Herdr takes the repo from the focused workspace, and refuses when that one shows a linked worktree.
Source Files