agentdispatch

package
v0.13.0 Latest Latest
Warning

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

 Go to latest Published: Jul 17, 2026 License: MIT Imports: 34 Imported by: 0

Documentation

Index

Constants

View Source 
const (

	// AntigravityPromptMaxBytes retains headroom below common ARG_MAX limits
	// because Antigravity accepts print-mode prompts only as an argument.
	AntigravityPromptMaxBytes = 100 * 1024
	// AntigravityPrintTimeout keeps a headless dispatch alive long enough for
	// a normal agent turn while the runner remains responsible for cancellation.
	AntigravityPrintTimeout = "24h"
)
View Source 
const (
	// AgentCodex is the Codex dispatch target and caller marker value.
	AgentCodex = "codex"
	// AgentClaude is the Claude dispatch target and caller marker value.
	AgentClaude = "claude"
	// AgentAntigravity is the Antigravity dispatch target and caller marker value.
	AgentAntigravity = "antigravity"
	// AgentRandom is the resolver value that selects an eligible target at random.
	AgentRandom = "random"
)
View Source 
const (
	// ExitUsage is the stable dispatch usage/resolution failure exit code.
	ExitUsage = 64
	// ExitConfig is the stable dispatch configuration/state failure exit code.
	ExitConfig = 65
	// ExitUnavailable is the stable dispatch target-unavailable exit code.
	ExitUnavailable = 69
	// ExitTargetFailure is the stable dispatch target/adapter failure exit code.
	ExitTargetFailure = 70
	// ExitNested is the stable dispatch nested-call failure exit code.
	ExitNested = 75
	// ExitSigint is the stable dispatch SIGINT exit code.
	ExitSigint = 130
	// ExitSigterm is the stable dispatch SIGTERM exit code.
	ExitSigterm = 143
)
View Source 
const MaxStdinPromptBytes = 10 * 1024 * 1024

MaxStdinPromptBytes caps stdin reads when resolving the dispatch prompt so a runaway producer cannot exhaust process memory. 10 MiB is well above any realistic agent prompt and below typical container memory budgets.

Variables

This section is empty.

Functions

func BuildChildPrompt 

func BuildChildPrompt(project *config.ProjectConfig, target string, prompt string, skill string) ([]byte, error)

BuildChildPrompt validates the optional skill and returns exact target-native prompt bytes for the selected target.

func Cancel added in v0.13.0 

func Cancel(request CancelRequest) error

Cancel terminates only the exact Agent Layer-owned process group.

func Delete added in v0.13.0 

func Delete(root string, name string) error

Delete releases an inactive Agent Layer mapping. Provider conversations and transcripts are intentionally untouched.

func Fanout added in v0.13.0 

func Fanout(opts FanoutOptions) error

Fanout sends one shared prompt and skill to two or more independently recorded targets, waits for all children, then emits one aggregate manifest.

func History added in v0.13.0 

func History(request HistoryRequest) error

History writes every retained immutable turn for one friendly name.

func Inspect added in v0.13.0 

func Inspect(request InspectionRequest) error

Inspect writes one factual dispatch inspection by current name or immutable run UUID. It does not mutate dispatch state or provider processes.

func List added in v0.13.0 

func List(request ListRequest) error

List writes all current name-keyed reservations and durable conversations.

func ResolvePrompt 

func ResolvePrompt(args []string, stdin io.Reader, readStdin bool) (string, error)

ResolvePrompt returns the caller prompt. Positional args win over piped stdin.

func Resume added in v0.13.0 

func Resume(opts ResumeOptions) error

Resume continues exactly the provider session addressed by name.

func Run 

func Run(opts RunOptions) error

Run starts one fresh provider conversation. Existing conversations are never selected implicitly; callers must use Resume with a durable friendly name.

func WriteOptions 

func WriteOptions(req OptionsRequest) error

WriteOptions renders stable JSON or concise human-readable capability facts.

Types

type Artifacts added in v0.13.0 

