ai/byre
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Add --data, --listen and --ports to byre serve for task previews

Browse Source
This commit is contained in:
Ian Gulliver
2026-10-15 12:39:46 -07:00
parent 8beab6e384
commit 4a9888e653
18 changed files with 100 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+1
View File
@@ -1,2 +1,3 @@
/web/node_modules/
/internal/claude/testdata/transcripts/
/.preview/
cmd/byre/serve.go
+11 -9
View File
@@ -15,27 +15,29 @@ import (
"time"
"g.fc.run/misc/byre/internal/server"
"g.fc.run/misc/byre/internal/store"
"g.fc.run/misc/byre/web"
)
const listenAddr = "127.0.0.1:8270"
func serveCmd(args []string) {
flags := flag.NewFlagSet("serve", flag.ExitOnError)
dev := flags.Bool("dev", false, "serve the SPA from ./web on disk instead of the embedded copy")
flags.Parse(args)
configDir, err := os.UserConfigDir()
if err != nil {
fatal("user config dir", "err", err)
}
flags := flag.NewFlagSet("serve", flag.ExitOnError)
dev := flags.Bool("dev", false, "serve the SPA from ./web on disk instead of the embedded copy")
dataDir := flags.String("data", filepath.Join(configDir, "byre"), "directory holding byre's database, worktrees, leads and blobs")
listenAddr := flags.String("listen", "127.0.0.1:8270", "address to listen on")
ports := flags.Int("ports", store.DefaultPortFirst, "first port of the tasks' port blocks")
flags.Parse(args)
spa := fs.FS(web.FS)
if *dev {
spa = os.DirFS("web")
}
srv, err := server.New(filepath.Join(configDir, "byre"), spa)
srv, err := server.New(*dataDir, *ports, spa)
if err != nil {
fatal("start server", "err", err)
}
@@ -45,7 +47,7 @@ func serveCmd(args []string) {
defer stop()
hs := &http.Server{
Addr: listenAddr,
Addr: *listenAddr,
Handler: srv.Handler(),
BaseContext: func(net.Listener) context.Context { return ctx },
}
@@ -57,7 +59,7 @@ func serveCmd(args []string) {
hs.Shutdown(shutdownCtx)
}()
slog.Info("listening", "addr", listenAddr, "dev", *dev)
slog.Info("listening", "addr", *listenAddr, "data", *dataDir, "ports", *ports, "dev", *dev)
err = hs.ListenAndServe()
if !errors.Is(err, http.ErrServerClosed) {
fatal("serve", "err", err)
docs/operations.md
+16 -5
View File
@@ -14,7 +14,7 @@
## Data
State lives in the `byre` directory under Go's `os.UserConfigDir()` (on macOS, `~/Library/Application Support/byre`): `byre.db`, `worktrees/<project-id>/<task-id>`, `leads/<login>` (each lead agent's working directory, the login path-escaped), and `blobs/<blob-id>` (uploaded images; the `blobs` table maps each id to its content type and its path relative to this directory). Task branches are `byre/<task-id>` in the project's repo.
State lives in the directory given by `byre serve --data`, by default the `byre` directory under Go's `os.UserConfigDir()` (on macOS, `~/Library/Application Support/byre`): `byre.db`, `worktrees/<project-id>/<task-id>`, `leads/<login>` (each lead agent's working directory, the login path-escaped), and `blobs/<blob-id>` (uploaded images; the `blobs` table maps each id to its content type and its path relative to this directory). Task branches are `byre/<task-id>` in the project's repo.
Schema changes are the `migrations` slice in `internal/store/store.go`: named entries, each with a short kebab-case name saying what it does. On open, byre applies, in slice order, every entry whose name isn't in the `migrations` table, each in its own transaction that also records the name. Each runs with foreign keys off, so a migration can rebuild a table other tables reference, and `PRAGMA foreign_key_check` must come back empty before it commits. byre is deployed from task branches that each append their own migrations, so after a merge a migration can land before others the database has already applied, and it still runs. Give a new migration a name no other branch will use, and make any data migration safe to run twice. `sqlite3 byre.db 'SELECT * FROM migrations'` lists what has been applied. A database from before the table existed is moved over on open: the first `PRAGMA user_version` entries are recorded as applied, and `user_version` is no longer read or written.
@@ -22,7 +22,7 @@ Schema changes are the `migrations` slice in `internal/store/store.go`: named en
Every task worktree is made by `createTask` (`internal/agents/tasks.go`): new tasks, `create_task`, `start_todo` and forks alike.
- **Ports.** Each active task holds a block of `store.PortBlock` ports starting at `tasks.port_base` (`port_base` on the Task). `Store.CreateTask` gives a new task the lowest block from `store.PortFirst` up that no active task holds, so a merged or discarded task's block is reused. The agent's `claude` process gets `PORT` (the first port, which most dev servers read on their own), and the session guidance names the range and says to run dev servers on it. `sqlite3 byre.db "SELECT id, port_base FROM tasks WHERE status = 'active'"` lists the blocks in use.
- **Ports.** Each active task holds a block of `store.PortBlock` ports starting at `tasks.port_base` (`port_base` on the Task). `Store.CreateTask` gives a new task the lowest block from `byre serve --ports` (default `store.DefaultPortFirst`) up that no active task holds, so a merged or discarded task's block is reused. The agent's `claude` process gets `PORT` (the first port, which most dev servers read on their own), and the session guidance names the range and says to run dev servers on it. `sqlite3 byre.db "SELECT id, port_base FROM tasks WHERE status = 'active'"` lists the blocks in use.
- **Setup script.** If the new worktree has an executable `script/setup` (`setupScript` in `internal/agents/setup.go`), byre runs it in the background, in the worktree, with `PORT` added to byre's environment. Nothing in its interface is byre-specific: a script that copies untracked files such as `.env` from the project's checkout finds it as the parent of `git rev-parse --path-format=absolute --git-common-dir`. It is the project's own file, so a branch that changes it changes the setup of tasks started or forked from that branch. It is killed after `setupTimeout`. The task's transcript shows a `setup.started` note and a `setup.ended` note holding the last `setupOutputBytes` of its combined output (`output`), how long it took (`duration_ms`) and `error` when it failed.
- **Waiting.** While setup runs, the task's turns are queued as if the caps were full (`Manager.settingUp`, checked in `turn` and `drain`), so the session shows `queued`; when setup ends, byre drains the queue. Task creation itself doesn't wait.
- **Failure.** A failed setup doesn't stop the agent. The next prompt its session submits gets the failure and the output appended to the `UserPromptSubmit` guidance (`remindTaskGuidance`), and at that moment byre files the same text as a `session_error` inbox item. The setup state and failure live in memory, so a byre restart during setup leaves the queued turn to start without it and nothing reruns the script.
@@ -45,13 +45,13 @@ One merge runs per project at a time. The Manager keeps the task holding each pr
## Running as a service
The listen address is `listenAddr` in `cmd/byre/serve.go`; it binds loopback only.
The listen address is `byre serve --listen`, whose default is in `cmd/byre/serve.go` (`go run ./cmd/byre serve --help` prints it); keep it on loopback, since identity relies on requests arriving from `tailscale serve`.
```
go install ./cmd/byre
cp deploy/run.fc.byre.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/run.fc.byre.plist
tailscale serve --bg --https=<port from listenAddr> http://<listenAddr>
tailscale serve --bg --https=<listen port> http://<listen address>
```
byre gets its own HTTPS port on the machine's `ts.net` name rather than a path under another service: the SPA and API use absolute paths, which break under a path prefix. `tailscale serve status` shows the URL and what else the machine serves.
@@ -60,6 +60,17 @@ After rebuilding: `go install ./cmd/byre && launchctl kickstart -k gui/$(id -u)/
Clients reach `tailscale serve` over HTTP/2; it proxies to byre over HTTP/1.1 and passes SSE through unbuffered.
## Previewing byre
A task's build of byre runs alongside the service with its own empty state, from the worktree root, on the task's port:
```
go run ./cmd/byre serve --dev --data "$PWD/.preview" --listen 127.0.0.1:$PORT --ports 51000
tailscale serve --bg --https=$PORT http://127.0.0.1:$PORT
```
It must never share the service's data directory: nothing locks the database, and startup resumes every session marked `running` in its recorded worktree. `--ports` puts the preview's own tasks' port blocks in a range the service's tasks don't use; each instance only knows its own tasks, so with the default both would hand out blocks from the same first port, starting with the one the preview listens on. `.preview/` is gitignored, so the end-of-turn commit leaves it out. The preview starts with no users, projects or sessions; set a git identity with `PUT /api/me` and add a project to try things. A project's Merge pushes to its checkout's `origin`, so a preview project should be a clone whose `origin` is a local bare repository (`git clone --bare <checkout> .preview/origin.git`, then clone that), never the real checkout. `tailscale serve --https=$PORT off` removes the preview's port; `tailscale serve status` lists what is served. byre's own environment doesn't have `tailscale` on its `PATH`; on macOS the CLI is `/Applications/Tailscale.app/Contents/MacOS/Tailscale`.
## Identity
`tailscale serve` adds `Tailscale-User-Login` and `Tailscale-User-Name` to proxied requests. The server accepts API requests only from loopback and only with both headers; anything else gets 401 or 403. The SPA's static files need no identity. Users are created on first request; each sets their commit identity with `PUT /api/me`.
@@ -67,7 +78,7 @@ Clients reach `tailscale serve` over HTTP/2; it proxies to byre over HTTP/1.1 an
To call the API locally without Tailscale, send the headers yourself:
```
curl -H 'Tailscale-User-Login: you@example.com' -H 'Tailscale-User-Name: You' http://<listenAddr>/api/me
curl -H 'Tailscale-User-Login: you@example.com' -H 'Tailscale-User-Name: You' http://<listen address>/api/me
```
## Agent sessions
internal/agents/inbox_internal_test.go
+1 -1
View File
@@ -69,7 +69,7 @@ func TestValidateAsk(t *testing.T) {
func TestCancelQuestion(t *testing.T) {
ctx := context.Background()
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), func(api.Event) {})
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), store.DefaultPortFirst, func(api.Event) {})
if err != nil {
t.Fatalf("open store: %v", err)
}
internal/agents/lead_internal_test.go
+1 -1
View File
@@ -13,7 +13,7 @@ import (
func TestPaneFreed(t *testing.T) {
ctx := context.Background()
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), func(api.Event) {})
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), store.DefaultPortFirst, func(api.Event) {})
if err != nil {
t.Fatalf("open store: %v", err)
}
internal/agents/manager_test.go
+1 -1
View File
@@ -48,7 +48,7 @@ func newEnv(t *testing.T) *env {
e := &env{t: t, ctx: ctx, events: make(chan api.Event, 4096), worktrees: t.TempDir(), leads: t.TempDir()}
var err error
e.store, err = store.Open(filepath.Join(t.TempDir(), "byre.db"), func(ev api.Event) { e.events <- ev })
e.store, err = store.Open(filepath.Join(t.TempDir(), "byre.db"), store.DefaultPortFirst, func(ev api.Event) { e.events <- ev })
if err != nil {
t.Fatalf("open store: %v", err)
}
internal/agents/mergetitle_internal_test.go
+1 -1
View File
@@ -14,7 +14,7 @@ import (
func TestSetMergeTitle(t *testing.T) {
ctx := context.Background()
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), func(api.Event) {})
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), store.DefaultPortFirst, func(api.Event) {})
if err != nil {
t.Fatalf("open store: %v", err)
}
internal/agents/ratelimit_internal_test.go
+1 -1
View File
@@ -13,7 +13,7 @@ import (
func TestRateLimitedTurn(t *testing.T) {
ctx := context.Background()
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), func(api.Event) {})
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), store.DefaultPortFirst, func(api.Event) {})
if err != nil {
t.Fatalf("open store: %v", err)
}
internal/agents/snapshots_internal_test.go
+1 -1
View File
@@ -17,7 +17,7 @@ import (
func TestSnapshots(t *testing.T) {
ctx := context.Background()
events := make(chan api.Event, 256)
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), func(ev api.Event) { events <- ev })
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), store.DefaultPortFirst, func(ev api.Event) { events <- ev })
if err != nil {
t.Fatalf("open store: %v", err)
}
internal/agents/subagent_internal_test.go
+1 -1
View File
@@ -13,7 +13,7 @@ import (
func TestSubagentEvents(t *testing.T) {
ctx := context.Background()
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), func(api.Event) {})
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), store.DefaultPortFirst, func(api.Event) {})
if err != nil {
t.Fatalf("open store: %v", err)
}
internal/push/push_test.go
+1 -1
View File
@@ -25,7 +25,7 @@ type received struct {
func TestBurstIsOneNotification(t *testing.T) {
ctx := context.Background()
var notifier *push.Notifier
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), func(ev api.Event) { notifier.Observe(ev) })
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), store.DefaultPortFirst, func(ev api.Event) { notifier.Observe(ev) })
if err != nil {
t.Fatalf("open store: %v", err)
}
internal/server/server.go
+2 -2
View File
@@ -38,7 +38,7 @@ type Server struct {
type ctxKey struct{}
func New(dataDir string, spa fs.FS) (*Server, error) {
func New(dataDir string, portFirst int, spa fs.FS) (*Server, error) {
err := os.MkdirAll(dataDir, 0o755)
if err != nil {
return nil, err
@@ -52,7 +52,7 @@ func New(dataDir string, spa fs.FS) (*Server, error) {
users: map[string]string{},
}
s.store, err = store.Open(filepath.Join(dataDir, "byre.db"), s.publish)
s.store, err = store.Open(filepath.Join(dataDir, "byre.db"), portFirst, s.publish)
if err != nil {
return nil, err
}
internal/server/server_test.go
+3 -2
View File
@@ -20,6 +20,7 @@ import (
"g.fc.run/misc/byre/internal/api"
"g.fc.run/misc/byre/internal/server"
"g.fc.run/misc/byre/internal/store"
"g.fc.run/misc/byre/web"
)
@@ -31,7 +32,7 @@ type harness struct {
}
func newHarness(t *testing.T) *harness {
srv, err := server.New(t.TempDir(), fstest.MapFS{"index.html": {Data: []byte("shell")}})
srv, err := server.New(t.TempDir(), store.DefaultPortFirst, fstest.MapFS{"index.html": {Data: []byte("shell")}})
if err != nil {
t.Fatalf("new server: %v", err)
}
@@ -109,7 +110,7 @@ func TestIdentityRequired(t *testing.T) {
}
func TestServesEmbeddedSPA(t *testing.T) {
srv, err := server.New(t.TempDir(), web.FS)
srv, err := server.New(t.TempDir(), store.DefaultPortFirst, web.FS)
if err != nil {
t.Fatalf("new server: %v", err)
}
internal/store/blob_test.go
+1 -1
View File
@@ -13,7 +13,7 @@ import (
func TestQueuedTurnKeepsImages(t *testing.T) {
ctx := context.Background()
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), func(api.Event) {})
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), store.DefaultPortFirst, func(api.Event) {})
if err != nil {
t.Fatalf("open store: %v", err)
}
internal/store/inbox_test.go
+1 -1
View File
@@ -13,7 +13,7 @@ import (
func TestClosingTaskDismissesOpenInbox(t *testing.T) {
ctx := context.Background()
events := []api.Event{}
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), func(ev api.Event) { events = append(events, ev) })
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), store.DefaultPortFirst, func(ev api.Event) { events = append(events, ev) })
if err != nil {
t.Fatalf("open store: %v", err)
}
internal/store/merging_test.go
+2 -2
View File
@@ -13,7 +13,7 @@ import (
func TestMergingBySurvivesReopen(t *testing.T) {
ctx := context.Background()
path := filepath.Join(t.TempDir(), "byre.db")
st, err := store.Open(path, func(api.Event) {})
st, err := store.Open(path, store.DefaultPortFirst, func(api.Event) {})
if err != nil {
t.Fatalf("open store: %v", err)
}
@@ -38,7 +38,7 @@ func TestMergingBySurvivesReopen(t *testing.T) {
}
st.Close()
st, err = store.Open(path, func(api.Event) {})
st, err = store.Open(path, store.DefaultPortFirst, func(api.Event) {})
if err != nil {
t.Fatalf("reopen store: %v", err)
}
internal/store/ports_test.go
+45
View File
@@ -0,0 +1,45 @@
package store_test
import (
"context"
"path/filepath"
"testing"
"time"
"g.fc.run/misc/byre/internal/api"
"g.fc.run/misc/byre/internal/store"
)
func TestPortBlocksStartAtPortFirst(t *testing.T) {
ctx := context.Background()
st, err := store.Open(filepath.Join(t.TempDir(), "byre.db"), 51000, func(api.Event) {})
if err != nil {
t.Fatalf("open store: %v", err)
}
t.Cleanup(func() { st.Close() })
now := time.Now().UTC()
_, err = st.EnsureUser(ctx, "alice", "Alice")
if err != nil {
t.Fatalf("ensure user: %v", err)
}
err = st.CreateProject(ctx, api.Project{Id: "p1", Name: "demo", RepoPath: "/nonexistent", DefaultBranch: "main", Remote: "none", CreatedBy: "alice", CreatedAt: now})
if err != nil {
t.Fatalf("create project: %v", err)
}
for i, want := range []int{51000, 51010} {
id := []string{"t1", "t2"}[i]
err = st.CreateTask(ctx, api.Task{Id: id, ProjectId: "p1", Title: id, Branch: id, WorktreePath: "/nonexistent", BaseRef: "x", Status: api.TaskStatusActive, CreatedBy: "alice", CreatedAt: now}, "alice")
if err != nil {
t.Fatalf("create task %s: %v", id, err)
}
task, err := st.GetTask(ctx, id)
if err != nil {
t.Fatalf("get task %s: %v", id, err)
}
if task.PortBase != want {
t.Fatalf("task %s port_base = %d, want %d", id, task.PortBase, want)
}
}
}
internal/store/store.go
+10 -9
View File
@@ -274,18 +274,19 @@ ALTER TABLE tasks ADD COLUMN merge_queued_at TEXT NOT NULL DEFAULT '';
`}}
const (
PortFirst = 41000
PortBlock = 10
DefaultPortFirst = 41000
PortBlock = 10
)
type Store struct {
db *sql.DB
path string
writeMu sync.Mutex
onEvent func(api.Event)
db *sql.DB
path string
portFirst int
writeMu sync.Mutex
onEvent func(api.Event)
}
func Open(path string, onEvent func(api.Event)) (*Store, error) {
func Open(path string, portFirst int, onEvent func(api.Event)) (*Store, error) {
dsn := "file:" + path + "?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)&_pragma=foreign_keys(1)&_txlock=immediate"
db, err := sql.Open("sqlite", dsn)
if err != nil {
@@ -298,7 +299,7 @@ func Open(path string, onEvent func(api.Event)) (*Store, error) {
return nil, err
}
return &Store{db: db, path: path, onEvent: onEvent}, nil
return &Store{db: db, path: path, portFirst: portFirst, onEvent: onEvent}, nil
}
func migrate(db *sql.DB, migrations []migration) error {
@@ -557,7 +558,7 @@ func (s *Store) CreateTask(ctx context.Context, t api.Task, actor string) error
SELECT ? AS candidate
UNION ALL SELECT port_base + ? FROM tasks WHERE status = ?
) WHERE candidate NOT IN (SELECT port_base FROM tasks WHERE status = ?)
`, PortFirst, PortBlock, string(api.TaskStatusActive), string(api.TaskStatusActive)).Scan(&t.PortBase)
`, s.portFirst, PortBlock, string(api.TaskStatusActive), string(api.TaskStatusActive)).Scan(&t.PortBase)
if err != nil {
return err
}