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), start time.Time) *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) 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 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)
)