relay-flow 0.0.1 → 0.2.0-alpha

package/internal/server/api_test.go

@@ -0,0 +1,300 @@
+package server_test
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"net/http"
+	"testing"
+	"time"
+
+	"github.com/rajpopat27/relay-flow/internal/run"
+	"github.com/rajpopat27/relay-flow/internal/task"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
+)
+
+// 3.35: server API per specs/workflow-repo-management "API responses and
+// status codes are stable". Drives the real http.Handler (server.New) over
+// in-process HTTP with fake services.
+
+type envelope struct {
+	OK    bool            `json:"ok"`
+	Data  json.RawMessage `json:"data"`
+	Error *struct {
+		Code    string `json:"code"`
+		Message string `json:"message"`
+	} `json:"error"`
+}
+
+func do(t *testing.T, c *http.Client, method, url string, body []byte) (int, envelope) {
+	t.Helper()
+	var rdr io.Reader
+	if body != nil {
+		rdr = bytes.NewReader(body)
+	}
+	req, err := http.NewRequest(method, url, rdr)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := c.Do(req)
+	if err != nil {
+		t.Fatalf("%s %s failed: %v", method, url, err)
+	}
+	defer resp.Body.Close()
+	raw, _ := io.ReadAll(resp.Body)
+	var env envelope
+	if err := json.Unmarshal(raw, &env); err != nil {
+		t.Fatalf("response not a JSON envelope: %q", raw)
+	}
+	return resp.StatusCode, env
+}
+
+func TestSuccessEnvelope(t *testing.T) {
+	c, cleanup := startHandler(t, &fakeServices{})
+	defer cleanup()
+	code, env := do(t, c, http.MethodGet, "http://relay/workflows", nil)
+	if code != http.StatusOK || !env.OK {
+		t.Fatalf("GET /workflows: code=%d env=%+v, want 200 ok", code, env)
+	}
+}
+
+func TestErrorEnvelopeAndStatusMapping(t *testing.T) {
+	c, cleanup := startHandler(t, &fakeServices{})
+	defer cleanup()
+
+	// 400 malformed JSON: drive a JSON endpoint (POST /repos) with malformed
+	// input. POST /workflows takes raw YAML by design (docs routes).
+	code, env := do(t, c, http.MethodPost, "http://relay/repos", []byte("{not json"))
+	if code != http.StatusBadRequest || env.OK || env.Error == nil || env.Error.Code == "" || env.Error.Message == "" {
+		t.Fatalf("malformed input: code=%d env=%+v, want 400 + lowerCamel error envelope", code, env)
+	}
+	if !isLowerCamel(env.Error.Code) {
+		t.Fatalf("error code %q not lowerCamel", env.Error.Code)
+	}
+
+	// 404 missing resource.
+	code, env = do(t, c, http.MethodGet, "http://relay/workflows/ghost", nil)
+	if code != http.StatusNotFound || env.OK || env.Error == nil {
+		t.Fatalf("missing resource: code=%d env=%+v, want 404", code, env)
+	}
+
+	// 405 wrong method.
+	code, env = do(t, c, http.MethodPatch, "http://relay/workflows", []byte("{}"))
+	if code != http.StatusMethodNotAllowed || env.OK {
+		t.Fatalf("wrong method: code=%d env=%+v, want 405", code, env)
+	}
+}
+
+func TestWorkflowConflictMapsTo409(t *testing.T) {
+	// basicFlow is seeded with an active run, so replacement conflicts -> 409.
+	c, cleanup := startHandler(t, &fakeServices{activeWorkflows: map[string]bool{"basicFlow": true}})
+	defer cleanup()
+
+	yamlBody := "name: basicFlow\nrepos: [payments]\nnodes:\n  start: {onSuccess: [{target: end}]}\n  end: {}\n"
+	// POST /workflows body IS the raw YAML (docs routes; client sends raw).
+	code, env := do(t, c, http.MethodPost, "http://relay/workflows", []byte(yamlBody))
+	if code != http.StatusConflict {
+		t.Fatalf("replacement during active run: code=%d, want 409", code)
+	}
+	if env.OK || env.Error == nil || !isLowerCamel(env.Error.Code) || env.Error.Message == "" {
+		t.Fatalf("409 without standard error envelope: %+v", env)
+	}
+}
+
+func TestUnexpectedFailureMapsTo500(t *testing.T) {
+	c, cleanup := startHandler(t, &fakeServices{failRepos: true})
+	defer cleanup()
+	code, env := do(t, c, http.MethodGet, "http://relay/repos/any", nil)
+	if code != http.StatusInternalServerError || env.OK || env.Error == nil {
+		t.Fatalf("unexpected failure: code=%d env=%+v, want 500 + error envelope", code, env)
+	}
+}
+
+func TestReportEndpointAcceptsJSON(t *testing.T) {
+	c, cleanup := startHandler(t, &fakeServices{})
+	defer cleanup()
+	report := `{"runId":"payments/basicFlow/PAY-101","node":"coding","reportId":"session-1:message-1","report":{"status":"success","nextStep":"end","summary":{"completed":"x","commits":"abc123","notCompleted":"None","issuesDiscovered":"None","verification":"x","notes":"None"},"feedback":{"reasonForNextStep":"None","requiredActions":"None","relevantContext":"None","expectedResult":"None"}}}`
+	code, env := do(t, c, http.MethodPost, "http://relay/reports", []byte(report))
+	if code != http.StatusOK || !env.OK {
+		t.Fatalf("valid report: code=%d env=%+v, want 200 ok", code, env)
+	}
+	var ack struct {
+		Accepted  bool `json:"accepted"`
+		Duplicate bool `json:"duplicate"`
+	}
+	if err := json.Unmarshal(env.Data, &ack); err != nil {
+		t.Fatalf("report ack data not the documented shape: %v", err)
+	}
+}
+
+func TestProcessedReportIDBypassesReportBodyValidation(t *testing.T) {
+	runID := "payments/basicFlow/PAY-101"
+	reportID := "session-1:message-1"
+	fake := &fakeServices{processedReports: map[string]bool{runID + ":" + reportID: true}}
+	c, cleanup := startHandler(t, fake)
+	defer cleanup()
+	body := []byte(`{"runId":"payments/basicFlow/PAY-101","node":"coding","reportId":"session-1:message-1","report":{"unknown":"ignored"}}`)
+	code, env := do(t, c, http.MethodPost, "http://relay/reports", body)
+	if code != http.StatusOK || !env.OK || !bytes.Contains(env.Data, []byte(`"duplicate":true`)) {
+		t.Fatalf("processed report: code=%d env=%+v, want duplicate ack", code, env)
+	}
+	if fake.submittedReports != 0 {
+		t.Fatalf("processed report reached SubmitReport %d times", fake.submittedReports)
+	}
+}
+
+func TestReportRejectsWrongWireKeyCasing(t *testing.T) {
+	c, cleanup := startHandler(t, &fakeServices{})
+	defer cleanup()
+	// runID/reportID (wrong casing) must be rejected by strict decoding.
+	bad := `{"runID":"payments/basicFlow/PAY-101","node":"coding","reportID":"session-1:message-1","report":{"status":"success","nextStep":"end","summary":{"completed":"x","commits":"abc123","notCompleted":"None","issuesDiscovered":"None","verification":"x","notes":"None"},"feedback":{"reasonForNextStep":"None","requiredActions":"None","relevantContext":"None","expectedResult":"None"}}}`
+	code, env := do(t, c, http.MethodPost, "http://relay/reports", []byte(bad))
+	if code != http.StatusBadRequest || env.OK {
+		t.Fatalf("wrong-cased wire keys: code=%d env=%+v, want 400 not ok", code, env)
+	}
+}
+
+func TestReportMultilineFieldsPreserved(t *testing.T) {
+	c, cleanup := startHandler(t, &fakeServices{})
+	defer cleanup()
+	// Multiline summary/feedback arrive as one JSON object, never as flags.
+	report := `{"runId":"payments/basicFlow/PAY-101","node":"coding","reportId":"session-1:message-1","report":{"status":"success","nextStep":"end","summary":{"completed":"line1\nline2\n- bullet","commits":"abc123","notCompleted":"None","issuesDiscovered":"None","verification":"ran ` + "`go test ./...`" + `","notes":"None"},"feedback":{"reasonForNextStep":"None","requiredActions":"None","relevantContext":"None","expectedResult":"None"}}}`
+	code, env := do(t, c, http.MethodPost, "http://relay/reports", []byte(report))
+	if code != http.StatusOK || !env.OK {
+		t.Fatalf("multiline report: code=%d env=%+v, want 200 ok", code, env)
+	}
+}
+
+func TestRuntimeSessionRegistrationEndpoint(t *testing.T) {
+	fake := &fakeServices{runtimeAck: run.NodeRuntimeRegistrationAck{Accepted: true}}
+	c, cleanup := startHandler(t, fake)
+	defer cleanup()
+	body := []byte(`{"runId":"payments/basic/PAY-101","node":"implement","sessionId":"session-1"}`)
+	code, env := do(t, c, http.MethodPost, "http://relay/runtime/session", body)
+	if code != http.StatusOK || !env.OK {
+		t.Fatalf("runtime registration: code=%d env=%+v", code, env)
+	}
+	if len(fake.registrations) != 1 || fake.registrations[0].SessionID != "session-1" {
+		t.Fatalf("registrations = %+v", fake.registrations)
+	}
+	if !bytes.Contains(env.Data, []byte(`"accepted":true`)) {
+		t.Fatalf("accepted ack missing: %s", env.Data)
+	}
+}
+
+func TestRepoAndRunEndpoints(t *testing.T) {
+	c, cleanup := startHandler(t, &fakeServices{})
+	defer cleanup()
+
+	// 200 repo list.
+	code, env := do(t, c, http.MethodGet, "http://relay/repos", nil)
+	if code != http.StatusOK || !env.OK {
+		t.Fatalf("GET /repos: code=%d env=%+v, want 200 ok", code, env)
+	}
+	// 404 missing repo.
+	code, env = do(t, c, http.MethodGet, "http://relay/repos/ghost", nil)
+	if code != http.StatusNotFound || env.OK {
+		t.Fatalf("GET /repos/ghost: code=%d, want 404", code)
+	}
+	// 200 run list.
+	code, env = do(t, c, http.MethodGet, "http://relay/runs", nil)
+	if code != http.StatusOK || !env.OK {
+		t.Fatalf("GET /runs: code=%d env=%+v, want 200 ok", code, env)
+	}
+	// 404 run by ticket.
+	code, env = do(t, c, http.MethodGet, "http://relay/runs/by-ticket/NOPE-1", nil)
+	if code != http.StatusNotFound || env.OK {
+		t.Fatalf("GET /runs/by-ticket/NOPE-1: code=%d, want 404", code)
+	}
+}
+
+func TestRunEndpointsExposeRetryDetails(t *testing.T) {
+	next := time.Now().UTC().Add(time.Minute)
+	retrying := run.Run{
+		ID: "payments/basicFlow/PAY-101", State: run.StateStarting,
+		Ticket: task.TicketRef{Key: "PAY-101"},
+		Retry:  &run.RetryStatus{Attempt: 2, LastError: "jira unavailable", NextRetryAt: next},
+	}
+	c, cleanup := startHandler(t, &fakeServices{runs: []run.Run{retrying}})
+	defer cleanup()
+
+	for _, url := range []string{"http://relay/runs", "http://relay/runs/by-ticket/PAY-101"} {
+		code, env := do(t, c, http.MethodGet, url, nil)
+		if code != http.StatusOK || !env.OK {
+			t.Fatalf("GET %s: code=%d env=%+v", url, code, env)
+		}
+		if !bytes.Contains(env.Data, []byte(`"state":"starting"`)) ||
+			!bytes.Contains(env.Data, []byte(`"retry":{"attempt":2,"lastError":"jira unavailable","nextRetryAt":`)) {
+			t.Fatalf("GET %s omitted lifecycle/retry details: %s", url, env.Data)
+		}
+	}
+}
+
+func TestRepoOperations(t *testing.T) {
+	c, cleanup := startHandler(t, &fakeServices{})
+	defer cleanup()
+
+	// Discover returns candidates (200). Route is GET per docs.
+	code, env := do(t, c, http.MethodGet, "http://relay/repos/discover", nil)
+	if code != http.StatusOK || !env.OK {
+		t.Fatalf("POST /repos/discover: code=%d env=%+v, want 200 ok", code, env)
+	}
+	// Register a repo (200), then get it (200).
+	code, env = do(t, c, http.MethodPost, "http://relay/repos", []byte(`{"name":"payments","path":"/srv/payments"}`))
+	if code != http.StatusOK && code != http.StatusCreated {
+		t.Fatalf("POST /repos: code=%d env=%+v, want 200/201", code, env)
+	}
+	code, env = do(t, c, http.MethodGet, "http://relay/repos/payments", nil)
+	if code != http.StatusOK || !env.OK {
+		t.Fatalf("GET /repos/payments: code=%d env=%+v, want 200 ok", code, env)
+	}
+	// Remove it (200).
+	code, env = do(t, c, http.MethodDelete, "http://relay/repos/payments", nil)
+	if code != http.StatusOK || !env.OK {
+		t.Fatalf("DELETE /repos/payments: code=%d env=%+v, want 200 ok", code, env)
+	}
+}
+
+func TestWorkflowGetRemoveAndRunCancel(t *testing.T) {
+	fake := &fakeServices{workflows: map[string]*workflow.Workflow{}, activeWorkflows: map[string]bool{}, runs: []run.Run{
+		{ID: "payments/basicFlow/PAY-101", State: run.StateRunning, Ticket: task.TicketRef{Key: "PAY-101"}},
+	}}
+	c, cleanup := startHandler(t, fake)
+	defer cleanup()
+
+	// Submit then GET a workflow (200).
+	wfYAML := "name: basicFlow\nrepos: [payments]\nnodes:\n  start: {onSuccess: [{target: coding}]}\n  coding: {type: agent, agent: build, description: work, onSuccess: [{target: end}], onFailure: [{target: coding}]}\n  end: {}\n"
+	code, _ := do(t, c, http.MethodPost, "http://relay/workflows", []byte(wfYAML))
+	if code != http.StatusOK && code != http.StatusCreated {
+		t.Fatalf("POST /workflows: code=%d, want 200/201", code)
+	}
+	code, env := do(t, c, http.MethodGet, "http://relay/workflows/basicFlow", nil)
+	if code != http.StatusOK || !env.OK {
+		t.Fatalf("GET /workflows/basicFlow: code=%d env=%+v, want 200 ok", code, env)
+	}
+	// Cancel the run by ticket (200), then remove the workflow (200).
+	// Route is /runs/by-ticket/{key}/cancel per docs.
+	code, env = do(t, c, http.MethodPost, "http://relay/runs/by-ticket/PAY-101/cancel", []byte(`{"reason":"done"}`))
+	if code != http.StatusOK || !env.OK {
+		t.Fatalf("POST /runs/PAY-101/cancel: code=%d env=%+v, want 200 ok", code, env)
+	}
+	code, env = do(t, c, http.MethodDelete, "http://relay/workflows/basicFlow", nil)
+	if code != http.StatusOK || !env.OK {
+		t.Fatalf("DELETE /workflows/basicFlow: code=%d env=%+v, want 200 ok", code, env)
+	}
+}
+
+func isLowerCamel(s string) bool {
+	if s == "" || s[0] < 'a' || s[0] > 'z' {
+		return false
+	}
+	for _, r := range s {
+		if r == '_' || r == '-' || r == ' ' {
+			return false
+		}
+	}
+	return true
+}

