harness

package
v0.47.0 Latest Latest
Warning

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

Go to latest
Published: Oct 11, 2026 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source
const (
	PrivilegeStagePreScript      = "pre_script"
	PrivilegeStageRuntime        = "runtime"
	PrivilegeStagePostScript     = "post_script"
	PrivilegeStageDefault        = "default"
	PrivilegeStageValidationLoop = "validation_loop"

	// DefaultPrivilegeLevel is used when privilege_levels is omitted or a
	// run-stage (and default) is unset. Preserves pre-ADR-0073 write tokens.
	DefaultPrivilegeLevel = "write"
)

Run-stage keys accepted by privilege_levels (ADR 0073). validation_loop is not a YAML key: it inherits the runtime level because it shares the runtime security context.

View Source
const MaxBaseDepth = 5

MaxBaseDepth is the maximum depth of base chain inheritance. This prevents runaway recursion from circular or pathologically deep chains.

Variables

This section is empty.

Functions

func BoolDefault added in v0.0.3

func BoolDefault(b *bool, def bool) bool

BoolDefault returns the value of a *bool, or the default if nil.

func BuildConfigMap added in v0.38.0

func BuildConfigMap(cfg config.ConfigReader) map[string]any

BuildConfigMap extracts user-facing per-repo config fields for overlay CEL evaluation (ADR 0088). The returned map is exposed to overlay when expressions as the "config" variable. Returns nil when cfg is nil or does not implement PerRepoConfigReader.

All safe per-repo config fields are exposed. Sensitive fields (mint_url, inference provider details) are excluded. Per PR #6285 review feedback, the 4-key whitelist was expanded to expose the full non-sensitive config.

Both the CLI (run, lock) and harnessdispatch (enumerate) call sites use this single implementation to ensure overlay CEL resolution sees the same config shape regardless of the call path.

func ChmodPluginDir added in v0.35.0

func ChmodPluginDir(dir string) error

ChmodPluginDir makes all files under dir executable (0755). It resolves symlinks first so it operates on the real directory tree. Plugins may contain scripts or MCP server binaries that need the execute bit.

func EvaluateOverlay added in v0.38.0

func EvaluateOverlay(expr string, event map[string]any, forgePlatform string, config map[string]any) (bool, error)

EvaluateOverlay evaluates an overlay when expression against the overlay CEL environment: event data, runtime context (forge platform), and per-repo config (ADR 0088).

func EvaluateTrigger added in v0.31.0

func EvaluateTrigger(expr string, event map[string]any) (bool, error)

EvaluateTrigger evaluates a compiled trigger against event data (map form).

func ForgeKeyList added in v0.18.0

func ForgeKeyList() string

ForgeKeyList returns a comma-separated list of valid forge platform keys.

func IsAbsPath added in v0.11.0

func IsAbsPath(s string) bool

IsAbsPath returns true if s is an absolute file path.

func IsProviderPath added in v0.34.0

func IsProviderPath(s string) bool

IsProviderPath returns true if s is a file path rather than a bare provider name. A provider string is a path if it contains a directory separator or ends with a YAML extension.

func IsRelPath added in v0.11.0

func IsRelPath(s string) bool

IsRelPath returns true if s is a non-empty relative file path (not a URL and not absolute).

func IsURL added in v0.11.0

func IsURL(s string) bool

IsURL returns true if s is a valid HTTPS URL suitable for remote resource references.

func LoadWithBase added in v0.18.0

func LoadWithBase(ctx context.Context, path string, opts ComposeOpts) (*Harness, []Dependency, error)

LoadWithBase loads a harness with base composition and conditional configuration resolution (forge blocks and CEL-guarded overlays). If the harness has a `base` field, the base chain is recursively loaded and merged before the child's own conditional config is resolved. Returns the merged harness and a list of dependencies for any URL bases that were fetched.

