@kyleroche/relay 0.0.0-stage → 0.2.0

package/dist/migrations/001_init.sql

@@ -0,0 +1,153 @@
+-- relay memory + event log. Postgres 15+. Works on Neon (prod) and PGlite (local/tests).
+-- Vector search needs the pgvector extension; full-text uses built-in tsvector.
+CREATE EXTENSION IF NOT EXISTS vector;
+
+CREATE TABLE IF NOT EXISTS meta (
+  key text PRIMARY KEY,
+  value jsonb NOT NULL,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+-- A registered repository. slug is the GitHub repo name; repo is "owner/name".
+CREATE TABLE IF NOT EXISTS projects (
+  slug text PRIMARY KEY,
+  repo text,
+  path text,
+  stack text,
+  check_cmd text,
+  summary text,
+  summary_tokens int,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+-- Per-file digest keyed by content hash; re-summarized only when sha256 changes.
+CREATE TABLE IF NOT EXISTS file_digests (
+  project text NOT NULL REFERENCES projects(slug) ON DELETE CASCADE,
+  path text NOT NULL,
+  sha256 text NOT NULL,
+  size int NOT NULL DEFAULT 0,
+  summary text,
+  summary_sha text,
+  tokens int NOT NULL DEFAULT 0,
+  seen_at timestamptz NOT NULL DEFAULT now(),
+  summarized_at timestamptz,
+  PRIMARY KEY (project, path)
+);
+
+-- Durable, cross-tool memory: decisions and preferences.
+CREATE TABLE IF NOT EXISTS decisions (
+  id bigserial PRIMARY KEY,
+  project text REFERENCES projects(slug) ON DELETE CASCADE,
+  text text NOT NULL,
+  source text,                 -- 'claude' | 'codex' | 'grok' | 'pr' | 'human' | 'nightly'
+  source_ref text,             -- session id, PR url, etc.
+  valid_from timestamptz NOT NULL DEFAULT now(),
+  valid_to timestamptz,        -- null = current; set when superseded
+  superseded_by bigint REFERENCES decisions(id),
+  embedding vector(1536),
+  tsv tsvector GENERATED ALWAYS AS (to_tsvector('english', text)) STORED,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS decisions_project_idx ON decisions(project) WHERE valid_to IS NULL;
+CREATE INDEX IF NOT EXISTS decisions_tsv_idx ON decisions USING gin(tsv);
+
+CREATE TABLE IF NOT EXISTS preferences (
+  key text NOT NULL,
+  scope text NOT NULL,         -- 'global' | 'project' | 'lane' | 'model'
+  scope_id text NOT NULL DEFAULT '',
+  value text NOT NULL,
+  reason text,
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (key, scope, scope_id)
+);
+
+-- Official vendor guidance per model (the onboarding gate).
+CREATE TABLE IF NOT EXISTS providers (
+  slug text PRIMARY KEY,
+  name text NOT NULL,
+  doc_domains text[] NOT NULL DEFAULT '{}',
+  skill_sources text[] NOT NULL DEFAULT '{}',
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS models (
+  id text PRIMARY KEY,         -- e.g. bytedance/seedance-2.5
+  provider text NOT NULL REFERENCES providers(slug),
+  lanes text[] NOT NULL DEFAULT '{}',
+  onboarded_at timestamptz,
+  guidance_count int NOT NULL DEFAULT 0,
+  skill_count int NOT NULL DEFAULT 0,
+  stale_days int NOT NULL DEFAULT 30,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS sources (
+  url text PRIMARY KEY,
+  provider text NOT NULL,
+  title text,
+  sha256 text,
+  etag text,
+  official boolean NOT NULL DEFAULT true,
+  fetched_at timestamptz,
+  checked_at timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE TABLE IF NOT EXISTS guidance (
+  id text NOT NULL,            -- sha256(source_url#index:head); the same source may guide several models
+  model text NOT NULL REFERENCES models(id) ON DELETE CASCADE,
+  provider text NOT NULL,
+  source_url text NOT NULL REFERENCES sources(url) ON DELETE CASCADE,
+  chunk_index int NOT NULL,
+  kind text NOT NULL,          -- prompting | limits | api | moderation | style | skill
+  title text NOT NULL,
+  text text NOT NULL,
+  tokens int NOT NULL,
+  embedding vector(1536),
+  tsv tsvector GENERATED ALWAYS AS (to_tsvector('english', coalesce(title,'') || ' ' || text)) STORED,
+  fetched_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (model, id)
+);
+CREATE INDEX IF NOT EXISTS guidance_model_idx ON guidance(model);
+CREATE INDEX IF NOT EXISTS guidance_tsv_idx ON guidance USING gin(tsv);
+CREATE TABLE IF NOT EXISTS skills (
+  name text NOT NULL,
+  model text NOT NULL REFERENCES models(id) ON DELETE CASCADE,
+  provider text NOT NULL,
+  install_path text NOT NULL,
+  version text NOT NULL,
+  sha256 text NOT NULL,
+  source_url text NOT NULL,
+  installed_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (name, model)
+);
+
+-- The event feed: one append-only log of everything agents and humans did. The ledger is a view over it.
+CREATE TABLE IF NOT EXISTS events (
+  id bigserial PRIMARY KEY,
+  ts timestamptz NOT NULL DEFAULT now(),
+  kind text NOT NULL,          -- issue.opened | run.started | run.finished | step.usage | pr.opened | pr.merged | preview.ready | decision.captured | memory.consolidated | onboard.refreshed | ...
+  actor text NOT NULL,         -- 'human:kyle' | 'bot:grok' | 'runner:mini' | 'agent:claude' | ...
+  project text,
+  repo text,
+  issue int,
+  pr int,
+  lane text,
+  model text,
+  subscription text,           -- max | codex | grok | gateway | cursor | local
+  tokens_in bigint NOT NULL DEFAULT 0,
+  tokens_out bigint NOT NULL DEFAULT 0,
+  cache_read bigint NOT NULL DEFAULT 0,
+  cache_write bigint NOT NULL DEFAULT 0,
+  cost_equiv numeric(12,6) NOT NULL DEFAULT 0,
+  duration_ms int,
+  summary text NOT NULL,
+  url text,
+  payload jsonb NOT NULL DEFAULT '{}'::jsonb,
+  dedupe_key text UNIQUE       -- e.g. github delivery id, so webhooks are idempotent
+);
+CREATE INDEX IF NOT EXISTS events_ts_idx ON events(ts DESC);
+CREATE INDEX IF NOT EXISTS events_project_ts_idx ON events(project, ts DESC);
+CREATE INDEX IF NOT EXISTS events_kind_ts_idx ON events(kind, ts DESC);
+
+CREATE OR REPLACE VIEW ledger AS
+  SELECT ts, actor, project, lane, model, subscription, tokens_in, tokens_out, cache_read, cache_write, cost_equiv, duration_ms, url
+  FROM events WHERE kind = 'step.usage';

package/dist/migrations/002_assets.sql

@@ -0,0 +1,33 @@
+-- Asset library: media too large to share inline, versioned, with an approve-or-reject review loop (docs/ASSETS.md).
+-- Access control is the app's job (API scopes); the table carries no per-row grants.
+CREATE TABLE IF NOT EXISTS assets (
+  id text PRIMARY KEY,                                  -- ulid
+  project text REFERENCES projects(slug) ON DELETE SET NULL,
+  issue int,
+  pr int,
+  title text NOT NULL,
+  description text,
+  kind text NOT NULL,                                   -- image | video | audio | pdf | html | file
+  mime text NOT NULL,
+  size bigint NOT NULL,
+  sha256 text NOT NULL,
+  storage_key text NOT NULL,                            -- blob pathname or local relative path
+  thumb_key text,
+  width int,
+  height int,
+  duration_ms int,
+  version int NOT NULL DEFAULT 1,
+  parent_id text REFERENCES assets(id) ON DELETE SET NULL,  -- previous version; survives the parent's expiry
+  status text NOT NULL DEFAULT 'pending',               -- pending | approved | rejected | superseded | published
+  created_by text NOT NULL,                             -- actor, e.g. bot:grok, runner:mini, human:kyle
+  created_at timestamptz NOT NULL DEFAULT now(),
+  reviewed_by text,
+  reviewed_at timestamptz,
+  review_note text,
+  public_url text,                                      -- set only after an explicit publish
+  expires_at timestamptz,                               -- set when rejected or superseded; null = keep
+  tags text[] NOT NULL DEFAULT '{}'
+);
+CREATE INDEX IF NOT EXISTS assets_project_status_idx ON assets(project, status, created_at DESC);
+CREATE INDEX IF NOT EXISTS assets_expires_idx ON assets(expires_at) WHERE expires_at IS NOT NULL;
+CREATE INDEX IF NOT EXISTS assets_parent_idx ON assets(parent_id);

package/dist/migrations/003_tokens.sql

@@ -0,0 +1,14 @@
+-- API bearer tokens for the web app and the HTTP MCP server. Only the SHA-256 of a token is stored; the plaintext is
+-- shown once by `relay token create`. Scopes are the names the OpenAPI description publishes (feed:read, memory:read,
+-- memory:write, assets:read, assets:write, assets:review).
+CREATE TABLE IF NOT EXISTS tokens (
+  id text PRIMARY KEY,                       -- ulid
+  name text NOT NULL,
+  token_hash text NOT NULL UNIQUE,           -- sha256 hex of the plaintext token
+  scopes text[] NOT NULL DEFAULT '{}',
+  created_by text NOT NULL,                  -- actor, e.g. human:kyle
+  created_at timestamptz NOT NULL DEFAULT now(),
+  last_used_at timestamptz,
+  revoked_at timestamptz
+);
+CREATE INDEX IF NOT EXISTS tokens_hash_live_idx ON tokens(token_hash) WHERE revoked_at IS NULL;

package/dist/migrations/004_tasks.sql

@@ -0,0 +1,12 @@
+-- Tasks: a thin record over a GitHub issue so bots can address work by one id ("<owner>/<repo>#<n>") and create it
+-- idempotently. State is never stored here; it is derived from the feed (packages/core/src/db/tasks.ts taskState).
+CREATE TABLE IF NOT EXISTS tasks (
+  id text PRIMARY KEY,                                   -- "<owner>/<repo>#<n>"
+  project text NOT NULL REFERENCES projects(slug) ON DELETE CASCADE,
+  repo text NOT NULL,                                    -- "owner/name"
+  issue int NOT NULL,
+  idempotency_key text UNIQUE,                           -- caller-supplied; a repeat create returns the same task
+  created_by text NOT NULL,                              -- actor, e.g. bot:grok or human:kyle
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS tasks_project_created_idx ON tasks(project, created_at DESC);

package/dist/migrations/005_webhooks.sql

@@ -0,0 +1,28 @@
+-- Outbound webhooks (docs/FEED.md "Outbound webhooks"): after an event is written, matching hooks receive a signed
+-- POST. The secret and bearer are stored as given because the dispatcher needs them to sign and authenticate; the
+-- API never returns them after creation. One delivery row per (webhook, event) records the attempts.
+CREATE TABLE IF NOT EXISTS webhooks (
+  id text PRIMARY KEY,                                   -- ulid
+  project text REFERENCES projects(slug) ON DELETE CASCADE,   -- null = every project
+  url text NOT NULL,
+  secret text NOT NULL,                                  -- HMAC key for X-Relay-Signature
+  bearer text,                                           -- sent as Authorization: Bearer when set
+  events text[] NOT NULL DEFAULT '{}',                   -- kinds, prefixes ending in '.', or '*'
+  active boolean NOT NULL DEFAULT true,
+  created_by text NOT NULL DEFAULT '',
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS webhooks_active_idx ON webhooks(active) WHERE active;
+
+CREATE TABLE IF NOT EXISTS webhook_deliveries (
+  id text PRIMARY KEY,                                   -- ulid; also the X-Relay-Delivery header
+  webhook_id text NOT NULL REFERENCES webhooks(id) ON DELETE CASCADE,
+  event_id bigint,                                       -- events.id; null for test.ping
+  kind text NOT NULL DEFAULT '',
+  status text NOT NULL DEFAULT 'pending',                -- pending | delivered | failed
+  attempts int NOT NULL DEFAULT 0,
+  last_error text,
+  delivered_at timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS webhook_deliveries_hook_idx ON webhook_deliveries(webhook_id, created_at DESC);

package/dist/migrations/006_oauth.sql

@@ -0,0 +1,85 @@
+-- OAuth 2.1 authorization server state (docs/SECURITY.md, "Access for agents"): registered clients, one-time
+-- authorization codes, device codes, refresh tokens, invites, and operator settings. Access tokens are rows in `tokens`
+-- (named `oauth:<client name>`), so every existing scope check keeps working; they gain an expiry and a client here.
+-- Every secret-bearing column stores a SHA-256, never the plaintext, except `settings.value`, which is sealed
+-- (AES-256-GCM under RELAY_SESSION_SECRET) when `sealed` is true.
+ALTER TABLE tokens ADD COLUMN IF NOT EXISTS expires_at timestamptz;
+ALTER TABLE tokens ADD COLUMN IF NOT EXISTS client_id text;
+
+CREATE TABLE IF NOT EXISTS oauth_clients (
+  client_id text PRIMARY KEY,
+  client_secret_hash text,                                -- null for public clients (token_endpoint_auth_method = none)
+  name text NOT NULL,
+  redirect_uris text[] NOT NULL DEFAULT '{}',
+  grant_types text[] NOT NULL DEFAULT '{}',
+  token_endpoint_auth_method text NOT NULL DEFAULT 'none',
+  scopes text[] NOT NULL DEFAULT '{}',                    -- the most the client may ask for; empty = any
+  software_id text,
+  client_uri text,
+  created_by text NOT NULL DEFAULT '',
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS oauth_codes (
+  code_hash text PRIMARY KEY,
+  client_id text NOT NULL REFERENCES oauth_clients(client_id) ON DELETE CASCADE,
+  redirect_uri text NOT NULL,
+  scopes text[] NOT NULL,
+  code_challenge text NOT NULL,
+  code_challenge_method text NOT NULL DEFAULT 'S256',
+  resource text,
+  actor text NOT NULL,                                    -- human:<login> who approved on the consent page
+  expires_at timestamptz NOT NULL,
+  used_at timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS oauth_device_codes (
+  device_code_hash text PRIMARY KEY,
+  user_code text NOT NULL UNIQUE,                         -- RLAY-4F7Q, what the person types on /activate
+  client_id text NOT NULL REFERENCES oauth_clients(client_id) ON DELETE CASCADE,
+  scopes text[] NOT NULL,
+  status text NOT NULL DEFAULT 'pending',                 -- pending | approved | denied | redeemed
+  actor text,                                             -- who decided
+  decided_at timestamptz,
+  token_id text,                                          -- tokens.id once redeemed
+  interval_seconds int NOT NULL DEFAULT 5,
+  last_polled_at timestamptz,
+  expires_at timestamptz NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS oauth_device_codes_pending_idx ON oauth_device_codes(expires_at) WHERE status = 'pending';
+
+CREATE TABLE IF NOT EXISTS oauth_refresh_tokens (
+  token_hash text PRIMARY KEY,
+  client_id text NOT NULL,
+  access_token_id text REFERENCES tokens(id) ON DELETE SET NULL,
+  scopes text[] NOT NULL,
+  actor text NOT NULL,                                    -- who the grant belongs to (the approver, or invite:<id>)
+  expires_at timestamptz NOT NULL,
+  rotated_from text,                                      -- the token_hash this one replaced
+  used_at timestamptz,                                    -- set when rotated; a second use revokes the lineage
+  revoked_at timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS invites (
+  id text PRIMARY KEY,                                    -- ulid
+  code_hash text NOT NULL UNIQUE,
+  name text NOT NULL,                                     -- who it is for; the token is named oauth:<name>
+  scopes text[] NOT NULL,
+  uses_left int NOT NULL DEFAULT 1,
+  max_uses int NOT NULL DEFAULT 1,
+  expires_at timestamptz NOT NULL,
+  created_by text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  revoked_at timestamptz,
+  last_redeemed_at timestamptz
+);
+
+CREATE TABLE IF NOT EXISTS settings (
+  key text PRIMARY KEY,
+  value text NOT NULL,
+  sealed boolean NOT NULL DEFAULT false,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);

package/dist/migrations/007_workers.sql

@@ -0,0 +1,31 @@
+-- Workers and claims (docs/WORKERS.md): relay schedules its own tasks. A worker is a machine that ran
+-- `relay work`; it registers by name, heartbeats, and claims the oldest queued task whose lane it serves. A claim
+-- is a lease: it expires unless the heartbeat renews it, and an expired lease puts the task back in the queue.
+-- Task state stays derived (packages/core/src/db/tasks.ts); claims only add the `claimed` step before run.started.
+CREATE TABLE IF NOT EXISTS workers (
+  id text PRIMARY KEY,                                   -- ulid
+  name text NOT NULL UNIQUE,                             -- `runner:<name>` is the actor on its run.* events
+  host text NOT NULL DEFAULT '',
+  lanes text[] NOT NULL DEFAULT '{}',                    -- claude | codex | grok, from the machine's logins
+  labels text[] NOT NULL DEFAULT '{}',                   -- extra capabilities (gpu, xcode, ...) a task may require
+  version text NOT NULL DEFAULT '',                      -- relay CLI version the worker runs
+  last_seen timestamptz NOT NULL DEFAULT now(),
+  status text NOT NULL DEFAULT 'online',                 -- what the worker last said: online | offline
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS claims (
+  id text PRIMARY KEY,                                   -- ulid
+  task_id text NOT NULL REFERENCES tasks(id) ON DELETE CASCADE,
+  worker_id text NOT NULL REFERENCES workers(id) ON DELETE CASCADE,
+  lease_until timestamptz NOT NULL,
+  claimed_at timestamptz NOT NULL DEFAULT now(),
+  released_at timestamptz,
+  outcome text                                           -- finished | failed | released | expired
+);
+-- one live claim per task; a second worker's insert fails instead of racing
+CREATE UNIQUE INDEX IF NOT EXISTS claims_live_task_idx ON claims(task_id) WHERE released_at IS NULL;
+CREATE INDEX IF NOT EXISTS claims_worker_idx ON claims(worker_id, claimed_at DESC);
+
+-- The lane a task was opened with, so the scheduler can match it without folding the feed first.
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS lane text;

package/dist/migrations/008_queue_state.sql

@@ -0,0 +1,13 @@
+-- The doorbell (docs/WORKERS.md, "The loop"): one row whose version moves every time the queue may have changed
+-- (a task opened, a lease released or expired). An idle worker reads it instead of running a claim, and claims only
+-- when the version moved or something is queued, so an empty queue costs the site one cheap query per tick.
+CREATE TABLE IF NOT EXISTS queue_state (
+  one boolean PRIMARY KEY DEFAULT true CHECK (one),  -- exactly one row
+  version bigint NOT NULL DEFAULT 0,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+INSERT INTO queue_state (one, version) VALUES (true, 0) ON CONFLICT DO NOTHING;
+
+-- The poll interval a worker last reported with its heartbeat (ms), so the workers page and `relay work status`
+-- can show how often an idle worker checks in. Null until a worker on this version heartbeats.
+ALTER TABLE workers ADD COLUMN IF NOT EXISTS poll_ms integer;

package/dist/migrations/009_worker_meters.sql

@@ -0,0 +1,5 @@
+-- Plan meters a worker reports with its heartbeat (packages/core/src/meters.ts): the 5-hour and 7-day used
+-- percentages Claude Code hands its status line, saved by relay's status-line script under ~/.harness/meters and sent
+-- along as [{subscription, window, used_percentage, resets_at, captured_at, source}]. Null until a worker on this
+-- version heartbeats; the site shows the freshest reading per window across online and idle workers.
+ALTER TABLE workers ADD COLUMN IF NOT EXISTS meters jsonb;

package/dist/migrations/010_task_state.sql

@@ -0,0 +1,20 @@
+-- Materialized task state (docs/ARCHITECTURE.md, "A task's life"). The feed stays the source of truth: these columns
+-- are a cache of the fold in packages/core/src/db/tasks.ts (deriveTaskStatus) and tasks/station.ts (deriveStation),
+-- written by refreshTaskState (db/task-state.ts) after every write that can change a task (an event with the task's
+-- repo and issue, a claim taken, released or expired, a task created). The flow map and the tasks list read them in
+-- one query instead of folding every task's history on every poll. NULL state means "not computed yet": readers fold
+-- the row and fill it in (backfillTaskState runs once when this migration lands).
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS title text;                      -- the issue title, from the creator or the feed
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS state text;                      -- queued | claimed | running | review | done | failed
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS station text;                    -- Queue | Claimed | Running | PR | Preview | Review | Merged | Failed
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS since timestamptz;               -- when the task entered `station`
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS pr integer;
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS pr_url text;
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS preview_state text;              -- ready | building | failed | none
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS preview_url text;
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS runner text;                     -- runner:<name> of the worker on it
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS last_error text;                 -- the latest run.failed (or failing run.finished) line
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS cost double precision;           -- folded cost_equiv of the task's step.usage rows
+ALTER TABLE tasks ADD COLUMN IF NOT EXISTS state_updated_at timestamptz;    -- when the cache was last written
+CREATE INDEX IF NOT EXISTS tasks_state_idx ON tasks(state);
+CREATE INDEX IF NOT EXISTS tasks_station_idx ON tasks(station);