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 AgentName(id, suffix, path string) string
- func Available() error
- func BareAgentName(id, suffix string) string
- 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 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 AgentName ¶ added in v0.38.0
AgentName names a task's agent. Herdr's live agent names share one namespace across every project, capped at 32 characters, so the bare name is cut to leave room for a short hash of the worktree path: the same id in two checkouts never collides.
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 BareAgentName ¶ added in v0.38.0
BareAgentName is the id lowercased, with the suffix so two attempts on one task can both run: the whole name of an agent started before names carried the path hash.
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 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