v1alpha1

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 28, 2026 License: AGPL-3.0 Imports: 17 Imported by: 0

Documentation

Overview

Package v1alpha1 holds the Go types for every factory kind: the config kinds that live in git under catalog/ (Provider, Group, Template, Rule, RuleSet, TaskSpec, Queue, Pool), the runtime kinds the dispatcher stores (Event, WorkItem, Task, Run, Agent, Effect, BudgetCounter, Approval), the agent's Result, the capability descriptors, the event vocabulary and the effect ops.

These types are the contract between workstreams (design/workstreams/foundation/LLD/contracts.md). Change them in their own PR. The JSON Schemas under schemas/ are generated from them by ./schemagen (make schemas).

Decoding is strict: Decode rejects unknown fields, unknown kinds and a foreign apiVersion. Values are kept as written (durations, patterns, templated values) so that a decoded document marshals back to the same document; checking them is the catalog loader's job.

Index

Constants

View Source
const (
	// MaxEnvScriptBytes is the most bytes each of setup, up and down may hold.
	MaxEnvScriptBytes = 64 << 10
	// MaxEnvReadyURLs is the most URLs ready.http may list.
	MaxEnvReadyURLs = 10
	// MaxEnvReadyTimeout is the longest ready.timeout.
	MaxEnvReadyTimeout = 60 * time.Minute
	// MaxEnvExposes is the most variables exposes may set.
	MaxEnvExposes = 20
	// MaxEnvExposeValueBytes is the most bytes an exposes value may hold.
	MaxEnvExposeValueBytes = 2048
	// MaxVersions is the most components a Task's spec.versions may list.
	MaxVersions = 50
	// MaxVersionBytes is the most bytes a spec.versions value may hold.
	MaxVersionBytes = 128
)

Limits of a workspace environment (P1 §4).

View Source
const (
	// EnvExposeNamePattern is what an exposes name must match.
	EnvExposeNamePattern = `^FACTORY_[A-Z0-9_]+$`
	// EnvVersionPrefix starts the variable the runtime exports for each spec.versions entry
	// (FACTORY_VERSION_<COMPONENT>); exposes may not use it.
	EnvVersionPrefix = "FACTORY_VERSION_"
	// VersionComponentPattern is what a spec.versions key must match.
	VersionComponentPattern = `^[a-z0-9][a-z0-9-]{0,62}$`
)

Patterns of a workspace environment. The schema uses the same ones.

View Source
const (
	KindProvider      = "Provider"
	KindGroup         = "Group"
	KindTemplate      = "Template"
	KindRule          = "Rule"
	KindRuleSet       = "RuleSet"
	KindTaskSpec      = "TaskSpec"
	KindQueue         = "Queue"
	KindPool          = "Pool"
	KindEvent         = "Event"
	KindWorkItem      = "WorkItem"
	KindTask          = "Task"
	KindRun           = "Run"
	KindAgent         = "Agent"
	KindEffect        = "Effect"
	KindBudgetCounter = "BudgetCounter"
	KindApproval      = "Approval"
)

Kind names.

View Source
const (
	SelectorOpIn           = "In"
	SelectorOpNotIn        = "NotIn"
	SelectorOpExists       = "Exists"
	SelectorOpDoesNotExist = "DoesNotExist"
)

Label selector operators.

View Source
const APIVersion = "factory.ccf.dev/v1alpha1"

APIVersion is the only apiVersion this package accepts. Documents may omit it.

View Source
const ExprPattern = `^=|\{\{[\s\S]*\}\}`

ExprPattern is what an expression string must match: it starts with "=" (CEL) or contains a "{{ … }}" template. The schema uses the same pattern.

View Source
const FactoryEventPrefix = "factory."

FactoryEventPrefix starts every type only the factory provider may emit.

View Source
const FactoryProvider = "factory"

FactoryProvider is the name (and type) of the built-in provider, the only source of factory.* events.

View Source
const HostPattern = `^(\*\.)?([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]([a-z0-9-]{0,61}[a-z0-9])?` +
	`(:([1-9][0-9]{0,3}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5]))?$`

HostPattern is what a host list entry must match: at least two lowercase RFC 1123 labels, an optional single leading "*." label followed by at least two more, a last label that starts with a letter (so no IPv4 literal fits) and an optional port 1-65535. No scheme, path or userinfo. The schema uses the same pattern; ValidateHost also checks the total length and refuses localhost.

View Source
const LimitsMemoryPattern = `^[1-9][0-9]{0,5}Gi$`

LimitsMemoryPattern is a whole number of GiB with the Gi suffix: the form of limits.memory and of the agent's workspace.size.memory and .disk (config.GiB parses all three with it). limits.memory must also be at least WorkspaceMinMemoryGiB (limitsMemoryMinPattern).

View Source
const MaxDecisions = 200

MaxDecisions is how many decisions a work item keeps.

View Source
const MaxWorkspaceHosts = 20

MaxWorkspaceHosts is the most entries a host list (workspace.environment.egress.allow) may have.

View Source
const ResultSchemaFile = "result.schema.json"

ResultSchemaFile is the file name of the Result schema.

View Source
const SchemaBaseURL = "https://factory.ccf.dev/schemas/v1alpha1/"

SchemaBaseURL is the base of the generated schemas' $id.

View Source
const WorkspaceMinMemoryGiB = 2

WorkspaceMinMemoryGiB is the least memory a workspace VM has, on every driver: limits.memory's minimum, and the agent config's for workspace.size.memory.

Variables

View Source
var (
	ErrUnknownKind = errors.New("unknown kind")
	ErrMissingKind = errors.New("missing kind")
	ErrAPIVersion  = errors.New("unsupported apiVersion")
)

Decoding errors, wrapped by DocumentError.

View Source
var (
	ErrEnvVersionsFrom   = errors.New("invalid versions.from")
	ErrEnvVersionsInput  = errors.New("invalid versions.input")
	ErrEnvScriptTooLong  = errors.New("script too long")
	ErrEnvNoUp           = errors.New("needs up")
	ErrEnvReadyURL       = errors.New("invalid ready URL")
	ErrEnvReadyTimeout   = errors.New("invalid ready timeout")
	ErrEnvExposeName     = errors.New("invalid exposes name")
	ErrEnvTooManyExposes = errors.New("too many exposes")
	ErrEnvExposeValue    = errors.New("invalid exposes value")
	ErrEnvEgressMode     = errors.New("invalid egress mode")
	ErrEnvEgressAllow    = errors.New("egress.allow needs deny-by-default")
	ErrEnvVersions       = errors.New("invalid versions")
)

Environment validation errors. Workspace.Validate and Task.Validate return a *ValidationError wrapping one of them (or a host error, for egress.allow).

View Source
var (
	ErrHostSyntax    = errors.New("not a hostname")
	ErrHostWildcard  = errors.New("wildcard not allowed")
	ErrHostIP        = errors.New("IP literal not allowed")
	ErrHostLocalhost = errors.New("localhost not allowed")
	ErrHostPort      = errors.New("invalid port")
	ErrTooManyHosts  = errors.New("too many hosts")
)

Host validation errors. A *HostError wraps exactly one of them; validateHostList wraps it in a *ValidationError, so errors.Is works on a decode error too.

View Source
var (
	ErrLimitsCPUs   = errors.New("invalid limits.cpus")
	ErrLimitsMemory = errors.New("invalid limits.memory")
)

Limits validation errors. Limits.Validate wraps one in a *ValidationError.

View Source
var ActionTypes = []string{"dispatch", "set", "notify", "requestApproval", "cancel", "link", "effect"}

ActionTypes are the member names of Action, in order.

View Source
var ErrInvalidSelector = errors.New("invalid label selector")

ErrInvalidSelector is wrapped by LabelSelector.Validate's errors.

View Source
var ReservedEnvNames = []string{
	"FACTORY_API",
	"FACTORY_EFFECTOR",
	"FACTORY_GIT_CREDENTIAL_SOCKET",
	"FACTORY_HARNESS",
	"FACTORY_HEADLESS",
	"FACTORY_OUT",
	"FACTORY_RESULT",
	"FACTORY_STACK_DIR",
	"FACTORY_STACK_PROJECT",
	"FACTORY_STACK_VERSIONS",
	"FACTORY_TASK_ID",
	"FACTORY_TOKEN",
}

ReservedEnvNames are the FACTORY_* variables the agent runtime sets in a run's environment (internal/agent: pipeline, gitcred, effector and stack). The runtime owns them, so an environment's exposes may not set them, nor any EnvVersionPrefix name. FACTORY_STACK_URL and FACTORY_STACK_API are not reserved: P1 §4 moves them from the stack to exposes.

Functions

func ConfigKinds

func ConfigKinds() []string

ConfigKinds lists the kinds that live in the catalog, in a fixed order.

func Encode

func Encode(obj Object) ([]byte, error)

Encode marshals an object to block-style YAML. It writes apiVersion only when the object has one.

func IsConfigKind

func IsConfigKind(kind string) bool

IsConfigKind reports whether kind is a catalog kind.

func IsExpression

func IsExpression(s string) bool

IsExpression reports whether s is an expression string (matches ExprPattern).

func NewReflector

func NewReflector() *jsonschema.Reflector

NewReflector returns the JSON Schema reflector Schemas uses: anonymous (no $id), the root struct expanded, other named types under $defs, generic types named without their package paths (ExprOr[…v1alpha1.HarnessRequest] → ExprOrHarnessRequest), free-form maps open (freeFormMap). Other generators (the OpenAPI components in api/) use it so their schemas match these.

func RuntimeKinds

func RuntimeKinds() []string

RuntimeKinds lists the kinds that live in the dispatcher's store, in a fixed order.

func SchemaFile

func SchemaFile(kind string) string

SchemaFile returns the schema file name for a config kind, e.g. taskspec.schema.json.

func Schemas

func Schemas() (map[string][]byte, error)

Schemas generates the JSON Schema of every config kind and of Result, keyed by file name. The output is deterministic and indented, with a trailing newline. Objects refuse additional properties, matching strict decoding.

func ValidateHost

func ValidateHost(h string) error

