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
- Variables
- func ConfigKinds() []string
- func Encode(obj Object) ([]byte, error)
- func IsConfigKind(kind string) bool
- func IsExpression(s string) bool
- func NewReflector() *jsonschema.Reflector
- func RuntimeKinds() []string
- func SchemaFile(kind string) string
- func Schemas() (map[string][]byte, error)
- func ValidateHost(h string) error
- type Action
- type Actor
- type AdapterCapabilities
- type Admission
- type Agent
- type AgentCapabilities
- type AgentPhase
- type AgentSpec
- type AgentStatus
- type AgentUsage
- type AppIdentity
- type Approval
- type ApprovalDecision
- type ApprovalMeta
- type ApprovalPhase
- type ApprovalRef
- type ApprovalSpec
- type ApprovalStatus
- type Artifact
- type Budget
- type BudgetCounter
- type BudgetCounterStatus
- type BudgetLimit
- type CancelAction
- type ChannelRef
- type CloseReason
- type ContextItem
- type Debounce
- type Decision
- type Destination
- type DispatchAction
- type DocumentError
- type Duration
- type Effect
- type EffectAction
- type EffectOp
- type EffectResult
- type EffectSpec
- type EffectStatus
- type EffectiveConfig
- type EffectsPolicy
- type EgressPolicy
- type Environment
- type Event
- type EventData
- type EventType
- type ExprOr
- type GitCredentialSpec
- type GitHubActionsBackend
- type GitHubProviderSpec
- type Group
- type GroupCache
- type GroupSource
- type GroupSpec
- type HarnessConfig
- type HarnessConstraint
- type HarnessOffer
- type HarnessPolicy
- type HarnessRequest
- type HarnessResolved
- type HostError
- type InlineRule
- type InputSpec
- type Instructions
- type LLMAuth
- type LabelSelector
- type LabelSelectorRequirement
- type LeasePolicy
- type Lending
- type Limits
- type Link
- type LinkAction
- type NotifyAction
- type Object
- type ObjectMeta
- type ObjectRef
- type OrgRole
- type OutputSpec
- type Pool
- type PoolBackend
- type PoolMode
- type PoolRequirements
- type PoolSpec
- type ProgressEvent
- type PromptRef
- type Provenance
- type Provider
- type ProviderScope
- type ProviderSpec
- type ProviderType
- type Queue
- type QueueSpec
- type RailVerdict
- type RailVerdictValue
- type ReadyCheck
- type RepoMount
- type Requires
- type Result
- type ResultHarness
- type ResultStatus
- type ResyncPolicy
- type RetryPolicy
- type RetryReason
- type Rule
- type RuleSelection
- type RuleSet
- type RuleSetSpec
- type RuleSpec
- type Run
- type RunEnd
- type RunSpec
- type RunStatus
- type Scaling
- type Scope
- type SecretRef
- type Side
- type SkillRef
- type SlackProviderSpec
- type StringOrList
- type Suggestion
- type Target
- type Task
- type TaskCredentials
- type TaskHarness
- type TaskMeta
- type TaskPhase
- type TaskRunSpec
- type TaskSpec
- type TaskSpecRef
- type TaskSpecSpec
- type TaskStatus
- type Template
- type TemplateBody
- type TemplateSpec
- type TrustRule
- type TypeMeta
- type Usage
- type ValidationError
- type VersionSource
- type Webhook
- type WorkItem
- type WorkItemClosed
- type WorkItemSpec
- type WorkItemStatus
- type Workspace
Constants ¶
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).
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.
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.
const ( SelectorOpIn = "In" SelectorOpNotIn = "NotIn" SelectorOpExists = "Exists" SelectorOpDoesNotExist = "DoesNotExist" )
Label selector operators.
const APIVersion = "factory.ccf.dev/v1alpha1"
APIVersion is the only apiVersion this package accepts. Documents may omit it.
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.
const FactoryEventPrefix = "factory."
FactoryEventPrefix starts every type only the factory provider may emit.
const FactoryProvider = "factory"
FactoryProvider is the name (and type) of the built-in provider, the only source of factory.* events.
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.
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).
const MaxDecisions = 200
MaxDecisions is how many decisions a work item keeps.
const MaxWorkspaceHosts = 20
MaxWorkspaceHosts is the most entries a host list (workspace.environment.egress.allow) may have.
const ResultSchemaFile = "result.schema.json"
ResultSchemaFile is the file name of the Result schema.
const SchemaBaseURL = "https://factory.ccf.dev/schemas/v1alpha1/"
SchemaBaseURL is the base of the generated schemas' $id.
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 ¶
var ( ErrUnknownKind = errors.New("unknown kind") ErrMissingKind = errors.New("missing kind") ErrAPIVersion = errors.New("unsupported apiVersion") )
Decoding errors, wrapped by DocumentError.
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).
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.
var ( ErrLimitsCPUs = errors.New("invalid limits.cpus") ErrLimitsMemory = errors.New("invalid limits.memory") )
Limits validation errors. Limits.Validate wraps one in a *ValidationError.
var ActionTypes = []string{"dispatch", "set", "notify", "requestApproval", "cancel", "link", "effect"}
ActionTypes are the member names of Action, in order.
var ErrInvalidSelector = errors.New("invalid label selector")
ErrInvalidSelector is wrapped by LabelSelector.Validate's errors.
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 ¶
Encode marshals an object to block-style YAML. It writes apiVersion only when the object has one.
func IsConfigKind ¶
IsConfigKind reports whether kind is a catalog kind.
func IsExpression ¶
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 ¶
SchemaFile returns the schema file name for a config kind, e.g. taskspec.schema.json.
func Schemas ¶
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 ¶
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.
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.
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 (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 ¶
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).
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 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 ¶
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 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.
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.
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 (EffectOp) JSONSchema ¶
func (EffectOp) JSONSchema() *jsonschema.Schema
JSONSchema describes EffectOp as the enum of known ops.
type EffectResult ¶
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).
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 ¶
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) ProviderTypes ¶
func (t EventType) ProviderTypes() []ProviderType
ProviderTypes returns the provider types that emit t, or nil for an unknown type.
type ExprOr ¶
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]) JSONSchema ¶
func (ExprOr[T]) JSONSchema() *jsonschema.Schema
JSONSchema describes ExprOr as oneOf [string, T].
func (ExprOr[T]) MarshalJSON ¶
MarshalJSON writes the expression string, or the value.
func (*ExprOr[T]) UnmarshalJSON ¶
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.
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.
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 ¶
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 ¶
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 ¶
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.
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 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.
type PoolBackend ¶
type PoolBackend struct {
Type string `json:"type"`
GitHubActions *GitHubActionsBackend `json:"githubActions,omitzero"`
}
PoolBackend runs ephemeral agents.
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 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.
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.
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 ¶
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.
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.
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.
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 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 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 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.
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.
type TaskSpecRef ¶
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.
type TemplateBody ¶
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 ¶
TypeMeta is embedded in every kind. APIVersion may be omitted in documents and is never added on output.
func (*TypeMeta) GetTypeMeta ¶
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 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.
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.
Source Files
¶
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. |