relay-flow 0.1.0-alpha.0

package/internal/orcacli/orcacli.go

@@ -0,0 +1,264 @@
+// Package orcacli wraps the `orca` CLI for worktree/terminal management.
+// Every call is skippable via DryRun for safe local testing. All real
+// `orca ... --json` output is wrapped as {id, ok, result: {...}}.
+package orcacli
+
+import (
+	"encoding/json"
+	"fmt"
+	"log"
+	"os/exec"
+	"regexp"
+	"strings"
+)
+
+type Client struct {
+	DryRun bool
+}
+
+func New(dryRun bool) *Client {
+	return &Client{DryRun: dryRun}
+}
+
+type Repo struct {
+	ID          string `json:"id"`
+	DisplayName string `json:"displayName"`
+}
+
+type Worktree struct {
+	ID             string `json:"id"`
+	RepoID         string `json:"repoId"`
+	DisplayName    string `json:"displayName"`
+	Branch         string `json:"branch"`
+	Path           string `json:"path"`
+	IsMainWorktree bool   `json:"isMainWorktree"`
+}
+
+// Terminal is a tab's persistent identity: Title is the tab-level title we
+// set via --title (visualLayouts[].root.tabs[].title), which persists —
+// unlike the pane-level title, which the running program (opencode) resets.
+type Terminal struct {
+	Handle    string
+	Title     string
+	Connected bool
+}
+
+// ListRepos returns all Orca-registered repos, used to resolve a Jira
+// ticket's component name to a repoId (component name == repo displayName).
+func (c *Client) ListRepos() ([]Repo, error) {
+	if c.DryRun {
+		log.Printf("[dry-run] orca repo list --json (skipped, returning empty)")
+		return nil, nil
+	}
+	var res struct {
+		Result struct {
+			Repos []Repo `json:"repos"`
+		} `json:"result"`
+	}
+	if err := runOrcaJSON(&res, "repo", "list", "--json"); err != nil {
+		return nil, fmt.Errorf("orca repo list: %w", err)
+	}
+	return res.Result.Repos, nil
+}
+
+func (c *Client) WorktreeList() ([]Worktree, error) {
+	if c.DryRun {
+		log.Printf("[dry-run] orca worktree list --json (skipped, returning empty)")
+		return nil, nil
+	}
+	var res struct {
+		Result struct {
+			Worktrees []Worktree `json:"worktrees"`
+		} `json:"result"`
+	}
+	if err := runOrcaJSON(&res, "worktree", "list", "--json"); err != nil {
+		return nil, fmt.Errorf("orca worktree list: %w", err)
+	}
+	return res.Result.Worktrees, nil
+}
+
+// WorktreeCreate always explicitly sets --parent-worktree and --base-branch
+// (never relies on Orca's inferred defaults) so every ticket's worktree has
+// a deliberate, known ancestry: main by default, or an explicit parent
+// ticket's worktree/branch for subtasks.
+func (c *Client) WorktreeCreate(ticketKey, repoID, parentWorktreeID, baseBranch string) error {
+	if c.DryRun {
+		log.Printf("[dry-run] orca worktree create --name %s --repo id:%s --parent-worktree worktree:%s --base-branch %s --json (skipped)", ticketKey, repoID, parentWorktreeID, baseBranch)
+		return nil
+	}
+	return runOrca("worktree", "create", "--name", ticketKey, "--repo", "id:"+repoID,
+		"--parent-worktree", "worktree:"+parentWorktreeID, "--base-branch", baseBranch, "--json")
+}
+
+// FindWorktree returns the worktree in repoID with the given displayName.
+func (c *Client) FindWorktree(repoID, displayName string) (Worktree, bool, error) {
+	wts, err := c.WorktreeList()
+	if err != nil {
+		return Worktree{}, false, err
+	}
+	for _, w := range wts {
+		if w.RepoID == repoID && w.DisplayName == displayName {
+			return w, true, nil
+		}
+	}
+	return Worktree{}, false, nil
+}
+
+// FindExistingBranch looks for a branch containing ticketKey
+// (prefix-agnostic — e.g. "Raj-Popat/KCC-1374" or "someone-else/KCC-1374"
+// both match) in the repo checked out at repoPath, checking BOTH local and
+// remote-tracking branches: Orca's worktree-create name-collision logic
+// consults remote branches too, so a leftover origin/Raj-Popat/KCC-1377
+// (pushed by an agent, local copy long deleted) would otherwise make Orca
+// silently suffix the new worktree (-2, -3, ...) and desync every
+// ticket-key-based lookup we do afterward.
+//
+// Return value is the ref to pass as --base-branch:
+//   - local-only branch  -> its name as-is ("Raj-Popat/KCC-1377")
+//   - remote-only branch -> the remote-qualified ref ("origin/Raj-Popat/KCC-1377");
+//     Orca recognizes this as "create the worktree on this existing branch"
+//     and does NOT suffix the worktree name (verified empirically).
+func FindExistingBranch(repoPath, ticketKey string) (string, bool, error) {
+	out, err := exec.Command("git", "-C", repoPath, "branch", "-a", "--list", "--format=%(refname:short)").CombinedOutput()
+	if err != nil {
+		return "", false, fmt.Errorf("git branch --list: %w: %s", err, out)
+	}
+	re := regexp.MustCompile(regexp.QuoteMeta(ticketKey))
+	for _, line := range strings.Split(string(out), "\n") {
+		branch := strings.TrimSpace(line)
+		if branch != "" && re.MatchString(branch) {
+			return branch, true, nil
+		}
+	}
+	return "", false, nil
+}
+
+// MainWorktree returns repoID's main worktree (the one checked out on the
+// repo's primary branch, e.g. main).
+func (c *Client) MainWorktree(repoID string) (Worktree, bool, error) {
+	wts, err := c.WorktreeList()
+	if err != nil {
+		return Worktree{}, false, err
+	}
+	for _, w := range wts {
+		if w.RepoID == repoID && w.IsMainWorktree {
+			return w, true, nil
+		}
+	}
+	return Worktree{}, false, nil
+}
+
+// TerminalList returns tabs (with their persistent tab-level title) for a
+// given worktree, e.g. "name:KCC-1373". --include-visual-layouts is
+// mandatory: orca omits visualLayouts from JSON without it, which would
+// make every lookup return zero tabs and the daemon would spawn duplicate
+// terminals on every poll.
+func (c *Client) TerminalList(worktree string) ([]Terminal, error) {
+	if c.DryRun {
+		log.Printf("[dry-run] orca terminal list --worktree %s --json (skipped, returning empty)", worktree)
+		return nil, nil
+	}
+	var res struct {
+		Result struct {
+			VisualLayouts []struct {
+				Root struct {
+					Tabs []struct {
+						Title string `json:"title"`
+						Panes struct {
+							Handle    string `json:"handle"`
+							Connected bool   `json:"connected"`
+						} `json:"panes"`
+					} `json:"tabs"`
+				} `json:"root"`
+			} `json:"visualLayouts"`
+		} `json:"result"`
+	}
+	if err := runOrcaJSON(&res, "terminal", "list", "--worktree", worktree, "--include-visual-layouts", "--json"); err != nil {
+		return nil, fmt.Errorf("orca terminal list: %w", err)
+	}
+	var terms []Terminal
+	for _, vl := range res.Result.VisualLayouts {
+		for _, tab := range vl.Root.Tabs {
+			terms = append(terms, Terminal{Handle: tab.Panes.Handle, Title: tab.Title, Connected: tab.Panes.Connected})
+		}
+	}
+	return terms, nil
+}
+
+// TerminalCreate launches the given shell command in a fresh terminal on
+// the ticket's worktree. (orca terminal create has no --agent/--prompt
+// flags — those exist only on `worktree create` — so the opencode
+// invocation, with its RELAY_* env markers, is a --command line.)
+func (c *Client) TerminalCreate(ticketKey, title, command string) (string, error) {
+	if c.DryRun {
+		log.Printf("[dry-run] orca terminal create --worktree name:%s --title %q --command %q --json (skipped)", ticketKey, title, command)
+		return "dry-run-handle", nil
+	}
+	var res struct {
+		Result struct {
+			Terminal struct {
+				Handle string `json:"handle"`
+			} `json:"terminal"`
+		} `json:"result"`
+	}
+	if err := runOrcaJSON(&res, "terminal", "create",
+		"--worktree", "name:"+ticketKey,
+		"--title", title,
+		"--command", command,
+		"--json"); err != nil {
+		return "", fmt.Errorf("orca terminal create: %w", err)
+	}
+	return res.Result.Terminal.Handle, nil
+}
+
+func (c *Client) TerminalWait(handle, forState string, timeoutMs int) error {
+	if c.DryRun {
+		log.Printf("[dry-run] orca terminal wait --terminal %s --for %s --timeout-ms %d --json (skipped)", handle, forState, timeoutMs)
+		return nil
+	}
+	return runOrca("terminal", "wait",
+		"--terminal", handle,
+		"--for", forState,
+		"--timeout-ms", fmt.Sprintf("%d", timeoutMs),
+		"--json")
+}
+
+func (c *Client) TerminalClose(handle string) error {
+	if c.DryRun {
+		log.Printf("[dry-run] orca terminal close --terminal %s (skipped)", handle)
+		return nil
+	}
+	return runOrca("terminal", "close", "--terminal", handle)
+}
+
+// TerminalSend types text into an existing terminal and presses Enter.
+// text must be pre-flattened to a single line by the caller — send works
+// via keystroke simulation, so an embedded newline would submit early.
+func (c *Client) TerminalSend(handle, text string) error {
+	if c.DryRun {
+		log.Printf("[dry-run] orca terminal send --terminal %s --text %q --enter --json (skipped)", handle, text)
+		return nil
+	}
+	return runOrca("terminal", "send", "--terminal", handle, "--text", text, "--enter", "--json")
+}
+
+func runOrca(args ...string) error {
+	out, err := exec.Command("orca", args...).CombinedOutput()
+	if err != nil {
+		return fmt.Errorf("orca %v: %w: %s", args, err, string(out))
+	}
+	return nil
+}
+
+func runOrcaJSON(dest any, args ...string) error {
+	out, err := exec.Command("orca", args...).Output()
+	if err != nil {
+		// orca prints its JSON error envelope to stdout even on failure —
+		// surface it so callers can match on codes like selector_not_found.
+		return fmt.Errorf("%w: %s", err, strings.TrimSpace(string(out)))
+	}
+	if err := json.Unmarshal(out, dest); err != nil {
+		return fmt.Errorf("parse json: %w", err)
+	}
+	return nil
+}

