Skip to content

Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.

13.4 KB
Raw Blame
package domain

import (
	"encoding/json"
	"time"
)

const (
	RunnerWorkspaceOperationCheckpointStatus  = "checkpoint_status"
	RunnerWorkspaceOperationCheckpointExport  = "checkpoint_export"
	RunnerWorkspaceOperationCheckpointRead    = "checkpoint_read"
	RunnerWorkspaceOperationCheckpointClose   = "checkpoint_close"
	RunnerWorkspaceOperationCheckpointUpload  = "checkpoint_upload"
	RunnerWorkspaceOperationCheckpointAppend  = "checkpoint_append"
	RunnerWorkspaceOperationCheckpointCommit  = "checkpoint_commit"
	RunnerWorkspaceOperationArtifacts         = "restore_artifacts" // additive, never replaces existing files
	RunnerWorkspaceOperationReclaim           = "reclaim"           // service-only worker reclamation
	RunnerWorkspaceOperationCheckpoint        = "checkpoint"
	RunnerWorkspaceOperationRestore           = "restore"
	RunnerWorkspaceOperationPrepare           = "prepare"
	RunnerWorkspaceOperationPreparationStatus = "preparation_status"
	RunnerWorkspaceOperationPreparationRecord = "preparation_record"
	RunnerWorkspaceOperationTerminal          = "terminal"
	RunnerWorkspaceOperationWrite             = "write"
	RunnerWorkspaceOperationInfo              = "info"
	RunnerWorkspaceOperationTree              = "tree"
	RunnerWorkspaceOperationFile              = "file"
	RunnerWorkspaceOperationDiff              = "diff"
	RunnerWorkspaceOperationSearch            = "search"
	RunnerWorkspaceOperationLog               = "log"
	RunnerWorkspaceOperationCommit            = "commit"
	RunnerWorkspaceOperationBrowser           = "browser"
	RunnerWorkspaceOperationCheckouts         = "checkouts"
	RunnerWorkspaceOperationMaintenance       = "maintenance"
	RunnerWorkspaceOperationLoginModels       = "login_models"
)

// RunnerWorkspaceRequest is a bounded workspace request sent over the
// runner's outbound control socket. Responses are transient and are never
// persisted in runner_tasks or the run record.
type RunnerWorkspaceRequest struct {
	Maintenance   *RunnerMaintenanceRequest `json:"maintenance,omitempty"`
	ModelProvider string                    `json:"modelProvider,omitempty"`
	Conversation  json.RawMessage           `json:"conversation,omitempty"`
	RunKind       string                    `json:"runKind,omitempty"`
	// ConcurrentEdit marks a person editing from the IDE: the runner writes and
	// opens terminals beside running tasks instead of waiting for their fence.
	ConcurrentEdit     bool                         `json:"concurrentEdit,omitempty"`
	CheckpointTransfer *WorkspaceCheckpointTransfer `json:"checkpointTransfer,omitempty"`
	// Only the control plane may allow a clean checkout to be refreshed, before
	// any non-preparation node has run. Later nodes keep their frozen baseline.
	RefreshCleanRepositories bool `json:"refreshCleanRepositories,omitempty"`
	// Sandbox and Workflow are resolved exclusively from the frozen run by the
	// control plane. A terminal must never silently substitute a host shell.
	PreparationNodeID     string                    `json:"preparationNodeId,omitempty"`
	PreparationOutput     string                    `json:"preparationOutput,omitempty"`
	PreparationInvocation *RunnerInvocation         `json:"preparationInvocation,omitempty"`
	Sandbox               *RunnerSandboxSpec        `json:"sandbox,omitempty"`
	Workflow              *WorkflowDefinition       `json:"workflow,omitempty"`
	ArtifactFiles         []WorkspaceArtifactFile   `json:"artifactFiles,omitempty"`
	CheckpointLease       string                    `json:"checkpointLease,omitempty"`
	Checkpoint            []byte                    `json:"checkpoint,omitempty"`
	Terminal              *WorkspaceTerminalRequest `json:"terminal,omitempty"`
	TerminalOwner         int64                     `json:"terminalOwner,omitempty"`
	TerminalGitSSHKeys    map[string]string         `json:"terminalGitSshKeys,omitempty"`
	// TerminalGitHTTPCredentials belongs to TerminalOwner and is sent only on open.
	TerminalGitHTTPCredentials map[string]GitHTTPExecutionCredential `json:"terminalGitHttpCredentials,omitempty"`
	// WorkspaceRunID selects the shared checkout owner; RunID continues to
	// identify this run's independent sandbox, terminal scope and locks.
	Browser         *BrowserRequest     `json:"browser,omitempty"`
	WorkspaceRunID  string              `json:"workspaceRunId,omitempty"`
	RunID           string              `json:"runId"`
	RunStatus       string              `json:"runStatus,omitempty"`
	WorkspaceLayout string              `json:"workspaceLayout,omitempty"`
	Operation       string              `json:"operation"`
	Content         string              `json:"content,omitempty"`
	ExpectedSHA256  string              `json:"expectedSha256,omitempty"`
	Path            string              `json:"path,omitempty"`
	Query           string              `json:"query,omitempty"`
	Ref             string              `json:"ref,omitempty"`
	Repositories    []RepositoryContext `json:"repositories,omitempty"`
}

