harness

package
v0.14.4-dev.25 Latest Latest
Warning

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

Go to latest
Published: Nov 21, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source
const LimitStateAvailable = "available"

LimitStateAvailable means the harness reported at least one usage window.

View Source
const LimitStateError = "error"

LimitStateError means the probe ran but could not produce usage windows.

View Source
const LimitStateUnsupported = "unsupported"

LimitStateUnsupported means no usage probe exists for this harness on this node.

View Source
const NoAttributionBody = `# Attribution policy

Do not add any AI-attribution lines to git commits, pull requests, or other artifacts you author.
Specifically, do not include:

- ` + "`Co-Authored-By: <model> <noreply@...>`" + ` trailers.
- ` + "`Generated with [agent name]`" + ` footers, banners, or similar credit lines.
- Tool/agent name signatures in commit messages or PR descriptions.

Write commit messages and PR descriptions as if a human author wrote them.
`

Variables

View Source
var ErrNoLSP = errors.New("no language server setting")

ErrNoLSP says an agent has no setting through which a language server can be configured for it.

Functions

func ACPAdapterCommand added in v0.13.0

func ACPAdapterCommand(executable string) *exec.Cmd

ACPAdapterCommand runs an installed adapter. Package tarballs carry no execute bits for bin scripts (npm sets them at install), so a node script runs through node, as npm's shims would.

func CopySelectedEntries

func CopySelectedEntries(sourceRoot, destinationRoot string, entries []string) error

func DisplayName

func DisplayName(target Target) string

DisplayName is the agent's product name, as messages name it.

func DurablePathMatches

func DurablePathMatches(path, target string) bool

func EnsureACPAdapterExecutable added in v0.13.0

func EnsureACPAdapterExecutable(ctx context.Context, packageSpec string) (string, error)

EnsureACPAdapterExecutable installs a pinned npm ACP adapter under $AGENTPACK_HOME/adapters/<name>@<version>/ and returns its launcher path.

func HasAny

func HasAny(arguments []string, values ...string) bool

func HasFlagValue

func HasFlagValue(arguments []string, flag string) bool

func LinkDurableDirectory

func LinkDurableDirectory(native, staged string) error

func LinkDurableFile

func LinkDurableFile(native, staged string) error

func LookPathEnv

func LookPathEnv(envName, binary string) (string, error)

LookPathEnv returns an executable path from env override or PATH.

func MCPJSONScopeDigest added in v0.9.0

func MCPJSONScopeDigest(data []byte, key string) (string, error)

func MCPTOMLScopeDigest added in v0.9.0

func MCPTOMLScopeDigest(data []byte, key string) (string, error)

func MarkMCPWarnings added in v0.9.0

func MarkMCPWarnings(servers []MCPProjectedServer, warnings []string)

func PrependOnce

func PrependOnce(arguments []string, flag string, aliases ...string) []string

func ReadMCPSeed added in v0.9.0

func ReadMCPSeed(path string) ([]byte, error)

func RecoverWithoutOverwrite

func RecoverWithoutOverwrite(source, destination, conflictsRoot string) error

func RefreshToken added in v0.14.1

func RefreshToken(ctx context.Context, endpoint string, grant map[string]string, reply any) error

RefreshToken sends an OAuth refresh_token grant as JSON and decodes the answer into reply. Errors name the status only: a token endpoint's body may echo credentials.

func ResolveBinary

func ResolveBinary(environment, fallback string) (string, error)

func RunLogout added in v0.14.1

func RunLogout(ctx context.Context, exe string, args ...string) error

RunLogout runs an agent's own logout command and returns its output as the error when it fails.

func SaveProbeEvidence

func SaveProbeEvidence(workspace, receiptID, phase string, result ProbeResult) (string, error)

SaveProbeEvidence retains bounded raw diagnostics privately; support exports must omit these references.

func SeriesFrom

func SeriesFrom(version, series string, from int) bool

SeriesFrom says whether version (its first word, as `--version` prints it) is <series>.<patch> with patch at least from: a release of the validated series, the validated one or later. Probes gate their parsers on it rather than on one exact release, which the agents' auto-updates leave behind within days; a parser that cannot read a later release reports that itself.

func ToolNames added in v0.11.0

func ToolNames(value any) ([]string, bool)

ToolNames reads `tools: Read, Grep, Bash(git:*)` or the YAML list form and returns the bare tool names.

func ValidateMCPProjectionInputs added in v0.9.0

