agentdispatch

package
v0.19.0 Latest Latest
Warning

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

 Go to latest Published: Sep 7, 2026 License: MIT Imports: 43 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ToolOptions  = "dispatch_options"
	ToolStart    = "dispatch_start"
	ToolWait     = "dispatch_wait"
	ToolContinue = "dispatch_continue"
	ToolCancel   = "dispatch_cancel"
	ToolInspect  = "dispatch_inspect"
	ToolOutput   = "dispatch_output"
)

MCP tool names. They are the canonical agent-facing Agent Dispatch surface and are deliberately terse: every enabled caller carries all seven schemas in its always-present context.

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"
	// AgentGrok is the Grok dispatch target and caller marker value.
	AgentGrok = "grok"
	// AgentRandom is rejected by start: every conversation names its exact agent.
	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 prompt sources (--prompt text and --prompt-file contents) 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 Continue added in v0.14.0 

func Continue(opts ContinueOptions) error

Continue starts the next invocation in an existing terminal conversation.

func Inspect added in v0.13.0 

func Inspect(request InspectRequest) error

Inspect returns a non-blocking observation of one invocation. It never signals processes or waits for a busy run lock.

func Output added in v0.19.0 

func Output(request OutputRequest) error

Output returns bounded text for a completed final answer or the captured event stream that may contain partial output from any invocation state.

func RunMCPServer added in v0.15.0 

func RunMCPServer(ctx context.Context, opts MCPServerOptions) error

RunMCPServer serves the Agent Dispatch tools over stdio until the client disconnects or ctx is cancelled. Nothing but the SDK ever writes to stdout: every dispatch operation renders into a private buffer.

func RunWorker added in v0.14.0 

func RunWorker(root string, runID string, gate io.Reader) error

RunWorker executes one prepared invocation after its parent authorizes it.

func Start added in v0.14.0 

func Start(opts StartOptions) error

Start creates a durable conversation and returns as soon as its worker is authorized to begin. The worker cannot contact the provider before the complete handle response has been written.

func Wait added in v0.14.0 

func Wait(request WaitRequest) error

Wait blocks until the selected condition is met or the bounded wait expires. Expiration reports the current observation and whether the requested condition was met. A handle is resolved once; an invocation ID never follows a later continuation.

func WriteOptions 

func WriteOptions(req OptionsRequest) error

WriteOptions renders the discovery contract as one JSON object.

Types

type AgentOption added in v0.14.0 

type AgentOption struct {
	Agent             string      `json:"agent"`
	Available         bool        `json:"available"`
	UnavailableReason string      `json:"unavailable_reason,omitempty"`
	Model             FieldOption `json:"model"`
	ReasoningEffort   FieldOption `json:"reasoning_effort"`
}

AgentOption describes one selectable provider and its optional overrides.

type CancelRequest added in v0.13.0 

type CancelRequest struct {
	Root         string
	ID           string
	Handle       string
	InvocationID string
	Stdout       io.Writer
}

CancelRequest identifies one active invocation by handle or invocation UUID.

type CapabilityOption added in v0.13.0 

type CapabilityOption struct {
	Supported bool
	Reason    string
}

CapabilityOption is an internal provider-availability result.

type CommandFactory 

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

CommandFactory creates a command for a target adapter.

type ContinueInput added in v0.15.0 

type ContinueInput struct {
	Handle     string `json:"handle"`
	Prompt     string `json:"prompt,omitempty"`
	PromptFile string `json:"prompt_file,omitempty"`
}

ContinueInput mirrors the CLI's `al dispatch continue` inputs.

type ContinueOptions added in v0.14.0 

type ContinueOptions struct {
	Root          string
	WorkDir       string
	Handle        string
	Prompt        string
	PromptFile    string
	Stdout        io.Writer
	Stderr        io.Writer
	Env           []string
	LookPath      func(string) (string, error)
	VersionLookup func(path string, agent string) (string, error)
	// contains filtered or unexported fields
}

ContinueOptions configures one asynchronous continuation of a conversation.

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 FieldOption 

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

