clirun

package
v0.3.0 Latest Latest
Warning

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

Go to latest
Published: Oct 29, 2026 License: AGPL-3.0 Imports: 17 Imported by: 0

Documentation

Overview

Package clirun is what the harness adapters (codex, claudecode) share to drive a coding agent's CLI: running it in its own process group and killing the whole group when the run ends, splitting its stdout into lines for the stream parser, keeping a bounded transcript and stderr tail, and the text helpers their parsers need (rate-limit resets, versions, summaries).

Index

Constants

View Source
const (
	// MaxLine is one stdout line; the rest of a longer one is dropped.
	MaxLine = 16 << 20
	// MaxTranscript is the transcript kept in memory (the pipeline caps it gzipped).
	MaxTranscript = 64 << 20
	// MaxStderr is the tail of stderr kept.
	MaxStderr = 64 << 10
)

Bounds on what one harness process may produce.

View Source
const DefaultThrottle = 15 * time.Minute

DefaultThrottle is how long a rate-limited agent waits when the error gives no reset (harness-adapters.md: else +15 min).

View Source
const EffectorServer = "factory"

EffectorServer is the Effector's MCP server name in every harness's MCP config. Its command is the workspace's `factory` CLI (`factory-agent fx`) with EffectorArgs, i.e. `factory-agent fx mcp`, the same server as `factory-agent mcp` (effector.md).

View Source
const MaxThrottle = 8 * 24 * time.Hour

MaxThrottle bounds a parsed reset: a weekly plan limit is the longest.

Variables

This section is empty.

Functions

func Clip

func Clip(s string, n int) string

Clip cuts s to n bytes on a rune boundary.

func ContainsFold

func ContainsFold(s string, words []string) bool

ContainsFold reports whether s contains any of words, ignoring case (words are lower case).

func EffectorArgs

func EffectorArgs() []string

EffectorArgs are the arguments of the Effector's MCP server.

func EnvNames

func EnvNames(env []string) []string

EnvNames are the variable names in env, sorted and unique: what a harness passes through to the Effector by name, so no value (a token among them) is written to a config file.

func FactoryCLI

func FactoryCLI(ws harness.Workspace) string

FactoryCLI is the workspace's `factory` CLI: the Effector's MCP server and the hooks run it.

func FirstLine

func FirstLine(s string) string

FirstLine is s's first line, with " …" when more follows.

func LastLine

func LastLine(s string) string

LastLine is s's last non-empty line.

func ParseAt

func ParseAt(s string, now time.Time) (time.Time, bool)

ParseAt reads a reset time: RFC 3339, or a wall time in now's location with or without a date ("3:05 PM", "3pm", "Oct 21st, 2026 3:05 PM", "Oct 21 at 3pm"). A time of day alone is the next one; a date without a year the next one too.

func ReadLimited

func ReadLimited(p string, n int64) ([]byte, error)

ReadLimited reads at most n bytes of the file at p.

func RepairPrompt

func RepairPrompt(problems []string, ws harness.Workspace) string

RepairPrompt asks the harness, in the session it ran, for a corrected Result only.

func ResetPlausible

func ResetPlausible(t, now time.Time) bool

ResetPlausible reports whether a parsed reset can be used: after now and at most MaxThrottle ahead.

func ResetTime

func ResetTime(raw []byte, msg string, now time.Time, def time.Duration) time.Time

ResetTime is when a rate limit ends: a resets_in_seconds / resets_at field in the event (raw), a "try again in …" or "try again at …" in its text, else now + def. A reset in the past or beyond MaxThrottle is ignored.

func Unfence

func Unfence(b []byte) []byte

Unfence is b trimmed, without a Markdown code fence (and its language tag) around it; nil when nothing is left.

func WithEnv

func WithEnv(env []string, key, value string) []string

WithEnv is env with key set to value (any earlier value dropped).

Types

type Exit

type Exit struct {
	// Err is the wait error: nil when the harness exited 0, also when a command it left
	// running held its output open past KillGrace.
	Err error
	// Stderr is the last MaxStderr bytes of its stderr.
	Stderr string
}

Exit is how a Process ended.

func Run

func Run(ctx context.Context, p Process) (Exit, error)

Run runs p to its end. The harness leads its own process group: when ctx ends the whole group gets SIGTERM, the harness SIGKILL after KillGrace, and whatever is left of the group SIGKILL once the harness has exited (always, so commands it left running don't outlive the run). The error is only a failure to start; how the harness ended is in Exit.

type Process

type Process struct {
	Binary string
	Args   []string
	Dir    string
	Env    []string
	Stdin  io.Reader
	// KillGrace is how long the harness gets to exit after SIGTERM before it is SIGKILLed.
	KillGrace time.Duration
	// Line gets each stdout line, without its newline, in order, from one goroutine.
	Line func([]byte)
}

Process is one harness invocation.

type Transcript

type Transcript struct {
	// Name prefixes the truncation line's kind: the harness (codex, claude).
	Name string
	// contains filtered or unexported fields
}

Transcript collects a harness's stream lines (JSON Lines) and the adapter's own factory.* lines, up to MaxTranscript. Past that, lines are counted and dropped, and Bytes ends with a factory.<Name>-transcript-truncated line. Safe for concurrent use.

func (*Transcript) Add

func (t *Transcript) Add(line []byte)

Add appends one line.

func (*Transcript) Bytes

func (t *Transcript) Bytes() []byte

Bytes is the transcript so far.

func (*Transcript) Factory

func (t *Transcript) Factory(kind string, fields map[string]any)

Factory appends the adapter's own line: {"type": "factory.<kind>", fields…}.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL