Documentation
¶
Index ¶
- Constants
- func BasePolicy() []byte
- func DeriveSlug(name string, owner string) string
- func DryRunEnvVar(name string) string
- func ExpandTrigger(on, name string) (string, error)
- func GitConfigOwner(dir string) string
- func PresetNames() []string
- func RoleHelp() string
- func RoleNames() []string
- func ValidateFullsendDir(fullsendDir string) error
- type AgentSpec
- type File
- type Options
- type RepoOwner
- type Result
- type Role
Constants ¶
const ( DefaultModel = "opus" DefaultEffort = "high" DefaultTimeoutMinutes = 15 // DefaultOn is the trigger preset used when neither --on nor --trigger // is given. A trigger is mandatory: ListTriggeredHarnesses skips a // trigger-less harness with a bare `continue` and no annotation, so such // an agent registers, validates, lists, and then never fires. DefaultOn = PresetCommand )
Default values for the generated harness.
const ( // PresetCommand fires on a slash command. entity.kind pins it to issues // and pull requests: a comment on a GitHub Discussion arrives with // entity.kind "conversation", and without this clause the agent would // fire there too and then fail in its post-script, which only accepts an // issue or pull-request URL. The change_proposal clause uses has() // rather than the reference doc's `!= null` because // change_proposal is ABSENT from state on a non-PR comment (schema // $defs.state requires only "labels"; see the jira-fs-triage-comment // and discussion-fs-vouch-comment fixtures), so `!= null` raises a // missing-key error on every issue comment. The guard refuses fork // pull requests without excluding plain issues. PresetCommand = "command" // PresetLabel fires when a label is added. PresetLabel = "label" // PresetIssueOpened fires on new work items. PresetIssueOpened = "issue-opened" // PresetPROpened fires when a non-fork pull request is opened or updated. PresetPROpened = "pr-opened" )
Trigger presets. The expansions below are reproduced from docs/guides/user/cel-triggers-reference.md rather than composed here: an expression that compiles but touches an absent optional field raises a missing-key error at dispatch time, and MatchHarnesses turns that into a red ::error:: annotation on every matching event (internal/harnessdispatch/enumerate.go:95-99). Emitting known-good text is the whole point of generating the trigger instead of asking the user to write one. TestTriggerPresetsArePinned asserts the exact strings.
const DefaultRole = "triage"
DefaultRole is the role assigned when --role is not given. It matches the role the Bring Your Own Agent guide's examples use.
const OpenAIProviderName = "openai"
OpenAIProviderName is the bare provider name every generated harness declares; the runner fills the definition in from the binary, and skips it on a run that does not call OpenAI.
const SpecVersion = "1"
SpecVersion is the only accepted `version:` value in a spec file.
Variables ¶
This section is empty.
Functions ¶
func BasePolicy ¶
func BasePolicy() []byte
BasePolicy returns the base sandbox policy a generated agent's harness names: filesystem, landlock and process rules with no network section, so egress comes only from the harness's providers (ADR 0065). The behaviour suite commits it for scenario harnesses, because OpenShell 0.1 refuses a sandbox with no policy and a policy file that declares no fields.
func DeriveSlug ¶
DeriveSlug builds the default harness slug from the repository owner. The slug is install-time App discovery only — the mint never reads it — so falling back to a constant is safe, but the fallback is reported so the user can pass --slug if they care.
func DryRunEnvVar ¶
DryRunEnvVar is the environment variable that makes a generated post-script print instead of commenting. Derived from the agent name, which has already passed harness.ValidAgentBasename, so the result is always a valid shell identifier.
func ExpandTrigger ¶
ExpandTrigger turns an --on preset into its CEL expression. name supplies the default command and label. The returned expression is not compiled here; the caller runs harness.ValidateTriggerExpression on it before any file is written.
func GitConfigOwner ¶
GitConfigOwner walks up from dir looking for a repository, and returns the owner segment of its origin remote. Pass an absolute path: the walk stops when filepath.Dir stops changing, which for a relative path is ".", so a relative one can never ascend above the process working directory. Returns "" when there is no repository, no origin, or an owner that would not be a valid slug segment.
func PresetNames ¶
func PresetNames() []string
PresetNames lists the recognised --on presets in help order.
func RoleHelp ¶
func RoleHelp() string
RoleHelp renders the role table for error messages and --help text.
func ValidateFullsendDir ¶
ValidateFullsendDir reports whether fullsendDir is usable as a target. Exported so a caller can fail with this message before running any other check, rather than reporting a missing directory as some downstream error.
Types ¶
type AgentSpec ¶
type AgentSpec struct {
Version string `yaml:"version"`
Name string `yaml:"name"`
Role string `yaml:"role,omitempty"`
Description string `yaml:"description,omitempty"`
On string `yaml:"on,omitempty"`
Trigger string `yaml:"trigger,omitempty"`
Model string `yaml:"model,omitempty"`
Effort string `yaml:"effort,omitempty"`
Runtime string `yaml:"runtime,omitempty"`
Slug string `yaml:"slug,omitempty"`
Image string `yaml:"image,omitempty"`
TimeoutMinutes *int `yaml:"timeout_minutes,omitempty"`
ValidationLoop bool `yaml:"validation_loop,omitempty"`
}
AgentSpec is the document accepted by `fullsend agent new -f <file>`. Keys mirror the command-line flags one for one so a local coding agent can emit either form. Command-line flags override spec keys.
func LoadSpecFile ¶
LoadSpecFile reads and validates a spec file.
type File ¶
File is one generated file. Shared is true for scaffold assets that are written only when absent and are never overwritten, even with --force: they are shared between every agent in the directory.
type Options ¶
type Options struct {
Name string
Role string
Description string
Trigger string
Model string
Effort string
Slug string
Image string
TimeoutMinutes int
ValidationLoop bool
// Runtime is the runtime the agent will dispatch under: --runtime, the
// spec's runtime:, or else the repo's config.yaml default, resolved by
// the caller. It is not written to the harness, but decides which
// credentials the harness asks for and whether the model must be an
// OpenAI id.
Runtime string
}
Options is the fully-resolved input to Render, after defaults, spec file and command-line flags have been merged. Every field is already validated: Render assumes it can use them without further checking.
func (Options) UsesVertex ¶ added in v0.45.0
UsesVertex reports whether the agent calls Vertex, and so whether its harness carries the Vertex provider, GCP credentials and Vertex env. codex never does; pi does unless its model has an explicit openai/ prefix.
Not agentruntime.NeedsOpenAIProvider: that reads FULLSEND_PI_PROVIDER from the environment of the run, and the generator runs elsewhere, so the harness would depend on the generating machine.
type RepoOwner ¶
RepoOwner returns the owner segment of the origin remote in gitDir's repository, or "" when it cannot be determined.
type Result ¶
type Result struct {
// Written lists the files created, in generation order. On a dry run it
// lists what would have been created.
Written []string
// Rendered carries the same files with their bodies, for --dry-run.
Rendered []File
// and therefore left alone.
SkippedShared []string
// Diagnostics are non-fatal lint warnings from the generated harness.
Diagnostics []harness.Diagnostic
// HarnessPath is the generated harness, relative to the fullsend dir.
HarnessPath string
}
Result describes what Generate did, so the caller can print next steps and tests can assert on it without reparsing output.
func Generate ¶
Generate renders an agent, validates it, and writes it into fullsendDir.
Ordering matters and is the reason this is not a straight loop of writes: everything is rendered and validated against a temporary tree first, so a harness that would fail validation never leaves a half-written .fullsend directory behind. Options must already have passed Validate.
type Role ¶
type Role struct {
// Name is the harness `role:` value and the mint role.
Name string
// Permissions mirrors mintcore's canonicalRolePermissions for this role.
// It is reproduced here so the CLI can explain what a role grants
// without importing the mint's internals into its help text.
Permissions map[string]string
// Providers are harness `providers:` entries, by bare name. Each is a
// name the fullsend binary ships, so the runner resolves its definition
// and imports its profile from the binary; no providers/ or profiles/
// files and no openshell.profiles entries are written (#7268).
Providers []string
// Image is the sandbox image this role's agents run under.
Image string
// ReadonlyRepo mirrors the fleet: the review harness makes the checked-out
// repository read-only in the sandbox, so a reviewer cannot modify the
// code it reviews. Set for roles whose fleet harness sets `readonly_repo`.
ReadonlyRepo bool
}
Role describes one mint role that `fullsend agent new` will generate for, together with the sandbox resources a harness needs to run under it.
The table is deliberately hardcoded rather than derived from mintcore.BuiltInRoles(). Derivation would re-admit roles the rest of the CLI excludes on purpose — config.ValidRoles() documents that mint-only dogfood roles such as scribe "must not silently pass config validation" — and it would fail open for any future canonical role that has no provider pairing here. RoleTableMatchesMint (roles_test.go) fails CI if the mint and this table drift apart.
func LookupRole ¶
LookupRole returns the Role for name. An unknown role is an error carrying the whole table, so the user sees the valid choices and their permissions rather than discovering the problem as an opaque 403 from the mint at first dispatch.