type RunnerMaintenanceRequest struct {
	Provider   string `json:"provider,omitempty"` // Empty selects the Runner binary.
	Apply      bool   `json:"apply,omitempty"`
	StatusOnly bool   `json:"statusOnly,omitempty"`
}

type RunnerMaintenanceResult struct {
	Status    string `json:"status"`
	Current   string `json:"current,omitempty"`
	Version   string `json:"version,omitempty"`
	Message   string `json:"message,omitempty"`
	CanUpdate bool   `json:"canUpdate,omitempty"`
}

// RunnerToolRequest is forwarded over the same instance-owned control socket
// as the conversation process, avoiding loopback and load-balancer affinity.
type RunnerToolRequest struct {
	SupportsCancel bool            `json:"supportsCancel,omitempty"`
	Token          string          `json:"token"`
	Body           json.RawMessage `json:"body"`
}
type RunnerToolResponse struct {
	Body  json.RawMessage `json:"body,omitempty"`
	Error string          `json:"error,omitempty"`
}

type WorkspaceCheckpointTransfer struct {
	ID     string `json:"id,omitempty"`
	Size   int64  `json:"size,omitempty"`
	SHA256 string `json:"sha256,omitempty"`
	Offset int64  `json:"offset,omitempty"`
	Data   []byte `json:"data,omitempty"`
}

func IsWorkspaceCheckpointTransferOperation(op string) bool {
	switch op {
	case RunnerWorkspaceOperationCheckpointExport, RunnerWorkspaceOperationCheckpointRead, RunnerWorkspaceOperationCheckpointClose, RunnerWorkspaceOperationCheckpointUpload, RunnerWorkspaceOperationCheckpointAppend, RunnerWorkspaceOperationCheckpointCommit:
		return true
	}
	return false
}

type RunnerWorkspaceResponse struct {
	Payload json.RawMessage `json:"payload,omitempty"`
	Error   string          `json:"error,omitempty"`
	Code    string          `json:"code,omitempty"`
	Status  int             `json:"status,omitempty"`
}

const (
	WorkspaceErrorBusy    = "workspace_busy"
	WorkspaceErrorMissing = "workspace_missing"
	// WorkspaceErrorTerminalActive: an exclusive human terminal holds the
	// workspace; waiting does not help until the user closes it.
	WorkspaceErrorTerminalActive = "workspace_terminal_active"
)

// WorkspaceRestoreStatus describes restoration separately from SOP execution.
type WorkspaceRestoreStatus struct {
	Status    string     `json:"status"`
	StartedAt *time.Time `json:"startedAt,omitempty"`
	Error     string     `json:"error,omitempty"`
}

// WorkspaceTerminalRequest carries transient PTY data, never durable chat or run logs.
type WorkspaceTerminalRequest struct {
	ExpiresAt time.Time `json:"expiresAt,omitempty"`
	Operation string    `json:"operation"`
	ID        string    `json:"id,omitempty"`
	Data      string    `json:"data,omitempty"`
	Cols      int       `json:"cols,omitempty"`
	Rows      int       `json:"rows,omitempty"`
}

// BrowserRequest drives the run's agent browser from the task panel. Frames
// and input are transient and are never persisted.
type BrowserRequest struct {
	Operation string `json:"operation"`
	After     int64  `json:"after,omitempty"`
	WaitMs    int    `json:"waitMs,omitempty"`
	URL       string `json:"url,omitempty"`
	TargetID  string `json:"targetId,omitempty"`
	Width     int    `json:"width,omitempty"`
	Height    int    `json:"height,omitempty"`
	// FrameWidth caps panel frames at the device pixels the panel shows, so
	// a wide viewport is not shipped at full size to a narrow dock.
	FrameWidth int                 `json:"frameWidth,omitempty"`
	Events     []BrowserInputEvent `json:"events,omitempty"`
	// Agent-driven operations (snapshot/click/type/press) address elements by
	// the refs returned in the latest snapshot.
	Ref    string `json:"ref,omitempty"`
	Text   string `json:"text,omitempty"`
	Key    string `json:"key,omitempty"`
	Submit bool   `json:"submit,omitempty"`
	// WithSnapshot returns the page snapshot after a navigation settles.
	WithSnapshot bool `json:"withSnapshot,omitempty"`
	// Ensure starts the run browser when none is running yet.
	Ensure bool `json:"ensure,omitempty"`
	// HTTP carries one request to a dev server port inside the run sandbox
	// (operation "http"), so the user's own browser renders the page natively.
	HTTP *BrowserHTTPRequest `json:"http,omitempty"`
	// File is the absolute path of a workspace file as the run browser sees
	// it (operation "file"), served so the user's browser renders file://
	// pages natively. The response comes back in BrowserState.HTTP.
	File string `json:"file,omitempty"`
	// Point is where the panel inspects the page (operation "inspect"), as a
	// fraction of the viewport like input events; Detail asks for the full
	// element description rather than just its box and label.
	Point  *BrowserPoint `json:"point,omitempty"`
	Detail bool          `json:"detail,omitempty"`
}