package/internal/server/client.go

@@ -5,122 +5,240 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"io"
 	"net"
 	"net/http"
-	"os"
+	"net/url"
 
-	"github.com/rajpopat27/relay-flow/internal/discovery"
+	"github.com/rajpopat27/relay-flow/internal/repo"
+	"github.com/rajpopat27/relay-flow/internal/run"
+	"github.com/rajpopat27/relay-flow/internal/runner"
+	"github.com/rajpopat27/relay-flow/internal/workflow"
 )
 
-// Client talks to a running `serve` process over its unix socket. Zero
-// value is unusable; construct with NewClient (prod socket) or set Socket
-// directly (tests).
+// Client is the typed HTTP-over-Unix-socket client matching the routes in
+// docs/structs-methods-interfaces.md. Commands use it; the CLI never
+// speaks JSON itself.
 type Client struct {
 	Socket string
 }
 
-// NewClient returns a Client for the default socket path.
-func NewClient() (*Client, error) {
-	p, err := discovery.SocketPath()
-	if err != nil {
-		return nil, err
-	}
-	return &Client{Socket: p}, nil
-}
+// NewClient returns a Client bound to the given socket path.
+func NewClient(socket string) *Client { return &Client{Socket: socket} }
 
 func (c *Client) httpClient() *http.Client {
-	return &http.Client{Transport: &http.Transport{
-		DialContext: func(_ context.Context, _, _ string) (net.Conn, error) {
-			return net.Dial("unix", c.Socket)
+	return &http.Client{
+		Transport: &http.Transport{
+			DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
+				return (&net.Dialer{}).DialContext(ctx, "unix", c.Socket)
+			},
 		},
-	}}
+	}
 }
 
