agenttty

package
v0.0.85 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 27, 2026 License: MIT Imports: 22 Imported by: 0

Documentation

Index

Constants

View Source 
const CodexSubmitSettle = 350 * time.Millisecond

CodexSubmitSettle is the pause between typing and a trailing Enter for codex-tty. Real Codex TUI often treats one-shot "text\r" as typing only.

View Source 
const EnvAgentRunnerConfigHome = "AGENT_RUNNER_CONFIG_HOME"

Variables

This section is empty.

Functions

func ApplyChildProcessEnv added in v0.0.57 

func ApplyChildProcessEnv(argv []string, runnerID, configHome string, prependPaths, envEntries []string) []string

ApplyChildProcessEnv prefixes argv with env(1) so the PTY child receives: - env entries (KEY=VALUE, later wins for the same KEY) - PATH with prependPaths joined ahead of the current PATH - GROK_HOME / CODEX_HOME from configHome

func AutoProvisionGrokConfigHome 

func AutoProvisionGrokConfigHome(runnerID, agentRunnerBinary, configHome string) (string, error)

AutoProvisionGrokConfigHome creates a temp grok home when using llm-mock-run-grok without an explicit config home so agent-run discovery matches the child process.

func BannerDetected added in v0.0.57 

func BannerDetected(scrollback []byte, provider string, markers []string) bool

BannerDetected reports whether legacy-style banner detection matches scrollback. It wraps bannerDetectedConfig for characterization and fake-TUI markers.

func BuildCodexCommandArgv 

func BuildCodexCommandArgv(env *exec.Env, settingsPath, agentRunnerBinary, model, resumeSession string) ([]string, error)

BuildCodexCommandArgv returns argv for the interactive Codex TUI inside the PTY.

func BuildCommandcodeCommandArgv added in v0.0.66 

func BuildCommandcodeCommandArgv(env *agentexec.Env, settingsPath, agentRunnerBinary, model, resumeSession string) ([]string, error)

func BuildGrokCommandArgv 

func BuildGrokCommandArgv(env *exec.Env, settingsPath, agentRunnerBinary, model, resumeSession string) ([]string, error)

BuildGrokCommandArgv returns argv for the interactive grok TUI inside the PTY.

func BuildStubCommandArgv 

func BuildStubCommandArgv(env *agentexec.Env, settingsPath, agentPath, model, resumeSession string) ([]string, error)

BuildStubCommandArgv returns argv for the stub TTY process inside the PTY.

func ClassifyGrokScreen added in v0.0.57 

func ClassifyGrokScreen(scrollback []byte) string

ClassifyGrokScreen returns a coarse frame class: empty | starting | busy | idle | modal | unknown.

func CodexHome 

func CodexHome() string

CodexHome returns the codex data directory.

func CodexHomeForRunner 

func CodexHomeForRunner(configHome string) string

CodexHomeForRunner returns the codex data directory for session discovery.

func DiscoverSession 

func DiscoverSession(ctx context.Context, grokHome, workspace, prompt string, runStart time.Time) (sessionID string, updatesPath string, err error)

DiscoverSession locates the grok on-disk session matching workspace cwd and prompt.

func ExtractAssistantTextFromSnapshot 

func ExtractAssistantTextFromSnapshot(runner string, scrollback []byte, prompt string) string

ExtractAssistantTextFromSnapshot extracts assistant response text from terminal scrollback.

func FindCodexResumeSessionID 

func FindCodexResumeSessionID(text string) string

FindCodexResumeSessionID extracts a codex resume session id from terminal text.

func FindUpdatesBySessionID added in v0.0.51 

func FindUpdatesBySessionID(grokHome, workspace, sessionID string) (string, bool)

FindUpdatesBySessionID locates updates.jsonl for an existing grok session id.

func GrokHome 

func GrokHome() string

GrokHome returns the grok data directory ($GROK_HOME or $HOME/.grok).

func GrokHomeForRunner 

func GrokHomeForRunner(configHome string) string

GrokHomeForRunner returns the grok data directory for session discovery.

func IDs 

func IDs() []string

IDs returns registered provider ids in registration order.

func InjectMessage added in v0.0.85 

func InjectMessage(listenAddr, sessionID, runner, text string, submit bool) error

InjectMessage writes text into a live TTY session. When submit is false, bytes are typed without trailing Enter. When submit is true:

  • codex-tty (real UI): type text, settle, bare \r (and \n for line discipline)
  • codex-tty (fake TUI via AGENT_RUN_CODEX_TTY_COMMAND): text+\n+\r for shell `read`
  • other runners: SendMessage with suffixCR=true (existing contract)

func IsBlockingUpdateMenu added in v0.0.54 

func IsBlockingUpdateMenu(text string) bool

IsBlockingUpdateMenu reports whether text is the Codex full-screen "Update available" menu modal (numbered Skip / Update now options). Residual banners that still say "Update available" without menu options return false.

Directory trust prompts also show "Press enter to continue" and must NOT match (they would otherwise block send as "codex update available").

func IsTTYRunner 

func IsTTYRunner(id string) bool

