command

type Contribution ¶

type Contribution struct {
	Spec
	// ObserveRead requests auxiliary read-completion evidence from the host.
	ObserveRead bool
	Run         func(context.Context, Request) (Output, error)
}

Contribution pairs catalog metadata with its compiled command implementation. Run receives the exact host argv and stdin. The frontend host publishes any omitted output before returning streams and status to Codex.

type Definition ¶

type Definition[S any] struct {
	Spec
	ObserveRead bool
	Run         func(S, context.Context, Request) (Output, error)
}

Definition binds a command to its module's constructed service.

type OmittedOutput ¶

type OmittedOutput struct {
	// Source provenance and requested recovery budget, separate from serialized output.
	SourceRow  uint64 `json:"-"`
	MaxTokens  int    `json:"-"`
	StdoutKind string `json:"stdoutKind,omitempty"`
	StderrKind string `json:"stderrKind,omitempty"`
	Stdout     string `json:"stdout"`
	Stderr     string `json:"stderr"`
}

type Output ¶

type Output struct {
	Delivery      PendingDelivery `json:"-"`
	OmittedOutput *OmittedOutput  `json:"omittedOutput,omitempty"`
	FailureClass  string          `json:"failureClass,omitempty"`
	Stdout        string          `json:"stdout"`
	Stderr        string          `json:"stderr"`
	ExitCode      int             `json:"exitCode"`
}

type PendingDelivery ¶

type PendingDelivery interface {
	ReferenceCount() int
	Prepare(references []string) (PreparedDelivery, error)
}

PendingDelivery finalizes captured output with actual reserved reference identities. Preparation performs no I/O and does not mutate the plan.

type PreparedDelivery ¶

type PreparedDelivery struct {
	Referenced, Unreferenced Output
	Recovery                 []RecoveryOutput
}

PreparedDelivery keeps the same admitted bodies on publication failure. Neither output contains another plan or an unprocessed omission.

type ProcessScope ¶

type ProcessScope uint8

ProcessScope states the caller's ownership of subprocess groups and descendants.

const (
	// StandaloneProcess permits a command to own its resolver process groups.
	StandaloneProcess ProcessScope = iota
	// HostProcessGroup keeps descendants in the host's group without process-wide cleanup.
	HostProcessGroup
	// DedicatedHostProcess additionally permits cleanup of this worker's descendants.
	// Only a dedicated authenticated frontend worker may receive this scope.
	DedicatedHostProcess
)

type RecoveryFailure ¶

type RecoveryFailure interface {
	RecoveryFailed(error) Output
}

RecoveryFailure optionally supplies a command-specific result after recovery fails. It performs no I/O and must return neither Delivery nor OmittedOutput. Cancellation takes precedence. Completed mutations use it to preserve their full report and original status without repeating an effect.

type RecoveryOutput ¶

type RecoveryOutput struct {
	// ChangeSelection is an opaque retained-evidence selection. When set, all
	// output fields and ExitCode must be zero.
	ChangeSelection []byte
	ReferenceIndex  int
	OmittedOutput
	ExitCode int
}

RecoveryOutput binds one captured payload to a reserved reference slot.

type Request ¶

type Request struct {
	Args         []string
	Stdin        *os.File
	Scope        scope.Retained
	ProcessScope ProcessScope
}

Request carries exact process input and the authenticated host-selected scope. Services are supplied by composition, never looked up through the request.

type Spec ¶

type Spec struct {
	Name, Description string
}

Spec is an executable contribution, independent of the backend's wire format.

func (s Spec) Validate() error