FieldOption describes an optional start override.

type HandleInput added in v0.15.0 

type HandleInput struct {
	Handle string `json:"handle"`
}

HandleInput identifies one conversation by its opaque handle.

type InspectRequest added in v0.19.0 

type InspectRequest struct {
	Root         string
	ID           string
	Handle       string
	InvocationID string
	Stdout       io.Writer
}

InspectRequest identifies one invocation for a prompt, non-blocking observation.

type InspectResult added in v0.19.0 

type InspectResult struct {
	Handle                 string     `json:"handle"`
	InvocationID           string     `json:"invocation_id"`
	State                  string     `json:"state"`
	Error                  string     `json:"error,omitempty"`
	LastActivityAt         *time.Time `json:"last_activity_at,omitempty"`
	LastOutputAt           *time.Time `json:"last_output_at,omitempty"`
	TerminationConfirmed   bool       `json:"termination_confirmed"`
	TerminationConfirmedAt *time.Time `json:"termination_confirmed_at,omitempty"`
}

InspectResult is a prompt observation of one invocation. Process identities and proof details remain private implementation evidence.

type MCPServerOptions added in v0.15.0 

type MCPServerOptions struct {
	// Root is the Agent Layer configuration root.
	Root string
	// WorkDir is the caller's working directory, which differs from Root when a
	// linked worktree uses an ancestor checkout's configuration.
	WorkDir string
	// Version is reported to clients during initialization.
	Version string
	// Env is the process environment used for dispatch depth and benchmark
	// policy discovery. Nil reads os.Environ.
	Env []string
}

MCPServerOptions configures one Agent Dispatch MCP stdio server.

type OptionsInput added in v0.15.0 

type OptionsInput struct{}

OptionsInput is the (empty) input of dispatch_options.

type OptionsRequest 

type OptionsRequest struct {
	Root          string
	Env           []string
	Stdout        io.Writer
	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 {
	Agents []AgentOption `json:"agents"`
}

OptionsResponse describes the agents that may be selected by dispatch start.

func BuildOptions 

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

BuildOptions loads strict project config and reports valid start selections.

type OutputInput added in v0.19.0 

type OutputInput struct {
	Handle       string `json:"handle,omitempty"`
	InvocationID string `json:"invocation_id,omitempty"`
	Artifact     string `json:"artifact"`
}

OutputInput retrieves bounded artifact content for one invocation.

type OutputRequest added in v0.19.0 

type OutputRequest struct {
	Root         string
	ID           string
	Handle       string
	InvocationID string
	Artifact     string
	Stdout       io.Writer
}

OutputRequest retrieves bounded final-answer or event text for one invocation.

type OutputResult added in v0.19.0 

type OutputResult struct {
	Handle       string `json:"handle"`
	InvocationID string `json:"invocation_id"`
	Artifact     string `json:"artifact"`
	Content      string `json:"content"`
	Truncated    bool   `json:"truncated,omitempty"`
}

OutputResult contains bounded text from one supported invocation output.

type Result added in v0.15.0 

type Result struct {
	Handle                 string     `json:"handle"`
	InvocationID           string     `json:"invocation_id,omitempty"`
	State                  string     `json:"state"`
	ResultPath             string     `json:"result_path,omitempty"`
	Error                  string     `json:"error,omitempty"`
	LastActivityAt         *time.Time `json:"last_activity_at,omitempty"`
	LastOutputAt           *time.Time `json:"last_output_at,omitempty"`
	TerminationConfirmed   bool       `json:"termination_confirmed"`
	TerminationConfirmedAt *time.Time `json:"termination_confirmed_at,omitempty"`
	ConditionMet           *bool      `json:"condition_met,omitempty"`
}

Result is the provider-agnostic public response shared by every Agent Dispatch surface. The CLI encodes it as one JSON line on stdout; the MCP tools decode that same rendering from a private buffer, so both surfaces report identical handles, invocation IDs, states, result paths, and failure text.

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"`
	Role                    string     `json:"role,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"`
	SupervisorPID           int        `json:"supervisor_pid,omitempty"`
	SupervisorStartIdentity string     `json:"supervisor_start_identity,omitempty"`
	LauncherPID             int        `json:"launcher_pid,omitempty"`
	LauncherStartIdentity   string     `json:"launcher_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"`
	NotResumable            bool       `json:"not_resumable,omitempty"`
	TerminalReason          string     `json:"terminal_reason,omitempty"`
	TerminalExitCode        int        `json:"terminal_exit_code,omitempty"`
	LastOutputAt            *time.Time `json:"last_output_at,omitempty"`
	LastActivityAt          *time.Time `json:"last_activity_at,omitempty"`
	AnswerPath              string     `json:"answer_path"`
	StdoutPath              string     `json:"stdout_path"`
	StderrPath              string     `json:"stderr_path"`
	EventsPath              string     `json:"events_path,omitempty"`
	LineagePath             string     `json:"lineage_path,omitempty"`
	ProviderLogPath         string     `json:"provider_log_path,omitempty"`
	LaunchProtocol          string     `json:"launch_protocol,omitempty"`
	ProviderLaunchIntent    bool       `json:"provider_launch_intent,omitempty"`
	LaunchFenced            bool       `json:"launch_fenced,omitempty"`
	TerminationConfirmed    bool       `json:"termination_confirmed,omitempty"`
	TerminationConfirmedAt  *time.Time `json:"termination_confirmed_at,omitempty"`
	TerminationObservation  string     `json:"termination_observation,omitempty"`
	TerminationAttemptError string     `json:"termination_attempt_error,omitempty"`
	TerminationProof        string     `json:"termination_proof,omitempty"`
}

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