-func (c *Client) do(method, path string, body any) error {
-	var rdr *bytes.Reader
+// call performs one HTTP request against the socket server and decodes
+// the standard envelope. Non-2xx responses return an error carrying the
+// server-provided code and message.
+func (c *Client) call(ctx context.Context, method, path string, body []byte, out any) error {
+	var rdr io.Reader
 	if body != nil {
-		b, _ := json.Marshal(body)
-		rdr = bytes.NewReader(b)
-	} else {
-		rdr = bytes.NewReader(nil)
+		rdr = bytes.NewReader(body)
 	}
-	req, err := http.NewRequest(method, "http://unix"+path, rdr)
+	req, err := http.NewRequestWithContext(ctx, method, "http://unix"+path, rdr)
 	if err != nil {
 		return err
 	}
-	req.Header.Set("Content-Type", "application/json")
+	if body != nil {
+		// Default to JSON; raw YAML workflow submits override below.
+		ct := "application/json"
+		if len(body) > 0 && body[0] != '{' && body[0] != '[' {
+			ct = "application/x-yaml"
+		}
+		req.Header.Set("Content-Type", ct)
+	}
 	resp, err := c.httpClient().Do(req)
 	if err != nil {
-		if _, statErr := os.Stat(c.Socket); os.IsNotExist(statErr) {
-			return fmt.Errorf("no server at %s — is `relay-flow serve` running?", c.Socket)
-		}
-		return fmt.Errorf("server call %s %s: %w (is `relay-flow serve` running?)", method, path, err)
+		return fmt.Errorf("server call %s %s: %w", method, path, err)
 	}
 	defer resp.Body.Close()
+	raw, _ := io.ReadAll(resp.Body)
 	var env struct {
-		OK  bool   `json:"ok"`
-		Err string `json:"error"`
+		OK    bool            `json:"ok"`
+		Data  json.RawMessage `json:"data"`
+		Error *struct {
+			Code    string `json:"code"`
+			Message string `json:"message"`
+		} `json:"error"`
+	}
+	if err := json.Unmarshal(raw, &env); err != nil {
+		return fmt.Errorf("server response not JSON envelope: %w", err)
 	}
-	if err := json.NewDecoder(resp.Body).Decode(&env); err != nil {
-		return fmt.Errorf("decode server reply: %w", err)
+	if !env.OK {
+		if env.Error != nil {
+			return fmt.Errorf("server %s: %s", env.Error.Code, env.Error.Message)
+		}
+		return fmt.Errorf("server returned not-ok (HTTP %d)", resp.StatusCode)
 	}
-	if resp.StatusCode >= 400 || (!env.OK && env.Err != "") {
-		if env.Err != "" {
-			return fmt.Errorf("server: %s", env.Err)
+	if out != nil && len(env.Data) > 0 {
+		if err := json.Unmarshal(env.Data, out); err != nil {
+			return fmt.Errorf("decode response data: %w", err)
 		}
-		return fmt.Errorf("server: status %d", resp.StatusCode)
 	}
 	return nil
 }
 
-// Submit sends a workflow YAML to the server (wired end-to-end in P6).
-func (c *Client) Submit(repoPath string, yamlBytes []byte) error {
-	return c.do("POST", "/submit", map[string]string{
-		"repoPath": repoPath, "yaml": string(yamlBytes),
-	})
+// Stop asks the server to shut down gracefully.
+func (c *Client) Stop(ctx context.Context) error {
+	return c.call(ctx, http.MethodPost, "/stop", nil, nil)
 }
 
-// Shutdown asks the server to stop.
-func (c *Client) Shutdown() error {
-	return c.do("POST", "/shutdown", nil)
+// SubmitWorkflow creates or replaces a workflow definition from YAML.
+// The request body is the raw YAML document, not a JSON wrapper.
+func (c *Client) SubmitWorkflow(ctx context.Context, yaml []byte) (*workflow.Workflow, error) {
+	var wf workflow.Workflow
+	if err := c.call(ctx, http.MethodPost, "/workflows", yaml, &wf); err != nil {
+		return nil, err
+	}
+	return &wf, nil
 }
 
-// ReportResult is the server's reply to a report call.
-type ReportResult struct {
-	Action string `json:"action"` // transitioned | commented | error
-	Detail string `json:"detail"`
+// RemoveWorkflow deletes a workflow by name.
+func (c *Client) RemoveWorkflow(ctx context.Context, name string) error {
+	return c.call(ctx, http.MethodDelete, "/workflows/"+url.PathEscape(name), nil, nil)
 }
 
-// Report posts an agent outcome to the server, which routes it to the
-// workflow's tasks adapter.
-func (c *Client) Report(workflow, ticket, node, outcome, summary string) (*ReportResult, error) {
-	b, _ := json.Marshal(map[string]string{
-		"workflow": workflow, "ticket": ticket, "node": node, "outcome": outcome, "summary": summary,
-	})
-	req, err := http.NewRequest("POST", "http://unix/report", bytes.NewReader(b))
-	if err != nil {
+// ListWorkflows returns every registered workflow.
+func (c *Client) ListWorkflows(ctx context.Context) ([]*workflow.Workflow, error) {
+	var out []*workflow.Workflow
+	if err := c.call(ctx, http.MethodGet, "/workflows", nil, &out); err != nil {
 		return nil, err
 	}
-	req.Header.Set("Content-Type", "application/json")
-	resp, err := c.httpClient().Do(req)
-	if err != nil {
-		if _, statErr := os.Stat(c.Socket); os.IsNotExist(statErr) {
-			return nil, fmt.Errorf("no server at %s — is `relay-flow serve` running?", c.Socket)
-		}
-		return nil, fmt.Errorf("server call POST /report: %w", err)
+	return out, nil
+}
+
+// GetWorkflow returns one workflow by name.
+func (c *Client) GetWorkflow(ctx context.Context, name string) (*workflow.Workflow, error) {
+	var wf workflow.Workflow
+	if err := c.call(ctx, http.MethodGet, "/workflows/"+url.PathEscape(name), nil, &wf); err != nil {
+		return nil, err
 	}
-	defer resp.Body.Close()
+	return &wf, nil
+}
+
+// DiscoverRepos returns runner-visible registration candidates.
+func (c *Client) DiscoverRepos(ctx context.Context) ([]runner.RepoCandidate, error) {
+	var out []runner.RepoCandidate
+	if err := c.call(ctx, http.MethodGet, "/repos/discover", nil, &out); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// RepoTaskFields returns the task factory's required repo keys, matching
+// GET /repos/task-fields (server wraps the list as {"fields": [...]}).
+func (c *Client) RepoTaskFields(ctx context.Context) ([]string, error) {
 	var out struct {
-		OK     bool   `json:"ok"`
-		Err    string `json:"error"`
-		Action string `json:"action"`
-		Detail string `json:"detail"`
+		Fields []string `json:"fields"`
+	}
+	if err := c.call(ctx, http.MethodGet, "/repos/task-fields", nil, &out); err != nil {
+		return nil, err
+	}
+	return out.Fields, nil
+}
+
+// RegisterRepo registers a repo by name/path with optional task config.
+func (c *Client) RegisterRepo(ctx context.Context, input repo.RegisterInput) (repo.Info, error) {
+	payload, _ := json.Marshal(input)
+	var out repo.Info
+	if err := c.call(ctx, http.MethodPost, "/repos", payload, &out); err != nil {
+		return repo.Info{}, err
+	}
+	return out, nil
+}
+
+// RemoveRepo unregisters a repo by name.
+func (c *Client) RemoveRepo(ctx context.Context, name string) error {
+	return c.call(ctx, http.MethodDelete, "/repos/"+url.PathEscape(name), nil, nil)
+}
+
+// ListRepos returns registered repo infos.
+func (c *Client) ListRepos(ctx context.Context) ([]repo.Info, error) {
+	var out []repo.Info
+	if err := c.call(ctx, http.MethodGet, "/repos", nil, &out); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// GetRepo returns one repo by name.
+func (c *Client) GetRepo(ctx context.Context, name string) (repo.Info, error) {
+	var out repo.Info
+	if err := c.call(ctx, http.MethodGet, "/repos/"+url.PathEscape(name), nil, &out); err != nil {
+		return repo.Info{}, err
+	}
+	return out, nil
+}
+
+// SubmitReport delivers one structured node report.
+func (c *Client) SubmitReport(ctx context.Context, report run.ReportRequest) (run.ReportAck, error) {
+	payload, err := json.Marshal(report)
+	if err != nil {
+		return run.ReportAck{}, err
 	}
-	if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
-		return nil, fmt.Errorf("decode server reply: %w", err)
+	var ack run.ReportAck
+	if err := c.call(ctx, http.MethodPost, "/reports", payload, &ack); err != nil {
+		return run.ReportAck{}, err
 	}
-	if resp.StatusCode >= 400 || (!out.OK && out.Err != "") {
-		return nil, fmt.Errorf("server: %s", out.Err)
+	return ack, nil
+}
+
+// RegisterNodeSession binds the OpenCode session emitted for a run/node.
+func (c *Client) RegisterNodeSession(ctx context.Context, registration run.NodeRuntimeRegistration) (run.NodeRuntimeRegistrationAck, error) {
+	payload, err := json.Marshal(registration)
+	if err != nil {
+		return run.NodeRuntimeRegistrationAck{}, err
+	}
+	var ack run.NodeRuntimeRegistrationAck
+	if err := c.call(ctx, http.MethodPost, "/runtime/session", payload, &ack); err != nil {
+		return run.NodeRuntimeRegistrationAck{}, err
+	}
+	return ack, nil
+}
+
+// CancelRun cancels the active run for the given ticket with a reason.
+func (c *Client) CancelRun(ctx context.Context, ticket, reason string) error {
+	payload, _ := json.Marshal(map[string]string{"reason": reason})
+	return c.call(ctx, http.MethodPost, "/runs/by-ticket/"+url.PathEscape(ticket)+"/cancel", payload, nil)
+}
+
+// ListRuns returns runs matching the filter.
+func (c *Client) ListRuns(ctx context.Context, filter run.Filter) ([]run.Run, error) {
+	q := url.Values{}
+	if filter.Repo != "" {
+		q.Set("repo", filter.Repo)
+	}
+	if filter.Workflow != "" {
+		q.Set("workflow", filter.Workflow)
+	}
+	if filter.Ticket != "" {
+		q.Set("ticket", filter.Ticket)
+	}
+	path := "/runs"
+	if s := q.Encode(); s != "" {
+		path += "?" + s
+	}
+	var out []run.Run
+	if err := c.call(ctx, http.MethodGet, path, nil, &out); err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// GetRunByTicket returns the run for a ticket.
+func (c *Client) GetRunByTicket(ctx context.Context, ticket string) (run.Run, error) {
+	var out run.Run
+	if err := c.call(ctx, http.MethodGet, "/runs/by-ticket/"+url.PathEscape(ticket), nil, &out); err != nil {
+		return run.Run{}, err
 	}
-	return &ReportResult{Action: out.Action, Detail: out.Detail}, nil
+	return out, nil
 }