Help us shape the future of Go! Take the 2026 Go Developer Survey

orca

package
v0.4.3 Latest Latest
Warning

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

 Go to latest Published: Nov 2, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package orca is a visor backend for the terminals of Orca on this machine. A session is an agent in an Orca terminal. Orca owns the terminal, so the session lives through a visor restart. The backend reads the agent state from the Orca agent cards. It has no typed events: it answers a permission prompt through the screen.

Index

Constants

View Source 
const (
	// LabelPane is the Orca pane (tabId:leafId). A hook call with it finds
	// the session.
	LabelPane = "orca.pane"
	// LabelTerminal is the Orca terminal handle.
	LabelTerminal = "orca.terminal"
	// LabelWorktree is the Orca worktree id. In a start spec, the terminal
	// opens in this worktree.
	LabelWorktree = "orca.worktree"
	// LabelShell is a terminal handle in a start spec. The agent command goes
	// into this shell, and no new terminal opens.
	LabelShell = "orca.shell"
)

The labels of an Orca session. The backend puts them on each session, and a start spec can set LabelWorktree and LabelShell.

View Source 
const (
	AgentWorking = "working"
	AgentWaiting = "waiting"
	AgentBlocked = "blocked"
	AgentDone    = "done"
)

The agent states of Orca.

View Source 
const EnvPane = "ORCA_PANE_KEY"

Env names of the hook process in an Orca terminal.

View Source 
const Kind agentvisor.Kind = "orca"

Kind is the session kind of this backend.

View Source 
const MacPath = "/Applications/Orca.app/Contents/Resources/bin/orca"

MacPath is the Orca CLI in the Orca app on macOS.

Variables

This section is empty.

Functions

func FindCLI 

func FindCLI() (path string, ok bool)

FindCLI gives the Orca CLI of the app on macOS, else orca on PATH. ok is false when there is none.

func HookLabels 

func HookLabels(getenv func(string) string) map[string]string

HookLabels gives the labels of a hook call from the env of the hook process. They are nil outside an Orca terminal.

func IsCode 

func IsCode(err error, code string) bool

IsCode tells whether err is an Orca error with the code.

Types

type Agent 

type Agent struct {
	PaneKey              string `json:"paneKey"`
	State                string `json:"state"`       // working, waiting, blocked, done
	WorkingMode          string `json:"workingMode"` // "monitoring" when only a background shell runs
	AgentType            string `json:"agentType"`
	Prompt               string `json:"prompt"`
	LastAssistantMessage string `json:"lastAssistantMessage"`
	ToolName             string `json:"toolName"`
	ToolInput            string `json:"toolInput"`
	Interrupted          bool   `json:"interrupted"`
	StateStartedAt       int64  `json:"stateStartedAt"`
	UpdatedAt            int64  `json:"updatedAt"`
	MainAgent            *struct {
		State          string `json:"state"`
		StateStartedAt int64  `json:"stateStartedAt"`
	} `json:"mainAgent"`
}

Agent is one agent pane of a workspace. The times are Unix milliseconds.

func (Agent) Effective 

func (a Agent) Effective() Agent

Effective gives the agent with a stale monitoring state replaced by the state of the main agent. A real background shell starts in the turn, so its monitoring state starts before the main agent finishes. Orca can go to monitoring after the turn with no shell, for example on a recap.

type Backend 

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

Backend hosts agent sessions in Orca terminals.

func New 

func New(o Options) (*Backend, error)

New starts the poll of the Orca state.

func (*Backend) Adopt 

func (b *Backend) Adopt(_ context.Context, s agentvisor.Session, pane string) (agentvisor.Handle, error)

Adopt binds the found pane to the visor session s.

func (*Backend) Binding 

func (b *Backend) Binding(session string) (pane, terminal, worktree string, ok bool)

Binding gives the Orca terminal of a session.

func (*Backend) CLI 

func (b *Backend) CLI() *CLI

CLI gives the Orca CLI of the backend.

