run

Documentation

Overview

Package run defines the Run domain entity for agent execution attempts.

Index

• type DeliverMode
• type ExecMode
• type Run
  • func (r *Run) Validate() error
• type StallTracker
  • func NewStallTracker(threshold int) *StallTracker
  • func (s *StallTracker) IsStalled() bool
  • func (s *StallTracker) RecordStep(tool string, success bool, output string) bool
  • func (s *StallTracker) Reset()
• type StartRequest
  • func (r *StartRequest) Validate() error
• type Status
• type ToolCallRequest
• type ToolCallResponse
• type ToolCallResult

Types

type DeliverMode

type DeliverMode string

DeliverMode defines how the output of a successful run is delivered.

const (
	DeliverModeNone        DeliverMode = ""             // No delivery action
	DeliverModePatch       DeliverMode = "patch"        // Generate diff/patch file
	DeliverModeCommitLocal DeliverMode = "commit-local" // Git commit locally (no push)
	DeliverModeBranch      DeliverMode = "branch"       // Push to feature branch
	DeliverModePR          DeliverMode = "pr"           // Create pull request
)

type ExecMode

type ExecMode string

ExecMode defines how the agent accesses the project filesystem.

const (
	ExecModeMount   ExecMode = "mount"   // Direct host filesystem access
	ExecModeSandbox ExecMode = "sandbox" // Isolated container
)

type Run

type Run struct {
	ID            string      `json:"id"`
	TaskID        string      `json:"task_id"`
	AgentID       string      `json:"agent_id"`
	ProjectID     string      `json:"project_id"`
	TeamID        string      `json:"team_id,omitempty"`
	PolicyProfile string      `json:"policy_profile"`
	ExecMode      ExecMode    `json:"exec_mode"`
	DeliverMode   DeliverMode `json:"deliver_mode,omitempty"`
	Status        Status      `json:"status"`
	StepCount     int         `json:"step_count"`
	CostUSD       float64     `json:"cost_usd"`
	Output        string      `json:"output,omitempty"`
	Error         string      `json:"error,omitempty"`
	Version       int         `json:"version"`
	StartedAt     time.Time   `json:"started_at"`
	CompletedAt   *time.Time  `json:"completed_at,omitempty"`
	CreatedAt     time.Time   `json:"created_at"`
	UpdatedAt     time.Time   `json:"updated_at"`
}

Run represents a single execution attempt of a task by an agent under a specific policy. One task can have multiple runs (retries, different agents, different policies).

func (*Run) Validate

func (r *Run) Validate() error

Validate checks that a Run has all required fields and valid values.

type StallTracker

type StallTracker struct {
	// contains filtered or unexported fields
}

StallTracker monitors consecutive non-progress steps to detect agent stalls.

func NewStallTracker

func NewStallTracker(threshold int) *StallTracker

NewStallTracker creates a tracker that triggers after threshold consecutive no-progress steps.

func (*StallTracker) IsStalled

func (s *StallTracker) IsStalled() bool

IsStalled returns whether the tracker has detected a stall.

func (*StallTracker) RecordStep

func (s *StallTracker) RecordStep(tool string, success bool, output string) bool

RecordStep records a tool execution and returns true if stalling is detected. Progress = Edit/Write/Bash with success=true and non-repeated output.

func (*StallTracker) Reset

func (s *StallTracker) Reset()

Reset clears the stall counter and hash history.

type StartRequest

type StartRequest struct {
	TaskID        string      `json:"task_id"`
	AgentID       string      `json:"agent_id"`
	ProjectID     string      `json:"project_id"`
	TeamID        string      `json:"team_id,omitempty"`
	PolicyProfile string      `json:"policy_profile,omitempty"`
	ExecMode      ExecMode    `json:"exec_mode,omitempty"`
	DeliverMode   DeliverMode `json:"deliver_mode,omitempty"`
}

StartRequest holds the fields needed to start a new run.

func (*StartRequest) Validate

func (r *StartRequest) Validate() error

Validate checks that a StartRequest has all required fields.

type Status

type Status string

Status represents the current state of a run.

const (
	StatusPending     Status = "pending"
	StatusRunning     Status = "running"
	StatusCompleted   Status = "completed"
	StatusFailed      Status = "failed"
	StatusCancelled   Status = "cancelled"
	StatusTimeout     Status = "timeout"
	StatusQualityGate Status = "quality_gate" // Quality gate check in progress
)

type ToolCallRequest

type ToolCallRequest struct {
	RunID   string `json:"run_id"`
	CallID  string `json:"call_id"`
	Tool    string `json:"tool"`
	Command string `json:"command,omitempty"`
	Path    string `json:"path,omitempty"`
}

ToolCallRequest represents a worker requesting permission to execute a tool.

type ToolCallResponse

type ToolCallResponse struct {
	RunID    string `json:"run_id"`
	CallID   string `json:"call_id"`
	Decision string `json:"decision"` // "allow", "deny", "ask"
	Reason   string `json:"reason,omitempty"`
}

ToolCallResponse is the control plane's decision on a tool call request.

type ToolCallResult

type ToolCallResult struct {
	RunID    string        `json:"run_id"`
	CallID   string        `json:"call_id"`
	Success  bool          `json:"success"`
	Output   string        `json:"output,omitempty"`
	Error    string        `json:"error,omitempty"`
	CostUSD  float64       `json:"cost_usd,omitempty"`
	Duration time.Duration `json:"duration,omitempty"`
}

ToolCallResult reports the outcome of an executed tool call.