harness

type ActivityTracker ¶

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

ActivityTracker classifies a wrapped harness as working or idle from PTY byte causality alone — no screen parsing. Output observed while no recent user input is in flight marks the harness working for outputActivityWindow; quiescence past the window reads as idle. Callers pass `now` explicitly so tests never sleep.

Not safe for concurrent use; the wrapper serializes observations onto its detection goroutine.

func NewActivityTracker(start time.Time) *ActivityTracker

func (t *ActivityTracker) ObserveInput(now time.Time)

func (t *ActivityTracker) ObserveOutput(now time.Time)

func (t *ActivityTracker) State(now time.Time) State

type Detection ¶

type Detection struct {
	Harness  string // canonical harness name, "" when none
	ChildPID int    // foreground pid when a harness is identified
	State    State  // StateUnknown when Harness is ""
}

Detection is the point-in-time snapshot the heartbeat loop stamps into payloads. Zero value means "no harness in the foreground".

type Detector ¶

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

Detector owns harness detection for one wrapped PTY: it polls the foreground process via the injected inspector and folds byte observations into an ActivityTracker. Inspect is the platform seam — TIOCGPGRP + process lookup in production, a fake in tests.

Inspect errors retain the previous identification (a transient ps failure must not flap `ppz who`); a successful inspect of a non-harness clears it. A harness change resets the activity tracker so each identification gets its own startup grace.

Safe for concurrent use: the wrapper calls Observe* from its PTY I/O goroutines, Poll from the detection ticker, and Snapshot from the heartbeat loop.

func NewDetector(inspect func() (ForegroundProc, error)) *Detector

func (d *Detector) ObserveInput(now time.Time)

func (d *Detector) ObserveOutput(now time.Time)

func (d *Detector) Poll(now time.Time)

func (d *Detector) SetScreen(src func() string)

func (d *Detector) Snapshot(now time.Time) Detection

type ForegroundProc ¶

type ForegroundProc struct {
	PID  int
	Comm string
	Argv []string
}

ForegroundProc is what the platform inspector reports about the PTY's foreground process group: the group leader's pid, its comm (binary name), and full argv (argv[0] included).

type ScreenDetector ¶ added in v0.48.0

type ScreenDetector interface {
	// Blocked reports whether the visible screen content (the bottom
	// lines of the live screen model) shows the harness waiting on
	// human input.
	Blocked(content string) bool
}

ScreenDetector is the phase-3 extension point: a per-harness matcher over the visible terminal screen that recognizes "waiting on human input" (permission dialogs, forms, choice prompts). It is consulted only when byte causality already says the harness is not working — PTY activity remains the authority for working, the screen only arbitrates idle vs blocked (same division of authority as herdr).

func ScreenDetectorFor(name string) ScreenDetector

type Spec ¶

type Spec struct {
	Name        string
	BinaryNames []string
}

Spec describes one known harness. Extending detection to a new harness is one new row here. Names are the canonical ids `ppz agent --harness` already uses, so heartbeat consumers see one vocabulary regardless of whether the value came from env or detection.

func Specs() []Spec

type State ¶

type State string

State of a wrapped agent harness, as stamped into heartbeat payloads.

const (
	StateUnknown State = ""        // no harness identified in the PTY foreground
	StateIdle    State = "idle"    // harness at rest, prompt waiting
	StateWorking State = "working" // harness actively producing output
	StateBlocked State = "blocked" // harness waiting on human input (phase 3)
)