effector

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: 29 Imported by: 0

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

View Source
const (
	ExitOK         = 0
	ExitUsage      = 2
	ExitNotAllowed = 3
	ExitRejected   = 4
	ExitGit        = 5
)

Exit codes (effector.md §Exit codes).

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

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

View Source
const StateFile = ".effector-seq"

StateFile is the idempotency state's name in $FACTORY_OUT.

Variables

This section is empty.

Functions

func IsOp

func IsOp(args []string) bool

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

func NewMCPServer(e *Effector) *mcp.Server

NewMCPServer is the Effector's MCP server: one tool per op, each calling e.

func ServeMCP

func ServeMCP(ctx context.Context, e *Effector, t mcp.Transport) error

ServeMCP serves the MCP protocol on t (stdio in a run) until the client disconnects or ctx is done.

func Usage

func Usage(w io.Writer)

Usage prints the op list.

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

func FromEnv(getenv func(string) string, client *http.Client) (*Effector, error)

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.

func New

func New(o Options) *Effector

New returns an Effector.

func (*Effector) Do

func (e *Effector) Do(ctx context.Context, op string, args map[string]any) (map[string]any, error)

Do runs the op named by its MCP tool name (pr_open) or CLI words (pr open) with its arguments (the MCP tool's input). The result is the JSON the CLI prints.

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.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

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.

func Ops

func Ops() []*Op

Ops returns the op table, in its fixed order.

func (*Op) Command

func (o *Op) Command() string

Command is the op's CLI command: "factory pr open".

func (*Op) Name

func (o *Op) Name() string

Name is the op's MCP tool name: its words joined by "_", with "-" as "_" (tool names must suit every harness's function-name rules).

func (*Op) Tool

func (o *Op) Tool() *mcp.Tool

Tool is the op's MCP tool: its name, description and JSON Schema input (one property per param; the CLI's --<flag>-file variants have no MCP property, the value is given inline).

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.

func (Param) CLIFlag

func (p Param) CLIFlag() string

CLIFlag is the param's CLI flag name.

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.

Jump to

Keyboard shortcuts

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