package/internal/runner/orca/README.md

@@ -0,0 +1,64 @@
+# runner/orca — Orca adapter
+
+Implements `runner.Runner` over the Orca CLI: each ticket gets an Orca
+worktree; each node visit gets a fresh terminal titled
+`<key>:<agent>:<node>` running opencode.
+
+## Config (runner.config)
+
+Empty — the adapter takes no YAML fields. Repo binding arrives at runtime:
+the server resolves the submitter's repo and calls `WithRepo(repoID,
+displayName, dryRun)` after construction.
+
+## Behavior
+
+- **Spawn** — verifies the opencode agent exists (`opencode agent list`),
+  ensures the ticket's worktree (creates off the repo's main worktree branch;
+  reuses an existing ticket branch if one exists; verifies the exact name
+  landed because Orca silently auto-suffixes on collisions), then creates the
+  terminal running `opencode --agent <agent> --prompt <p>` with `RELAY_FLOW_*` env
+  markers (`RELAY_FLOW_WORKFLOW/TICKET/NODE/AGENT`) so the plugin can report back.
+- **Find** — exact-title match on the ticket's terminal list. A missing
+  worktree (`selector_not_found`) means "no session", not an error — that's
+  what lets bounce respawn after a crash.
+- **Nudge** — waits for `tui-idle` (typed text mid-turn corrupts the input
+  box), then sends the prompt flattened to one line (keystroke simulation
+  submits on newline).
+- **Close** — closes every terminal titled `<key>:*`; scaffolding tabs
+  ("Terminal 1", "Setup") survive.
+
+## Writing a new runner (tmux, ...)
+
+1. Create `internal/runner/<name>/` with:
+   ```go
+   func init() {
+       runner.Register("<name>", runner.Factory{
+           UnmarshalConfig: unmarshalConfig, // strict-decode runner.config (empty is fine)
+           New: func(cfg any) (runner.Runner, error) { ... },
+       })
+   }
+   ```
+2. Implement the interface:
+   ```go
+   type Runner interface {
+       Spawn(t tasks.Ticket, node, agent, prompt string, env map[string]string) error
+       Find(t tasks.Ticket, node string) (runner.Session, bool, error)
+       Nudge(s runner.Session, prompt string) error
+       Close(t tasks.Ticket) error
+   }
+   ```
+   Contract highlights:
+   - **Titles are identity**: sessions must be findable later by
+     `<key>:<agent>:<node>` — bounce depends on it.
+   - **env must reach the agent process** — the report plugin keys off
+     `RELAY_FLOW_WORKFLOW/TICKET/NODE/AGENT`.
+   - **Find must distinguish "gone" from "error"** — a missing session is a
+     normal bounce case (respawn), not a failure.
+   - The runner must still launch **opencode** inside whatever session it
+     creates — the report plugin is opencode-specific. (tmux example:
+     `tmux new-session -s key-agent-node` + `send-keys "RELAY_FLOW_*=... opencode --agent ..." Enter`.)
+3. If your runner needs the repo binding, implement
+   `WithRepo(repoID, repoName string, dryRun bool)` — the server calls it via
+   interface assertion when present.
+4. Import for side effects in `internal/server/server.go`.
+5. Tests with a fake CLI seam (see `orca_test.go` / the `orcaCLI` interface).

package/internal/runner/orca/orca.go

@@ -0,0 +1,243 @@
+// Package orca is the built-in Runner adapter: it executes agent sessions
+// as Orca terminals on per-ticket worktrees. It knows nothing about
+// trackers — tickets arrive as tasks.Ticket values.
+package orca
+
+import (
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/opencode"
+	"github.com/rajpopat27/relay-flow/internal/orcacli"
+	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/tasks"
+)
+
+func init() {
+	runner.Register("orca", runner.Factory{
+		UnmarshalConfig: unmarshalConfig,
+		New: func(cfg any) (runner.Runner, error) {
+			c, ok := cfg.(Config)
+			if !ok {
+				return nil, fmt.Errorf("internal: orca factory received %T", cfg)
+			}
+			return NewRunner(c, nil), nil
+		},
+	})
+}
+
+// Config is the strictly-unmarshalled runner.config for type orca.
+// Empty today — worktree ancestry details (repo, parent) are passed by
+// the server at construction, not committed in YAML.
+type Config struct{}
+
+func unmarshalConfig(m map[string]any) (any, error) {
+	if len(m) > 0 {
+		for k := range m {
+			return nil, fmt.Errorf("unknown field %q (orca runner takes no config)", k)
+		}
+	}
+	return Config{}, nil
+}
+
+// orcaCLI is the seam to the orca CLI. *orcacli.Client satisfies it;
+// tests fake it.
+type orcaCLI interface {
+	WorktreeList() ([]orcacli.Worktree, error)
+	WorktreeCreate(ticketKey, repoID, parentWorktreeID, baseBranch string) error
+	FindWorktree(repoID, displayName string) (orcacli.Worktree, bool, error)
+	MainWorktree(repoID string) (orcacli.Worktree, bool, error)
+	TerminalList(worktree string) ([]orcacli.Terminal, error)
+	TerminalCreate(ticketKey, title, command string) (string, error)
+	TerminalWait(handle, forState string, timeoutMs int) error
+	TerminalClose(handle string) error
+	TerminalSend(handle, text string) error
+}
+
+type orcaRunner struct {
+	repoID     string
+	repoName   string // Jira component name; unused by the runner itself
+	dryRun     bool
+	orca       orcaCLI
+	exists     func(string) (bool, error)
+	findBranch func(repoPath, key string) (string, bool, error)
+	sleep      func(time.Duration) // test seam for ensureWorktree retries
+}
+
+// NewRunner builds the orca runner. oc nil → real orcacli client (dryRun
+// plumbed through). repoID is set by WithRepo at submit time.
+func NewRunner(_ Config, oc orcaCLI) runner.Runner {
+	r := &orcaRunner{
+		exists:     opencode.Exists,
+		findBranch: orcacli.FindExistingBranch,
+		sleep:      time.Sleep,
+	}
+	if oc != nil {
+		r.orca = oc
+	}
+	return r
+}
+
+// WithRepo binds the repo this runner serves (resolved server-side from
+// the submitting client's cwd) and the dry-run flag.
+func (r *orcaRunner) WithRepo(repoID, repoName string, dryRun bool) {
+	r.repoID, r.repoName, r.dryRun = repoID, repoName, dryRun
+	if r.orca == nil {
+		r.orca = orcacli.New(dryRun)
+	}
+}
+
+// title is the session identity: <key>:<agent>:<node>. Bounce and Close
+// both match on it.
+func title(t tasks.Ticket, node, agent string) string {
+	return fmt.Sprintf("%s:%s:%s", t.Key, agent, node)
+}
+
+// Spawn ensures the ticket's worktree exists, then creates a fresh
+// terminal titled key:agent:node running opencode with the RELAY_FLOW_* env
+// markers and the initial prompt. A fresh terminal per node visit:
+// reusing an old session would leak the previous node's context.
+func (r *orcaRunner) Spawn(t tasks.Ticket, node, agent, prompt string, env map[string]string) error {
+	if ok, err := r.exists(agent); err != nil {
+		return fmt.Errorf("verify opencode agent %q: %w", agent, err)
+	} else if !ok {
+		return fmt.Errorf("opencode agent %q does not exist", agent)
+	}
+	if err := r.ensureWorktree(t); err != nil {
+		return fmt.Errorf("ensure worktree: %w", err)
+	}
+	command := buildCommand(env, agent, prompt)
+	handle, err := r.orca.TerminalCreate(t.Key, title(t, node, agent), command)
+	if err != nil {
+		return fmt.Errorf("terminal create: %w", err)
+	}
+	// Best-effort: the wait only bounds how long Spawn blocks; the plugin
+	// report is the real synchronization.
+	_ = r.orca.TerminalWait(handle, "tui-idle", 10*60*1000)
+	return nil
+}
+
+// buildCommand renders the opencode invocation typed into the new
+// terminal, with RELAY_FLOW_* env markers so the plugin can report back. A
+// developer's own opencode session never has these set, so it never
+// reports.
+func buildCommand(env map[string]string, agent, prompt string) string {
+	parts := make([]string, 0, len(env))
+	// Deterministic order for logs/tests.
+	for _, k := range []string{"RELAY_FLOW_WORKFLOW", "RELAY_FLOW_TICKET", "RELAY_FLOW_NODE", "RELAY_FLOW_AGENT"} {
+		if v, ok := env[k]; ok {
+			parts = append(parts, k+"="+shellQuote(v))
+		}
+	}
+	return fmt.Sprintf("%s opencode --agent %s --prompt %s",
+		strings.Join(parts, " "), shellQuote(agent), shellQuote(prompt))
+}
+
+func shellQuote(s string) string {
+	return "'" + strings.ReplaceAll(s, "'", `'\''`) + "'"
+}
+
+// Find locates the live session for ticket+node by exact title. A
+// missing worktree (selector_not_found — e.g. claim label survived a
+// crash but the worktree didn't) means "no session", not an error.
+func (r *orcaRunner) Find(t tasks.Ticket, node string) (runner.Session, bool, error) {
+	terms, err := r.orca.TerminalList("name:" + t.Key)
+	if err != nil {
+		if strings.Contains(err.Error(), "selector_not_found") {
+			return runner.Session{}, false, nil
+		}
+		return runner.Session{}, false, fmt.Errorf("terminal list: %w", err)
+	}
+	want := t.Key + ":"
+	for _, term := range terms {
+		if strings.HasPrefix(term.Title, want) && strings.HasSuffix(term.Title, ":"+node) {
+			return runner.Session{ID: term.Handle, Title: term.Title}, true, nil
+		}
+	}
+	return runner.Session{}, false, nil
+}
+
+// Nudge types a prompt into an existing session. The caller must have
+// waited for idle first — typed text mid-turn corrupts the input box.
+func (r *orcaRunner) Nudge(s runner.Session, prompt string) error {
+	flat := strings.Join(strings.Fields(prompt), " ")
+	if err := r.orca.TerminalWait(s.ID, "tui-idle", 3000); err != nil {
+		return fmt.Errorf("session %q busy, nudge not delivered", s.Title)
+	}
+	return r.orca.TerminalSend(s.ID, flat)
+}
+
+// Close tears down every terminal titled <key>:* on the ticket's
+// worktree. Scaffolding tabs ("Terminal 1", "Setup") are not ours and
+// survive.
+func (r *orcaRunner) Close(t tasks.Ticket) error {
+	terms, err := r.orca.TerminalList("name:" + t.Key)
+	if err != nil {
+		return fmt.Errorf("terminal list: %w", err)
+	}
+	prefix := t.Key + ":"
+	for _, term := range terms {
+		if strings.HasPrefix(term.Title, prefix) {
+			if err := r.orca.TerminalClose(term.Handle); err != nil {
+				return fmt.Errorf("close %q: %w", term.Title, err)
+			}
+		}
+	}
+	return nil
+}
+
+// ensureWorktree creates the ticket's worktree if missing, verifying the
+// exact name landed (Orca silently auto-suffixes on collisions).
+func (r *orcaRunner) ensureWorktree(t tasks.Ticket) error {
+	for attempt := 0; attempt < 3; attempt++ {
+		if _, ok, err := r.orca.FindWorktree(r.repoID, t.Key); err != nil {
+			return err
+		} else if ok {
+			return nil
+		}
+		if attempt < 2 {
+			r.sleep(2 * time.Second)
+		}
+	}
+	parentID, baseBranch, err := r.resolveWorktreeParent(t)
+	if err != nil {
+		return err
+	}
+	if err := r.orca.WorktreeCreate(t.Key, r.repoID, parentID, baseBranch); err != nil {
+		return err
+	}
+	for attempt := 0; attempt < 3; attempt++ {
+		if _, ok, err := r.orca.FindWorktree(r.repoID, t.Key); err != nil {
+			return err
+		} else if ok {
+			return nil
+		}
+		if attempt < 2 {
+			r.sleep(2 * time.Second)
+		}
+	}
+	return fmt.Errorf("worktree %q not found after create (Orca likely auto-suffixed it on a name/branch collision) — clean up the suffixed worktree/branch manually", t.Key)
+}
+
+// resolveWorktreeParent picks the ancestry for a new ticket worktree:
+// main worktree's branch, reused ticket branch if one exists. (The
+// baseBranch-label and subtask-parent rules from v3 need ticket labels/
+// parent info that tasks.Ticket doesn't carry — deferred; YAGNI until a
+// tracker adapter exposes them.)
+func (r *orcaRunner) resolveWorktreeParent(t tasks.Ticket) (parentWorktreeID, baseBranch string, err error) {
+	w, ok, err := r.orca.MainWorktree(r.repoID)
+	if err != nil {
+		return "", "", err
+	}
+	if !ok {
+		return "", "", fmt.Errorf("could not find main worktree for repo %s", r.repoID)
+	}
+	// A branch for this ticket may already exist (left over from a
+	// removed worktree). Reuse it — Orca silently renames the worktree on
+	// branch collision, desyncing every ticket-key lookup.
+	if existing, ok, err := r.findBranch(w.Path, t.Key); err == nil && ok {
+		return w.ID, existing, nil
+	}
+	return w.ID, w.Branch, nil
+}