IsTTYRunner reports whether id is a registered TTY runner.

func LookupSession 

func LookupSession(home, terminalSessionID string) (*ttywatch.RegistryEntry, string, error)

LookupSession searches registered providers' registry dirs in registration order and returns the first reachable live entry. Stale unreachable entries are removed.

func OpenReady added in v0.0.57 

func OpenReady(scrollback []byte) bool

OpenReady reports whether grok-tty open lifecycle may proceed past banner wait. True for modern starting/busy/idle chrome or legacy banner markers; false for empty scrollback and the project-directory modal (even when legacy detection false-positives on the "grok build" substring).

func ParseShellWords 

func ParseShellWords(line string) ([]string, error)

ParseShellWords splits a shell-style command line into argv words.

func PrependCommandEnv 

func PrependCommandEnv(argv []string, runnerID, configHome string) []string

PrependCommandEnv prefixes argv with env(1) assignments for the PTY child process.

func ProviderRegistrySubdirs 

func ProviderRegistrySubdirs() []string

ProviderRegistrySubdirs returns registry subdir names for all registered providers.

func Register 

func Register(p Provider) error

Register adds a TTY runner provider. RegistryDir defaults to ID + "-registry".

func ResolveAgentRunnerConfigHome 

func ResolveAgentRunnerConfigHome(flagValue string) string

ResolveAgentRunnerConfigHome returns the flag value or AGENT_RUNNER_CONFIG_HOME env.

func RunHeadless 

func RunHeadless(ctx context.Context, opts RunOptions) (runnerSessionID, terminalSessionID string, err error)

RunHeadless starts a detached ttywatch serve session, injects the prompt, tails agent events, and waits for the child to exit unless KeepTerminalAlive is set. When Open is set, starts keep-alive, injects only if prompt non-empty, auto-attaches, and returns after attach without printing the session id (caller prints after). When Detach is set, starts keep-alive, optional inject for resume follow-up, and returns immediately without attach or event stream (caller prints both ids).

func RunStubTTYMain 

func RunStubTTYMain() error

RunStubTTYMain runs the test-only stub TTY alt-screen mock (invoked via __stub-tty).

func RunnerConfigHomeEnv 

func RunnerConfigHomeEnv(runnerID, configHome string) []string

RunnerConfigHomeEnv returns runner-specific env assignments for a PTY child.

func StripANSI 

func StripANSI(data []byte) string

StripANSI removes ANSI escape sequences from terminal scrollback.

func TailCodexTranscriptFromOffset 

func TailCodexTranscriptFromOffset(ctx context.Context, path string, startOffset int64, emit func(types.AgentEvent) error) error

TailCodexTranscriptFromOffset tails a codex transcript jsonl from offset.

func TailGrokSessionFromOffset added in v0.0.51 

func TailGrokSessionFromOffset(ctx context.Context, grokHome, workspace, grokSessionID string, startOffset int64, emit func(types.AgentEvent) error) error

TailGrokSessionFromOffset tails updates.jsonl for an existing grok session id.

func TailUpdatesFromOffset 

func TailUpdatesFromOffset(ctx context.Context, updatesPath string, startOffset int64, emit func(types.AgentEvent) error, onInitialSynced ...func()) error

TailUpdatesFromOffset tails updates.jsonl starting at the given byte offset. onInitialSynced, when non-nil, is invoked after the first batch of updates is emitted.

func UpdateMenuSelection added in v0.0.54 

func UpdateMenuSelection(text string) string

UpdateMenuSelection returns which menu option the › / U+203A marker is on: UPDATE_NOW, SKIP, SKIP_UNTIL_NEXT, or "" when no menu selection is visible.

func UpdatesTailOffset added in v0.0.51 

func UpdatesTailOffset(grokHome, workspace, grokSessionID string) int64

UpdatesTailOffset returns the current byte size of a grok session updates.jsonl.

func WriteTTYJSON 

func WriteTTYJSON(home string, snap TTYSnapshot) error

WriteTTYJSON dual-writes the denormalized TTY snapshot.

Types

type BuildArgvFunc 

type BuildArgvFunc func(env *agentexec.Env, settingsPath, agentPath, model, resumeSession string) ([]string, error)

BuildArgvFunc builds the argv for a TTY runner command inside the PTY.

type Provider 

type Provider struct {
	ID             string
	RegistryDir    string
	BannerProvider string
	BannerMarkers  []string
	DisableTail    bool

	BuildArgv          BuildArgvFunc
	StartEventTail     func(ctx TailContext) (runnerSessionID string, err error)
	DetectScreenStatus func(scrollback []byte) string
	CheckWritable      func(scrollback []byte) WritableStatus
}

Provider describes a pluggable TTY runner.

func Get 

func Get(id string) (Provider, bool)

Get returns a registered provider by id.

func ProviderListSorted 

func ProviderListSorted() []Provider

ProviderListSorted returns providers in registration order.

type RunOptions 

