relay-flow 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raj Popat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# relay-flow
+
+Graph-based agent workflow engine. Tickets are tokens moving across **nodes**; each node has an **agent** (an OpenCode agent); the node's edges (`onSuccess`/`onFailure`) decide where the token goes next. The tracker (Jira built-in) is the scoreboard; the runner (Orca built-in) is the playing field. Both are pluggable.
+
+---
+
+## Setup
+
+### Prerequisites
+
+| Tool | Why |
+|---|---|
+| [opencode](https://opencode.ai) | Agents run in opencode sessions |
+| [Orca](https://github.com/Necmttn/orca) CLI + app | Worktrees + terminals (the built-in runner) |
+| [acli](https://developer.atlassian.com/cloud/acli) | Jira access (the built-in tracker) |
+| Go 1.21+ | Build the CLI |
+
+### Install
+
+```sh
+# simplest — prebuilt binary into ~/.local/bin:
+curl -fsSL https://raw.githubusercontent.com/rajpopat27/relay-flow/main/install.sh | sh
+
+# or once npm unblocks (24h cooldown after unpublish):
+npm install -g relay-flow
+
+# or with Go:
+go install github.com/rajpopat27/relay-flow/cmd/relay-flow@v0.1.2
+
+# or with Homebrew (after the v0.1.2 release publishes the formula):
+brew install rajpopat27/tap/relay-flow
+```
+
+Install the opencode plugin (report loopback): copy `plugin/report-status.ts` into your repo's `.opencode/plugin/` directory (auto-loaded by opencode), committed so every ticket worktree inherits it.
+
+### Required configuration
+
+1. **Machine identity** (per machine, never committed):
+   ```sh
+   relay-flow init --assignee "Jane Doe"     # Jira display name or accountId
+   ```
+   Writes `~/.relay-flow/config.yaml` (0600), probe-validated against Jira.
+
+2. **Orca repo** — the repo must be registered in Orca (`orca repo add --path .`) with a base ref set (`orca repo set-base-ref --repo id:<id> --ref master`).
+
+3. **Jira board transitions** must allow the moves your edges imply (e.g. To Do → In Progress → Testing → In Review → Done).
+
+4. **Workflow YAML** at `.workflow/workflow.yaml` (committed, team-shared):
+
+```yaml
+name: xyzTaskFlow               # camelCase identity: registry key + claim label wf:<name>
+pollIntervalSeconds: 15         # optional, default 15
+
+tasks:                          # ticket-system adapter
+  type: jira
+  config:                       # opaque to core; strictly validated by the adapter
+    query: project = ABCD       # JQL fragment (no issuetype/assignee/ORDER BY)
+    issueTypes: [Task]
+    assigneeIsAgent: true       # or omit → assignee comes from `relay-flow init`
+
+runner:                         # execution backend
+  type: orca
+
+closeOn: [done]                 # terminal nodes whose tickets close their terminals
+
+nodes:
+  coding:
+    agent: build                # OpenCode agent for this node
+    when: "In Progress"         # tracker state routing tickets here (unique per file)
+    onSuccess: reviewing        # outcome edges — required for agent nodes
+    onFailure: coding           # self-loop allowed → comment only, no transition
+    nudgePrompt: "..."          # optional; {{ticket}} {{node}} templates; sane default
+  reviewing:
+    agent: build                # the same agent may serve many nodes
+    when: "In Review"
+    onSuccess: done
+    onFailure: coding
+  done:
+    when: "Done"                # no agent → terminal / human-gate node
+```
+
+Validation is strict and happens at submit: unknown fields, duplicate `when` values, dangling edges, agent nodes missing edges, and every referenced tracker state is probe-validated against the tracker.
+
+### Run
+
+```sh
+relay-flow serve                            # central process (artifacts in ~/.relay-flow/)
+relay-flow submit -f .workflow/workflow.yaml
+relay-flow stop serve
+```
+
+`relay-flow report` is invoked by the plugin, not by hand.
+
+---
+
+## Architecture
+
+### The board-game model
+
+- **Nodes** are squares. Each maps to exactly one tracker state via `when`. One node = one state; the same agent may serve many nodes.
+- **Agents** are robots sitting on squares. A ticket landing on an agent's square triggers work in a dedicated terminal/worktree.
+- **Edges** (`onSuccess`/`onFailure`) are the only legal moves. Self-loops comment without transitioning (trackers have no self-transitions).
+- **Terminal nodes** (in `closeOn`) tear down the ticket's terminals. **Agentless nodes** (no `agent:`) are human gates: the daemon claims the ticket (so other workflows skip it) but never spawns, nudges, or closes anything.
+- The **tracker is the single source of truth**. The server holds no database; restart = resubmit, and claim labels (`wf:<name>`) survive to drive recovery.
+
+### End-to-end sequence
+
+```mermaid
+sequenceDiagram
+    participant J as Tracker (Jira)
+    participant S as relay-flow serve
+    participant R as Runner (Orca)
+    participant O as OpenCode + plugin
+
+    loop every pollIntervalSeconds
+        S->>J: List() — one query (query + issuetype + component + assignee)
+        J-->>S: tickets (Node via when-map, ClaimedBy via wf:* labels)
+    end
+    S->>J: Claim(ticket) — add label wf:xyzTaskFlow
+    S->>R: Spawn(ticket, node, agent, env RELAY_*)
+    R->>R: ensure worktree → terminal key:agent:node → opencode --prompt
+    R->>O: agent session starts
+    O->>O: works… ends reply with STATUS/SUMMARY
+    O->>S: plugin: relay-flow report --workflow --ticket --node --outcome --summary
+    S->>J: Report → transition to target node's state + comment
+    S-->>O: {action: transitioned | commented | error}
+    Note over O: action=error → plugin retries 3× → nudges the session
+```
+
+### The poll-cycle 3-way switch
+
+```mermaid
+flowchart TD
+    L[tasks.List] --> T{per ticket}
+    T -->|ClaimedBy = other workflow| SKIP1[skip — mutex]
+    T -->|Node unmapped| SKIP2[log + skip]
+    T -->|node in closeOn| CLOSE[runner.Close — tear down terminals]
+    T -->|node agentless| GATE[claim if unclaimed, then leave for the human]
+    T -->|ClaimedBy = me, unknown in memory| BOUNCE[go bounce]
+    T -->|unclaimed| DISP[go dispatch]
+
+    DISP --> C1[tasks.Claim] --> S1[runner.Spawn fresh session]
+    BOUNCE --> F{runner.Find by title}
+    F -->|session alive| N1[Nudge once per node visit]
+    F -->|gone| S2[Spawn fresh — claim already held]
+```
+
+Claimed tickets are never touched by other workflows: the label is the cross-workflow mutex. "Claimed by me but unknown in memory" happens after a server restart — the bounce path re-finds the terminal by title (`<key>:<agent>:<node>`) and nudges it in place, preserving the agent's context instead of burning tokens on a fresh session.
+
+### Components
+
+```mermaid
+flowchart LR
+    subgraph CLI[relay-flow CLI]
+        M[cmd/relay-flow<br/>serve · submit · report · init]
+    end
+    subgraph SRV[server — one process, N workflows]
+        H[/submit · /report · /shutdown/]
+        D1[daemon: poll loop] --> T1[tasks iface]
+        D1 --> R1[runner iface]
+    end
+    subgraph ADAPTERS[adapters — registry pattern]
+        J[tasks/jira<br/>acli] -.-> T1
+        O[runner/orca<br/>worktrees + terminals] -.-> R1
+    end
+    M -->|unix socket ~/.relay-flow/server.sock| H
+    H --> D1
+```
+
+| Component | Location | Role |
+|---|---|---|
+| opencode plugin | `plugin/report-status.ts` | Parses STATUS/SUMMARY deterministically, calls `relay-flow report` (thin socket client), retries/nudges |
+| CLI | `cmd/relay-flow/` | `serve` hosts workflows; `submit` registers one; `report` is a one-shot client |
+| daemon | `internal/daemon/` | Poll loop, 3-way switch, dispatch/bounce goroutines |
+| server | `internal/server/` | Socket lifecycle, submit validation, report routing |
+| config | `internal/config/` | Workflow YAML schema + graph validation |
+| Jira adapter | `internal/tasks/jira/` | [readme](internal/tasks/jira/README.md) — query/claim/report over acli |
+| Orca adapter | `internal/runner/orca/` | [readme](internal/runner/orca/README.md) — worktrees, terminals, prompts |
+
+### Key invariants
+
+- **Fail fast**: everything validates at submit — YAML structure, graph shape, tracker states, assignee, adapters' configs.
+- **No fallback paths**: report goes through the server or not at all; server down = system down (the plugin's 3× retry + nudge covers transient gaps).
+- **Labels are never removed**: `wf:<name>` is the crash-recovery anchor.
+- **Terminals outlive their node visit** — a bounce reuses the session; only `closeOn` nodes close them.
+- **Parallelism**: one long-lived poll goroutine per workflow; short-lived dispatch/bounce goroutines per ticket; tickets at the same node run in parallel terminals with isolated worktrees.
+
+### Extending
+
+New tracker (beads, Linear, GitHub): implement `tasks.Tasks` + register — see [tasks/jira README](internal/tasks/jira/README.md#writing-a-new-tasks-adapter-beads-linear-github-).
+New execution backend (tmux, …): implement `runner.Runner` + register — see [runner/orca README](internal/runner/orca/README.md#writing-a-new-runner-tmux-).
+
+## Development
+
+```sh
+cd cli
+go test ./... -race
+go install ./...
+```

package/bin/relay-flow.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// relay-flow npm wrapper: downloads the prebuilt Go binary for this
+// platform from GitHub Releases (tag v<version>), falling back to
+// `go build` from the packaged source when no release asset matches
+// or the network is unavailable. Cached in os.tmpdir()/relay-flow/bin.
+const { spawnSync } = require("node:child_process")
+const fs = require("node:fs")
+const os = require("node:os")
+const path = require("node:path")
+
+const pkg = require(path.join(__dirname, "..", "package.json"))
+const version = pkg.version
+const root = path.dirname(__dirname)
+const binDir = path.join(os.tmpdir(), "relay-flow", "bin")
+const isWin = process.platform === "win32"
+const bin = path.join(binDir, isWin ? "relay-flow.exe" : "relay-flow")
+
+const goos = { linux: "linux", darwin: "darwin", win32: "windows" }[process.platform]
+const goarch = { x64: "amd64", arm64: "arm64" }[process.arch]
+
+function buildFromSource() {
+  const build = spawnSync("go", ["build", "-o", bin, path.join(root, "cmd", "relay-flow")], {
+    cwd: root,
+    stdio: "inherit",
+  })
+  if (build.status !== 0) process.exit(build.status ?? 1)
+}
+
+if (!fs.existsSync(bin)) {
+  fs.mkdirSync(binDir, { recursive: true })
+  let got = false
+  if (goos && goarch && !isWin) {
+    const asset = `relay-flow_${goos}_${goarch}.tar.gz`
+    const url = `https://github.com/rajpopat27/relay-flow/releases/download/v${version}/${asset}`
+    const archive = path.join(binDir, asset)
+    const dl = spawnSync("curl", ["-fsSL", "-o", archive, url], { stdio: "inherit" })
+    if (dl.status === 0) {
+      const untar = spawnSync("tar", ["-xzf", archive, "-C", binDir], { stdio: "inherit" })
+      fs.rmSync(archive, { force: true })
+      if (untar.status === 0 && fs.existsSync(bin)) {
+        fs.chmodSync(bin, 0o755)
+        got = true
+      }
+    }
+  }
+  if (!got) buildFromSource()
+}
+
+const run = spawnSync(bin, process.argv.slice(2), { stdio: "inherit" })
+process.exit(run.status ?? 0)

package/cmd/relay-flow/main.go

@@ -0,0 +1,250 @@
+// Command relay-flow automates tracker ↔ runner agent workflows.
+// `serve` is a central process hosting any number of workflows submitted via
+// `submit`. `report` is a one-shot socket client (invoked by the opencode
+// plugin) that asks the server to record an agent outcome.
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"io"
+	"log"
+	"net"
+	"os"
+	"os/exec"
+	"os/signal"
+	"path/filepath"
+
+	"syscall"
+
+	"github.com/rajpopat27/relay-flow/internal/acli"
+	"github.com/rajpopat27/relay-flow/internal/config"
+	"github.com/rajpopat27/relay-flow/internal/discovery"
+	"github.com/rajpopat27/relay-flow/internal/server"
+)
+
+func main() {
+	if len(os.Args) < 2 {
+		usage()
+		os.Exit(1)
+	}
+	switch os.Args[1] {
+	case "init":
+		cmdInit(os.Args[2:])
+	case "stop":
+		cmdStop(os.Args[2:])
+	case "serve":
+		cmdServe(os.Args[2:])
+	case "submit":
+		cmdSubmit(os.Args[2:])
+	case "report":
+		cmdReport(os.Args[2:])
+	default:
+		usage()
+		os.Exit(1)
+	}
+}
+
+func usage() {
+	fmt.Fprintln(os.Stderr, "usage: relay-flow init --assignee \"<your Jira display name or accountId>\"")
+	fmt.Fprintln(os.Stderr, "       relay-flow stop serve")
+	fmt.Fprintln(os.Stderr, "       relay-flow serve [--dry-run] [--foreground]")
+	fmt.Fprintln(os.Stderr, "       relay-flow submit [-f <yaml>]   (workflow name comes from the YAML's name field)")
+	fmt.Fprintln(os.Stderr, "       relay-flow report --workflow <name> --ticket <key> --node <node> --outcome <success|failure> --summary <text>")
+	fmt.Fprintln(os.Stderr, "  server artifacts (lock/sock/log) are always under ~/.relay-flow/")
+}
+
+// daemonize re-execs the binary detached with childArgs, log file attached
+// as stdout+stderr. No supervisor, no IPC: the child IS the worker. Returns
+// after spawning.
+func daemonize(logPath string, childArgs ...string) {
+	f, err := os.OpenFile(logPath, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o644)
+	if err != nil {
+		log.Fatalf("open log file: %v", err)
+	}
+	self, err := os.Executable()
+	if err != nil {
+		log.Fatalf("resolve executable: %v", err)
+	}
+	cmd := exec.Command(self, childArgs...)
+	cmd.Stdout, cmd.Stderr = f, f
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
+	cmd.Env = append(os.Environ(), "RELAY_FLOW_DAEMONIZED=1")
+	if err := cmd.Start(); err != nil {
+		log.Fatalf("daemonize: %v", err)
+	}
+	fmt.Printf("started (pid %d), logging to %s\n", cmd.Process.Pid, logPath)
+}
+
+// cmdInit writes the machine config (~/.relay-flow/config.yaml) with this machine
+// user's tracker identity, probe-validated against the tracker.
+func cmdInit(args []string) {
+	fs := flag.NewFlagSet("init", flag.ExitOnError)
+	assignee := fs.String("assignee", "", "your tracker display name or accountId")
+	fs.Parse(args)
+	if *assignee == "" {
+		log.Fatalf("usage: relay-flow init --assignee \"<your tracker display name or accountId>\"")
+	}
+	if err := acli.New().ValidateAssignee(*assignee); err != nil {
+		log.Fatalf("%v", err)
+	}
+	if err := (&config.MachineConfig{Assignee: *assignee}).Save(); err != nil {
+		log.Fatalf("%v", err)
+	}
+	p, _ := config.MachineConfigPath()
+	fmt.Printf("machine config written to %s (assignee=%q)\n", p, *assignee)
+}
+
+func cmdStop(args []string) {
+	// `stop serve` asks the central server to shut down over its socket;
+	// process exit releases the flock, so no pid file exists to clean up.
+	if len(args) != 1 || args[0] != "serve" {
+		log.Fatalf("usage: relay-flow stop serve")
+	}
+	client, err := server.NewClient()
+	if err != nil {
+		log.Fatalf("%v", err)
+	}
+	if err := client.Shutdown(); err != nil {
+		log.Fatalf("%v", err)
+	}
+	fmt.Println("server stopped")
+}
+
+// cmdServe runs the central server: one process hosting any number of
+// workflows submitted over its unix socket. Daemonizes by default.
+func cmdServe(args []string) {
+	fs := flag.NewFlagSet("serve", flag.ExitOnError)
+	dryRun := fs.Bool("dry-run", false, "log every runner command instead of executing it")
+	foreground := fs.Bool("foreground", false, "stay in the foreground")
+	fs.Parse(args)
+
+	home, err := os.UserHomeDir()
+	if err != nil {
+		log.Fatalf("%v", err)
+	}
+	logPath := filepath.Join(home, ".relay-flow", "server.log")
+
+	if !*foreground {
+		// Acquire the single-instance lock in the PARENT, before spawning:
+		// this is where the user is watching, so "already running" must
+		// fail here, not silently in the detached child.
+		release, err := discovery.AcquireServerLock()
+		if err != nil {
+			log.Fatalf("%v", err)
+		}
+		release()
+		childArgs := []string{"serve", "--foreground"}
+		if *dryRun {
+			childArgs = append(childArgs, "--dry-run")
+		}
+		daemonize(logPath, childArgs...)
+		return
+	}
+
+	// Tee logs to server.log when run interactively; daemonized child
+	// already has stderr attached to the log file.
+	if os.Getenv("RELAY_FLOW_DAEMONIZED") == "" {
+		if f, err := os.OpenFile(logPath, os.O_CREATE|os.O_APPEND|os.O_WRONLY, 0o644); err == nil {
+			log.SetOutput(io.MultiWriter(os.Stderr, f))
+			defer f.Close()
+		}
+	}
+
+	// Single instance enforcement via flock: the kernel holds the lock for
+	// this process's life and releases it on ANY exit (clean, crash,
+	// kill -9), so there is never stale state to clean up. No pid file.
+	releaseLock, err := discovery.AcquireServerLock()
+	if err != nil {
+		log.Fatalf("%v", err)
+	}
+	defer releaseLock()
+
+	sockPath, err := discovery.SocketPath()
+	if err != nil {
+		log.Fatalf("%v", err)
+	}
+	os.Remove(sockPath) // stale socket from a crashed server
+	ln, err := net.Listen("unix", sockPath)
+	if err != nil {
+		log.Fatalf("listen %s: %v", sockPath, err)
+	}
+	defer os.Remove(sockPath)
+
+	srv := server.New(*dryRun, server.ProdDeps(*dryRun))
+	log.Printf("relay-flow serve: socket=%s dry-run=%v", sockPath, *dryRun)
+
+	sig := make(chan os.Signal, 1)
+	signal.Notify(sig, syscall.SIGINT, syscall.SIGTERM)
+	go func() {
+		<-sig
+		log.Printf("shutting down")
+		srv.Shutdown()
+	}()
+	if err := srv.Serve(ln); err != nil {
+		log.Fatalf("serve: %v", err)
+	}
+}
+
+// cmdReport is invoked by the opencode plugin once per session.idle.
+// Thin socket client: the server resolves the outcome edge and calls the
+// tasks adapter — no config load, no tracker calls, no fallback. The
+// agent terminal is deliberately NOT closed here: it stays alive for
+// bounce nudges; only closeOn nodes close terminals.
+func cmdReport(args []string) {
+	fs := flag.NewFlagSet("report", flag.ExitOnError)
+	workflow := fs.String("workflow", "", "workflow name")
+	ticket := fs.String("ticket", "", "ticket key")
+	node := fs.String("node", "", "node name")
+	outcome := fs.String("outcome", "", "success or failure")
+	summary := fs.String("summary", "", "agent's summary of what it did")
+	fs.Parse(args)
+	if *workflow == "" || *ticket == "" || *node == "" || *outcome == "" || *summary == "" {
+		log.Fatalf("usage: relay-flow report --workflow <name> --ticket <key> --node <node> --outcome <success|failure> --summary <text>")
+	}
+	client, err := server.NewClient()
+	if err != nil {
+		log.Fatalf("%v", err)
+	}
+	result, err := client.Report(*workflow, *ticket, *node, *outcome, *summary)
+	if err != nil {
+		log.Fatalf("report %s: %v", *ticket, err)
+	}
+	// JSON on stdout (log goes to stderr) so the plugin can parse it.
+	out, _ := json.Marshal(map[string]string{"action": result.Action, "detail": result.Detail})
+	fmt.Println(string(out))
+	log.Printf("report %s: workflow=%s node=%s action=%s detail=%q", *ticket, *workflow, *node, result.Action, result.Detail)
+}
+
+// cmdSubmit reads a workflow YAML and sends it to the running server. cwd
+// must be inside the repo the workflow governs (repo resolved client-side).
+// The workflow's identity is the `name` field inside the YAML.
+func cmdSubmit(args []string) {
+	fs := flag.NewFlagSet("submit", flag.ExitOnError)
+	file := fs.String("f", "", "path to workflow YAML (default .workflow/workflow.yaml)")
+	fs.Parse(args)
+	if fs.NArg() != 0 {
+		log.Fatalf("usage: relay-flow submit [-f <yaml>]  (workflow name comes from the YAML's `name` field)")
+	}
+	path := *file
+	if path == "" {
+		path = filepath.Join(".workflow", "workflow.yaml")
+	}
+	yamlBytes, err := os.ReadFile(path)
+	if err != nil {
+		log.Fatalf("read %s: %v", path, err)
+	}
+	cwd, err := os.Getwd()
+	if err != nil {
+		log.Fatalf("%v", err)
+	}
+	client, err := server.NewClient()
+	if err != nil {
+		log.Fatalf("%v", err)
+	}
+	if err := client.Submit(cwd, yamlBytes); err != nil {
+		log.Fatalf("submit: %v", err)
+	}
+	fmt.Println("submitted")
+}

package/go.mod

@@ -0,0 +1,5 @@
+module github.com/rajpopat27/relay-flow
+
+go 1.21.11
+
+require gopkg.in/yaml.v3 v3.0.1 // indirect

package/go.sum

@@ -0,0 +1,3 @@
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=