agentnew

package
v0.49.0 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source
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.

View Source
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.

View Source
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.

View Source
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.

View Source
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

func DeriveSlug(name string, owner string) string

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

func DryRunEnvVar(name string) string

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

func ExpandTrigger(on, name string) (string, error)

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

func GitConfigOwner(dir string) string

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 RoleNames

func RoleNames() []string

RoleNames returns the offered role names in table order.

func ValidateFullsendDir

func ValidateFullsendDir(fullsendDir string) error

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

func LoadSpecFile(path string) (*AgentSpec, error)

LoadSpecFile reads and validates a spec file.

func ParseSpec

func ParseSpec(data []byte) (*AgentSpec, error)

ParseSpec decodes a spec document. Unknown keys are an error rather than a silent no-op: a typo in a spec file would otherwise generate a different agent than the author asked for, which is the failure mode this command exists to remove.

type File

type File struct {
	Path   string
	Data   []byte
	Mode   uint32
	Shared bool
}

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.

func Render

func Render(opts Options) ([]File, error)

Render produces the full set of files for one agent. It performs no I/O beyond reading the embedded templates, so every branch is unit-testable without a filesystem.

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) UsesGateway added in v0.47.0

func (o Options) UsesGateway() bool

UsesGateway reports whether a codex agent's model selects the inference gateway route (gateway/<model>), which needs no OpenAI credential.

func (Options) UsesVertex added in v0.45.0

func (o Options) UsesVertex() bool

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; opencode always does (its OPENCODE_CONFIG_CONTENT carries the Vertex provider registration).

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.

func (*Options) Validate

func (o *Options) Validate() error

Validate checks every field that reaches a generated file, and does so before anything touches disk. Name is checked first and most strictly: it is interpolated into a shell script, so it must satisfy the same pattern harness.Validate relies on for shell safety.

type RepoOwner

type RepoOwner func(dir string) string

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
	// SkippedShared lists shared scaffold assets that were already present
	// 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

func Generate(opts Options, fullsendDir string, force, dryRun bool) (*Result, error)

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

func LookupRole(name string) (Role, error)

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.

Jump to

Keyboard shortcuts

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