Documentation
¶
Overview ¶
Package effector is the Effector (design/workstreams/agent/LLD/effector.md): every change a run makes on GitHub goes through it. It has one implementation, Effector.Do over the op table in ops.go, and two front-ends generated from that table, so they can't drift: the CLI (`factory <op> …`, which is `factory-agent fx <op> …` through the workspace's shim) and a stdio MCP server (`factory mcp`) with one tool per op.
API-side ops are POST /tasks/{id}/effects with an idempotency key (keys.go); git-side ops (push-branch, stack.push, stack.rebase) run git (or `gh stack`) in the workspace through the run's in-memory credential helper, then record the op through the same endpoint. A local pre-check of the task's effects.allow and effects.labels gives fast, clear refusals; the dispatcher re-checks everything and is authoritative.
In a VM workspace ($FACTORY_RUNTIME=workspace) the Effector holds no credential: there is no FACTORY_TOKEN and no credential helper, and the workspace's gateway (HTTP_PROXY, HTTPS_PROXY) adds the run token to its effects and the repo's credential to its pushes, refusing a push to a repo the task may not write. Stack ops always take the git fallback there.
Index ¶
- Constants
- func IsOp(args []string) bool
- func Main(ctx context.Context, e *Effector, args []string, stdin io.Reader, ...) int
- func NewMCPServer(e *Effector) *mcp.Server
- func ServeMCP(ctx context.Context, e *Effector, t mcp.Transport) error
- func Usage(w io.Writer)
- type API
- type Effector
- type Error
- type Kind
- type Op
- type Options
- type Param
- type Problem
Constants ¶
const ( ExitOK = 0 ExitUsage = 2 ExitNotAllowed = 3 ExitRejected = 4 ExitGit = 5 )
Exit codes (effector.md §Exit codes).
const DefaultAttempts = 3
DefaultAttempts is how many times one call is sent when the dispatcher can't be reached (a network error), always with the same idempotency key.
const MCPInstructions = "The factory tools make every change on GitHub for this task (comments, labels, issues, pull requests, " +
"reviews, review threads, pushes) and validate the task's Result. They are the same ops as the `factory` CLI. " +
"Only the task's allowed effects succeed; a refusal says why. Repeating a call that failed is safe: it replays."
MCPInstructions are the MCP server's instructions to the harness.
const StateFile = ".effector-seq"
StateFile is the idempotency state's name in $FACTORY_OUT.
Variables ¶
This section is empty.
Functions ¶
func IsOp ¶
IsOp reports whether args name an Effector op (as opposed to the fx command's internal ones).
func Main ¶
func Main(ctx context.Context, e *Effector, args []string, stdin io.Reader, stdout, stderr io.Writer) int
Main runs `factory <op> [flags]` and returns its exit code (effector.md §Exit codes). The op's result is printed as JSON on stdout; a failure prints a message on stderr and {"error": …} on stdout.
func NewMCPServer ¶
NewMCPServer is the Effector's MCP server: one tool per op, each calling e.
Types ¶
type API ¶
type API interface {
CreateEffect(ctx context.Context, id apiclient.TaskID, body apiclient.CreateEffectJSONRequestBody, reqEditors ...apiclient.RequestEditorFn) (*http.Response, error)
}
API is the part of the dispatcher client the Effector uses.
type Effector ¶
type Effector struct {
// contains filtered or unexported fields
}
Effector runs effect ops for one task.
func FromEnv ¶
FromEnv builds the Effector of a run from its environment: FACTORY_API, FACTORY_TASK_ID, FACTORY_OUT, FACTORY_RESULT, FACTORY_EFFECTOR and FACTORY_RUNTIME. Requests carry no Authorization: the gateway adds the run token. A nil client uses a default one, which honours HTTP_PROXY (the workspace's gateway).
It fails closed on the runtime: FACTORY_RUNTIME must be pipeline.RuntimeWorkspace (the host runtime is gone), and a FACTORY_TOKEN is refused, since the workspace holds no credential. Both are usage errors that name the variable, never its value.
type Error ¶
type Error struct {
Exit int
Msg string
Problem *Problem
// Extra is more detail for the JSON error (validation problems, git output).
Extra map[string]any
Err error
}
Error is a failed op: its exit code, a message for people (and agents), and the dispatcher's problem when it answered with one.
type Kind ¶
type Kind int
Kind is a parameter's type.
const ( // String is a string; a JSON number is accepted too (PR numbers). String Kind = iota // Bool is a flag. Bool // List is a list of strings: an MCP array (or a comma-separated string), a repeatable // and comma-separated CLI flag. List // Text is a body: an MCP string; on the CLI --<flag> <text> or --<flag>-file <path> // ("-" is stdin). Text // JSON is a JSON value: the MCP value itself; on the CLI --<flag> <json> or // --<flag>-file <path>. JSON )
Parameter kinds.
type Op ¶
type Op struct {
// Words are the CLI command after `factory`: {"pr", "open"}.
Words []string
// Effects are the effect ops it may send (the review op picks one by its event); empty
// for local ops.
Effects []v1alpha1.EffectOp
Help string
Params []Param
// contains filtered or unexported fields
}
Op is one Effector op: a CLI command (Words), an MCP tool (Name), its params, and what it does. Both front-ends are generated from the ops table.
type Options ¶
type Options struct {
// API is the dispatcher client: authenticated as the agent on the host, or without a
// credential in a VM workspace, where the gateway adds the run token. nil refuses API-side
// ops (and the records of git-side ones) with a usage error.
API API
// TaskID is the run's task ($FACTORY_TASK_ID).
TaskID string
// Config is the run's policy and layout ($FACTORY_EFFECTOR); nil skips the local
// pre-check (the dispatcher still checks).
Config *pipeline.EffectorConfig
// State is the idempotency state file ($FACTORY_OUT/.effector-seq); "" keeps the state
// in memory, for this process only.
State string
// Result is $FACTORY_RESULT, where `factory result` copies a valid Result.
Result string
// Dir is where git ops run: Config.RepoDir, else the working directory.
Dir string
// Git is the git executable (default "git", from PATH).
Git string
// Env is git's environment (default os.Environ()): the VM workspace run's, with no
// credential helper, a placeholder GH_TOKEN, and the gateway's proxy and CA variables.
Env []string
// Attempts per call on network errors (default DefaultAttempts).
Attempts int
// Sleep waits between attempts (default: a timer, honouring ctx).
Sleep func(ctx context.Context, d time.Duration) error
}
Options configure an Effector.
type Param ¶
type Param struct {
Name string
Flag string
Kind Kind
Required bool
Enum []string
Help string
// Schema is a JSON param's JSON Schema.
Schema map[string]any
}
Param is one argument of an op: an MCP property named Name and a CLI flag named Flag (kebab-case Name by default), plus --<flag>-file for Text and JSON.
type Problem ¶
type Problem struct {
Status int `json:"status"`
Code string `json:"code,omitempty"`
Title string `json:"title,omitempty"`
Detail string `json:"detail,omitempty"`
Fields []apiclient.FieldError `json:"fields,omitempty"`
RetryAfter int `json:"retryAfterSeconds,omitempty"`
}
Problem is the dispatcher's answer to a refused or failed effect.