// BrowserPoint is a position as a fraction of the viewport (0..1).
type BrowserPoint struct {
	X float64 `json:"x"`
	Y float64 `json:"y"`
}

// BrowserInspection is the element under a point of the Agent browser page.
// Rect is in CSS pixels of the top-level viewport.
type BrowserInspection struct {
	Label    string                `json:"label"`
	Rect     ElementRect           `json:"rect"`
	Viewport ElementRect           `json:"viewport"`
	Element  *AssistantPageElement `json:"element,omitempty"`
}

// BrowserHTTPRequest is one proxied request to http://localhost:Port in the
// run's network namespace. Path keeps the query string.
type BrowserHTTPRequest struct {
	Port   int                 `json:"port"`
	Method string              `json:"method"`
	Path   string              `json:"path"`
	Header map[string][]string `json:"header,omitempty"`
	Body   []byte              `json:"body,omitempty"`
}

// BrowserHTTPResponse is the dev server's answer to a BrowserHTTPRequest.
type BrowserHTTPResponse struct {
	Status int                 `json:"status"`
	Header map[string][]string `json:"header,omitempty"`
	Body   []byte              `json:"body,omitempty"`
}

// BrowserInputEvent coordinates are normalized to the frame (0..1).
type BrowserInputEvent struct {
	Type       string  `json:"type"`
	Action     string  `json:"action,omitempty"`
	X          float64 `json:"x,omitempty"`
	Y          float64 `json:"y,omitempty"`
	Button     string  `json:"button,omitempty"`
	Buttons    int     `json:"buttons,omitempty"`
	ClickCount int     `json:"clickCount,omitempty"`
	Modifiers  int     `json:"modifiers,omitempty"`
	DeltaX     float64 `json:"deltaX,omitempty"`
	DeltaY     float64 `json:"deltaY,omitempty"`
	Key        string  `json:"key,omitempty"`
	Code       string  `json:"code,omitempty"`
	KeyCode    int     `json:"keyCode,omitempty"`
	Text       string  `json:"text,omitempty"`
}

type BrowserTab struct {
	ID     string `json:"id"`
	Title  string `json:"title"`
	URL    string `json:"url"`
	Active bool   `json:"active,omitempty"`
}

type BrowserState struct {
	Available bool    `json:"available"`
	Reason    string  `json:"reason,omitempty"`
	Kind      string  `json:"kind,omitempty"`
	Seq       int64   `json:"seq"`
	Frame     string  `json:"frame,omitempty"`
	Width     float64 `json:"width,omitempty"`
	Height    float64 `json:"height,omitempty"`
	URL       string  `json:"url,omitempty"`
	Title     string  `json:"title,omitempty"`
	// ScrollX/Y and ContentWidth/Height (CSS px) bound how far the panel may
	// slide a frame ahead of the page when it predicts a scroll.
	ScrollX       float64          `json:"scrollX,omitempty"`
	ScrollY       float64          `json:"scrollY,omitempty"`
	ContentWidth  float64          `json:"contentWidth,omitempty"`
	ContentHeight float64          `json:"contentHeight,omitempty"`
	CanGoBack     bool             `json:"canGoBack,omitempty"`
	CanGoForward  bool             `json:"canGoForward,omitempty"`
	Tabs          []BrowserTab     `json:"tabs,omitempty"`
	Snapshot      *BrowserSnapshot `json:"snapshot,omitempty"`
	// HTTP answers operation "http"; Reason explains a missing answer.
	HTTP *BrowserHTTPResponse `json:"http,omitempty"`
	// Inspect answers operation "inspect"; nil when nothing is at the point.
	Inspect *BrowserInspection `json:"inspect,omitempty"`
}

// BrowserSnapshot is a text view of the active page for language models.
type BrowserSnapshot struct {
	Text      string           `json:"text"`
	Truncated bool             `json:"truncated,omitempty"`
	Elements  []BrowserElement `json:"elements"`
}

type BrowserElement struct {
	Ref      string `json:"ref"`
	Role     string `json:"role"`
	Name     string `json:"name,omitempty"`
	Value    string `json:"value,omitempty"`
	Checked  bool   `json:"checked,omitempty"`
	Disabled bool   `json:"disabled,omitempty"`
}

// WorkspaceArtifactFile is an immutable archived output, restored only if absent.
type WorkspaceArtifactFile struct {
	Path    string `json:"path"`
	Content string `json:"content"`
	SHA256  string `json:"sha256"`
}