agentruncli

package
v0.0.135 Latest Latest
Warning

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

 Go to latest Published: Aug 18, 2026 License: MIT Imports: 44 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AppendEventBusFlags added in v0.0.112 

func AppendEventBusFlags(args []string, url, token string) []string

AppendEventBusFlags appends --event-bus-url / --event-bus-token to args when URL is non-empty. Empty URL returns a copy of args unchanged (no flags added). Token is appended only when non-empty.

func ClearProcessHostDriver added in v0.0.72 

func ClearProcessHostDriver()

ClearProcessHostDriver clears the process default (tests).

func Handle 

func Handle(args []string) error

Handle is the full agent-run CLI entrypoint for args after the program name (os.Args[1:]). Same command surface as today's cmd/agent-run: web, run, resume, attach, send, msg, snapshot, watch, sessions, status, kill, tty, pty, top-level help, --agent-runner, and internal serve/stub paths. Success (including help) returns nil; failures return an error for the thin main to print and exit 1.

func IdlePolicyPath added in v0.0.135 

func IdlePolicyPath(home, sessionID string) string

IdlePolicyPath is $home/sessions/<sessionID>/idle-policy.json.

func NotifyOnOpenPath added in v0.0.112 

func NotifyOnOpenPath(kind string, opts EventBusOpts, sessionID, runner, workspace string)

NotifyOnOpenPath dispatches open-path publish policy:

  • "new-terminal" — after successful ForceNew / open-profile → NotifyTTYStarted once
  • "send" — live send path → no-op here (library OnTTYRestarted handles follow-up)

func NotifyTTYRestarted added in v0.0.113 

func NotifyTTYRestarted(opts EventBusOpts, sessionID, runner, workspace, reason string)

NotifyTTYRestarted publishes type=agent.tty.restarted source=agent-run with payload {session_id, runner, workspace, reason}. reason should be followup|resume. No AlreadyNotified guard — each restart may re-open local attach.

func NotifyTTYStarted added in v0.0.112 

func NotifyTTYStarted(opts EventBusOpts, sessionID, runner, workspace string)

NotifyTTYStarted publishes type=agent.tty.started source=agent-run with payload {session_id, runner, workspace, reason}. reason defaults to "new". Best-effort: empty URL is a no-op; publish errors write a "warning:" line. When AlreadyNotified is non-nil and *true, skips; after a non-empty-URL publish attempt, sets *true (empty URL does not set).

func NotifyTTYStartedReason added in v0.0.113 

func NotifyTTYStartedReason(opts EventBusOpts, sessionID, runner, workspace, reason string)

NotifyTTYStartedReason is NotifyTTYStarted with an explicit reason field.

func ParseRunIdle added in v0.0.135 

func ParseRunIdle(exitOnIdle bool, timeoutRaw string) (enabled bool, d time.Duration, err error)

ParseRunIdle interprets launch-time idle flags after the CLI reads --exit-on-idle and the raw --idle-timeout string (empty = omitted). Invalid raw → error before NormalizeIdle. !exitOnIdle → enabled=false, no error even if timeout parses (including 2s). Does not start a TTY.

func ResolveRunPrompt added in v0.0.122 

func ResolveRunPrompt(positionalPrompt, promptFile string) (string, error)

ResolveRunPrompt resolves agent-run run's initial prompt from a positional string and optional --prompt-file path. Exported for L2 pure doctests; runHeadless uses the same policy after flag parse.

Policy:

  • if promptFile non-empty (TrimSpace) and positional non-empty (TrimSpace) → error (mutually exclusive)
  • if promptFile non-empty → read file UTF-8 body, TrimSpace, return
  • else return TrimSpace(positional)
  • missing/unreadable path → non-nil error

func RunFocus added in v0.0.89 

func RunFocus(args []string, stdout, stderr io.Writer) error

RunFocus implements `agent-run focus` with injectable writers for L2 tests. CLI surface: focus <session-id> [--index N] [--dry-run] [--session-id ID] [-h]

func RunHelpText added in v0.0.112 

func RunHelpText() string

RunHelpText returns the `agent-run run -h` help body (same text flags.Help uses). Always ends with a trailing newline.

func SampleIsIdle added in v0.0.135 

func SampleIsIdle(s IdleSample) bool

SampleIsIdle is true only when sendable, screen idle, box empty, and queue empty.

func SetProcessHostDriver added in v0.0.72 

func SetProcessHostDriver(d agentdriver.Driver)

SetProcessHostDriver sets the default host Driver for this process when Opts leave Driver zero. Used by embedding hosts (spl agent-run); bare agent-run leaves this unset so serve falls back to agentdriver.DefaultSelf.

func WireOnTTYRestarted added in v0.0.113 

func WireOnTTYRestarted(opts EventBusOpts) func(agentrunapi.TTYStartedInfo)

