Documentation
¶
Index ¶
- Constants
- func BoolDefault(b *bool, def bool) bool
- func BuildConfigMap(cfg config.ConfigReader) map[string]any
- func ChmodPluginDir(dir string) error
- func EvaluateOverlay(expr string, event map[string]any, forgePlatform string, config map[string]any) (bool, error)
- func EvaluateTrigger(expr string, event map[string]any) (bool, error)
- func ForgeKeyList() string
- func IsAbsPath(s string) bool
- func IsProviderPath(s string) bool
- func IsRelPath(s string) bool
- func IsURL(s string) bool
- func LoadWithBase(ctx context.Context, path string, opts ComposeOpts) (*Harness, []Dependency, error)
- func MatchingAllowedPrefixInList(rawURL string, allowlist []string) string
- func NewOverlayEnv() (*cel.Env, error)
- func NewTriggerEnv() (*cel.Env, error)
- func ParseIntegrityHash(rawURL string) (cleanURL, hash string, hasHash bool)
- func SkillSources(entries []SkillEntry) []string
- func ValidForgePlatform(platform string) bool
- func ValidPluginBasename(name string) bool
- func ValidateSkillOverrides(skills []SkillEntry) error
- func ValidateTriggerExpression(expr string) error
- type APIServer
- type AgentInfo
- type ComposeOpts
- type Dependency
- type Diagnostic
- type DiagnosticSeverity
- type EnvConfig
- type EscalationConfig
- type ForgeConfig
- type Harness
- func (h *Harness) EffectiveMaxRuntimeFetches() int
- func (h *Harness) FailModeClosed() bool
- func (h *Harness) HasURLDirResources() bool
- func (h *Harness) HasURLReferences() bool
- func (h *Harness) Lint() []Diagnostic
- func (h *Harness) MatchesAllowedPrefix(rawURL string) bool
- func (h *Harness) MatchingAllowedPrefix(rawURL string) string
- func (h *Harness) OpenShellProfiles() []string
- func (h *Harness) ResolveForge(platform string) error
- func (h *Harness) ResolveOverlays(event map[string]any, forgePlatform string, config map[string]any) error
- func (h *Harness) ResolveRelativeTo(baseDir string) error
- func (h *Harness) Scripts() []string
- func (h *Harness) SecurityEnabled() bool
- func (h *Harness) Validate() error
- func (h *Harness) ValidateAllowedRemoteResources(orgAllowlist []string) error
- func (h *Harness) ValidateFilesExist() error
- func (h *Harness) ValidatePluginDirs() error
- func (h *Harness) ValidateResourceTypes() error
- func (h *Harness) ValidateRunnerEnv() error
- func (h *Harness) ValidateRunnerEnvWith(lookup func(string) (string, bool)) error
- type HostFile
- type HostScanners
- type LLMGuardConfig
- type LoadOpts
- type OpenShellConfig
- type OverlayEntry
- type PiPluginOptions
- type PluginSpec
- type ProviderDef
- type RegisteredAgent
- type ResolvedPath
- type SandboxHooks
- type SecurityConfig
- type SkillEntry
- type TirithConfig
- type ToolAllowlistConfig
- type TraceConfig
- type ValidationLoop
Constants ¶
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
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 (e.g. org-mode configs).
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
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
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 IsProviderPath ¶ added in v0.34.0
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
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
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:
- LoadRaw(path) — preserves forge map
- If base absent: resolve URL-sourced resources → ResolveForge → ResolveOverlays → Validate → return
- 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
- Resolve remaining URL-sourced resources and scripts (child's own relative paths)
- ResolveForge and ResolveOverlays on child's own forge/overlay blocks
- Validate
When base is absent, this behaves identically to LoadWithOpts.
func MatchingAllowedPrefixInList ¶ added in v0.18.0
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
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
NewTriggerEnv creates a CEL environment with root variable event (dyn type).
func ParseIntegrityHash ¶ added in v0.11.0
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 ValidForgePlatform ¶ added in v0.18.0
ValidForgePlatform reports whether platform is a recognized forge key.
func ValidPluginBasename ¶ added in v0.34.0
ValidPluginBasename reports whether name matches the allowed plugin name pattern.
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
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
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 allowed_remote_resources from config.yaml (org-level
// or per-repo-level). Base URLs and agent source URLs must match a prefix
// in this list. Callers should merge org and per-repo allowlists when both
// are available.
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 (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"`
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 LoadRaw ¶ added in v0.18.0
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
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
EffectiveMaxRuntimeFetches returns the configured max runtime fetches, or defaultMaxRuntimeFetches (10) when the field is omitted.
func (*Harness) FailModeClosed ¶ added in v0.0.3
FailModeClosed returns true if the security fail mode is "closed" (default).
func (*Harness) HasURLDirResources ¶ added in v0.34.0
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
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
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
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 (*Harness) ResolveForge ¶ added in v0.17.0
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 ¶
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
Scripts returns all script paths configured in the harness.
func (*Harness) SecurityEnabled ¶ added in v0.0.3
SecurityEnabled returns true if security scanning is enabled (default: true).
func (*Harness) ValidateAllowedRemoteResources ¶ added in v0.12.0
ValidateAllowedRemoteResources checks that each entry in AllowedRemoteResources is a valid HTTPS URL ending with "/" and is covered by at least one entry in the org-level allowlist. Org allowlist entries are also validated: each must be a valid HTTPS URL ending with "/" and must not contain double-encoded sequences.
func (*Harness) ValidateFilesExist ¶
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
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
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 ¶
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
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.