func ValidateMCPProjectionInputs(projections []MCPProjection) error

func WorkspaceRoot

func WorkspaceRoot(projectRoot string) string

func WriteGuidance

func WriteGuidance(path, blob string) error

func WriteLSPFile

func WriteLSPFile(path string, servers map[string]json.RawMessage) error

WriteLSPFile writes language servers as a .lsp.json file, the format that Claude Code reads at a plugin root and Grok reads as $GROK_HOME/lsp.json.

func WriteLSPProjection added in v0.9.0

func WriteLSPProjection(projection LSPProjection) error

func WriteMCPProjection added in v0.9.0

func WriteMCPProjection(projection MCPProjection) error

Types

type ACPLaunch added in v0.13.0

type ACPLaunch struct {
	Cmd                  *exec.Cmd
	AuthenticateMethodID string
	Rewrite              func([]byte) []byte
	AdaptAgent           func([]byte) AgentAdaptResult
	// ClientPermissionBypass lets Agentpack offer Bypass Permissions and answer ACP approval requests.
	ClientPermissionBypass bool
	// UnpromptedUsageSettle closes an unprompted cycle with a synthetic turn_end after a
	// parent usage_update stays quiet for this long (Antigravity's background-task wakeups
	// stream session/update notifications with no session/prompt RPC or idle signal).
	UnpromptedUsageSettle time.Duration
}

ACPLaunch starts an ACP-speaking agent subprocess. Rewrite adjusts client→agent JSON-RPC lines; AdaptAgent normalizes agent→client lines into standard ACP plus optional harness-specific event-log rows.

type Account added in v0.14.1

type Account struct {
	Installed bool          `json:"installed"`
	SignedIn  bool          `json:"signed_in"`
	Label     string        `json:"label,omitempty"`
	Methods   []LoginMethod `json:"methods,omitempty"`
	SignOut   bool          `json:"sign_out,omitempty"` // the gateway can sign it out
	Error     string        `json:"error,omitempty"`
}

Account is what an agent reports about its sign-in on this machine. Label is what the person recognizes: an email, a plan or the signed-in providers. It never holds a token. Methods and SignOut are filled in by the gateway from the agent's registry entry.

type AgentAdaptResult added in v0.13.0

type AgentAdaptResult struct {
	Forward []byte
	Log     []LogKind
}

AgentAdaptResult is the outcome of adapting one agent stdout JSON-RPC line. Forward nil leaves the line unchanged; non-nil replaces it (empty drops it).

type Definition

type Definition struct {
	Target           Target
	UserRoots        func(home string) []string
	Root             func(StageContext) (string, error)
	Reset            func(StageContext) ([]string, error)
	BeforeReset      func(StageContext) error
	Begin            func(StageContext) (RebuildTransaction, error)
	Setup            func(StageContext) error
	MCP              func(mcp.Entries, StageContext) error
	ProjectMCP       func(mcp.Entries, StageContext) (MCPProjection, error)
	ProjectLSP       func(map[string]json.RawMessage, StageContext) (LSPProjection, error)
	LSP              func(map[string]json.RawMessage, StageContext) error
	Guidance         func(string, StageContext) error
	AfterStage       func(mcp.Entries, StageContext) error
	WorkspaceOverlay func(StageContext) error
	Check            func(StageContext) error
	Launch           func(LaunchContext) (*exec.Cmd, error)
	LaunchACP        func(LaunchContext) (ACPLaunch, error)
	LaunchFinished   func(LaunchContext) error
}

func (Definition) ACP added in v0.13.0

func (definition Definition) ACP(ctx LaunchContext) (ACPLaunch, error)

func (Definition) AfterLaunch

func (definition Definition) AfterLaunch(ctx LaunchContext) error

func (Definition) BeginRebuild

func (definition Definition) BeginRebuild(ctx StageContext) (RebuildTransaction, error)

func (Definition) Finalize

func (definition Definition) Finalize(entries mcp.Entries, ctx StageContext) error

func (Definition) FinalizeWorkspaceOverlay

func (definition Definition) FinalizeWorkspaceOverlay(ctx StageContext) error

func (Definition) ID

func (definition Definition) ID() Target

func (Definition) InjectGuidance

func (definition Definition) InjectGuidance(blob string, ctx StageContext) error

func (Definition) LaunchCommand

func (definition Definition) LaunchCommand(ctx LaunchContext) (*exec.Cmd, error)