type Artifacts struct {
	Answer      string `json:"answer"`
	Stdout      string `json:"stdout"`
	Stderr      string `json:"stderr"`
	Events      string `json:"events,omitempty"`
	ProviderLog string `json:"provider_log,omitempty"`
}

Artifacts identifies private diagnostic evidence without embedding it in normal command output.

type CallerInfo 

type CallerInfo struct {
	Known bool   `json:"known"`
	Agent string `json:"agent,omitempty"`
}

CallerInfo describes env-only dispatch caller detection.

type CancelRequest added in v0.13.0 

type CancelRequest struct {
	Root string
	ID   string
}

CancelRequest identifies one active run, friendly conversation, or fanout.

type CapabilityOption added in v0.13.0 

type CapabilityOption struct {
	Supported bool   `json:"supported"`
	Reason    string `json:"reason,omitempty"`
}

CapabilityOption reports a distinct operation capability. Capabilities are never collapsed into a misleading single dispatch-capable boolean.

type CommandFactory 

type CommandFactory func(name string, args ...string) *exec.Cmd

CommandFactory creates a command for a target adapter.

type ExitError 

type ExitError struct {
	Code    int
	Message string
	Err     error
}

ExitError carries a dispatch-owned exit category and the message already written or intended for stderr by the CLI wrapper.

func (*ExitError) Error 

func (e *ExitError) Error() string

Error returns the user-facing dispatch error text.

func (*ExitError) Unwrap 

func (e *ExitError) Unwrap() error

Unwrap returns the wrapped lower-level error.

type FanoutChild added in v0.13.0 

type FanoutChild struct {
	RunID      string       `json:"run_id"`
	Name       string       `json:"name"`
	Target     FanoutTarget `json:"target"`
	Status     string       `json:"status"`
	ResultPath string       `json:"result_path"`
	Error      string       `json:"error,omitempty"`
}

FanoutChild is immutable child evidence referenced by a fanout manifest.

type FanoutManifest added in v0.13.0 

type FanoutManifest struct {
	ID          string        `json:"id"`
	State       string        `json:"state"`
	CreatedAt   time.Time     `json:"created_at"`
	CompletedAt *time.Time    `json:"completed_at,omitempty"`
	Children    []FanoutChild `json:"children"`
	Error       string        `json:"error,omitempty"`
}

FanoutManifest is the aggregate terminal evidence for one synchronous fanout.

type FanoutOptions added in v0.13.0 

type FanoutOptions struct {
	Root          string
	WorkDir       string
	Targets       []FanoutTarget
	Skill         string
	PromptArgs    []string
	Stdin         io.Reader
	ReadStdin     bool
	Stdout        io.Writer
	Stderr        io.Writer
	Env           []string
	Quiet         bool
	LookPath      func(string) (string, error)
	NewCommand    CommandFactory
	VersionLookup func(path string, agent string) (string, error)
}

FanoutOptions configures one synchronous shared-prompt fanout.

type FanoutTarget added in v0.13.0 

type FanoutTarget struct {
	Agent           string `json:"agent"`
	Model           string `json:"model,omitempty"`
	ReasoningEffort string `json:"reasoning_effort,omitempty"`
}

FanoutTarget is one self-contained provider target specification.

func ParseFanoutTarget added in v0.13.0 

func ParseFanoutTarget(value string) (FanoutTarget, error)

ParseFanoutTarget validates one repeated self-contained --target value.

type FieldOption 

type FieldOption struct {
	OverrideSupported bool     `json:"override_supported"`
	Configured        string   `json:"configured"`
	Suggestions       []string `json:"suggestions"`
	AllowCustom       bool     `json:"allow_custom"`
}

FieldOption describes per-run override metadata.

type HistoryRequest added in v0.13.0 

type HistoryRequest struct {
	Root   string
	Name   string
	Stdout io.Writer
	Stderr io.Writer
	JSON   bool
}

HistoryRequest configures immutable turn-history output.

type Inspection added in v0.13.0 