ValidateHost checks one host list entry: a lowercase hostname of at least two RFC 1123 labels, at most 253 characters, with an optional port and an optional single leading "*." label followed by at least two labels (*.example.com, not *.com). It refuses schemes, paths, userinfo, other wildcards, single-label names, IP literals and localhost, returning a *HostError.

Types

type Action

type Action struct {
	Dispatch *DispatchAction `json:"dispatch,omitzero"`
	// Set updates work-item state keys; values are literals or "=CEL".
	Set    map[string]any `json:"set,omitzero"`
	Notify *NotifyAction  `json:"notify,omitzero"`
	// RequestApproval creates an Approval (future, Q18): accepted by the schema, the engine
	// returns Unsupported in the PoC.
	RequestApproval *ApprovalSpec `json:"requestApproval,omitzero"`
	Cancel          *CancelAction `json:"cancel,omitzero"`
	Link            *LinkAction   `json:"link,omitzero"`
	Effect          *EffectAction `json:"effect,omitzero"`
}

Action is a tagged union: exactly one member is set. String values starting with "=" are CEL evaluated at runtime; "{{ params.x }}" is substituted at catalog load.

func (Action) JSONSchemaExtend

func (Action) JSONSchemaExtend(s *jsonschema.Schema)

JSONSchemaExtend enforces the one-of in the schema: every property is a member and additional properties are refused, so exactly one property means exactly one member.

func (*Action) Type

func (a *Action) Type() string

Type returns the name of the member that is set, or "" when none is.

func (*Action) Validate

func (a *Action) Validate() error

Validate checks that exactly one member is set, and the notify destinations.

type Actor

type Actor struct {
	// ID is provider-instance:login, e.g. github-public:octocat.
	ID        string `json:"id"`
	Tier      string `json:"tier,omitzero"`
	IsBot     bool   `json:"isBot,omitzero"`
	IsFactory bool   `json:"isFactory,omitzero"`
	// Identity is the factory identity (author, reviewer) when IsFactory.
	Identity string `json:"identity,omitzero"`
}

Actor is who caused an event.

type AdapterCapabilities

type AdapterCapabilities struct {
	Harness string `json:"harness"`
	// EffortMapping maps a normalised effort to the harness's native value.
	EffortMapping map[string]string `json:"effortMapping,omitzero"`
	// Features: "structured-output", "mcp", "plugins", "skills-dir".
	Features []string `json:"features,omitzero"`
}

AdapterCapabilities is published by each harness adapter (static per adapter version). `factory validate --capabilities` checks catalog patterns against it.

type Admission

type Admission struct {
	TokenRef SecretRef `json:"tokenRef"`
	// Owners is the Group of the people expected to lend agents here (informational: the
	// admin who mints an enrollment names its owner).
	Owners string `json:"owners"`
}

Admission marks a registered pool that takes enrollments (P1 §6): an admin mints them with createEnrollment, naming each agent's owner. Since P1 phase 6 the dispatcher reads neither field: TokenRef was the removed join token's secret, and Owners, shown in the UI, is informational (who is expected to lend agents here).

type Agent

type Agent struct {
	TypeMeta
	Metadata ObjectMeta   `json:"metadata"`
	Spec     AgentSpec    `json:"spec"`
	Status   *AgentStatus `json:"status,omitzero"`
}

Agent is a registered worker.

func (*Agent) GetName

func (a *Agent) GetName() string

GetName returns metadata.name.

type AgentCapabilities

type AgentCapabilities struct {
	Harnesses []HarnessOffer `json:"harnesses,omitzero"`
	Labels    []string       `json:"labels,omitzero"`
}

AgentCapabilities are the agent's harness offers and labels.

type AgentPhase

type AgentPhase string

AgentPhase is a registered agent's state.

const (
	AgentReady     AgentPhase = "Ready"
	AgentBusy      AgentPhase = "Busy"
	AgentThrottled AgentPhase = "Throttled"
	AgentDraining  AgentPhase = "Draining"
	AgentOffline   AgentPhase = "Offline"
)

Agent phases.

func AgentPhases

func AgentPhases() []AgentPhase

AgentPhases lists the agent phases.

func (AgentPhase) JSONSchema

func (AgentPhase) JSONSchema() *jsonschema.Schema

JSONSchema makes AgentPhase an enum of AgentPhases.

type AgentSpec

type AgentSpec struct {
	Pool string `json:"pool"`
	// Owner must be in the pool's owners Group.
	Owner        string            `json:"owner"`
	Capabilities AgentCapabilities `json:"capabilities"`
	Lending      *Lending          `json:"lending,omitzero"`
}

AgentSpec is what the agent offers and what its owner lends.

type AgentStatus

type AgentStatus struct {
	Phase          AgentPhase  `json:"phase"`
	ThrottledUntil *time.Time  `json:"throttledUntil" jsonschema:"nullable"`
	LastHeartbeat  time.Time   `json:"lastHeartbeat,omitzero"`
	Running        []string    `json:"running,omitzero"`
	Today          *AgentUsage `json:"today,omitzero"`
}

AgentStatus is the agent's state. ThrottledUntil is null unless the harness reported plan limits.

type AgentUsage

type AgentUsage struct {
	Runs   int   `json:"runs"`
	Tokens int64 `json:"tokens"`
}

AgentUsage is the agent's usage today, checked against its lending.

type AppIdentity

type AppIdentity struct {
	AppID         int64     `json:"appID"`
	PrivateKeyRef SecretRef `json:"privateKeyRef"`
}

AppIdentity is a GitHub App.

type Approval

type Approval struct {
	TypeMeta
	Metadata ApprovalMeta    `json:"metadata"`
	Spec     ApprovalSpec    `json:"spec"`
	Status   *ApprovalStatus `json:"status,omitzero"`
}

Approval turns "a human said yes" into one factory event. Type only in the PoC (Q18).

func (*Approval) GetName

func (a *Approval) GetName() string

GetName returns metadata.name.

type ApprovalDecision

type ApprovalDecision struct {
	By       string    `json:"by"`
	Decision string    `json:"decision"`
	At       time.Time `json:"at"`
	Via      string    `json:"via,omitzero"`
}

ApprovalDecision is one human's answer.

type ApprovalMeta

type ApprovalMeta struct {
	ObjectMeta
	WorkItem string `json:"workItem"`
}

ApprovalMeta is ObjectMeta plus the work item the approval belongs to.

type ApprovalPhase

type ApprovalPhase string

ApprovalPhase is an Approval's state: Pending → Granted | Denied | Expired.

const (
	ApprovalPending ApprovalPhase = "Pending"
	ApprovalGranted ApprovalPhase = "Granted"
	ApprovalDenied  ApprovalPhase = "Denied"
	ApprovalExpired ApprovalPhase = "Expired"
)

Approval phases.

func ApprovalPhases

func ApprovalPhases() []ApprovalPhase

ApprovalPhases lists the approval phases.

func (ApprovalPhase) JSONSchema

func (ApprovalPhase) JSONSchema() *jsonschema.Schema

JSONSchema makes ApprovalPhase an enum of ApprovalPhases.

type ApprovalRef

type ApprovalRef struct {
	Name  string        `json:"name"`
	Phase ApprovalPhase `json:"phase"`
}

ApprovalRef is an approval's name and phase, as shown on the work item.

type ApprovalSpec

type ApprovalSpec struct {
	// Name is what rules test: approval.name == 'implement'.
	Name string `json:"name"`
	// Approvers is a Group.
	Approvers string `json:"approvers"`
	Quorum    int    `json:"quorum,omitzero"`
	// Via is where it's presented and answers are accepted.
	Via      []string `json:"via,omitzero"`
	Template string   `json:"template,omitzero"`
	Expires  Duration `json:"expires,omitzero"`
}

ApprovalSpec is what is asked, of whom. It is also the payload of the requestApproval action.

type ApprovalStatus

type ApprovalStatus struct {
	Phase     ApprovalPhase      `json:"phase"`
	Decisions []ApprovalDecision `json:"decisions,omitzero"`
}

ApprovalStatus is the approval's state and the decisions so far.

type Artifact

type Artifact struct {
	Kind string `json:"kind"`
	URL  string `json:"url,omitzero"`
	Ref  string `json:"ref,omitzero"`
}

Artifact is something the run produced.

type Budget

type Budget struct {
	Daily *BudgetLimit `json:"daily,omitzero"`
}

Budget caps spend.

type BudgetCounter

type BudgetCounter struct {
	TypeMeta
	Metadata ObjectMeta          `json:"metadata"`
	Status   BudgetCounterStatus `json:"status"`
}

BudgetCounter counts spend in one budget window. Its name is budget.<scope>.<name>.<YYYY-MM-DD>; the scheduler updates it with compare-and-swap.

func (*BudgetCounter) GetName

func (b *BudgetCounter) GetName() string

GetName returns metadata.name.

type BudgetCounterStatus

type BudgetCounterStatus struct {
	Runs   int     `json:"runs"`
	Tokens int64   `json:"tokens"`
	USD    float64 `json:"usd"`
}

BudgetCounterStatus is the spend so far.

type BudgetLimit

type BudgetLimit struct {
	Runs   int     `json:"runs,omitzero"`
	Tokens int64   `json:"tokens,omitzero"`
	USD    float64 `json:"usd,omitzero"`
}

BudgetLimit is one budget window's limits; an unset limit is unlimited.

type CancelAction

type CancelAction struct {
	TaskSpec string `json:"taskSpec"`
}

CancelAction cancels the active tasks of a task spec for the work item.

type ChannelRef

type ChannelRef struct {
	Provider string `json:"provider"`
	Name     string `json:"name"`
}

ChannelRef is a channel on a provider.

type CloseReason

type CloseReason string

CloseReason is why a work item was closed.

const (
	CloseDone      CloseReason = "done"
	CloseWontDo    CloseReason = "wont-do"
	CloseDuplicate CloseReason = "duplicate"
)

Close reasons.

func CloseReasons

func CloseReasons() []CloseReason

CloseReasons lists the close reasons, in the order of WorkItemClosed.Reason's enum.

func (CloseReason) Valid

func (r CloseReason) Valid() bool

Valid reports whether r is a close reason.