func (Definition) NativeUserRoots added in v0.8.6

func (definition Definition) NativeUserRoots(home string) []string

func (Definition) PlanLSP added in v0.9.0

func (definition Definition) PlanLSP(servers map[string]json.RawMessage, ctx StageContext) (LSPProjection, error)

func (Definition) PlanMCP added in v0.9.0

func (definition Definition) PlanMCP(entries mcp.Entries, ctx StageContext) (MCPProjection, error)

func (Definition) PreReset

func (definition Definition) PreReset(ctx StageContext) error

func (Definition) Prepare

func (definition Definition) Prepare(ctx StageContext) error

func (Definition) ResetPaths

func (definition Definition) ResetPaths(ctx StageContext) ([]string, error)

func (Definition) StagedRoot

func (definition Definition) StagedRoot(ctx StageContext) (string, error)

func (Definition) Verify

func (definition Definition) Verify(ctx StageContext) error

func (Definition) WriteLSP

func (definition Definition) WriteLSP(servers map[string]json.RawMessage, ctx StageContext) error

func (Definition) WriteMCP

func (definition Definition) WriteMCP(entries mcp.Entries, ctx StageContext) error

type Harness

type Harness interface {
	ID() Target
	// NativeUserRoots returns user artifact roots available outside the staged bundle.
	NativeUserRoots(home string) []string
	StagedRoot(StageContext) (string, error)
	ResetPaths(StageContext) ([]string, error)
	PreReset(StageContext) error
	BeginRebuild(StageContext) (RebuildTransaction, error)
	Prepare(StageContext) error
	WriteMCP(mcp.Entries, StageContext) error
	PlanMCP(mcp.Entries, StageContext) (MCPProjection, error)
	PlanLSP(map[string]json.RawMessage, StageContext) (LSPProjection, error)
	// WriteLSP writes language servers (Claude Code format, by name); it
	// returns ErrNoLSP when the agent has no language server setting.
	WriteLSP(map[string]json.RawMessage, StageContext) error
	InjectGuidance(string, StageContext) error
	Finalize(mcp.Entries, StageContext) error
	FinalizeWorkspaceOverlay(StageContext) error
	Verify(StageContext) error
	LaunchCommand(LaunchContext) (*exec.Cmd, error)
	ACP(LaunchContext) (ACPLaunch, error)
	AfterLaunch(LaunchContext) error
}

type LSPProjection added in v0.9.0

type LSPProjection struct {
	Files    []MCPProjectedFile
	Warnings []string
	Omitted  []string
}

type LaunchContext

type LaunchContext struct {
	ProjectRoot    string
	WorkspaceRoot  string
	Arguments      []string
	Mode           mode.Effective
	Yolo           bool
	StrictExternal bool
	Command        *exec.Cmd
}

type LimitSnapshot added in v0.10.0

type LimitSnapshot struct {
	Harness    string        `json:"harness"`
	State      string        `json:"state"`
	Source     string        `json:"source,omitempty"`
	ObservedAt time.Time     `json:"observed_at"`
	Plan       string        `json:"plan,omitempty"`
	Error      string        `json:"error,omitempty"`
	Windows    []LimitWindow `json:"windows"`
}

LimitSnapshot is the sanitized usage observation for one harness on one node. Absent numbers are unknown; a measured zero is a real zero.

type LimitWindow added in v0.10.0

type LimitWindow struct {
	ID               string     `json:"id"`
	Label            string     `json:"label"`
	UsedPercent      *float64   `json:"used_percent,omitempty"`
	RemainingPercent *float64   `json:"remaining_percent,omitempty"`
	DurationSeconds  *int64     `json:"duration_seconds,omitempty"`
	ResetAt          *time.Time `json:"reset_at,omitempty"`
	ResetText        string     `json:"reset_text,omitempty"`
}

LimitWindow is one usage window reported by a harness. Provider IDs and scope are kept rather than assigning a generic meaning such as "primary = five-hour".

type LogKind added in v0.13.0

type LogKind struct {
	Kind    string
	Payload json.RawMessage
}

LogKind is one synthetic event-log row produced by AdaptAgent.

type LoginAnswer added in v0.14.1

type LoginAnswer struct{ Screen, Keys string }

type LoginFlow added in v0.14.1