WireOnTTYRestarted returns a callback for agentrunapi.Opts.OnTTYRestarted. Empty URL → nil. Does not share AlreadyNotified with started.

func WireOnTTYStarted added in v0.0.113 

func WireOnTTYStarted(opts EventBusOpts) func(agentrunapi.TTYStartedInfo)

WireOnTTYStarted returns a callback for agentrunapi.Opts.OnTTYStarted. Empty URL → nil. Uses info.Reason when set, else "new".

func WriteIdlePolicy added in v0.0.135 

func WriteIdlePolicy(home, sessionID string, p IdlePolicy) error

WriteIdlePolicy writes compact JSON. Zero timeout + ExitOnIdle → 10m.

Types

type EventBusOpts added in v0.0.112 

type EventBusOpts struct {
	URL   string
	Token string
	// PublishHook, when set, replaces the production HTTP publisher (tests).
	// Signature matches wire type/source + payload only (no eventbus import in harness).
	PublishHook func(ctx context.Context, eventType, source string, payload json.RawMessage) error
	// WarnWriter receives best-effort failure lines (prefix "warning:"). Nil → os.Stderr.
	WarnWriter io.Writer
	// AlreadyNotified, when non-nil, is an at-most-once guard for agent.tty.started only
	// (ForceNew NotifyOnOpenPath + library WireOnTTYStarted). Never used for restarted.
	// If *true, NotifyTTYStarted skips. After publishing with a non-empty URL, sets *true.
	// Empty URL does not set the flag.
	AlreadyNotified *bool
}

EventBusOpts configures best-effort publish of agent.tty.* events. Empty URL disables publish (no HTTP, no warning). PublishHook is the L2 inject seam; when nil, production uses eventbus.NewPublisher.

type FrontendSource added in v0.0.71 

type FrontendSource string

FrontendSource names where the SPA tree came from. 

const (
	FrontendSourceEmbed    FrontendSource = "embed"
	FrontendSourceCache    FrontendSource = "cache"
	FrontendSourceDownload FrontendSource = "download"
	FrontendSourceA1       FrontendSource = "a1"
)

type IdlePolicy added in v0.0.135 

type IdlePolicy = agentstorage.IdlePolicy

IdlePolicy is the session-dir idle-exit file (not meta.json).

func ReadIdlePolicy added in v0.0.135 

func ReadIdlePolicy(home, sessionID string) (p IdlePolicy, found bool, err error)

ReadIdlePolicy loads idle-policy.json. Missing file → found=false, err=nil.

type IdleSample added in v0.0.135 

type IdleSample struct {
	Sendable bool
	Screen   string // idle|busy|starting|modal|unknown
	InputBox string // empty|occupied|unknown
	QueueLen int
}

IdleSample is one watchdog observation of TTY + queue idleness.

type IdleWatchdog added in v0.0.135 

type IdleWatchdog struct {
	Timeout  time.Duration
	Grace    time.Duration // 0 → 5s
	Now      func() time.Time
	Sample   func() IdleSample
	SoftExit func()
	Shutdown func()
	// contains filtered or unexported fields
}

IdleWatchdog is the injectable keep-alive idle-exit state machine.

func NewIdleWatchdog added in v0.0.135 

func NewIdleWatchdog(found bool, p IdlePolicy, cfg IdleWatchdog) *IdleWatchdog

NewIdleWatchdog copies cfg. Tick is a no-op when !found or !p.ExitOnIdle. Timeout comes from p.IdleTimeout when cfg.Timeout == 0.

func (*IdleWatchdog) Tick added in v0.0.135 

func (w *IdleWatchdog) Tick()

Tick advances the idle clock one sample. SoftExit fires once at timeout; Shutdown fires once after grace. Non-idle clears idleSince only.

type ResolvedFrontend added in v0.0.71 

type ResolvedFrontend struct {
	FS       fs.FS
	Source   FrontendSource
	CacheDir string
	// EnsureErr is set when download was attempted and failed (A1 fallback).
	EnsureErr error
}

ResolvedFrontend is the result of resolveAgentRunFrontend. When Source is FrontendSourceA1, FS is nil and callers should serve the A1 shell.

type TakeoverDeps added in v0.0.112 

type TakeoverDeps struct {
	ListProcs func() []procresolve.Proc
	Lsof      func(pid int) []string
	Kill      func(pid int, sig syscall.Signal) error
	WaitDead  func(pid int, timeout time.Duration) bool
	OpenIterm func(dir string, followUp string) error
	// HooksActive is true when AGENT_RUN_TAKEOVER_TEST_HOOKS was loaded (synthetic PIDs).
	HooksActive bool
	// ProcsSnapshot is the full ListProcs result used for ancestry walks.
	ProcsSnapshot []procresolve.Proc
	// KillLog path from hooks file (may be empty).
	KillLog string
}

TakeoverDeps injects process/kill/iTerm behavior for tests. When nil fields are present, production defaults are used unless hooks env is set.

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.