type ContextItem

type ContextItem struct {
	Kind     string `json:"kind"`
	Provider string `json:"provider,omitzero"`
	Ref      string `json:"ref"`
	Trust    string `json:"trust,omitzero"`
	Mount    string `json:"mount,omitzero"`
}

ContextItem is something the agent is given, with its trust label.

type Debounce

type Debounce struct {
	Window Duration `json:"window"`
	Key    string   `json:"key,omitzero"`
}

Debounce collapses bursts of events into one action.

type Decision

type Decision struct {
	At      time.Time `json:"at,omitzero"`
	Event   string    `json:"event,omitzero"`
	RuleSet string    `json:"ruleSet,omitzero"`
	Rule    string    `json:"rule,omitzero"`
	Fired   bool      `json:"fired,omitzero"`
	// Inputs are the values `where` saw.
	Inputs  map[string]any `json:"inputs,omitzero"`
	Rails   []RailVerdict  `json:"rails,omitzero"`
	Actions []string       `json:"actions,omitzero"`
	Reason  string         `json:"reason,omitzero"`
	// Replay marks a decision an admin's replay of its event made (replayEvent): only the
	// decisions that differ from the event's earlier ones are recorded.
	Replay bool `json:"replay,omitzero"`
}

Decision records why a rule did (or didn't) act: the UI's "why did this happen?".

type Destination

type Destination struct {
	Group   string      `json:"group,omitzero" jsonschema:"minLength=1"`
	Via     string      `json:"via,omitzero"`
	As      string      `json:"as,omitzero" jsonschema:"enum=mention,enum=dm"`
	Channel *ChannelRef `json:"channel,omitzero"`
	// Item comments on, or replies in, the work item's linked objects.
	Item string `json:"item,omitzero" jsonschema:"enum=primary,enum=threads,enum=all"`
}

Destination is one recipient of a notification. Set one of group, channel or item.

func (Destination) JSONSchemaExtend

func (Destination) JSONSchemaExtend(s *jsonschema.Schema)

JSONSchemaExtend requires exactly one of group, channel or item.

func (*Destination) Validate

func (d *Destination) Validate() error

Validate checks that exactly one of group, channel or item is set.

type DispatchAction

type DispatchAction struct {
	TaskSpec string `json:"taskSpec"`
	Queue    string `json:"queue"`
	// Inputs must match the TaskSpec's declared inputs.
	Inputs   map[string]any          `json:"inputs,omitzero"`
	Harness  *ExprOr[HarnessRequest] `json:"harness,omitzero"`
	Requires *Requires               `json:"requires,omitzero"`
	// Context lists what the agent is given, e.g. event.object.
	Context []string `json:"context,omitzero"`
	Target  *Target  `json:"target,omitzero"`
}

DispatchAction creates a Task (Pending) in a queue.

type DocumentError

type DocumentError struct {
	// Index is the 0-based index of the document among the non-empty documents.
	Index int
	// Line is the 1-based line of the document's root node; 0 when unknown (YAML syntax errors
	// carry their line in Err).
	Line int
	// Kind is the document's kind, when it could be read.
	Kind string
	Err  error
}

DocumentError is an error in one document of a (multi-document) YAML stream.

func (*DocumentError) Error

func (e *DocumentError) Error() string

func (*DocumentError) Unwrap

func (e *DocumentError) Unwrap() error

type Duration

type Duration string

Duration is a duration as written in the catalog ("30s", "10m", "7d"). The original string is kept so documents round-trip exactly; Parse gives the time.Duration.

func (Duration) JSONSchema

func (Duration) JSONSchema() *jsonschema.Schema

JSONSchema describes Duration as a string.

func (Duration) Parse

func (d Duration) Parse() (time.Duration, error)

Parse returns the duration. On top of time.ParseDuration it accepts a leading whole number of days: "7d", "1d12h".

func (Duration) String

func (d Duration) String() string

String returns the duration as written.

type Effect

type Effect struct {
	TypeMeta
	Metadata ObjectMeta    `json:"metadata"`
	Spec     EffectSpec    `json:"spec"`
	Status   *EffectStatus `json:"status,omitzero"`
}

Effect is an audit record of one provider write.

func (*Effect) GetName

func (e *Effect) GetName() string

GetName returns metadata.name.

type EffectAction

type EffectAction struct {
	Op EffectOp `json:"op"`
	// Target is the object to act on: primary, a ref, or "=CEL".
	Target string `json:"target,omitzero"`
	// Args are the op-specific fields, every key other than op and target. The catalog
	// loader checks them per op.
	Args map[string]any `json:"-"`
}

EffectAction is a direct, no-LLM provider effect: the op, an optional target and the op-specific fields written inline, e.g. { op: label.add, labels: [needs-human] }. Inline fields keep the catalog readable (design/04-flows.md). The Effector HTTP request is {op, target, args, idempotencyKey}; the dispatcher maps Args to args.

func (EffectAction) JSONSchemaExtend

func (EffectAction) JSONSchemaExtend(s *jsonschema.Schema)

JSONSchemaExtend allows the inline op-specific fields.

func (EffectAction) MarshalJSON

func (e EffectAction) MarshalJSON() ([]byte, error)

MarshalJSON writes op, target, then the op-specific fields inline in sorted key order.

func (*EffectAction) UnmarshalJSON

func (e *EffectAction) UnmarshalJSON(data []byte) error

UnmarshalJSON reads op and target, and collects every other key into Args.

type EffectOp

type EffectOp string

EffectOp is a provider effect, as named in TaskSpec effects.allow and the effect action.

const (
	OpComment              EffectOp = "comment"
	OpPRComment            EffectOp = "pr.comment"
	OpLabelAdd             EffectOp = "label.add"
	OpLabelRemove          EffectOp = "label.remove"
	OpCreateIssue          EffectOp = "create-issue"
	OpSubIssueAdd          EffectOp = "sub-issue.add"
	OpClose                EffectOp = "close"
	OpLinkDuplicate        EffectOp = "link-duplicate"
	OpPROpen               EffectOp = "pr.open"
	OpPRUpdate             EffectOp = "pr.update"
	OpPRRetarget           EffectOp = "pr.retarget"
	OpPRMerge              EffectOp = "pr.merge"
	OpReviewComment        EffectOp = "review.comment"
	OpReviewRequestChanges EffectOp = "review.request-changes"
	OpReviewApprove        EffectOp = "review.approve"
	OpThreadReply          EffectOp = "thread.reply"
	OpThreadResolve        EffectOp = "thread.resolve"
	OpPushBranch           EffectOp = "push-branch"
	OpStackPush            EffectOp = "stack.push"
	OpStackRebase          EffectOp = "stack.rebase"
)

Effect ops.

func EffectOps

func EffectOps() []EffectOp

EffectOps lists every effect op, in a fixed order.

func (EffectOp) JSONSchema

func (EffectOp) JSONSchema() *jsonschema.Schema

JSONSchema describes EffectOp as the enum of known ops.

func (EffectOp) Known

func (o EffectOp) Known() bool

Known reports whether o is a known effect op.

func (EffectOp) Side

func (o EffectOp) Side() (side Side, ok bool)

Side returns who executes op; ok is false for an unknown op.

type EffectResult

type EffectResult struct {
	URL   string `json:"url,omitzero"`
	Error string `json:"error,omitzero"`
}

EffectResult is the outcome of an effect.

type EffectSpec

type EffectSpec struct {
	Task           string         `json:"task"`
	Op             EffectOp       `json:"op"`
	Target         ObjectRef      `json:"target"`
	IdempotencyKey string         `json:"idempotencyKey"`
	Identity       string         `json:"identity,omitzero"`
	Request        map[string]any `json:"request,omitzero"`
}

EffectSpec is what was asked.

type EffectStatus

type EffectStatus struct {
	Result *EffectResult `json:"result,omitzero"`
	At     time.Time     `json:"at,omitzero"`
}

EffectStatus is what happened.

type EffectiveConfig

type EffectiveConfig struct {
	Model           string `json:"model"`
	ReasoningEffort string `json:"reasoningEffort,omitzero"`
}

EffectiveConfig is the exact config the harness ran with.

type EffectsPolicy

type EffectsPolicy struct {
	Allow []EffectOp `json:"allow,omitzero"`
	// Labels are globs every label an effect can write is checked against: label.add/remove,
	// and the labels other ops carry (create-issue and pr.open labels, pr.merge's mergeLabel).
	Labels []string `json:"labels,omitzero"`
}

EffectsPolicy is what a task may do.

type EgressPolicy

type EgressPolicy struct {
	// Mode is default (open through the gateway, except its denied ranges) or deny-by-default
	// (only Allow, plus the git host and the dispatcher).
	Mode string `json:"mode,omitzero" jsonschema:"enum=default,enum=deny-by-default"`
	// Allow are hostnames reachable under deny-by-default: each a lowercase hostname of at
	// least two labels with an optional port and an optional single leading "*." label
	// followed by at least two labels (*.example.com, not *.com); no scheme, path, userinfo,
	// IP literal or localhost; at most 20 (ValidateHost). Only valid with deny-by-default.
	Allow []string `json:"allow,omitzero"`
}

EgressPolicy narrows a workspace's network.

func (EgressPolicy) JSONSchemaExtend

func (EgressPolicy) JSONSchemaExtend(s *jsonschema.Schema)

JSONSchemaExtend constrains allow (extendHostListSchema).

type Environment

type Environment struct {
	// Versions says where component versions come from; the compiler resolves them into the
	// Task's spec.versions.
	Versions *VersionSource `json:"versions,omitzero"`
	// Setup runs first (install tools the base image lacks); Up brings the environment up;
	// Down runs best effort at the end. Each is a shell script for /bin/bash, at most 64 KiB.
	Setup string `json:"setup,omitzero"`
	Up    string `json:"up,omitzero"`
	Down  string `json:"down,omitzero"`
	// Ready is checked after Up; the run fails (environment failure) if it isn't ready in time.
	Ready *ReadyCheck `json:"ready,omitzero"`
	// Exposes are exported to the harness's environment: FACTORY_* names to values, typically
	// URLs inside the workspace (FACTORY_STACK_URL: http://localhost:8000). At most 20; no
	// name the runtime sets (ReservedEnvNames, FACTORY_VERSION_*).
	Exposes map[string]string `json:"exposes,omitzero"`
	// Egress narrows the workspace's network (P1 §3); default is open through the gateway.
	// Egress widens what a prompt-injected run could reach, so a catalog change to egress.allow
	// (or a mode away from deny-by-default) needs two approvals (FACTORY-CAT-002).
	Egress *EgressPolicy `json:"egress,omitzero"`
}

Environment is what a task's workspace brings up before the harness runs (P1 §4): plain commands run as root inside the task's VM workspace, which has its own Docker. It never runs on the dispatcher, and the factory knows nothing about what the commands start.

func (Environment) JSONSchemaExtend

func (Environment) JSONSchemaExtend(s *jsonschema.Schema)

JSONSchemaExtend constrains the scripts' length (in characters, so the byte limit only Validate checks) and exposes (names, reserved names, count, values).

func (*Environment) Validate

func (e *Environment) Validate() error

Validate checks the environment's rules. Field paths are relative to the environment (versions.from, ready.http[0]). TaskSpec.Validate also checks that versions.input names one of the spec's inputs.

type Event

type Event struct {
	TypeMeta
	ID      string    `json:"id"`
	Source  string    `json:"source"`
	Type    EventType `json:"type"`
	Subject string    `json:"subject,omitzero"`
	Time    time.Time `json:"time"`
	Data    EventData `json:"data"`
	// WorkItem is set on factory.* events, which always carry their work item.
	WorkItem string `json:"workItem,omitzero"`
}

Event is a normalised provider event, shaped as a CloudEvent: its identity is (Source = provider instance or "factory", Type).

func (*Event) GetName

func (e *Event) GetName() string

GetName returns the event id.

type EventData

type EventData struct {
	Provider   string         `json:"provider"`
	Actor      *Actor         `json:"actor,omitzero"`
	Object     *ObjectRef     `json:"object,omitzero"`
	Repo       string         `json:"repo,omitzero"`
	ContentRef string         `json:"contentRef,omitzero"`
	Facts      map[string]any `json:"facts,omitzero"`
	// Effect is the idempotency key of the factory effect that created the event's object
	// (its Effect's spec.idempotencyKey), read from the object's hidden effect marker. Set
	// only on the event that creates the object, and only when the factory's own App wrote it.
	Effect string `json:"effect,omitzero"`
	// Raw is the provider payload, kept for audit; never shown to rules.
	Raw json.RawMessage `json:"raw,omitzero"`
}

EventData is the event's payload.

type EventType

type EventType string

EventType is a normalised event type. Rules match it in `on`.

const (
	EventIssueOpened    EventType = "issue.opened"
	EventIssueCommented EventType = "issue.commented"
	EventIssueLabeled   EventType = "issue.labeled"
	EventIssueClosed    EventType = "issue.closed"

	EventPROpened          EventType = "pr.opened"
	EventPRUpdated         EventType = "pr.updated"
	EventPRReadyForReview  EventType = "pr.ready_for_review"
	EventPRLabeled         EventType = "pr.labeled"
	EventPRReviewSubmitted EventType = "pr.review.submitted"
	EventPRChecksCompleted EventType = "pr.checks.completed"
	EventPRMerged          EventType = "pr.merged"
	EventPRClosed          EventType = "pr.closed"

	EventReleasePublished EventType = "release.published"

	EventDeploySucceeded EventType = "deploy.succeeded"
	EventDeployFailed    EventType = "deploy.failed"

	EventMessagePosted  EventType = "message.posted"
	EventMessageMention EventType = "message.mention"
)

Provider event types.

const (
	EventFactoryRunCompleted      EventType = "factory.run.completed"
	EventFactoryRunFailed         EventType = "factory.run.failed"
	EventFactoryApprovalGranted   EventType = "factory.approval.granted"
	EventFactoryApprovalDenied    EventType = "factory.approval.denied"
	EventFactoryApprovalExpired   EventType = "factory.approval.expired"
	EventFactoryScheduleTick      EventType = "factory.schedule.tick"
	EventFactoryWorkItemResynced  EventType = "factory.workitem.resynced"
	EventFactoryCommandPause      EventType = "factory.command.pause"
	EventFactoryCommandResume     EventType = "factory.command.resume"
	EventFactoryCommandRedispatch EventType = "factory.command.redispatch"
	EventFactoryCommandCancel     EventType = "factory.command.cancel"
)

Factory event types, emitted only by the built-in factory provider.

func EventTypes

func EventTypes() []EventType

EventTypes lists every known event type, in vocabulary order.

func (EventType) EmittedBy

func (t EventType) EmittedBy(p ProviderType) bool

EmittedBy reports whether provider type p may emit t.

func (EventType) IsFactory

func (t EventType) IsFactory() bool

IsFactory reports whether t is a factory.* type, which only the factory provider may emit.

func (EventType) JSONSchema

func (EventType) JSONSchema() *jsonschema.Schema

JSONSchema describes EventType as the enum of the vocabulary.

func (EventType) Known

func (t EventType) Known() bool

Known reports whether t is in the vocabulary.

func (EventType) ProviderTypes

func (t EventType) ProviderTypes() []ProviderType

ProviderTypes returns the provider types that emit t, or nil for an unknown type.

type ExprOr

type ExprOr[T any] struct {
	Expr  string
	Value T
}

ExprOr holds either an expression string or a typed value. It is used where the catalog writes a template that catalog load substitutes ("{{ params.harness }}"), or a "=CEL" value evaluated at runtime, in place of a structure. A string must look like one of the two (ExprPattern), so a bare value such as `harness: codex` is an error rather than an expression; checking the expression itself is the catalog loader's job.

func (ExprOr[T]) IsExpr

func (e ExprOr[T]) IsExpr() bool

IsExpr reports whether the field holds an expression.

func (ExprOr[T]) JSONSchema

func (ExprOr[T]) JSONSchema() *jsonschema.Schema

JSONSchema describes ExprOr as oneOf [string, T].

func (ExprOr[T]) MarshalJSON

func (e ExprOr[T]) MarshalJSON() ([]byte, error)

MarshalJSON writes the expression string, or the value.

func (*ExprOr[T]) UnmarshalJSON

func (e *ExprOr[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts a non-empty string (the expression) or the value, decoded strictly.

type GitCredentialSpec

type GitCredentialSpec struct {
	Provider string `json:"provider"`
	Identity string `json:"identity"`
	Repo     string `json:"repo"`
	// ReadRepos are the task's other repos, which it only reads. Each gets its own read-only
	// token (contents: read) at lease time, unless PublicReads is set.
	ReadRepos []string `json:"readRepos,omitzero"`
	// PublicReads says the read repos are public (the TaskSpec's workspace.publicReads): the
	// agent clones them anonymously and they get no token.
	PublicReads bool              `json:"publicReads,omitzero"`
	Permissions map[string]string `json:"permissions,omitzero"`
	TTL         Duration          `json:"ttl,omitzero"`
}

GitCredentialSpec describes the scoped git tokens minted for a task: one for Repo with the TaskSpec permissions and, unless PublicReads is set, a read-only one per read repo.

type GitHubActionsBackend

type GitHubActionsBackend struct {
	ProviderRef string `json:"providerRef"`
	Repo        string `json:"repo"`
	Workflow    string `json:"workflow"`
}

GitHubActionsBackend runs agents as a workflow.

type GitHubProviderSpec

type GitHubProviderSpec struct {
	APIURL  string  `json:"apiURL,omitzero"`
	Webhook Webhook `json:"webhook"`
	// Identities are the GitHub Apps this provider can act as, by role (author, reviewer).
	Identities map[string]AppIdentity `json:"identities"`
}

GitHubProviderSpec is the connection to a GitHub (or GHE) instance.

type Group

type Group struct {
	TypeMeta
	Metadata ObjectMeta `json:"metadata"`
	Spec     GroupSpec  `json:"spec"`
}

Group is a named set of people, resolved per provider.

func (*Group) GetName

func (g *Group) GetName() string

GetName returns metadata.name.

func (*Group) Validate

func (g *Group) Validate() error

Validate checks that each member source sets exactly one source.

type GroupCache

type GroupCache struct {
	TTL Duration `json:"ttl"`
}

GroupCache says how long resolved members are cached.

type GroupSource

type GroupSource struct {
	Provider  string   `json:"provider"`
	Team      string   `json:"team,omitzero" jsonschema:"minLength=1"`
	OrgRole   *OrgRole `json:"orgRole,omitzero"`
	Users     []string `json:"users,omitzero"`
	UserGroup string   `json:"userGroup,omitzero" jsonschema:"minLength=1"`
}

GroupSource is one source of members on one provider. Set exactly one of the sources.

func (GroupSource) JSONSchemaExtend

func (GroupSource) JSONSchemaExtend(s *jsonschema.Schema)

JSONSchemaExtend requires exactly one source.

func (*GroupSource) Validate

func (g *GroupSource) Validate() error

Validate checks that exactly one source is set.

type GroupSpec

type GroupSpec struct {
	Members []GroupSource `json:"members"`
	Cache   *GroupCache   `json:"cache,omitzero"`
}

GroupSpec is the spec of a Group.

type HarnessConfig

type HarnessConfig struct {
	Model           StringOrList `json:"model,omitzero"`
	ReasoningEffort StringOrList `json:"reasoningEffort,omitzero"`
	// Prefer orders candidate models when several match.
	Prefer []string `json:"prefer,omitzero"`
}

HarnessConfig is a requested harness config.

type HarnessConstraint

type HarnessConstraint struct {
	Name            string       `json:"name"`
	Models          StringOrList `json:"models,omitzero"`
	ReasoningEffort StringOrList `json:"reasoningEffort,omitzero"`
}

HarnessConstraint bounds what a harness may run. Strings are patterns.

type HarnessOffer

type HarnessOffer struct {
	Name    string `json:"name"`
	Version string `json:"version,omitzero"`
	// Auth is subscription, apiKey, accessToken or cloud.
	Auth   string   `json:"auth,omitzero"`
	Models []string `json:"models,omitzero"`
	// DefaultModel is the model the harness uses when none is asked for; resolution prefers
	// it over the highest version (patterns LLD). Empty when the probe can't tell.
	DefaultModel    string   `json:"defaultModel,omitzero"`
	ReasoningEffort []string `json:"reasoningEffort,omitzero"`
}

HarnessOffer is what one agent can actually run with one harness (from the agent's Probe and local config): concrete values, not patterns.

type HarnessPolicy

type HarnessPolicy struct {
	// Allowed are constraints: nothing outside them runs for this task spec.
	Allowed []HarnessConstraint `json:"allowed,omitzero"`
	Default *HarnessRequest     `json:"default,omitzero"`
}

HarnessPolicy is a TaskSpec's harness constraints and default request.

type HarnessRequest

type HarnessRequest struct {
	Name   string         `json:"name"`
	Config *HarnessConfig `json:"config,omitzero"`
}

HarnessRequest asks for a harness and config. Strings are patterns; it must fall inside the TaskSpec's constraints.

type HarnessResolved

type HarnessResolved struct {
	Name            string `json:"name"`
	Version         string `json:"version,omitzero"`
	Auth            string `json:"auth,omitzero"`
	Model           string `json:"model,omitzero"`
	ReasoningEffort string `json:"reasoningEffort,omitzero"`
}

HarnessResolved is the concrete harness config chosen when an agent leased the task.

type HostError

type HostError struct {
	Host   string
	Reason string
	// Err is one of the ErrHost* sentinels.
	Err error
}

HostError is a host list entry that ValidateHost refuses.

func (*HostError) Error

func (e *HostError) Error() string

func (*HostError) Unwrap

func (e *HostError) Unwrap() error

type InlineRule

type InlineRule struct {
	Metadata ObjectMeta `json:"metadata"`
	Spec     RuleSpec   `json:"spec"`
}

InlineRule is a Rule without its TypeMeta, embedded in a RuleSet.

type InputSpec

type InputSpec struct {
	Type     string `json:"type,omitzero" jsonschema:"enum=string,enum=number,enum=integer,enum=boolean,enum=object,enum=array"`
	Enum     []any  `json:"enum,omitzero"`
	Default  any    `json:"default,omitzero"`
	Required bool   `json:"required,omitzero"`
}

InputSpec declares one TaskSpec input.

type Instructions

type Instructions struct {
	Template string `json:"template"`
	Headless *bool  `json:"headless,omitzero"`
}

Instructions is the prompt template.

type LLMAuth

type LLMAuth struct {
	APIKeyRef *SecretRef `json:"apiKeyRef,omitzero"`
}

LLMAuth is the LLM credential ephemeral agents use.

type LabelSelector

type LabelSelector struct {
	MatchLabels      map[string]string          `json:"matchLabels,omitzero"`
	MatchExpressions []LabelSelectorRequirement `json:"matchExpressions,omitzero"`
}

LabelSelector selects objects by their labels, as in Kubernetes.

func (*LabelSelector) Matches

func (s *LabelSelector) Matches(labels map[string]string) bool

Matches reports whether labels satisfy the selector, as in Kubernetes: every matchLabels entry and every matchExpressions requirement must hold. A nil or empty selector matches everything; a requirement with an unknown operator matches nothing.

func (*LabelSelector) Validate

func (s *LabelSelector) Validate() error

Validate reports the first malformed matchExpressions entry, wrapping ErrInvalidSelector: a missing key, an unknown operator, In or NotIn without values, or Exists or DoesNotExist with values. A nil selector is valid.

type LabelSelectorRequirement

type LabelSelectorRequirement struct {
	Key      string   `json:"key"`
	Operator string   `json:"operator" jsonschema:"enum=In,enum=NotIn,enum=Exists,enum=DoesNotExist"`
	Values   []string `json:"values,omitzero"`
}

LabelSelectorRequirement is one matchExpressions entry.

type LeasePolicy

type LeasePolicy struct {
	TTL              Duration `json:"ttl,omitzero"`
	Heartbeat        Duration `json:"heartbeat,omitzero"`
	MaxTasksPerAgent int      `json:"maxTasksPerAgent,omitzero"`
}

LeasePolicy sets lease timing.

type Lending

type Lending struct {
	Unlimited       bool     `json:"unlimited,omitzero"`
	Queues          []string `json:"queues,omitzero"`
	RuleSets        []string `json:"ruleSets,omitzero"`
	Harnesses       []string `json:"harnesses,omitzero"`
	MaxConcurrent   int      `json:"maxConcurrent,omitzero"`
	MaxRunsPerDay   int      `json:"maxRunsPerDay,omitzero"`
	MaxTokensPerDay int64    `json:"maxTokensPerDay,omitzero"`
	Hours           string   `json:"hours,omitzero"`
}

Lending is the owner's consent: what the agent may take. Unlimited means any queue, any hour, no daily cap.

type Limits

type Limits struct {
	MaxTurns     int      `json:"maxTurns,omitzero"`
	MaxWallClock Duration `json:"maxWallClock,omitzero"`
	MaxCostUSD   float64  `json:"maxCostUSD,omitzero"`
	// CPUs is the workspace VM's vCPUs for this task: at least 1, and hard-capped at the
	// agent's workspace.size.cpus. A larger request gets workspace.size.cpus, and the run says
	// so (a warning in the agent's log and a progress message with the requested and the
	// granted size). There is no budget or overcommit, by design: a task that needs more runs
	// on an agent whose workspace.size is that big (requires.labels can pick one). A smaller
	// value is taken as given: on tart the VM gets cpus vCPUs; on kata the container gets
	// max(cpus-1, 1) and Kata adds a vCPU of its own, so cpus 1 and cpus 2 both give a 2-vCPU
	// guest. Unset means the agent's size.
	CPUs int `json:"cpus,omitzero"`
	// Memory is the workspace VM's memory for this task: a whole number of GiB in the form of
	// the agent's workspace.size.memory (e.g. "4Gi"), at least 2Gi on every driver (the minimum
	// workspace.size.memory has too), and hard-capped at the agent's workspace.size.memory as
	// cpus is: a larger request gets workspace.size.memory, and the run says so. A value in
	// between is taken as given. Unset means the agent's size.
	Memory string `json:"memory,omitzero"`
}

Limits bound a run.

func (Limits) JSONSchemaExtend

func (Limits) JSONSchemaExtend(s *jsonschema.Schema)

JSONSchemaExtend constrains cpus (at least 1) and memory (limitsMemoryMinPattern) the way Validate does.

func (*Limits) Validate

func (l *Limits) Validate() error

Validate checks the workspace size a task asks for: cpus at least 1 and memory a whole number of GiB, at least WorkspaceMinMemoryGiB (limitsMemoryMinPattern), each when set. A nil Limits is valid. That the size is at most the agent's workspace.size is the agent's to enforce (it caps the request).

type Link struct {
	Provider string `json:"provider"`
	Ref      string `json:"ref"`
	Kind     string `json:"kind,omitzero"`
	Primary  bool   `json:"primary,omitzero"`
}

Link is a provider object that belongs to the work item.

type LinkAction

type LinkAction struct {
	// From is CEL giving the object ref.
	From string `json:"from"`
}

LinkAction adds a provider object to the work item.

type NotifyAction

type NotifyAction struct {
	Template string        `json:"template"`
	To       []Destination `json:"to"`
}

NotifyAction sends a templated message through the providers; no LLM involved.

type Object

type Object interface {
	GetTypeMeta() *TypeMeta
	// GetName is metadata.name, or the id for kinds named by id (Task, Event).
	GetName() string
}

Object is any decoded kind.

func Decode

func Decode(data []byte) ([]Object, error)

Decode decodes a YAML 1.2 stream of one or more documents (separated by `---`, optionally ended by `...`). Each document is decoded strictly into the type of its kind: unknown fields, duplicate keys, non-string keys, unknown kinds and an apiVersion other than APIVersion are errors. A missing apiVersion is accepted. Empty documents are skipped.

func DecodeOne

func DecodeOne(data []byte) (Object, error)

DecodeOne decodes a stream that must hold exactly one document.

func New

func New(kind string) (Object, error)

New returns an empty object of the given kind, with its Kind set.

type ObjectMeta

type ObjectMeta struct {
	Name            string            `json:"name"`
	Labels          map[string]string `json:"labels,omitzero"`
	ResourceVersion string            `json:"resourceVersion,omitzero"` // runtime kinds only
	CreatedAt       time.Time         `json:"createdAt,omitzero"`
}

ObjectMeta is the metadata of every kind except Task (TaskMeta) and Event (CloudEvents attributes).

type ObjectRef

type ObjectRef struct {
	Provider string `json:"provider,omitzero"`
	Kind     string `json:"kind,omitzero"`
	Ref      string `json:"ref"`
}

ObjectRef identifies a provider object, e.g. {github-public, issue, compliance-framework/docs#42}.

type OrgRole

type OrgRole struct {
	Org  string `json:"org"`
	Role string `json:"role"`
}

OrgRole selects the members of an org with a role, e.g. the admins.

type OutputSpec

type OutputSpec struct {
	Schema   string   `json:"schema,omitzero"`
	Outcomes []string `json:"outcomes,omitzero"`
}

OutputSpec is the expected Result: its spec-specific schema and outcomes.

type Pool

type Pool struct {
	TypeMeta
	Metadata ObjectMeta `json:"metadata"`
	Spec     PoolSpec   `json:"spec"`
}

Pool is who takes tasks out of queues and how capacity scales.

func (*Pool) GetName

func (p *Pool) GetName() string

GetName returns metadata.name.

type PoolBackend

type PoolBackend struct {
	Type          string                `json:"type"`
	GitHubActions *GitHubActionsBackend `json:"githubActions,omitzero"`
}

PoolBackend runs ephemeral agents.

type PoolMode

type PoolMode string

PoolMode is how a pool gets agents.

const (
	PoolRegistered PoolMode = "registered"
	PoolEphemeral  PoolMode = "ephemeral"
)

Pool modes.

type PoolRequirements

type PoolRequirements struct {
	// Harnesses: any of.
	Harnesses []string `json:"harnesses,omitzero"`
}

PoolRequirements is the minimum an agent must offer to join.

type PoolSpec

type PoolSpec struct {
	Mode      PoolMode          `json:"mode" jsonschema:"enum=registered,enum=ephemeral"`
	Admission *Admission        `json:"admission,omitzero"`
	Lease     *LeasePolicy      `json:"lease,omitzero"`
	Require   *PoolRequirements `json:"require,omitzero"`
	Fairness  string            `json:"fairness,omitzero"`
	Backend   *PoolBackend      `json:"backend,omitzero"`
	Image     string            `json:"image,omitzero"`
	Scaling   *Scaling          `json:"scaling,omitzero"`
	LLMAuth   *LLMAuth          `json:"llmAuth,omitzero"`
}

PoolSpec is the spec of a Pool. Backend, Image, Scaling and LLMAuth are for ephemeral pools.

type ProgressEvent

type ProgressEvent struct {
	At      time.Time      `json:"at"`
	Kind    string         `json:"kind"`
	Message string         `json:"message,omitzero"`
	Data    map[string]any `json:"data,omitzero"`
}

ProgressEvent is one progress line streamed by the agent.

type PromptRef

type PromptRef struct {
	Ref    string `json:"ref"`
	Digest string `json:"digest,omitzero"`
}

PromptRef is where the agent fetches the rendered prompt.

type Provenance

type Provenance struct {
	Event      string `json:"event"`
	RuleSet    string `json:"ruleSet"`
	Rule       string `json:"rule"`
	CatalogSHA string `json:"catalogSHA"`
}

Provenance is the event, RuleSet, rule and catalog commit that created a task.

type Provider

type Provider struct {
	TypeMeta
	Metadata ObjectMeta   `json:"metadata"`
	Spec     ProviderSpec `json:"spec"`
}

Provider says how to connect to one provider instance. It never holds secrets inline.

func (*Provider) GetName

func (p *Provider) GetName() string

GetName returns metadata.name.

type ProviderScope

type ProviderScope struct {
	Orgs     []string `json:"orgs,omitzero"`
	Channels []string `json:"channels,omitzero"`
}

ProviderScope bounds what a provider instance covers.

type ProviderSpec

type ProviderSpec struct {
	Type   ProviderType        `json:"type" jsonschema:"enum=github,enum=slack"`
	GitHub *GitHubProviderSpec `json:"github,omitzero"`
	Slack  *SlackProviderSpec  `json:"slack,omitzero"`
	// Scope is the outer bound of what the factory sees; RuleSets can only narrow it.
	Scope *ProviderScope `json:"scope,omitzero"`
	// Trust resolves actor.tier; the first matching rule wins.
	Trust  []TrustRule   `json:"trust,omitzero"`
	Resync *ResyncPolicy `json:"resync,omitzero"`
}

ProviderSpec is the spec of a Provider.

type ProviderType

type ProviderType string

ProviderType is a provider adapter type.

const (
	ProviderTypeGitHub  ProviderType = "github"
	ProviderTypeSlack   ProviderType = "slack"
	ProviderTypeFactory ProviderType = "factory"
)

Provider types. "factory" is the reserved built-in provider; the catalog can't declare it.

type Queue

type Queue struct {
	TypeMeta
	Metadata ObjectMeta `json:"metadata"`
	Spec     QueueSpec  `json:"spec"`
}

Queue holds tasks until a pool's agents take them.

func (*Queue) GetName

func (q *Queue) GetName() string

GetName returns metadata.name.

type QueueSpec

type QueueSpec struct {
	Pool        string       `json:"pool"`
	Concurrency int          `json:"concurrency,omitzero"`
	Priority    int          `json:"priority,omitzero"`
	Budget      *Budget      `json:"budget,omitzero"`
	Retry       *RetryPolicy `json:"retry,omitzero"`
}

QueueSpec is the spec of a Queue.

type RailVerdict

type RailVerdict struct {
	Rail string `json:"rail"`
	// Verdict is the stored verdict; the dry-run's EvaluationRail.verdict is its summary.
	Verdict RailVerdictValue `json:"verdict" jsonschema:"enum=allowed,enum=suppressed,enum=deferred,enum=unsupported"`
	Reason  string           `json:"reason,omitzero"`
}

RailVerdict is one safety rail's verdict on a decision as the work item stores it (lowercase, unsupported included); the dry-run API's EvaluationRail is a different view of it (Allowed, Suppressed or Deferred), where unsupported shows as Suppressed and the rail name is prefixed to the reason.

Only the first sentence becomes the schema description, so it carries the mapping.

type RailVerdictValue

type RailVerdictValue string

RailVerdictValue is a stored rail verdict (RailVerdict.Verdict).

const (
	// RailAllowed: the action is applied.
	RailAllowed RailVerdictValue = "allowed"
	// RailSuppressed: the action is not applied (kill switch, run cap, active run).
	RailSuppressed RailVerdictValue = "suppressed"
	// RailDeferred: the action is applied held back (budget: the Task is created Pending).
	RailDeferred RailVerdictValue = "deferred"
	// RailUnsupported: the engine doesn't support the action (requestApproval in the PoC); the
	// rails are not consulted.
	RailUnsupported RailVerdictValue = "unsupported"
)

Rail verdicts.

func RailVerdictValues

func RailVerdictValues() []RailVerdictValue

RailVerdictValues lists the rail verdicts, in the order of RailVerdict.Verdict's enum.

type ReadyCheck

type ReadyCheck struct {
	// HTTP URLs that must each answer 2xx or 3xx; at most 10, http or https.
	HTTP []string `json:"http,omitzero"`
	// Timeout for all of them together; default 15m, at most 60m.
	Timeout Duration `json:"timeout,omitzero"`
}

ReadyCheck is how the runtime waits for an environment.

func (ReadyCheck) JSONSchemaExtend

func (ReadyCheck) JSONSchemaExtend(s *jsonschema.Schema)

JSONSchemaExtend constrains http: 1 to MaxEnvReadyURLs absolute http or https URLs. It stays optional in the schema (the field is omitzero); Validate requires it.

type RepoMount

type RepoMount struct {
	// Ref is owner/repo@ref, or "=CEL".
	Ref  string `json:"ref"`
	Mode string `json:"mode,omitzero" jsonschema:"enum=ro,enum=rw"`
}

RepoMount is one repo in the workspace.

type Requires

type Requires struct {
	Labels []string `json:"labels,omitzero"`
}

Requires lists the agent labels a task needs.

type Result

type Result struct {
	Task      string         `json:"task"`
	Status    ResultStatus   `json:"status" jsonschema:"enum=done,enum=failed,enum=needs_input,enum=noop"`
	Outcome   string         `json:"outcome,omitzero"`
	Summary   string         `json:"summary,omitzero"`
	Verdict   map[string]any `json:"verdict,omitzero"`
	Artifacts []Artifact     `json:"artifacts,omitzero"`
	Suggest   []Suggestion   `json:"suggest,omitzero"`
	// Question is set when Status is needs_input; null otherwise.
	Question *string        `json:"question" jsonschema:"nullable"`
	Harness  *ResultHarness `json:"harness,omitzero"`
	Data     map[string]any `json:"data,omitzero"`
}

Result is what an agent reports when a run completes. Spec-specific fields go under Data and are validated by the TaskSpec's output schema.

func DecodeResult

func DecodeResult(data []byte) (*Result, error)

DecodeResult strictly decodes a Result (JSON or YAML).

type ResultHarness

type ResultHarness struct {
	Name            string          `json:"name"`
	Version         string          `json:"version,omitzero"`
	Auth            string          `json:"auth,omitzero"`
	EffectiveConfig EffectiveConfig `json:"effectiveConfig"`
	Usage           Usage           `json:"usage"`
}

ResultHarness is the harness that ran, its effective config and usage.

type ResultStatus

type ResultStatus string

ResultStatus is how a run ended.

const (
	ResultDone       ResultStatus = "done"
	ResultFailed     ResultStatus = "failed"
	ResultNeedsInput ResultStatus = "needs_input"
	ResultNoop       ResultStatus = "noop"
)

Result statuses.

type ResyncPolicy

type ResyncPolicy struct {
	Every Duration `json:"every"`
}

ResyncPolicy says how often the provider's objects are re-observed.

type RetryPolicy

type RetryPolicy struct {
	Max int           `json:"max"`
	On  []RetryReason `json:"on,omitzero"`
}

RetryPolicy says how often, and on what, a task is retried.

type RetryReason

type RetryReason string

RetryReason is a failure that may be retried. Throttling never consumes an attempt.

const (
	RetryAgentLost    RetryReason = "agent-lost"
	RetryInfraFailure RetryReason = "infra-failure"
)

Retry reasons.

type Rule

type Rule struct {
	TypeMeta
	Metadata ObjectMeta `json:"metadata"`
	Spec     RuleSpec   `json:"spec"`
}

Rule is when and what. It has no scope: the RuleSets that select it decide where it applies.

func (*Rule) GetName

func (r *Rule) GetName() string

GetName returns metadata.name.

func (*Rule) Validate

func (r *Rule) Validate() error

Validate checks the rule's actions (exactly one member each).

type RuleSelection

type RuleSelection struct {
	Refs     []string       `json:"refs,omitzero"`
	Selector *LabelSelector `json:"selector,omitzero"`
	Exclude  []string       `json:"exclude,omitzero"`
}

RuleSelection picks rules: refs ∪ selector, minus exclude.

type RuleSet

type RuleSet struct {
	TypeMeta
	Metadata ObjectMeta  `json:"metadata"`
	Spec     RuleSetSpec `json:"spec"`
}

RuleSet is where rules apply: it binds provider instances, sets the scope, selects rules and overrides their params. Rules only fire through a RuleSet.

func (*RuleSet) GetName

func (r *RuleSet) GetName() string

GetName returns metadata.name.

func (*RuleSet) Validate

func (r *RuleSet) Validate() error

Validate checks the inline rules' actions.

type RuleSetSpec

type RuleSetSpec struct {
	// ProviderSelector binds provider instances.
	ProviderSelector LabelSelector `json:"providerSelector"`
	Scope            *Scope        `json:"scope,omitzero"`
	Rules            RuleSelection `json:"rules"`
	// Overrides are per-rule params, by rule name.
	Overrides map[string]map[string]any `json:"overrides,omitzero"`
	// Defaults are params applied to every selected rule unless the rule overrides them.
	Defaults map[string]any `json:"defaults,omitzero"`
	Budget   *Budget        `json:"budget,omitzero"`
	// StateKeys, when declared, are the only keys `set` may write.
	StateKeys []string `json:"stateKeys,omitzero"`
	// InlineRules are rules defined in the RuleSet itself, selected implicitly.
	InlineRules []InlineRule `json:"inlineRules,omitzero"`
}

RuleSetSpec is the spec of a RuleSet.

type RuleSpec

type RuleSpec struct {
	RuleSet string `json:"ruleSet,omitzero"`
	// ProviderSelector names the provider types or families the rule is written for
	// (validation only; RuleSets bind instances). Not needed for factory.*-only rules.
	ProviderSelector *LabelSelector `json:"providerSelector,omitzero"`
	On               []EventType    `json:"on"`
	// Where is CEL over event, actor, item, run, approval, provider, params, now.
	Where    string         `json:"where,omitzero"`
	Params   map[string]any `json:"params,omitzero"`
	Actions  []Action       `json:"actions"`
	Priority int            `json:"priority,omitzero"`
	Final    bool           `json:"final,omitzero"`
	Debounce *Debounce      `json:"debounce,omitzero"`
	// Schedule is a cron expression, only with on: [factory.schedule.tick].
	Schedule string `json:"schedule,omitzero"`
}

RuleSpec is the spec of a Rule.

type Run

type Run struct {
	TypeMeta
	Metadata ObjectMeta `json:"metadata"`
	Spec     RunSpec    `json:"spec"`
	Status   *RunStatus `json:"status,omitzero"`
}

Run is one attempt at a Task by one agent.

func (*Run) GetName

func (r *Run) GetName() string

GetName returns metadata.name.

type RunEnd

type RunEnd string

RunEnd is how a run ended.

const (
	RunCompleted RunEnd = "completed" // the agent returned a Result (done, failed, needs_input or noop)
	RunFailed    RunEnd = "failed"    // timeout, invalid result or infrastructure failure
	RunCancelled RunEnd = "cancelled" // cancelled by a rule or command, and acknowledged
	RunAbandoned RunEnd = "abandoned" // the agent gave the lease back (throttled, error, shutdown)
	RunLost      RunEnd = "lost"      // the lease expired without a heartbeat
)

Run ends.

type RunSpec

type RunSpec struct {
	Task    string `json:"task"`
	Attempt int    `json:"attempt"`
	Agent   string `json:"agent"`
	Owner   string `json:"owner,omitzero"`
}

RunSpec is a Run's spec.

type RunStatus

type RunStatus struct {
	StartedAt time.Time `json:"startedAt,omitzero"`
	EndedAt   time.Time `json:"endedAt,omitzero"`
	// End is how the run ended; empty while it runs.
	End RunEnd `json:"end,omitzero" jsonschema:"enum=completed,enum=failed,enum=cancelled,enum=abandoned,enum=lost"`
	// Progress is a ring buffer of the latest progress events.
	Progress      []ProgressEvent `json:"progress,omitzero"`
	Result        *Result         `json:"result,omitzero"`
	TranscriptRef string          `json:"transcriptRef,omitzero"`
	// EnvironmentLogRef is set once the agent uploaded the workspace's environment log (the
	// TaskSpec environment's scripts' output, redacted).
	EnvironmentLogRef string `json:"environmentLogRef,omitzero"`
	Usage             *Usage `json:"usage,omitzero"`
}

RunStatus is a Run's status.

type Scaling

type Scaling struct {
	Min int `json:"min"`
	Max int `json:"max"`
}

Scaling bounds an ephemeral pool's size.

type Scope

type Scope struct {
	Repos    []string `json:"repos,omitzero"`
	Exclude  []string `json:"exclude,omitzero"`
	Channels []string `json:"channels,omitzero"`
	Branches []string `json:"branches,omitzero"`
}

Scope narrows a RuleSet to repos (globs) or channels.

type SecretRef

type SecretRef struct {
	Name string `json:"name"`
	Key  string `json:"key"`
}

SecretRef points at a secret held outside the catalog. Secrets are never inline.

type Side

type Side string

Side says who executes an effect op.

const (
	// SideAPI ops are executed by the dispatcher's Effector through the provider API.
	SideAPI Side = "api"
	// SideGit ops are executed by the agent in its workspace with the scoped git token; the
	// agent still records them through the Effector API for audit.
	SideGit Side = "git"
)

Sides.

type SkillRef

type SkillRef struct {
	Source string   `json:"source"`
	Ref    string   `json:"ref,omitzero"`
	Commit string   `json:"commit,omitzero"`
	Use    []string `json:"use,omitzero"`
}

SkillRef pins skills from a skills repo. Commit is filled in on a Task.

type SlackProviderSpec

type SlackProviderSpec struct {
	Mode        string     `json:"mode,omitzero"`
	AppTokenRef *SecretRef `json:"appTokenRef,omitzero"`
	BotTokenRef *SecretRef `json:"botTokenRef,omitzero"`
}

SlackProviderSpec is the connection to a Slack workspace (future).

type StringOrList

type StringOrList struct {
	Values []string
	// contains filtered or unexported fields
}

StringOrList is a field that takes one string (often a pattern, e.g. "*") or a list of strings. It remembers which form it was decoded from so it marshals back the same way.

func List

func List(values ...string) StringOrList

List returns a StringOrList written as a list.

func Scalar

func Scalar(s string) StringOrList

Scalar returns a StringOrList written as a single string.

func (StringOrList) IsList

func (s StringOrList) IsList() bool

IsList reports whether the value was written (or built) as a list.

func (StringOrList) IsZero

func (s StringOrList) IsZero() bool

IsZero reports whether the value is unset, so `omitzero` drops it.

func (StringOrList) JSONSchema

func (StringOrList) JSONSchema() *jsonschema.Schema

JSONSchema describes StringOrList as a string or a list of strings.

func (StringOrList) MarshalJSON

func (s StringOrList) MarshalJSON() ([]byte, error)

MarshalJSON writes a string when the value was a single string, a list otherwise.

func (*StringOrList) UnmarshalJSON

func (s *StringOrList) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts a string or a list of strings.

type Suggestion

type Suggestion struct {
	TaskSpec string         `json:"taskSpec"`
	Reason   string         `json:"reason,omitzero"`
	Inputs   map[string]any `json:"inputs,omitzero"`
}

Suggestion is a follow-up the agent proposes; rules decide.

type Target

type Target struct {
	Provider string `json:"provider,omitzero"`
	Repo     string `json:"repo,omitzero"`
	Ref      string `json:"ref,omitzero"`
}

Target says which repo or object the work happens on, when it isn't the event's object.

type Task

type Task struct {
	TypeMeta
	Metadata TaskMeta    `json:"metadata"`
	Spec     TaskRunSpec `json:"spec"`
	Status   *TaskStatus `json:"status,omitzero"`
}

Task is one instantiation of a TaskSpec for a work item.

func (*Task) GetName

func (t *Task) GetName() string

GetName returns the task id.

func (*Task) Validate

func (t *Task) Validate() error

Validate checks the task's environment (Environment.Validate), versions (validateVersions) and limits (Limits.Validate).

type TaskCredentials

type TaskCredentials struct {
	Git *GitCredentialSpec `json:"git,omitzero"`
	LLM string             `json:"llm,omitzero"`
}

TaskCredentials are the credentials a task gets. LLM is always "agent-local": the factory never sees LLM credentials.

type TaskHarness

type TaskHarness struct {
	Request  *HarnessRequest  `json:"request,omitzero"`
	Resolved *HarnessResolved `json:"resolved" jsonschema:"nullable"`
}

TaskHarness is the requested harness and, once leased, the resolved one (null until then).

type TaskMeta

type TaskMeta struct {
	ID              string            `json:"id"`
	WorkItem        string            `json:"workItem"`
	Provenance      *Provenance       `json:"provenance,omitzero"`
	Labels          map[string]string `json:"labels,omitzero"`
	ResourceVersion string            `json:"resourceVersion,omitzero"`
	CreatedAt       time.Time         `json:"createdAt,omitzero"`
}

TaskMeta is a Task's metadata: tasks are named by id and carry their provenance.

type TaskPhase

type TaskPhase string

TaskPhase is a Task's lifecycle phase.

const (
	TaskPending   TaskPhase = "Pending"
	TaskLeased    TaskPhase = "Leased"
	TaskRunning   TaskPhase = "Running"
	TaskSucceeded TaskPhase = "Succeeded"
	TaskFailed    TaskPhase = "Failed"
	// TaskCancelling is a task being cancelled (the cancel command): its agent is told on the
	// next heartbeat and the task becomes Cancelled on the agent's ack or on lease expiry.
	TaskCancelling TaskPhase = "Cancelling"
	TaskCancelled  TaskPhase = "Cancelled"
)

Task phases: Pending → Leased → Running → Succeeded | Failed, and Running → Cancelling → Cancelled.

func TaskPhases

func TaskPhases() []TaskPhase

TaskPhases lists the task phases in lifecycle order.

func (TaskPhase) JSONSchema

func (TaskPhase) JSONSchema() *jsonschema.Schema

JSONSchema makes TaskPhase an enum of TaskPhases.

type TaskRunSpec

type TaskRunSpec struct {
	TaskSpec TaskSpecRef    `json:"taskSpec"`
	Queue    string         `json:"queue"`
	Pool     string         `json:"pool,omitzero"`
	Provider string         `json:"provider,omitzero"`
	Target   *Target        `json:"target,omitzero"`
	Inputs   map[string]any `json:"inputs,omitzero"`
	Harness  *TaskHarness   `json:"harness,omitzero"`
	// Requires are the agent labels the task needs: the TaskSpec's requires merged with the
	// dispatch's. The scheduler matches them against agent capabilities.
	Requires    *Requires        `json:"requires,omitzero"`
	Skills      []SkillRef       `json:"skills,omitzero"`
	Prompt      *PromptRef       `json:"prompt,omitzero"`
	Context     []ContextItem    `json:"context,omitzero"`
	Credentials *TaskCredentials `json:"credentials,omitzero"`
	Effects     *EffectsPolicy   `json:"effects,omitzero"`
	Limits      *Limits          `json:"limits,omitzero"`
	Output      *OutputSpec      `json:"output,omitzero"`
	// Environment is copied from the TaskSpec's workspace.environment when the Task is compiled.
	Environment *Environment `json:"environment,omitzero"`
	// Versions are the environment's component versions, resolved at compile time from
	// environment.versions (component name -> version). The workspace runtime exports each as
	// FACTORY_VERSION_<COMPONENT>, so a Redispatch re-resolves explicitly.
	Versions map[string]string `json:"versions,omitzero"`
}

TaskRunSpec is a Task's spec: the TaskSpec resolved for this work item.

func (TaskRunSpec) JSONSchemaExtend

func (TaskRunSpec) JSONSchemaExtend(s *jsonschema.Schema)

JSONSchemaExtend constrains versions (extendVersionsSchema).

type TaskSpec

type TaskSpec struct {
	TypeMeta
	Metadata ObjectMeta   `json:"metadata"`
	Spec     TaskSpecSpec `json:"spec"`
}

TaskSpec is what and how for one role, with no triggers or transitions.

func (*TaskSpec) GetName

func (t *TaskSpec) GetName() string

GetName returns metadata.name.

func (*TaskSpec) Validate

func (t *TaskSpec) Validate() error

Validate checks the limits (Limits.Validate), the workspace (Workspace.Validate), and that an environment's versions.input names one of the spec's inputs.

type TaskSpecRef

type TaskSpecRef struct {
	Name   string `json:"name"`
	Digest string `json:"digest,omitzero"`
}

TaskSpecRef is the TaskSpec a task was made from, by name and digest.

type TaskSpecSpec

type TaskSpecSpec struct {
	Description string `json:"description,omitzero"`
	// Inputs are the declared, typed inputs that dispatch.inputs must satisfy.
	Inputs       map[string]InputSpec `json:"inputs,omitzero"`
	Instructions *Instructions        `json:"instructions,omitzero"`
	Skills       []SkillRef           `json:"skills,omitzero"`
	// Requires lists agent labels needed; dispatch can add to it.
	Requires    *Requires         `json:"requires,omitzero"`
	Harness     *HarnessPolicy    `json:"harness,omitzero"`
	Workspace   *Workspace        `json:"workspace,omitzero"`
	Identity    string            `json:"identity,omitzero"`
	Permissions map[string]string `json:"permissions,omitzero"`
	Effects     *EffectsPolicy    `json:"effects,omitzero"`
	Limits      *Limits           `json:"limits,omitzero"`
	Output      *OutputSpec       `json:"output,omitzero"`
}

TaskSpecSpec is the spec of a TaskSpec. String fields that depend on inputs may be "=CEL".

type TaskStatus

type TaskStatus struct {
	Phase  TaskPhase `json:"phase"`
	Agent  *string   `json:"agent" jsonschema:"nullable"`
	Reason string    `json:"reason,omitzero"`
	// ReasonDetail is a human sentence for a pending task's reason: for git-credential, the
	// App identity, the repo and the fix.
	ReasonDetail   string    `json:"reasonDetail,omitzero"`
	Attempts       int       `json:"attempts,omitzero"`
	LeaseExpiresAt time.Time `json:"leaseExpiresAt,omitzero"`
}

TaskStatus is a Task's status. Agent is null until the task is leased.

type Template

type Template struct {
	TypeMeta
	Metadata ObjectMeta   `json:"metadata"`
	Spec     TemplateSpec `json:"spec"`
}

Template is the text of notifications and approval prompts, one body per provider type.

func (*Template) GetName

func (t *Template) GetName() string

GetName returns metadata.name.

type TemplateBody

type TemplateBody struct {
	Text   string
	Blocks string
}

TemplateBody is either an inline Go text/template (written as a string) or, for Slack, a Block Kit file ({blocks: path}).

func (TemplateBody) JSONSchema

func (TemplateBody) JSONSchema() *jsonschema.Schema

JSONSchema describes TemplateBody as oneOf [string, {blocks}].

func (TemplateBody) MarshalJSON

func (b TemplateBody) MarshalJSON() ([]byte, error)

MarshalJSON writes the text as a string, or the object form.

func (*TemplateBody) UnmarshalJSON

func (b *TemplateBody) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts a string or {blocks: path}.

type TemplateSpec

type TemplateSpec struct {
	Bodies map[ProviderType]TemplateBody `json:"bodies"`
}

TemplateSpec is the spec of a Template.

func (TemplateSpec) JSONSchemaExtend

func (TemplateSpec) JSONSchemaExtend(s *jsonschema.Schema)

JSONSchemaExtend limits the body keys to the provider types a catalog can use.

type TrustRule

type TrustRule struct {
	Tier              string   `json:"tier"`
	Group             string   `json:"group,omitzero"`
	AuthorAssociation []string `json:"authorAssociation,omitzero"`
	Bots              []string `json:"bots,omitzero"`
	WorkspaceMember   bool     `json:"workspaceMember,omitzero"`
}

TrustRule maps actors to a trust tier. The matchers are ANDed; a rule with none matches anyone.

type TypeMeta

type TypeMeta struct {
	APIVersion string `json:"apiVersion,omitzero"`
	Kind       string `json:"kind"`
}

TypeMeta is embedded in every kind. APIVersion may be omitted in documents and is never added on output.

func (*TypeMeta) GetTypeMeta

func (t *TypeMeta) GetTypeMeta() *TypeMeta

GetTypeMeta gives access to the kind and apiVersion of any Object.

type Usage

type Usage struct {
	InputTokens  int64    `json:"inputTokens"`
	OutputTokens int64    `json:"outputTokens"`
	Turns        int      `json:"turns,omitzero"`
	WallClock    Duration `json:"wallClock,omitzero"`
	CostUSD      *float64 `json:"costUSD" jsonschema:"nullable"`
}

Usage is what a run consumed. CostUSD is null for subscription runs.

type ValidationError

type ValidationError struct {
	// Field is the path of the offending field, e.g. spec.actions[1].
	Field   string
	Message string
	// Err is the typed cause, when there is one (e.g. a *HostError); Unwrap returns it.
	Err error
}

ValidationError is a rule the types enforce beyond the schema of each field, such as the Action one-of.

func (*ValidationError) Error

func (e *ValidationError) Error() string

func (*ValidationError) Unwrap

func (e *ValidationError) Unwrap() error

type VersionSource

type VersionSource struct {
	// From is latest (each component's latest final release), inputs (a map in the task's
	// inputs) or train (a release-train reference in the task's inputs).
	From string `json:"from" jsonschema:"enum=latest,enum=inputs,enum=train"`
	// Input names the TaskSpec input that holds the map (inputs) or the train reference
	// (train). Required for those two, forbidden for latest.
	Input string `json:"input,omitzero"`
}

VersionSource is where an environment's component versions come from.

type Webhook

type Webhook struct {
	Path      string    `json:"path"`
	SecretRef SecretRef `json:"secretRef"`
}

Webhook is where the provider's webhook is mounted, and the secret that signs it.

type WorkItem

type WorkItem struct {
	TypeMeta
	Metadata ObjectMeta      `json:"metadata"`
	Spec     WorkItemSpec    `json:"spec"`
	Status   *WorkItemStatus `json:"status,omitzero"`
}

WorkItem groups the provider objects that are about one piece of work.

func (*WorkItem) GetName

func (w *WorkItem) GetName() string

GetName returns metadata.name.

type WorkItemClosed

type WorkItemClosed struct {
	Reason CloseReason `json:"reason" jsonschema:"enum=done,enum=wont-do,enum=duplicate"`
	Note   string      `json:"note,omitzero"`
	At     time.Time   `json:"at"`
	// By is the admin's actor id (provider-instance:login, or cli).
	By string `json:"by,omitzero"`
}

WorkItemClosed records why and when an admin closed a work item.

type WorkItemSpec

type WorkItemSpec struct {
	Links []Link `json:"links,omitzero"`
}

WorkItemSpec is the spec of a WorkItem.

type WorkItemStatus

type WorkItemStatus struct {
	State map[string]any `json:"state,omitzero"`
	// Counters are runs per task spec (derived).
	Counters  map[string]int `json:"counters,omitzero"`
	Approvals []ApprovalRef  `json:"approvals,omitzero"`
	// Decisions are bounded to the newest MaxDecisions.
	Decisions []Decision `json:"decisions,omitzero"`
	Reporter  *Actor     `json:"reporter,omitzero"`
	// Closed is set when an admin closed the work item: the rules evaluate nothing for it
	// any more (its events are still stored).
	Closed *WorkItemClosed `json:"closed,omitzero"`
}

WorkItemStatus is the work item's state, set only by rules and controllers.

type Workspace

type Workspace struct {
	// Repos are mounted repos; at most one is rw.
	Repos    []RepoMount `json:"repos,omitzero"`
	Checkout string      `json:"checkout,omitzero"`
	// PublicReads lets the agent clone public repos anonymously at runtime, and says the ro
	// repos are public: they are cloned anonymously and get no read-only token.
	PublicReads *bool `json:"publicReads,omitzero"`
	// Environment is what the task's VM workspace brings up before the harness runs (P1 §4).
	// The compiler copies it to the Task's spec.environment.
	Environment *Environment `json:"environment,omitzero"`
}

Workspace says what the agent checks out.

func (*Workspace) Validate

func (w *Workspace) Validate() error

Validate checks the environment (Environment.Validate).

Directories

Path Synopsis
Command schemagen writes the JSON Schemas of the v1alpha1 config kinds and of Result: one <kind>.schema.json per kind, plus result.schema.json.
Command schemagen writes the JSON Schemas of the v1alpha1 config kinds and of Result: one <kind>.schema.json per kind, plus result.schema.json.

Jump to

Keyboard shortcuts

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