control

type Handler interface {
	// List reports every session, or only those of group when it is non-empty.
	List(group string) []SessionInfo
	Read(idOrName string, tail int) (string, error)
	New(spec NewSpec) (id string, err error)
	Send(idOrName, text string) error
	Kill(idOrName string) error
	Rename(idOrName, name string) error
	// SetGroup moves a session into group, or out of every group when it is
	// empty.
	SetGroup(idOrName, group string) error
	// GroupSend and GroupKill act on every session of a group and report how
	// many that was. An empty group, or one with no sessions, is an error:
	// silently doing nothing is the worst possible answer to "kill this
	// group", since the caller cannot tell it from success.
	GroupSend(group, text string) (int, error)
	GroupKill(group string) (int, error)
	// Wait blocks until idOrName — or, when idOrName is empty and group is
	// not, the first session of group — reaches state, and reports that
	// session. timeout is already resolved (see resolveWaitTimeout): always
	// positive by the time an implementation sees it.
	//
	// Returns an error, never blocking past timeout, when: neither idOrName
	// nor group is given, the session or group is unknown, state does not
	// parse, the timeout elapses first, or the targeted session (or, in group
	// mode, every member of the group) exits without ever reaching state.
	Wait(idOrName, group, state string, timeout time.Duration) (SessionInfo, error)
}

type NewSpec struct {
	Name    string
	Cwd     string
	Command string
	Group   string
}

type Request struct {
	Verb string `json:"verb"`
	// ID names the session a verb applies to, by manager id ("session-3", the
	// value of $LAZYSHELL_SESSION_ID) or by exact display name. Unused by
	// VerbList and VerbNew. For VerbWait, ID names the single session to wait
	// on; leave it empty and set Group instead to wait on a group's first
	// match.
	ID string `json:"id,omitempty"`
	// Name is the session name to give (VerbNew) or to change to (VerbRename).
	Name string `json:"name,omitempty"`
	// Group is the group to put a session in (VerbNew, VerbGroup — empty means
	// ungrouped), the group to act on (VerbGroupSend, VerbGroupKill), an
	// optional filter (VerbList), or the group to wait on (VerbWait, in place
	// of ID — see ID's doc comment). Empty on VerbList means "every session",
	// which is why the group verbs reject an empty Group themselves rather
	// than relying on this field alone to say what they mean.
	Group string `json:"group,omitempty"`
	// Cwd is the working directory a new session starts in. Empty means
	// lazyshell's own.
	Cwd string `json:"cwd,omitempty"`
	// Command is typed into the new session's shell, not exec'd in place of it
	// — the same semantics as session.Options.Command and tmux's send-keys, so
	// the shell survives the command.
	Command string `json:"command,omitempty"`
	// Text is what VerbSend writes into the session, verbatim. A trailing "\r"
	// is the caller's to add: pressing Enter is an explicit act.
	Text string `json:"text,omitempty"`
	// Tail limits VerbRead to the last N lines. Zero means the whole
	// scrollback.
	Tail int `json:"tail,omitempty"`
	// State is the agent state VerbWait blocks for: one of the four spellings
	// agent.ParseState accepts ("idle"/"working"/"blocked"/"done"). Parsed by
	// the Handler implementation, not here — this package stays free of an
	// agent import, per its own doc comment. Unused by every other verb.
	State string `json:"state,omitempty"`
	// Timeout bounds VerbWait, in seconds. Zero or negative means
	// DefaultWaitTimeout. Unused by every other verb.
	Timeout int `json:"timeout,omitempty"`
}

type Response struct {
	OK    bool   `json:"ok"`
	Error string `json:"error,omitempty"`
	// ID is the id of the session VerbNew created.
	ID string `json:"id,omitempty"`
	// Output is VerbRead's text.
	Output string `json:"output,omitempty"`
	// Sessions is VerbList's answer — every matching session — or VerbWait's,
	// a single-element slice holding the session that matched.
	Sessions []SessionInfo `json:"sessions,omitempty"`
	// Count is how many sessions a group verb acted on. Only meaningful for
	// VerbGroupSend and VerbGroupKill; omitempty drops it everywhere else, and
	// a group verb that matched nothing errors rather than reporting 0, so the
	// ambiguity a plain int would carry here never arises.
	Count int `json:"count,omitempty"`
}

type Server struct {
	// contains filtered or unexported fields
}

type SessionInfo struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	// Status is the process's state, "running" or "exited".
	Status string `json:"status"`
	// AgentState is the detected AI agent state ("idle"/"working"/"blocked"/
	// "done"), empty for a session running no known agent.
	AgentState string `json:"agent_state,omitempty"`
	// Group is the session's group, absent for an ungrouped one.
	Group string `json:"group,omitempty"`
	Cwd   string `json:"cwd,omitempty"`
	// ExitCode is meaningful only once Status is "exited", hence the pointer:
	// nil is "still running, ask again later", and it is the only shape that
	// works here. A plain int with omitempty drops the field for exit code
	// *zero* — the successful case — so a script could not tell a build that
	// passed from one still going, which is the single most likely thing to
	// ask this API. A plain int without omitempty is no better: it reports a
	// confident 0 for every running session.
	ExitCode *int `json:"exit_code,omitempty"`
}