func (*Backend) Caps 

func (b *Backend) Caps(string) agentvisor.Caps

Caps has no typed events and no structured permissions: the backend answers a prompt through the screen.

func (*Backend) Close 

func (b *Backend) Close(context.Context) error

Close stops the poll and detaches each handle. The terminals keep running.

func (*Backend) Folders 

func (b *Backend) Folders(ctx context.Context) ([]string, error)

Folders gives the repo paths of Orca.

func (*Backend) Found 

func (b *Backend) Found() <-chan agentvisor.Found

Found gives the agents that the visor did not start, when Options.Discover is set.

func (*Backend) Kind 

func (b *Backend) Kind() agentvisor.Kind

func (*Backend) Recover 

func (b *Backend) Recover(context.Context) ([]agentvisor.Handle, error)

Recover gives a handle for each stored binding. The poll ends the handles whose terminal is gone.

func (*Backend) Snapshot added in v0.3.1 

func (b *Backend) Snapshot() Snapshot

Snapshot gives the Orca state of the last read. A consumer can read it in place of a second poll of Orca.

func (*Backend) Start 

func (b *Backend) Start(ctx context.Context, l agentvisor.Launch) (agentvisor.Handle, error)

Start opens a terminal in Orca and runs the agent command in it. Then it waits until the agent is idle and sends the first prompt.

type CLI 

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

CLI calls the Orca CLI of this machine. Each call has an argument array and --json. No call has --environment: the CLI talks only to the local Orca.

func NewCLI 

func NewCLI(exe string, run Runner) *CLI

func (*CLI) Close 

func (c *CLI) Close(ctx context.Context, handle string) error

Close closes one terminal.

func (*CLI) CreateTerminal 

func (c *CLI) CreateTerminal(ctx context.Context, worktree, title, command string) (Terminal, error)

CreateTerminal opens a terminal in the worktree selector and runs command.

func (*CLI) EnsureWorkspace 

func (c *CLI) EnsureWorkspace(ctx context.Context, w WorkspaceSpec, shellWait time.Duration) (Workspace, error)

EnsureWorkspace finds the workspace with the name in the repo, or makes it. A new workspace runs the Orca setup of the repo.

func (*CLI) Line 

func (c *CLI) Line(ctx context.Context, handle, text string) error

Line types text and Enter. It does not wait for a prompt submit.

func (*CLI) Reachable 

func (c *CLI) Reachable(ctx context.Context) bool

Reachable tells whether `orca status` reaches the Orca runtime.

func (*CLI) Repos 

func (c *CLI) Repos(ctx context.Context) ([]Repo, error)

Repos lists the repos of Orca.

func (*CLI) Screen 

func (c *CLI) Screen(ctx context.Context, handle string) ([]string, error)

Screen gives the rows that the terminal renders now.

func (*CLI) Show 

func (c *CLI) Show(ctx context.Context, handle string) (Terminal, error)

Show gives the metadata of one terminal.

func (*CLI) Submit 

func (c *CLI) Submit(ctx context.Context, handle, text string) (bool, error)

Submit sends text as a prompt to the agent in the terminal. It is true when the agent started a turn on it.

func (*CLI) Tail 

func (c *CLI) Tail(ctx context.Context, handle string, lines int) ([]string, error)

Tail gives the last lines of the terminal output, with no escape codes.

func (*CLI) Terminals 

func (c *CLI) Terminals(ctx context.Context) ([]Terminal, error)

Terminals lists the live terminals.

func (*CLI) Type 

func (c *CLI) Type(ctx context.Context, handle, text string) error

Type writes text to the terminal verbatim. Control bytes pass through.

func (*CLI) WaitIdle 

func (c *CLI) WaitIdle(ctx context.Context, handle string) (bool, error)

WaitIdle waits until the agent TUI in the terminal is idle. It is false when the wait ended first.

func (*CLI) Worktrees 

func (c *CLI) Worktrees(ctx context.Context) ([]Worktree, error)