type Inspection struct {
	ID                   string     `json:"id"`
	Name                 string     `json:"name"`
	Agent                string     `json:"agent"`
	Model                string     `json:"model,omitempty"`
	ReasoningEffort      string     `json:"reasoning_effort,omitempty"`
	Skill                string     `json:"skill,omitempty"`
	State                string     `json:"state"`
	RecoveryState        string     `json:"recovery_state"`
	Mode                 string     `json:"mode"`
	Attempt              int        `json:"attempt"`
	Process              string     `json:"process"`
	StartedAt            time.Time  `json:"started_at"`
	LastOutputAt         *time.Time `json:"last_output_at,omitempty"`
	LastActivityAt       *time.Time `json:"last_activity_at,omitempty"`
	LastActivityKind     string     `json:"last_activity_kind,omitempty"`
	ProviderConversation string     `json:"provider_conversation,omitempty"`
	NotResumable         bool       `json:"not_resumable,omitempty"`
	TerminalReason       string     `json:"terminal_reason,omitempty"`
	Artifacts            Artifacts  `json:"artifacts"`
}

Inspection is the stable factual shape emitted by inspect. It deliberately reports process transport facts without inferring provider health.

type InspectionRequest added in v0.13.0 

type InspectionRequest struct {
	Root   string
	ID     string
	Stdout io.Writer
	JSON   bool
}

InspectionRequest configures factual, read-only dispatch inspection.

type ListRequest added in v0.13.0 

type ListRequest struct {
	Root   string
	Stdout io.Writer
	JSON   bool
}

ListRequest configures durable mapping listing.

type OptionsRequest 

type OptionsRequest struct {
	Root          string
	Env           []string
	Stdout        io.Writer
	JSON          bool
	LookPath      func(string) (string, error)
	VersionLookup func(path string, agent string) (string, error)
}

OptionsRequest configures an Agent Dispatch options response.

type OptionsResponse 

type OptionsResponse struct {
	Caller  CallerInfo     `json:"caller"`
	Random  RandomInfo     `json:"random"`
	Targets []TargetOption `json:"targets"`
}

OptionsResponse is the stable v0.13 Agent Dispatch capability contract.

func BuildOptions 

func BuildOptions(req OptionsRequest) (*OptionsResponse, error)

BuildOptions loads strict project config and reports each operation's exact availability for the installed provider version.

type RandomChooser 

type RandomChooser func([]string) (string, error)

RandomChooser selects one target from an already-built random pool.

type RandomInfo 

type RandomInfo struct {
	Pool           []string `json:"pool"`
	ExcludesCaller bool     `json:"excludes_caller"`
	Empty          bool     `json:"empty"`
}

RandomInfo describes the current fresh-dispatch random pool.

type ResumeOptions added in v0.13.0 

type ResumeOptions struct {
	Root          string
	WorkDir       string
	Name          string
	Skill         string
	PromptArgs    []string
	Stdin         io.Reader
	ReadStdin     bool
	Stdout        io.Writer
	Stderr        io.Writer
	Env           []string
	Quiet         bool
	LookPath      func(string) (string, error)
	NewCommand    CommandFactory
	VersionLookup func(path string, agent string) (string, error)
}

ResumeOptions configures one explicit continuation of a durable session.

type RunOptions 

type RunOptions struct {
	Root            string
	WorkDir         string
	Agent           string
	Model           string
	ReasoningEffort string
	Skill           string
	PromptArgs      []string
	Stdin           io.Reader
	ReadStdin       bool
	Stdout          io.Writer
	Stderr          io.Writer
	Env             []string
	Quiet           bool
	LookPath        func(string) (string, error)
	NewCommand      CommandFactory
	ChooseRandom    RandomChooser
	// VersionLookup reads the installed provider version. Production uses the
	// provider's --version output; tests may inject exact fixture evidence.
	VersionLookup func(path string, agent string) (string, error)
}

RunOptions configures a single dispatch run.

type RunRecord added in v0.13.0 