type RunOptions struct {
	Home            string
	Workspace       string
	Prompt          string
	Model           string
	ResumeSessionID string
	// Fork appends grok --fork-session after --resume (grok-tty only). Requires
	// non-empty ResumeSessionID. Creates a new Grok conversation branch.
	Fork bool
	// ForkSessionID optional Grok --session-id for the forked session (with Fork).
	ForkSessionID string
	RunnerID      string
	// SessionID is the terminal registry id. Empty → auto-reserve session-N.
	// When set (explicit --session or --session-id-from-prompt), storage and registry share it.
	SessionID             string
	AgentSessionID        string
	SettingsPath          string
	AgentPath             string
	AgentRunnerConfigHome string
	// PrependPaths are absolute dirs prepended to the PTY child PATH (ordered).
	PrependPaths []string
	// Env is ordered KEY=VALUE entries applied to the PTY child (last-win per key).
	Env []string
	// Driver is the host re-exec config for __serve_* children (see agentdriver).
	// Zero → DefaultSelf. Prefer over BinaryPath.
	Driver agentdriver.Driver
	// BinaryPath is deprecated: use Driver.Binary.
	BinaryPath        string
	KeepTerminalAlive bool
	// Open is run --open: silent start, optional inject, auto-attach, no pre-attach id print.
	Open bool
	// Detach is run/resume --detach: keep-alive daemon, no attach, no stream tail;
	// caller prints session-id/terminal-id on stdout after return.
	Detach bool
	// NoSubmit injects the prompt without trailing Enter (suffixCR=false). Used with Open.
	NoSubmit            bool
	GrokSyncOwnsEvents  bool
	Stderr              io.Writer
	Emit                func(types.AgentEvent) error
	OnTerminalSessionID func(string)
}

RunOptions configures a headless TTY runner invocation via detached serve.

type StubEvent 

type StubEvent struct {
	DelayMs int    `json:"delay_ms"`
	Type    string `json:"type"`
	Role    string `json:"role"`
	Text    string `json:"text"`
}

type StubFrame 

type StubFrame struct {
	DelayMs int    `json:"delay_ms"`
	Text    string `json:"text"`
}

type StubScenario 

type StubScenario struct {
	BannerDelayMs       int         `json:"banner_delay_ms"`
	BannerText          string      `json:"banner_text"`
	PromptLatencyMs     int         `json:"prompt_latency_ms"`
	ResponseText        string      `json:"response_text"`
	ScreenStatus        string      `json:"screen_status"`
	ScreenFrames        []StubFrame `json:"screen_frames"`
	LLMEvents           []StubEvent `json:"llm_events"`
	RunnerSessionID     string      `json:"runner_session_id"`
	TurnCompleteDelayMs int         `json:"turn_complete_delay_ms"`
	ExitAfterTurn       bool        `json:"exit_after_turn"`
	WritableReason      string      `json:"writable_reason"`
}

StubScenario configures the test-only stub TTY mock process.

type TTYSession 

type TTYSession struct {
	RunnerID          string
	AgentSessionID    string
	TerminalSessionID string
	Registry          ttywatch.RegistryEntry
	Meta              *agentstorage.SessionMeta
	TTY               *TTYSnapshot
	TCPReachable      bool
	ScreenStatus      string
}

TTYSession is the unified resolver result for status, attach, and send.

func ResolveByAgentSession 

func ResolveByAgentSession(store agentstorage.Store, runner, agentSessionID string) (*TTYSession, error)

ResolveByAgentSession resolves via meta.terminal_session_id then live registry.

func ResolveByTerminalID 

func ResolveByTerminalID(home, terminalSessionID string) (*TTYSession, error)

ResolveByTerminalID resolves a terminal-session-id across registered providers. Unlike LookupSession, stale entries are retained for status probes (TCPReachable=false).

func ResolveTerminalStatus added in v0.0.51 

func ResolveTerminalStatus(store agentstorage.Store, runner, agentSessionID string) (*TTYSession, error)

ResolveTerminalStatus resolves a live terminal for status probes. It avoids removing stale registry entries and scans the runner registry when meta.terminal_session_id has not been persisted yet for a running session.

type TTYSnapshot 

type TTYSnapshot struct {
	RunnerID          string `json:"runner_id"`
	AgentSessionID    string `json:"agent_session_id"`
	TerminalSessionID string `json:"terminal_session_id"`
	ListenAddr        string `json:"listen_addr"`
	PID               int    `json:"pid"`
	CreatedAt         string `json:"created_at"`
	ScreenStatus      string `json:"screen_status,omitempty"`
	Alive             bool   `json:"alive"`
}

TTYSnapshot is the denormalized TTY cross-ref written to sessions/.../tty.json.

type TailContext 

type TailContext struct {
	ScenarioPath string
	Emit         func(types.AgentEvent) error
}

TailContext carries dependencies for provider event tail hooks.

type WritableStatus 

type WritableStatus = ttywatch.WritableStatus

WritableStatus reports whether a TTY session is ready to receive injected input.

func WaitUntilWritable 

func WaitUntilWritable(provider Provider, listenAddr, sessionID string, timeout time.Duration) WritableStatus

WaitUntilWritable polls CheckWritable until ready or timeout.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.