Worktrees lists the workspaces with their agents.

type Error 

type Error struct{ Code, Message string }

Error is an error reply of the Orca CLI.

func (*Error) Error 

func (e *Error) Error() string

type ExecRunner 

type ExecRunner struct{}

ExecRunner runs the process with os/exec.

func (ExecRunner) Run 

func (ExecRunner) Run(ctx context.Context, exe string, args []string) ([]byte, []byte, error)

type Options 

type Options struct {
	// CLI is the Orca CLI. Nil uses FindCLI.
	CLI *CLI
	// Dir keeps the session bindings and the launch scripts.
	Dir string
	// Poll is the time between two reads of the Orca state. Zero is 2 s.
	Poll time.Duration
	// Command gives the command of an agent session. Nil runs the harness
	// program with the model args and the extra args. A resume needs it.
	Command agentvisor.TerminalCommand
	// Discover reports the agents that the visor did not start, for example
	// the agents that the user started in Orca.
	Discover bool
	// ShellWait is the pause between two looks for the first shell of a new
	// workspace. Zero is 300 ms.
	ShellWait time.Duration
	// OnPoll runs after each read of the Orca state. With OnPoll, the backend
	// reads Orca also when it has no session.
	OnPoll func()
	Logger *slog.Logger
}

Options configures the backend.

type Repo 

type Repo struct {
	ID          string `json:"id"`
	Path        string `json:"path"`
	DisplayName string `json:"displayName"`
	Kind        string `json:"kind"` // git or folder
}

Repo is one repo of `orca repo list`.

type Runner 

type Runner interface {
	Run(ctx context.Context, exe string, args []string) (stdout, stderr []byte, err error)
}

Runner runs one child process.

type Snapshot added in v0.3.1 

type Snapshot struct {
	Worktrees []Worktree
	Terminals []Terminal
	At        time.Time // zero before the first read
}

Snapshot is the Orca state of the last read.

type Terminal 

type Terminal struct {
	Handle          string `json:"handle"`
	WorktreeID      string `json:"worktreeId"`
	WorktreePath    string `json:"worktreePath"`
	TabID           string `json:"tabId"`
	LeafID          string `json:"leafId"`
	Key             string `json:"paneKey"`
	RecordedPaneKey string `json:"recordedPaneKey"`
	Title           string `json:"title"`
	AgentIdentity   string `json:"agentIdentity"`
	Orphaned        bool   `json:"orphaned"`
	Connected       bool   `json:"connected"`
}

Terminal is one terminal of `orca terminal list`, `create`, or `show`.

func (Terminal) PaneKey 

func (t Terminal) PaneKey() string

PaneKey is the pane of the terminal (tabId:leafId). An orphaned terminal keeps its old pane in recordedPaneKey.

type Workspace 

type Workspace struct {
	ID    string
	Path  string
	Shell string
	New   bool
}

Workspace is a workspace that EnsureWorkspace found or made. Shell is the first shell of a new workspace, or empty.

type WorkspaceSpec 

type WorkspaceSpec struct {
	// Repo is the path of the repo in Orca.
	Repo string
	Name string
	// BaseBranch and Comment apply to a new workspace.
	BaseBranch string
	Comment    string
}

WorkspaceSpec names a workspace to find or make in a repo.

type Worktree 

type Worktree struct {
	ID          string  `json:"worktreeId"`
	RepoID      string  `json:"repoId"`
	Repo        string  `json:"repo"`
	Path        string  `json:"path"`
	Branch      string  `json:"branch"`
	DisplayName string  `json:"displayName"`
	Comment     string  `json:"comment"`
	IsArchived  bool    `json:"isArchived"`
	IsMain      bool    `json:"isMainWorktree"`
	Agents      []Agent `json:"agents"`
}

Worktree is one workspace of `orca worktree ps`.

func (Worktree) BranchName 

func (w Worktree) BranchName() string

BranchName is Branch without refs/heads/.

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.