type RunRecord struct {
	ID                   string     `json:"id"`
	Name                 string     `json:"name"`
	Agent                string     `json:"agent"`
	ProviderVersion      string     `json:"provider_version"`
	Model                string     `json:"model,omitempty"`
	ReasoningEffort      string     `json:"reasoning_effort,omitempty"`
	Skill                string     `json:"skill,omitempty"`
	Mode                 string     `json:"mode"`
	State                string     `json:"state"`
	RecoveryState        string     `json:"recovery_state"`
	Revision             uint64     `json:"revision"`
	Attempt              int        `json:"attempt"`
	PID                  int        `json:"pid,omitempty"`
	ProcessGroupID       int        `json:"process_group_id,omitempty"`
	ProcessStartIdentity string     `json:"process_start_identity,omitempty"`
	StartedAt            time.Time  `json:"started_at"`
	UpdatedAt            time.Time  `json:"updated_at"`
	CompletedAt          *time.Time `json:"completed_at,omitempty"`
	ProviderSessionID    string     `json:"provider_session_id,omitempty"`
	PreviousRunID        string     `json:"previous_run_id,omitempty"`
	ParentRunID          string     `json:"parent_run_id,omitempty"`
	FanoutGroupID        string     `json:"fanout_group_id,omitempty"`
	NotResumable         bool       `json:"not_resumable,omitempty"`
	TerminalReason       string     `json:"terminal_reason,omitempty"`
	LastOutputAt         *time.Time `json:"last_output_at,omitempty"`
	LastActivityAt       *time.Time `json:"last_activity_at,omitempty"`
	LastActivityKind     string     `json:"last_activity_kind,omitempty"`
	AnswerPath           string     `json:"answer_path"`
	StdoutPath           string     `json:"stdout_path"`
	StderrPath           string     `json:"stderr_path"`
	EventsPath           string     `json:"events_path,omitempty"`
	ProviderLogPath      string     `json:"provider_log_path,omitempty"`
}

RunRecord is private, recoverable dispatch evidence. It never contains the caller prompt or a provider transcript.

type Session added in v0.13.0 

type Session struct {
	Name              string    `json:"name"`
	Agent             string    `json:"agent"`
	Model             string    `json:"model,omitempty"`
	ReasoningEffort   string    `json:"reasoning_effort,omitempty"`
	TargetPinned      bool      `json:"target_pinned,omitempty"`
	ProviderSessionID string    `json:"provider_session_id,omitempty"`
	CreatedAt         time.Time `json:"created_at"`
	LastUsedAt        time.Time `json:"last_used_at"`
	State             string    `json:"state,omitempty"`
	RunID             string    `json:"run_id,omitempty"`
	ActiveRunID       string    `json:"active_run_id,omitempty"`
	ActiveClaimKnown  bool      `json:"active_claim_known,omitempty"`
}

Session is the durable, name-keyed mapping owned by Agent Layer. Provider transcripts remain provider-owned; this record contains only the alias needed for explicit continuation.

type TargetCapabilities added in v0.13.0 

type TargetCapabilities struct {
	Fresh   CapabilityOption `json:"fresh"`
	Resume  CapabilityOption `json:"resume"`
	Inspect CapabilityOption `json:"inspect"`
}

TargetCapabilities reports fresh execution, durable continuation, and factual inspection separately.

type TargetOption 

type TargetOption struct {
	Agent                 string             `json:"agent"`
	Enabled               bool               `json:"enabled"`
	Installed             bool               `json:"installed"`
	InstalledVersion      string             `json:"installed_version,omitempty"`
	SupportedVersion      string             `json:"supported_version"`
	CompatibilityWarning  string             `json:"compatibility_warning,omitempty"`
	Capabilities          TargetCapabilities `json:"capabilities"`
	RandomEligible        bool               `json:"random_eligible"`
	RandomExclusionReason *string            `json:"random_exclusion_reason,omitempty"`
	Model                 FieldOption        `json:"model"`
	ReasoningEffort       FieldOption        `json:"reasoning_effort"`
	UnavailableReasons    []string           `json:"unavailable_reasons"`
}

TargetOption describes one target's installed/configured capability facts. CompatibilityWarning is set when the installed version is newer than the tested version: the target stays supported and dispatchable, and the warning names both versions.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.