type SelectorInput added in v0.19.0 

type SelectorInput struct {
	Handle       string `json:"handle,omitempty"`
	InvocationID string `json:"invocation_id,omitempty"`
}

SelectorInput identifies one invocation by exactly one of handle or invocation_id.

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 StartInput added in v0.15.0 

type StartInput struct {
	Agent           string `json:"agent"`
	Model           string `json:"model,omitempty"`
	ReasoningEffort string `json:"reasoning_effort,omitempty"`
	Role            string `json:"role,omitempty"`
	Skill           string `json:"skill,omitempty"`
	Prompt          string `json:"prompt,omitempty"`
	PromptFile      string `json:"prompt_file,omitempty"`
}

StartInput mirrors the CLI's `al dispatch start` selection flags. Exactly one prompt source is required, matching the CLI contract.

type StartOptions added in v0.14.0 

type StartOptions struct {
	Root            string
	WorkDir         string
	Agent           string
	Model           string
	ReasoningEffort string
	Role            string
	Skill           string
	Prompt          string
	PromptFile      string
	Stdout          io.Writer
	Stderr          io.Writer
	Env             []string
	LookPath        func(string) (string, error)
	VersionLookup   func(path string, agent string) (string, error)
	// contains filtered or unexported fields
}

StartOptions configures the first asynchronous invocation of a conversation.

type WaitInput added in v0.19.0 

type WaitInput struct {
	Handle       string `json:"handle,omitempty"`
	InvocationID string `json:"invocation_id,omitempty"`
	Condition    string `json:"condition,omitempty"`
}

WaitInput waits for one invocation. Condition applies only to wait.

type WaitRequest added in v0.14.0 

type WaitRequest struct {
	Context context.Context
	Root    string
	// ID is a single positional selector: a conversation handle or invocation UUID.
	ID           string
	Handle       string
	InvocationID string
	// Condition selects the wait target. Empty and "terminal" wait for a
	// terminal outcome. "termination_confirmed" waits for durable termination proof.
	Condition string
	Stdout    io.Writer
	Timeout   time.Duration
	// PollInterval sets how often this request re-reads run state. The CLI
	// leaves it zero and keeps the responsive default; a long MCP wait sets a
	// coarser interval so a 30-minute block does not spend the whole time
	// re-reading run records.
	PollInterval time.Duration
}

WaitRequest identifies one existing dispatch invocation, by handle or invocation ID, to await without changing provider work or execution state.

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.