Pipeline:

  1. LoadRaw(path) — preserves forge map
  2. If base absent: resolve URL-sourced resources → ResolveForge → ResolveOverlays → Validate → return
  3. If base present: loadBaseChain recursively (each base layer resolves its own forge/overlays via resolveBaseForgeAndOverlays before merging into the next layer), then mergeBaseIntoChild with the flat base
  4. Resolve remaining URL-sourced resources and scripts (child's own relative paths)
  5. ResolveForge and ResolveOverlays on child's own forge/overlay blocks
  6. Validate

When base is absent, this behaves identically to LoadWithOpts.

func MatchingAllowedPrefixInList added in v0.18.0

func MatchingAllowedPrefixInList(rawURL string, allowlist []string) string

MatchingAllowedPrefixInList checks if a URL matches any prefix in the given allowlist. Returns the matching prefix or "" if none match. Standalone version of MatchingAllowedPrefix.

func NewOverlayEnv added in v0.38.0

func NewOverlayEnv() (*cel.Env, error)

NewOverlayEnv creates a CEL environment for overlay when expressions. It extends the trigger environment with runtime and config variables (ADR 0088). runtime.forge is the effective forge platform; config is the per-repo config from config.yaml.

func NewTriggerEnv added in v0.31.0

func NewTriggerEnv() (*cel.Env, error)

NewTriggerEnv creates a CEL environment with root variable event (dyn type).

func ParseIntegrityHash added in v0.11.0

func ParseIntegrityHash(rawURL string) (cleanURL, hash string, hasHash bool)

ParseIntegrityHash extracts the SHA256 hash from a URL fragment (#sha256=...). Returns the URL without the fragment, the hash value, and whether a valid hash was found. The hash is normalized to lowercase; both "sha256=ABC..." and "sha256=abc..." are accepted.

func SkillSources added in v0.37.0

func SkillSources(entries []SkillEntry) []string

SkillSources extracts the source paths from a slice of SkillEntry values. This is a convenience function for call sites that only need the directory paths (e.g., bootstrap, display).

func ValidAgentBasename added in v0.44.0

func ValidAgentBasename(name string) bool

ValidAgentBasename reports whether name is a safe agent name — the same check Validate applies to the agent: basename (minus .md). Exported so a caller that constructs a harness, rather than loading one, can reject an unsafe name before writing it anywhere: the name reaches shell interpolation, so this is a security check, not a style check.

func ValidForgePlatform added in v0.18.0

func ValidForgePlatform(platform string) bool

ValidForgePlatform reports whether platform is a recognized forge key.

func ValidPluginBasename added in v0.34.0

func ValidPluginBasename(name string) bool

ValidPluginBasename reports whether name matches the allowed plugin name pattern.

func ValidSlug added in v0.44.0

func ValidSlug(slug string) bool

ValidSlug reports whether slug matches the allowed harness slug pattern.

func ValidateHostFileDest added in v0.46.0

func ValidateHostFileDest(dest string) error

ValidateHostFileDest reports whether dest is an absolute path under /sandbox or /tmp that does not name a runner-owned location. The path is cleaned first, so "..", "//" and a trailing "/" cannot reach a reserved path by another spelling.

func ValidateSkillOverrides added in v0.37.0

func ValidateSkillOverrides(skills []SkillEntry) error

ValidateSkillOverrides checks that all file override keys in the skills list are safe relative paths (no traversal, no absolute paths) and that override source paths are either null (removal) or non-empty strings. Already-resolved values (absolute cache paths or URLs) are skipped — they were validated pre-resolution by resolveBaseResources or will be validated by ResolveHarness.

func ValidateTriggerExpression added in v0.31.0

func ValidateTriggerExpression(expr string) error

ValidateTriggerExpression compiles a harness trigger CEL expression. Empty trigger is valid (manual fullsend run only).

Types

type APIServer

type APIServer struct {
	Name   string            `yaml:"name"`
	Script string            `yaml:"script"`
	Port   int               `yaml:"port"`
	Env    map[string]string `yaml:"env,omitempty"`
}

APIServer describes a host-side REST proxy server.

type AgentInfo added in v0.18.0

type AgentInfo struct {
	Role     string // from the harness role: field
	Slug     string // from the harness slug: field
	Filename string // e.g. "triage.yaml"
	Path     string // absolute path to the harness file
}

AgentInfo holds the identity of an agent discovered from a harness file.

func DiscoverAgents added in v0.18.0

func DiscoverAgents(dir string) ([]AgentInfo, error)

DiscoverAgents scans dir for harness YAML files and returns agent identity (role, slug) from each. Files where both role and slug are empty are skipped. Parse errors on individual files are collected into a multi-error; valid files are still returned alongside the error.

Results are sorted by Role, then by Filename for deterministic output. Only top-level role/slug fields are read — base chains are not resolved. This is correct because generated wrappers set role/slug at the top level.

func DiscoverRemoteAgents added in v0.18.0

func DiscoverRemoteAgents(ctx context.Context, client forge.Client, owner, repo, ref string) ([]AgentInfo, error)

DiscoverRemoteAgents discovers agent identity (role, slug) from harness files in a remote config repo via the forge API. It is the remote counterpart of DiscoverAgents, which reads from the local filesystem.

Files where both role and slug are empty are skipped. Per-file errors (parse failures, GetFileContentAtRef failures) are collected into a multi-error; valid files are still returned alongside the error.

Results are sorted by Role, then by Filename for deterministic output. Returns (nil, nil) when the harness/ directory does not exist.

type ComposeOpts added in v0.18.0

type ComposeOpts struct {
	// WorkspaceRoot is the root directory for cache paths (typically the repo root).
	WorkspaceRoot string

	// FetchPolicy controls SSRF protection, offline mode, and size limits.
	FetchPolicy fetch.FetchPolicy

	// TraceID is a correlation ID for audit log entries.
	TraceID string

	// AuditLogPath is the path to the fetch audit log (JSONL).
	// If empty, audit logging is skipped.
	AuditLogPath string

	// ForgePlatform is the platform to resolve after base merging (e.g., "github").
	// If empty, ResolveForge is a no-op.
	ForgePlatform string

	// OrgAllowlist is the config-level allowed_remote_resources from the
	// repository's layered .fullsend config (config.yaml over
	// config.base.yaml), or the built-in defaults when no config is present.
	// Base URLs and agent source URLs must match a prefix in this list.
	OrgAllowlist []string

	// TreeFetcher fetches all files under a path in a remote repository.
	// When nil, defaults to gitfetch.FetchTree (git sparse checkout).
	TreeFetcher gitfetch.TreeFetchFunc

	// GitToken is an optional token for authenticating git fetches.
	// Empty means unauthenticated (sufficient for public repos).
	GitToken string

	// SourceURL is the URL from which the harness was fetched (e.g., via
	// FetchAgentHarness for config-registered agents). When set and the harness
	// has no base: field, LoadWithBase resolves relative resource paths (agent,
	// policy, skills, scripts) against this URL using the same infrastructure
	// as base composition (ADR-0045). If empty, no URL resolution is performed
	// for no-base harnesses.
	SourceURL string

	// Event is the normalized event data for CEL overlay resolution (ADR 0088).
	// When nil, ResolveOverlays substitutes an empty map so overlays conditioned
	// on runtime.forge or config can still evaluate and match (CLI flows without
	// event context).
	Event map[string]any

	// Config is the per-repo config (from config.yaml) exposed to overlay
	// CEL when expressions as the config variable (ADR 0088).
	Config map[string]any
	// contains filtered or unexported fields
}

ComposeOpts controls base composition behavior.

type Dependency added in v0.18.0

type Dependency struct {
	Field     string
	URL       string
	LocalPath string
	SHA256    string
	FetchedAt time.Time
	CacheHit  bool
	Type      string // "file" for base harnesses
	Warning   string // non-fatal warning about this dependency (e.g., partial skill fetch)
}

Dependency records a single URL that was resolved to a local cache path. This mirrors resolve.Dependency but lives here to avoid circular imports.

func FetchAgentHarness added in v0.25.0

func FetchAgentHarness(ctx context.Context, rawURL string, opts ComposeOpts) (localPath string, dep Dependency, err error)

FetchAgentHarness fetches a URL-sourced agent harness using the same infrastructure as base composition (ADR 0038). It downloads the content, verifies the integrity hash, caches it, and returns the local cache path so the caller can pass it to LoadWithBase.

type Diagnostic added in v0.18.0

type Diagnostic struct {
	Severity DiagnosticSeverity
	Field    string
	Message  string
}

Diagnostic represents a non-fatal issue found by Lint.

func CheckGenerated added in v0.44.0

func CheckGenerated(h *Harness, absDir string) ([]Diagnostic, error)

CheckGenerated validates a harness that was just constructed in memory and written to disk, in the order a caller needs after its own Load.

It exists for `fullsend agent new`, whose whole purpose is to surface at generation time the errors that otherwise appear only at the first dispatch after merge. It is deliberately NOT wired into `fullsend run` or `fullsend lock`: those two interleave minting, runner-env validation and ${VAR} expansion between the same steps, in different orders, and collapsing them here would change their behaviour.

Returned diagnostics are Lint()'s non-fatal warnings; the caller decides how to present them. An error means the harness is not usable.

Not checked here, on purpose: ValidateRunnerEnvWith. It requires every ${VAR} in env.runner/env.sandbox to be set in the calling process, which is true in CI and false on a developer's machine. Failing generation because GITHUB_ISSUE_URL is unset would make the command unusable for its main audience. The consequence is that an unset variable surfaces at `fullsend run` time instead; the generated docs say so.

func (Diagnostic) String added in v0.18.0

func (d Diagnostic) String() string

type DiagnosticSeverity added in v0.18.0

type DiagnosticSeverity int

DiagnosticSeverity indicates whether a diagnostic is a warning or an error.

const (
	SeverityWarning DiagnosticSeverity = iota
	SeverityError
)

func (DiagnosticSeverity) String added in v0.18.0

func (s DiagnosticSeverity) String() string

String returns a human-readable description of the diagnostic severity.

type EnvConfig added in v0.24.0

type EnvConfig struct {
	Runner  map[string]string `yaml:"runner,omitempty"`
	Sandbox map[string]string `yaml:"sandbox,omitempty"`
}

EnvConfig holds environment variable maps for runner and sandbox targets. Replaces runner_env (ADR 0055). Values support ${VAR} expansion from the host environment.

type EscalationConfig added in v0.0.3

type EscalationConfig struct {
	OnCritical  string `yaml:"on_critical,omitempty"`  // "halt" or "review". Default: "halt"
	ReviewLabel string `yaml:"review_label,omitempty"` // Default: "requires-manual-review"
}

EscalationConfig controls what happens when critical findings are detected.

type ForgeConfig added in v0.17.0

type ForgeConfig struct {
	PreScript      string            `yaml:"pre_script,omitempty"`
	PostScript     string            `yaml:"post_script,omitempty"`
	Policy         string            `yaml:"policy,omitempty"`
	Skills         []SkillEntry      `yaml:"skills,omitempty"` // SkillEntry (not string) to support file-level overrides
	Providers      []string          `yaml:"providers,omitempty"`
	OpenShell      *OpenShellConfig  `yaml:"openshell,omitempty"`
	HostFiles      []HostFile        `yaml:"host_files,omitempty"`
	ValidationLoop *ValidationLoop   `yaml:"validation_loop,omitempty"`
	RunnerEnv      map[string]string `yaml:"runner_env,omitempty"`
	Env            *EnvConfig        `yaml:"env,omitempty"`
}

ForgeConfig holds platform-specific harness configuration. This is purely declarative YAML config — it selects which scripts, skills, host files, and env vars to use per platform. It is distinct from the forge.Client interface (internal/forge/), which is the runtime abstraction for forge API operations.

type Harness

type Harness struct {
	Agent                  string                  `yaml:"agent"`
	Doc                    string                  `yaml:"doc,omitempty"`
	Description            string                  `yaml:"description,omitempty"`
	Role                   string                  `yaml:"role,omitempty"`
	Slug                   string                  `yaml:"slug,omitempty"`
	Base                   string                  `yaml:"base,omitempty"`
	Image                  string                  `yaml:"image,omitempty"`
	Policy                 string                  `yaml:"policy,omitempty"`
	Skills                 []SkillEntry            `yaml:"skills,omitempty"`
	Plugins                []PluginSpec            `yaml:"plugins,omitempty"` // runtime-scoped plugin directories (ADR 0094)
	Providers              []string                `yaml:"providers,omitempty"`
	OpenShell              *OpenShellConfig        `yaml:"openshell,omitempty"`
	HostFiles              []HostFile              `yaml:"host_files,omitempty"`
	APIServers             []APIServer             `yaml:"api_servers,omitempty"`
	Model                  string                  `yaml:"model,omitempty"`
	Effort                 string                  `yaml:"effort,omitempty"`
	PreScript              string                  `yaml:"pre_script,omitempty"`
	PostScript             string                  `yaml:"post_script,omitempty"`
	PrivilegeLevels        map[string]string       `yaml:"privilege_levels,omitempty"` // run-stage → mint privilege level (ADR 0073)
	AgentInput             string                  `yaml:"agent_input,omitempty"`
	ValidationLoop         *ValidationLoop         `yaml:"validation_loop,omitempty"`
	RunnerEnv              map[string]string       `yaml:"runner_env,omitempty"`
	Env                    *EnvConfig              `yaml:"env,omitempty"`
	TimeoutMinutes         int                     `yaml:"timeout_minutes,omitempty"`
	ReadonlyRepo           bool                    `yaml:"readonly_repo,omitempty"`
	SandboxTimeoutSeconds  int                     `yaml:"sandbox_timeout_seconds,omitempty"`
	Security               *SecurityConfig         `yaml:"security,omitempty"`
	AllowedRemoteResources []string                `yaml:"allowed_remote_resources,omitempty"`
	AllowRuntimeFetch      bool                    `yaml:"allow_runtime_fetch,omitempty"` // opt-in to runtime skill fetching (default: false)
	MaxRuntimeFetches      *int                    `yaml:"max_runtime_fetches,omitempty"` // per-run fetch cap; nil = default (10), valid range 1-1000
	Forge                  map[string]*ForgeConfig `yaml:"forge,omitempty"`
	Overlays               []OverlayEntry          `yaml:"overlays,omitempty"` // CEL-guarded conditional config (ADR 0088)
	Trigger                string                  `yaml:"trigger,omitempty"`  // optional CEL boolean over normevent (ADR 0061)
	// contains filtered or unexported fields
}

Harness is the per-agent configuration that the runner reads to provision a sandbox and launch one agent. It follows the ADR-0017 schema.

func Load

func Load(path string) (*Harness, error)

Load reads a harness YAML file from path, unmarshals it, and validates it.

func LoadRaw added in v0.18.0

func LoadRaw(path string) (*Harness, error)

LoadRaw reads and unmarshals a harness YAML file without calling Validate or ResolveForge. Used by base composition to load base harnesses without consuming their forge maps before merging, and by the lock command to discover forge keys without resolving them.

func LoadWithOpts added in v0.18.0

func LoadWithOpts(path string, opts LoadOpts) (*Harness, error)

LoadWithOpts reads a harness YAML file and applies forge resolution before validation. The pipeline is: Unmarshal → validateForge → ResolveForge → Validate. validateForge runs first to reject malformed forge maps before ResolveForge consumes (nils out) the map. When ForgePlatform is empty, ResolveForge is a no-op but validateForge still runs.

func (*Harness) EffectiveMaxRuntimeFetches added in v0.18.0

func (h *Harness) EffectiveMaxRuntimeFetches() int

EffectiveMaxRuntimeFetches returns the configured max runtime fetches, or defaultMaxRuntimeFetches (10) when the field is omitted.

func (*Harness) FailModeClosed added in v0.0.3

func (h *Harness) FailModeClosed() bool

FailModeClosed returns true if the security fail mode is "closed" (default).

func (*Harness) HasURLDirResources added in v0.34.0

func (h *Harness) HasURLDirResources() bool

HasURLDirResources reports whether any skill or plugin field contains a URL. Used to determine whether a forge client is needed for resolution.

func (*Harness) HasURLReferences added in v0.14.0

func (h *Harness) HasURLReferences() bool

HasURLReferences reports whether any declarative field (agent, policy, skills, plugins, profiles, providers) contains a URL reference. Used to skip remote resource validation and resolution when the harness references only local paths.

func (*Harness) Lint added in v0.18.0

func (h *Harness) Lint() []Diagnostic

Lint returns non-fatal diagnostics for the harness. Call only after a successful Validate — Lint does not re-check structural validity, and its results are meaningless on an invalid harness. Returns nil when no diagnostics are found.

func (*Harness) MatchesAllowedPrefix added in v0.12.0

func (h *Harness) MatchesAllowedPrefix(rawURL string) bool

MatchesAllowedPrefix reports whether rawURL starts with any entry in AllowedRemoteResources (case-insensitive). The URL path is percent-decoded and normalized (resolving ".." and "." segments) before prefix matching to prevent path-traversal bypasses via both literal and encoded dot segments. Returns false if the URL contains "%25" (double-encoded percent sign) or cannot be parsed.

func (*Harness) MatchingAllowedPrefix added in v0.13.0

func (h *Harness) MatchingAllowedPrefix(rawURL string) string

MatchingAllowedPrefix returns the first AllowedRemoteResources entry that matches rawURL, or "" if none match. It applies the same normalization as MatchesAllowedPrefix.

func (*Harness) OpenShellProfiles added in v0.31.0

func (h *Harness) OpenShellProfiles() []string

func (*Harness) PrivilegeLevelForStage added in v0.44.0

func (h *Harness) PrivilegeLevelForStage(stage string) string

PrivilegeLevelForStage returns the mint privilege level for a run-stage. validation_loop inherits runtime. Unlisted stages inherit default, then DefaultPrivilegeLevel ("write") so omitting privilege_levels is a no-op.

func (*Harness) ResolveForge added in v0.17.0

func (h *Harness) ResolveForge(platform string) error

ResolveForge merges forge-specific overrides into the harness in place. After merging, h.Forge is set to nil (consumed). If platform is empty or h.Forge is nil, this is a no-op. If platform is not present in h.Forge, an error is returned.

Pipeline ordering: LoadWithOpts calls validateForge → ResolveForge → Validate. validateForge must run first because ResolveForge consumes h.Forge (sets it to nil). After ResolveForge, Validate's validateForge call sees nil and is a no-op, which is correct because the forge map was already validated before merging.

func (*Harness) ResolveOverlays added in v0.38.0

func (h *Harness) ResolveOverlays(event map[string]any, forgePlatform string, config map[string]any) error

ResolveOverlays evaluates each overlay's When expression against the overlay CEL environment (event, runtime.forge, config) and merges all matching entries into the harness in order (later matches take precedence over earlier matches). After resolution, h.Overlays is set to nil (consumed). When h.Overlays is empty, this is a no-op. When event is nil, an empty map is passed to CEL so overlays conditioned only on runtime.forge or config can still match (e.g., CLI run/lock flows that don't have an event context).

CEL evaluation errors are treated as non-matching: the error is logged and evaluation continues to the next entry. This matches the MatchHarnesses pattern in harnessdispatch/enumerate.go and ensures that a more-specific overlay (e.g., event.source.system == "jira" && runtime.forge == "github") that fails on key access when event is empty does not prevent a broader fallback overlay from matching.

func (*Harness) ResolveRelativeTo

func (h *Harness) ResolveRelativeTo(baseDir string) error

ResolveRelativeTo resolves all relative paths in the harness against baseDir. Relative paths that resolve outside baseDir are rejected to prevent directory traversal (e.g. ../../etc/shadow). Absolute paths and ${VAR} paths are allowed.

func (*Harness) Scripts added in v0.0.4

func (h *Harness) Scripts() []string

Scripts returns all script paths configured in the harness.

func (*Harness) SecurityEnabled added in v0.0.3

func (h *Harness) SecurityEnabled() bool

SecurityEnabled returns true if security scanning is enabled (default: true).

func (*Harness) Validate

func (h *Harness) Validate() error

Validate checks that required fields are present.

func (*Harness) ValidateAllowedRemoteResources added in v0.12.0

func (h *Harness) ValidateAllowedRemoteResources(orgAllowlist []string) error

ValidateAllowedRemoteResources checks that each entry in AllowedRemoteResources is a valid HTTPS URL ending with "/" and is covered by at least one entry in the config-level allowlist. Allowlist entries are also validated: each must be a valid HTTPS URL ending with "/" and must not contain double-encoded sequences.

func (*Harness) ValidateFilesExist

func (h *Harness) ValidateFilesExist() error

ValidateFilesExist checks that all file paths referenced by the harness exist on disk. Callers must invoke ResolveRelativeTo first (to make paths absolute), then resolve.ResolveHarness (to replace any URL references with local cache paths). The IsURL guard inside is defense-in-depth in case the ordering is violated.

func (*Harness) ValidatePluginDirs added in v0.42.0

func (h *Harness) ValidatePluginDirs() error

ValidatePluginDirs runs the on-disk checks for every resolved plugins: entry — the directory exists, one runtime format claims it, the entry's env/pi options fit that format, and no two entries share a sandbox basename. ValidateFilesExist calls it; fullsend lock calls it directly after resolution, since Validate() is filesystem-blind and a URL entry's format is unknown until it has been fetched. Entries still holding a URL are skipped: an unresolved URL here is the caller's ordering bug.

func (*Harness) ValidateResourceTypes added in v0.12.0

func (h *Harness) ValidateResourceTypes() error

ValidateResourceTypes checks that executable fields (pre_script, post_script, validation_loop.script, host_files[].src, api_servers[].script) are local paths and not URLs, and that declarative fields (agent, policy, skills[], plugins[]) that are URLs include an integrity hash (#sha256=...).

func (*Harness) ValidateRunnerEnv

func (h *Harness) ValidateRunnerEnv() error

ValidateRunnerEnv checks that all ${VAR} references in RunnerEnv and HostFiles.Src are defined in the host environment.

func (*Harness) ValidateRunnerEnvWith added in v0.0.4

func (h *Harness) ValidateRunnerEnvWith(lookup func(string) (string, bool)) error

ValidateRunnerEnvWith checks that all ${VAR} references in RunnerEnv, Env.Runner, Env.Sandbox, and HostFiles.Src are defined in the host environment using the provided lookup function. Variables set to an empty string are allowed; only truly unset variables produce an error.

type HostFile

type HostFile struct {
	Src      string `yaml:"src"`                // host path (may use ${VAR} expansion)
	Dest     string `yaml:"dest"`               // destination path inside the sandbox
	Expand   bool   `yaml:"expand,omitempty"`   // expand ${VAR} in file content before copying
	Optional bool   `yaml:"optional,omitempty"` // skip if src path is missing or expands to empty
}

HostFile describes a file on the host that must be copied into the sandbox during bootstrap. Src may contain ${VAR} references that are expanded from the host environment at bootstrap time. Use this for any file that must exist inside the sandbox (e.g. GCP service account JSON, CA certificates).

When Expand is true, the file content is read and ${VAR} references in the content are expanded from the host environment before copying to the sandbox. Use this for env files that contain variable references which must be resolved on the host (because the sandbox does not have those variables set).

type HostScanners added in v0.0.3

type HostScanners struct {
	UnicodeNormalizer *bool           `yaml:"unicode_normalizer,omitempty"` // default: true
	ContextInjection  *bool           `yaml:"context_injection,omitempty"`  // default: true
	SSRFValidator     *bool           `yaml:"ssrf_validator,omitempty"`     // default: true
	SecretRedactor    *bool           `yaml:"secret_redactor,omitempty"`    // default: true
	LLMGuard          *LLMGuardConfig `yaml:"llm_guard,omitempty"`
}

HostScanners configures which scanners run on the host before sandbox creation (Path A: GHA workflow pre-step) or inside the sandbox before the agent starts (Path B: fullsend scan context).

type LLMGuardConfig added in v0.0.3

type LLMGuardConfig struct {
	Enabled   *bool   `yaml:"enabled,omitempty"`    // default: true
	Threshold float64 `yaml:"threshold,omitempty"`  // default: 0.92
	MatchType string  `yaml:"match_type,omitempty"` // "sentence" or "full". Default: "sentence"
}

LLMGuardConfig configures the ML-based prompt injection scanner. As of #6522 the scanner ships enabled only in the runner image; the release binaries are built CGO_ENABLED=0 with no -tags ORT, so it is compiled out of those. Neither Path A (scanRepoContextFiles) nor Path B (fullsend scan context) ever called it; the sole call site is `fullsend scan input`.

These fields are validated but never read: the scanner is constructed with zero values and hardcodes 0.92/sentence, and the call is gated on MLScanAvailable() rather than on Enabled. See #6506.

type LoadOpts added in v0.18.0

type LoadOpts struct {
	ForgePlatform string
	Event         map[string]any // event data for CEL overlay resolution (ADR 0088)
	Config        map[string]any // per-repo config for CEL overlay resolution (ADR 0088)
}

LoadOpts configures forge-aware and overlay-aware harness loading.

type OpenShellConfig added in v0.31.0

type OpenShellConfig struct {
	Profiles []string `yaml:"profiles,omitempty"`
}

type OverlayEntry added in v0.38.0

type OverlayEntry struct {
	When        string `yaml:"when"`
	ForgeConfig `yaml:",inline"`
}

OverlayEntry is a CEL-guarded conditional config block (ADR 0088). Each entry carries a CEL expression in When and the same override fields as ForgeConfig. All entries whose When evaluates to true are merged into the harness in order (later matches override earlier matches). The When expression is evaluated against the overlay CEL environment: event (normevent map), runtime.forge (platform string), and config (per-repo config map).

type PiPluginOptions added in v0.42.0

type PiPluginOptions struct {
	Args []string
}

PiPluginOptions are the knobs that apply when pi loads the entry. Args are appended to pi's command line right after the entry's `-e <path>`; they are the flags the extension registered with pi.registerFlag, and pi's own options are rejected (pluginformat.PiArgsProblem).

type PluginSpec added in v0.42.0

type PluginSpec struct {
	Path string
	Env  map[string]string
	Pi   *PiPluginOptions
}

PluginSpec is one `plugins:` entry: a directory a runtime loads (ADR 0094). Which runtime loads it follows from the directory's format, not from the key: a directory with plugin.json at its root or .claude-plugin/plugin.json is Claude Code's, a directory pi's `-e <dir>` loader resolves an entry point in is pi's, and each runtime names and skips the entries of the other format. Two YAML forms:

# String form — just the directory
- plugins/gopls-lsp

# Object form — when the entry needs environment or runtime options
- path: extensions/pi-fff
  env:
    FFF_MULTIGREP: "1"
  pi:
    args: ["--fff-mode", "override"]

Path is a path inside the harness repository or a pinned forge tree URL, the same sourcing rule as skills:. npm:/git:/ssh: forms are rejected — pi would install such a source from the network at startup, which the sandbox cannot do.

Env and the pi: block only apply to an entry a runtime loads as code (today: pi), and validation refuses them on a Claude plugin rather than dropping them silently. Env is exported right before pi starts and is inherited by pi and by every hook script it spawns, so a broad deny-list — not the export order — is what keeps the runtime's own names out of a plugin's reach (see reservedPluginEnvKey).

func (PluginSpec) MarshalYAML added in v0.42.0

func (p PluginSpec) MarshalYAML() (interface{}, error)

MarshalYAML round-trips: the string form when the entry is only a path, the object form otherwise.

func (PluginSpec) Name added in v0.42.0

func (p PluginSpec) Name() string

Name is the plugin's sandbox name: the directory basename, which is also what the runtime uploads it as.

func (PluginSpec) PiArgs added in v0.42.0

func (p PluginSpec) PiArgs() []string

PiArgs is the entry's pi args, or nil when it carries no pi: block.

func (PluginSpec) SameOptions added in v0.42.0

func (p PluginSpec) SameOptions(o PluginSpec) bool

SameOptions reports whether two entries carry the same env and pi options, treating an absent map, block or args list as equal to an empty one — `env: {}` and no `env:` mean the same thing to every runtime.

func (*PluginSpec) UnmarshalYAML added in v0.42.0

func (p *PluginSpec) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler for the string and object forms.

type ProviderDef

type ProviderDef struct {
	Name        string            `yaml:"name"`
	Type        string            `yaml:"type"`
	Credentials map[string]string `yaml:"credentials"`      // KEY: VALUE or KEY: ${HOST_VAR}
	Config      map[string]string `yaml:"config,omitempty"` // e.g. OPENAI_BASE_URL
}

ProviderDef is a declarative definition of an OpenShell provider. Files in the experiment's providers/ directory are loaded as ProviderDefs and reconciled against the gateway before sandbox creation.

func LoadProviderDefs

func LoadProviderDefs(dir string, only ...map[string]struct{}) ([]ProviderDef, error)

LoadProviderDefs reads YAML files from a providers/ directory and returns the parsed definitions. Returns nil (no error) if the directory does not exist. When only is non-nil, only files whose stem (filename without extension) matches a key in the set are loaded.

func ParseProviderDef added in v0.38.0

func ParseProviderDef(data []byte) (ProviderDef, error)

ParseProviderDef parses and validates one provider definition document.

type RegisteredAgent added in v0.31.0

type RegisteredAgent struct {
	Entry  config.AgentEntry
	Name   string
	Source string
}

RegisteredAgent is a validated config-registered agent entry.

func RegisteredAgents added in v0.31.0

func RegisteredAgents(cfg config.ConfigReader) ([]RegisteredAgent, error)

RegisteredAgents validates and returns entries from a ConfigReader.

type ResolvedPath added in v0.31.0

type ResolvedPath struct {
	Path string
	Dep  Dependency
}

ResolvedPath is the local filesystem path for a registered agent source.

func ResolveRegisteredPath added in v0.31.0

func ResolveRegisteredPath(ctx context.Context, configDir string, entry config.AgentEntry, allowlist []string, opts ComposeOpts) (ResolvedPath, error)

ResolveRegisteredPath resolves a config AgentEntry to a local filesystem path. URL sources use FetchAgentHarness; local sources are contained under configDir.

type SandboxHooks added in v0.0.3

type SandboxHooks struct {
	Tirith                  *TirithConfig        `yaml:"tirith,omitempty"`
	SSRFPreTool             *bool                `yaml:"ssrf_pretool,omitempty"`              // default: true
	SSRFEgressAllowlist     string               `yaml:"ssrf_egress_allowlist,omitempty"`     // comma-separated host:port entries
	SecretRedactPostTool    *bool                `yaml:"secret_redact_posttool,omitempty"`    // default: true
	UnicodePostTool         *bool                `yaml:"unicode_posttool,omitempty"`          // default: true
	ContextSuppressPostTool *bool                `yaml:"context_suppress_posttool,omitempty"` // default: true
	CanaryPreTool           *bool                `yaml:"canary_pretool,omitempty"`            // default: true
	CanaryPostTool          *bool                `yaml:"canary_posttool,omitempty"`           // default: true
	ToolAllowlistPreTool    *ToolAllowlistConfig `yaml:"tool_allowlist_pretool,omitempty"`
}

SandboxHooks configures Claude Code PreToolUse/PostToolUse hooks that run inside the sandbox during agent execution.

type SecurityConfig added in v0.0.3

type SecurityConfig struct {
	Enabled      *bool             `yaml:"enabled,omitempty"`   // nil = true (secure by default)
	FailMode     string            `yaml:"fail_mode,omitempty"` // "closed" or "open". Default: "closed"
	HostScanners *HostScanners     `yaml:"host_scanners,omitempty"`
	SandboxHooks *SandboxHooks     `yaml:"sandbox_hooks,omitempty"`
	Escalation   *EscalationConfig `yaml:"escalation,omitempty"`
	Trace        *TraceConfig      `yaml:"trace,omitempty"`
}

SecurityConfig configures security scanning for the agent run. Secure by default: omitting this block enables all scanners with fail_mode: closed.

type SkillEntry added in v0.37.0

type SkillEntry struct {
	// Source is the skill directory path or URL.
	Source string

	// Overrides maps paths within the skill directory to local override
	// paths. A nil value means the file should be removed from the
	// resolved skill tree. Both the key (path within skill) and the
	// value (override source path) are validated during harness
	// validation.
	Overrides map[string]*string
}

SkillEntry represents a skill source with optional file-level overrides. It supports two YAML forms:

# String form — no overrides
- skills/pr-review

# Object form — with file-level overrides
- skills/pr-review:
    sub-agents/security.md: .fullsend/overrides/security.md
    sub-agents/supply-chain.md: null   # removes this file

func (SkillEntry) HasOverrides added in v0.37.0

func (e SkillEntry) HasOverrides() bool

HasOverrides reports whether this entry has any file-level overrides.

func (SkillEntry) MarshalYAML added in v0.37.0

func (e SkillEntry) MarshalYAML() (interface{}, error)

MarshalYAML implements yaml.Marshaler to round-trip correctly. Entries without overrides are serialized as plain strings; entries with overrides use the map form.

func (*SkillEntry) UnmarshalYAML added in v0.37.0

func (e *SkillEntry) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML implements yaml.Unmarshaler to handle both string and map forms in YAML skill lists.

type TirithConfig added in v0.0.3

type TirithConfig struct {
	Enabled *bool  `yaml:"enabled,omitempty"` // default: true
	FailOn  string `yaml:"fail_on,omitempty"` // "critical", "high", "medium". Default: "high"
}

TirithConfig configures the Tirith Rust CLI scanner for terminal security.

type ToolAllowlistConfig added in v0.5.0

type ToolAllowlistConfig struct {
	Enabled *bool `yaml:"enabled,omitempty"` // default: false (opt-in)
}

ToolAllowlistConfig configures the tool call allowlist PreToolUse hook. Disabled by default — requires FULLSEND_TOOL_ALLOWLIST env var to define the allowed tool set per agent role.

type TraceConfig added in v0.0.3

type TraceConfig struct {
	Enabled *bool `yaml:"enabled,omitempty"` // default: true
}

TraceConfig controls trace ID generation for security finding correlation.

type ValidationLoop

type ValidationLoop struct {
	Script         string `yaml:"script"`
	Schema         string `yaml:"schema,omitempty"`
	MaxIterations  int    `yaml:"max_iterations"`
	FeedbackMode   string `yaml:"feedback_mode,omitempty"`
	PreflightCheck string `yaml:"preflight_check,omitempty"` // shell command to validate host deps before sandbox creation
}

ValidationLoop configures a deterministic validation step after the agent exits.

Jump to

Keyboard shortcuts

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