type LoginFlow struct {
	Command *exec.Cmd
	// Answers types each Keys once when its Screen appears before the link, in any order; a prompt
	// that never shows is skipped. Used to pick a menu entry.
	Answers []LoginAnswer
	// Code finds a one-time code printed next to the link (device flows). Nil when there is none.
	Code *regexp.Regexp
	// Input says what the person pastes back after signing in: "" (nothing), "code", or "url"
	// (the address the browser landed on).
	Input string
	// Verify reports whether sign-in succeeded, for a command that keeps running afterwards (a TUI
	// that goes on to its chat). It is checked after the person pastes their input. Nil means
	// success is a zero exit.
	Verify func(context.Context) bool
	// Finish runs after success, e.g. to install credentials the command wrote to an isolated home.
	Finish func() error
	// Cleanup runs once the attempt ends, whatever the outcome.
	Cleanup func()
}

LoginFlow is how an agent signs in from the web UI: the agent's own login command, run in a terminal on this machine. The gateway shows the person the link (and code) the command prints, and types back what they paste. Nothing here opens a browser on the machine.

type LoginMethod added in v0.14.1

type LoginMethod struct {
	ID    string `json:"id"`
	Label string `json:"label"`
}

LoginMethod is one way to sign in. Agents with several providers (OMP, OpenCode) list one per provider.

type MCPProjectedFile added in v0.9.0

type MCPProjectedFile struct {
	Path        string
	Contents    []byte
	Scope       string
	ScopeDigest string
	MergeOrder  []string
}

type MCPProjectedInput added in v0.9.0

type MCPProjectedInput struct {
	Path   string
	Digest string
	Exists bool
}

func MCPInput added in v0.9.0

func MCPInput(path string, contents []byte) (MCPProjectedInput, error)

func ReadMCPInput added in v0.9.0

func ReadMCPInput(path string) (MCPProjectedInput, error)

type MCPProjectedServer added in v0.9.0

type MCPProjectedServer struct {
	Name, Source, Module, Winner string
	Dropped                      []string
}

func ProjectedMCPServers added in v0.9.0

func ProjectedMCPServers(entries mcp.Entries) []MCPProjectedServer

type MCPProjection added in v0.9.0

type MCPProjection struct {
	Files    []MCPProjectedFile
	Servers  []MCPProjectedServer
	Warnings []string
	Inputs   []MCPProjectedInput
}

type PackagedNames

type PackagedNames struct {
	Skills   []string
	Commands []string
	Agents   []string
}

PackagedNames lists the artifacts of the plan that a probe should look for, by kind.

type ProbePlan

type ProbePlan struct {
	Executable string
	Argv       []string
	Cwd        string
	Env        []string // full env if non-nil; otherwise process env
	Timeout    time.Duration
	Categories []string
	Network    string
	WriteScope string
	ModelCalls bool
}

ProbePlan is a fixed, non-shell native diagnostic invocation.

type ProbeResult

type ProbeResult struct {
	Stdout    string
	Stderr    string
	ExitCode  int
	TimedOut  bool
	Canceled  bool
	Truncated bool
	Duration  time.Duration
}

ProbeResult is bounded process output.

func RunProbe

func RunProbe(ctx context.Context, plan ProbePlan) (ProbeResult, error)

RunProbe executes a plan with cancellation and stdout/stderr caps.

type RebuildTransaction

type RebuildTransaction interface {
	Root() string
	Commit() error
	Abort() error
}

RebuildTransaction keeps a newly staged root private until all staging and verification succeeds. Abort must leave the previously published root intact.

type StageContext

type StageContext struct {
	ProjectRoot    string
	WorkspaceRoot  string
	Mode           mode.Effective
	LaunchTarget   *Target
	StagedRoots    map[Target]string
	SeedConfig     []byte
	StrictExternal bool
}

type Target

type Target string
const (
	Claude   Target = "claude"
	Cursor   Target = "cursor"
	Codex    Target = "codex"
	OpenCode Target = "opencode"
	Grok     Target = "grok"
	Agy      Target = "agy"
	OMP      Target = "omp"
)

func AllTargets

func AllTargets() []Target

func ParseTarget

func ParseTarget(value string) (Target, error)

func (Target) Binary added in v0.14.1

func (target Target) Binary() (environment, program string)

Binary names the environment override and default program for the agent's CLI.

func (Target) RawPluginSubdirs

func (target Target) RawPluginSubdirs() []string

func (Target) UsesWorkspaceOverlay

func (target Target) UsesWorkspaceOverlay() bool

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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