viewable-one 0.0.0-stage → 0.12.1

package/lib/runnerAdmission.mjs

@@ -0,0 +1,35 @@
+/** Admission requires durable completion delivery and a free slot. */
+import { randomUUID } from "node:crypto";
+import { acquireAdmission } from "./admission.mjs";
+import { flushCompletions } from "./runnerSettlement.mjs";
+import * as runnerApiModule from "./runnerApi.mjs";
+
+const retryHint = (out) => (Number.isFinite(out.retryAfterMs) ? { retryAfterMs: out.retryAfterMs } : {});
+
+export async function claimOne(root, project, settings) {
+  const runnerApi = settings.runnerApi ?? runnerApiModule;
+  const rowsOpts = { env: settings.env, fetchImpl: settings.fetchImpl };
+  const admission = await acquireAdmission(root);
+  if (!admission.ok) return { claimed: false, detail: admission.detail };
+  try {
+    // `transient` (ticket e8): the claim loop backs off on these. A saved
+    // completion that will not sync is almost always the server failing, and
+    // claiming is blocked until it lands either way.
+    if (!(await flushCompletions(project, settings))) return { claimed: false, transient: true, detail: "Saved completions are waiting to sync." };
+    // With no limit on how many run at once (the default) the count can never
+    // refuse, so it is not asked for: one call fewer per pass (#616).
+    if (Number.isFinite(settings.maxConcurrent)) {
+      const listed = await runnerApi.runs({ projectIds: [project.id], status: "running" }, rowsOpts);
+      if (!listed.ok) return { claimed: false, transient: listed.transient === true, ...retryHint(listed), detail: `Cannot verify running sessions: ${listed.error}` };
+      const running = (listed.runs ?? []).length;
+      if (running >= settings.maxConcurrent) return { claimed: false, detail: `${running} session(s) already running, and up to ${settings.maxConcurrent} run at once` };
+    }
+    const claimed = await runnerApi.claim({ projectIds: [project.id], runnerInstanceId: settings.runnerInstanceId ??= randomUUID() }, rowsOpts);
+    if (!claimed.ok) return { claimed: false, transient: claimed.transient === true, ...retryHint(claimed), detail: claimed.error };
+    if (!claimed.run) return { claimed: false, idle: true, detail: "nothing pending" };
+    return { claimed: true, run: claimed.run };
+  } finally {
+    await admission.release();
+  }
+}
+

package/lib/runnerApi.mjs

@@ -0,0 +1,312 @@
+// THE ROWS CLIENT (brief 30, Move 2, 2026-09-11). Every `.glytch/` file the
+// runner used to read or write becomes a row, reached over ONE Edge Function,
+// `supabase/functions/board-runner/` - built in parallel against the same
+// contract (brief 30, "Move 2 contract").
+// This file is the bridge's whole half of that wire: one function per op,
+// same bearer resolution as everything else in this package
+// (lib/auth.mjs's hostedToken - a `glytch login` credential, or
+// VIEWABLE_BOARD_TOKEN for a script), never PostgREST directly, because
+// neither a `pmb_` nor a `pmo_` token is a Supabase JWT.
+//
+// THE FUNCTION DOES NOT EXIST YET when this file was written - another
+// worker builds `supabase/functions/board-runner/` against the same
+// contract, in parallel. This file is written against the CONTRACT, and its
+// own tests stub the HTTP layer (`fetchImpl`) rather than talking to
+// anything real, exactly the way lib/hosted.mjs's tests already do for
+// board-mcp.
+//
+// URL RESOLUTION mirrors hostedConfig: `GLYTCH_RUNNER_URL` overrides
+// everything (a local dev deploy, a staging function under a different
+// path); otherwise it is `${appUrl}/functions/v1/board-runner`, derived from
+// the same stored `appUrl` (or `GLYTCH_APP_URL`/the production default)
+// hostedConfig already resolves for the MCP endpoint - one app origin, two
+// functions under it.
+//
+// WHY ONE call() AND NOT ONE FETCH PER OP: every op answers the same
+// envelope (`{ok:true, ...}` / `{ok:false, error}`), needs the same bearer,
+// and gets the same one-retry-after-forced-refresh treatment a token aging
+// out mid-run already gets in lib/hosted.mjs's callTool - a spawned run can
+// sit inside this contract for up to two hours (spawn.mjs's MAX_WALL_MS), so
+// an access token expiring partway through a run must not read as a hard
+// failure the first time it happens.
+
+import { DEFAULT_APP_URL, hostedConfig } from "./auth.mjs";
+import { RETIRED_APP_URLS } from "./retired-address.mjs";
+import { authenticatedJsonPost } from "./authenticatedHttp.mjs";
+export { NOT_SIGNED_IN_HINT } from "./authenticatedHttp.mjs";
+
+/** The hosted project's own address for `board-runner` (#813, report #795
+ *  option a). The production app proxies `/functions/v1/` through its
+ *  Worker; the runner calls the function directly instead, so its traffic
+ *  never meets the Worker's rate limit. The bearer is unchanged: the function
+ *  checks a token's resource against its own configured issuer, not against
+ *  the host the request arrived on. */
+export const HOSTED_RUNNER_URL = "https://edqgfvgbxmfvfahlofqd.supabase.co/functions/v1/board-runner";
+
+/** Where the runner's own function lives: `GLYTCH_RUNNER_URL` wins outright
+ *  (a local dev deploy, a staging function at a different path); the
+ *  production app goes straight to the hosted project; any other app origin
+ *  (a local stack) uses its own `board-runner` function, derived from the same
+ *  `appUrl` the MCP endpoint's URL comes from. */
+export function runnerApiUrlFrom(appUrl, env = process.env) {
+  const explicit = typeof (env.VIEWABLE_RUNNER_URL ?? env.GLYTCH_RUNNER_URL) === "string" ? (env.VIEWABLE_RUNNER_URL ?? env.GLYTCH_RUNNER_URL).trim() : "";
+  if (explicit !== "") return explicit;
+  if (appUrl === DEFAULT_APP_URL || RETIRED_APP_URLS.includes(appUrl)) return HOSTED_RUNNER_URL;
+  return `${appUrl}/functions/v1/board-runner`;
+}
+
+/** Turn whatever an error-shaped field carries into a string worth showing a
+ *  person, never `[object Object]` (2026-09-21: seen all night in
+ *  runner.log as `board-runner answered 502: [object Object]`, because a
+ *  Supabase gateway error can put an OBJECT where this package always
+ *  expected a string). A string passes through unchanged; an object hands
+ *  back its own `.message` when that is a string (the shape a Supabase
+ *  gateway error carries), else the object itself, stringified and capped at
+ *  400 characters like every other piece of raw response text this file
+ *  reports. `undefined`/`null` stay `undefined`, so a caller can still fall
+ *  through to the next candidate. */
+function errorDetail(value) {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object") {
+    if (typeof value.message === "string") return value.message;
+    try {
+      return JSON.stringify(value).slice(0, 400);
+    } catch {
+      return String(value);
+    }
+  }
+  return undefined;
+}
+
+/** How long a 429 or 503 asks us to wait, in ms, from its `Retry-After`
+ *  header (seconds or an HTTP date). undefined when absent or unreadable.
+ *  The runner sleeps at least this long before its next call (#616). */
+export function retryAfterMs(value, now = Date.now()) {
+  if (typeof value !== "string" || value.trim() === "") return undefined;
+  const seconds = Number(value.trim());
+  if (Number.isFinite(seconds)) return seconds >= 0 ? seconds * 1000 : undefined;
+  const at = Date.parse(value);
+  return Number.isFinite(at) ? Math.max(0, at - now) : undefined;
+}
+
+/** Cloudflare's Ray ID for a failed call: the `cf-ray` header, or the
+ *  "Ray ID: ..." line on its own HTML error page. It is what Cloudflare asks
+ *  for when a rate limit or block needs looking into (#616). */
+export function cloudflareRayId(headers, text) {
+  const header = headers?.get?.("cf-ray");
+  if (typeof header === "string" && header.trim() !== "") return header.trim();
+  const match = typeof text === "string" ? text.match(/Ray ID:?\s*(?:<[^>]*>\s*)*([0-9a-f]{16})/i) : null;
+  return match ? match[1] : undefined;
+}
+
+const looksLikeHtml = (text) => typeof text === "string" && /^\s*<(?:!doctype|html)/i.test(text);
+
+/** One call to the board-runner function. Never throws on a network or HTTP
+ *  failure - every caller gets `{ok:false, error}` back and decides for
+ *  itself whether that is worth logging, retrying on the next poll, or
+ *  surfacing on a receipt. `op` and the rest of `body` are sent flat, per the
+ *  contract's `{op, ...}` shape. */
+async function call(op, body = {}, options = {}) {
+  const { env = process.env } = options;
+  const { appUrl } = await hostedConfig({ env });
+  const url = runnerApiUrlFrom(appUrl, env);
+  let result;
+  try {
+    result = await authenticatedJsonPost(url, { op, ...body }, options);
+  } catch (error) {
+    // "fetch failed" alone says nothing; undici puts the reason (ENOTFOUND,
+    // ECONNRESET, a TLS code) on `cause` (QA 2026-10-01, e8).
+    const cause = error?.cause?.code ?? error?.cause?.message;
+    // `transient` marks the failures the runner backs off on (ticket e8,
+    // lib/runnerPace.mjs): a network failure or timeout here, a 5xx or 429
+    // below. A 401 and every refusal leave it unset.
+    return { ok: false, transient: true, error: `Could not reach ${url}: ${error instanceof Error ? error.message : String(error)}${cause ? ` (${cause})` : ""}` };
+  }
+  if (result.authError) return { ok: false, error: result.authError };
+
+  const { response, text, payload } = result;
+  if (!response.ok) {
+    // A CLOUDFLARE PAGE (#616): a rate limit answers 429 with a whole HTML
+    // page, not JSON. Four hundred characters of markup told nobody
+    // anything; say what it is and keep the Ray ID, which is what Cloudflare
+    // needs to look the block up.
+    const rayId = cloudflareRayId(response.headers, text);
+    const html = !payload && looksLikeHtml(text);
+    const detail = errorDetail(payload?.error) ?? errorDetail(payload?.message)
+      ?? (html ? (response.status === 429 ? "Cloudflare rate limited this computer" : "Cloudflare answered with an error page") : text.slice(0, 400));
+    // THE REQUEST ID (QA 2026-10-01, e8): ten 500s overnight read "Could not
+    // check that token" and nothing else. The id finds the call in the
+    // function's own logs, where board-runner now writes the cause.
+    const requestId = response.headers?.get?.("sb-request-id");
+    const transient = response.status >= 500 || response.status === 429;
+    const wait = transient ? retryAfterMs(response.headers?.get?.("retry-after")) : undefined;
+    const ids = [requestId ? `request ${requestId}` : "", rayId ? `Ray ID ${rayId}` : ""].filter(Boolean).join(", ");
+    return {
+      ok: false,
+      ...(transient ? { transient: true } : {}),
+      ...(wait !== undefined ? { retryAfterMs: wait } : {}),
+      error:
+        response.status === 401
+          ? `${detail || "Unauthorized."} Sign in again with \`viewable login\`, or mint a new personal access token and set VIEWABLE_BOARD_TOKEN.`
+          : `board-runner answered ${response.status}${detail ? `: ${detail}` : ""}${ids ? ` (${ids})` : ""}${wait !== undefined ? `; retry after ${Math.ceil(wait / 1000)}s` : ""}`,
+    };
+  }
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return { ok: false, error: `board-runner answered with unreadable JSON: ${text.slice(0, 400)}` };
+  }
+  if (payload.ok === false) {
+    return { ok: false, error: errorDetail(payload.error) ?? "board-runner refused the request." };
+  }
+  if (payload.ok !== true) return { ok: false, error: "board-runner returned an incomplete response." };
+  return payload;
+}
+
+// ---------- one function per op, per the Move 2 contract ----------
+
+/** `register {runnerId, host, platform, presence, projects:[{path, name?}]}`
+ *  -> `{projects:[{id, path, name}]}`. Upserts `runner_projects` on
+ *  `(user, host, path)` and bumps `last_seen_at`. Called on start and every
+ *  beat with EVERY folder this machine knows about (`~/.glytch/folders.json`),
+ *  not only the folder a particular watch loop is polling - the upsert is
+ *  idempotent, so two runner processes registering the same folder twice
+ *  costs nothing. */
+export function register({ runnerId, host, platform, presence, projects }, options = {}) {
+  return call("register", { runnerId, host, platform, presence, projects }, options);
+}
+
+/** `heartbeat {projectIds, presence?}` -> `{stops:[runId...], ops:[...]}`.
+ *  One call per tick covers presence (bumps `last_seen_at` on those project
+ *  rows), stop signals for every running run on them, and op signals
+ *  (untaken `run_ops` rows) - replacing `.runner.json`'s beat, `<id>.stop`,
+ *  and the merge/delete/relaunch/preview signal files all at once. */
+export function heartbeat({ projectIds, presence, runnerInstanceId, activeRunIds } = {}, options = {}) {
+  return call("heartbeat", { projectIds, ...(presence !== undefined ? { presence } : {}), ...(runnerInstanceId !== undefined ? { runnerInstanceId } : {}), ...(activeRunIds !== undefined ? { activeRunIds } : {}) }, options);
+}
+
+/** `claim {projectIds}` -> `{run}` or `{run:null}`. The oldest approved,
+ *  unclaimed, pending run on those projects, claimed atomically - replaces
+ *  `listRequests`/`claimRequest`'s exclusive-create-on-disk race. `run.request`
+ *  is the SpawnRequest a file used to carry; `run.project_id` names which
+ *  registered project (and therefore which root) it belongs to. */
+export function claim({ projectIds, runnerInstanceId }, options = {}) {
+  return call("claim", { projectIds, ...(runnerInstanceId !== undefined ? { runnerInstanceId } : {}) }, options);
+}
+
+/** `update {runId, patch}` -> ok, or `{ok:false, error:"result already
+ *  written"}` when `patch.result` collides with the write-once rule. `patch`
+ *  may carry `status`, `sidecar`, `server`, `finished_at`, `result` - this
+ *  is the one call that replaces `<id>.session.json`, `<id>.server`, and
+ *  `<id>.result.txt` all at once, plus the `startSession`/`endSession` ops
+ *  files: the run row IS the start/end stamp now. */
+export function update({ runId, patch }, options = {}) {
+  return call("update", { runId, patch }, options);
+}
+
+/** `events {runId, events:[{seq, kind, text}]}` -> insert, duplicates on
+ *  `(run_id, seq)` ignored. Replaces the runner's own append-to-`<id>.log`
+ *  streaming; `kind` is `"log"` or `"cut"` (an elision marker), matching
+ *  `run_events.kind`'s check constraint. */
+export function events({ runId, events }, options = {}) {
+  return call("events", { runId, events }, options);
+}
+
+/** `opTake {opId}` -> `{op}` or `{op:null}`. Sets `taken_at` if it was null
+ *  and hands back the op row (or null if someone else already took it, or
+ *  it does not exist/is not this user's) - the row equivalent of consuming a
+ *  `.merge`/`.delete`/`.relaunch` signal file, or a preview request. */
+export function opTake({ opId }, options = {}) {
+  return call("opTake", { opId }, options);
+}
+
+/** `opResult {opId, result}` -> ok. merge/delete/relaunch write-once;
+ *  preview is updatable (its lifecycle ticks through starting/ready/offline/
+ *  error on one op row rather than one receipt file per state). */
+export function opResult({ opId, result }, options = {}) {
+  return call("opResult", { opId, result }, options);
+}
+
+/** `runs {projectIds, status?}` -> a list, for maintenance: the sweep's
+ *  equivalent of scanning `inbox/spawn/` for finished ids, and late
+ *  promotion's equivalent of finding a session's own row to resume. */
+export function runs({ projectIds, status } = {}, options = {}) {
+  return call("runs", { projectIds, ...(status !== undefined ? { status } : {}) }, options);
+}
+
+/** `resume {runId, message, images?}` -> inserts an APPROVED child run row
+ *  copying the parent's request with `resumeSessionId` set, and returns its
+ *  id. This is Move 2's replacement for `promoteReplyToRequest`/
+ *  `promoteLateReplies` filing a new request FILE that resumes a session:
+ *  the runner cannot call the app's `run_request` RPC directly (it holds no
+ *  Supabase JWT), so this one op does the whole thing server-side under the
+ *  service role, the same way `claim` and `update` already do. Added to the
+ *  contract here, dated, because a bare `promoteReplyToRequest`-shaped call
+ *  would otherwise have no row-side equivalent to land on; see the brief's
+ *  "Move 2 contract" section, amended 2026-09-11, for the twin of this
+ *  comment on the function side.
+ *
+ *  `images` (item 6, brief 30 Move 2b, same date): a late message's images,
+ *  the same shape a reply file's `images` array carried, sent when the
+ *  caller has any (`rowsAnswers.mjs`'s `promoteLateRows`). The op does not
+ *  declare this field yet on its own side (its header says why:
+ *  `session_messages` gaining an `images` column, and `collect_session`
+ *  exposing it, are another worker's change, not landed on this branch) -
+ *  sent anyway, because an unrecognised field in a POST body a Deno
+ *  function does not destructure is simply absent from `body` there, never
+ *  a hard failure; the day that worker's change lands, this call needs no
+ *  edit to start actually delivering pictures. */
+export function resume({ runId, message, images, unlessStopped }, options = {}) {
+  return call("resume", { runId, message, ...(images?.length > 0 ? { images } : {}), ...(unlessStopped ? { unlessStopped: true } : {}) }, options);
+}
+
+/** `presence {paths?}` -> `{projects:[{id, path, host, runner_id,
+ *  last_seen_at}]}`. Read-only, added 2026-09-12 (brief 31, "doctor asks the
+ *  board"): the one caller today is `lib/doctor.mjs`'s "daemon beating" row,
+ *  which used to read a local mark file (`.glytch/inbox/spawn/.runner.json`)
+ *  that nothing over rows has written since `register`/`heartbeat` replaced
+ *  it - `runner_projects.last_seen_at` is the truth now, and this is the
+ *  only op that reads it back to a caller. `paths`, when given, narrows the
+ *  result to those folders instead of every project this account has ever
+ *  registered on any machine.
+ *
+ *  It also answers `account:{id, email?}` since 2026-09-14 - WHICH account
+ *  this bearer actually reaches, as the endpoint that resolved the token
+ *  sees it. A credential left behind on a previous account looks identical
+ *  to one on the right account from this side of the wire, which is how two
+ *  days of session reports landed on a board nobody was watching. See the
+ *  block over `accountOf` in supabase/functions/board-runner/runner.mjs; the
+ *  reader is `lib/doctor.mjs`'s "board sign-in" row, which now says who. */
+export function presence({ paths } = {}, options = {}) {
+  return call("presence", { ...(paths !== undefined ? { paths } : {}) }, options);
+}
+
+/** `forget {projectIds}` -> `{deleted:[id...], kept:[id...]}`. THE DAEMON'S
+ *  ACKNOWLEDGEMENT, added 2026-09-12 (ruling 3 on the Project panel's
+ *  picker: "removing must be END TO END, not just hiding the row").
+ *
+ *  A person clicks Remove in the app, which raises `forgotten_at` on the row
+ *  through its own RPC; the next `heartbeat` hands this daemon a
+ *  `{kind:"forget", project_id, payload:{path}}` op; the daemon drops that
+ *  folder from `~/.glytch/folders.json` (lib/registry.mjs's `removeFolder`,
+ *  which is also what makes multiwatch stop its watcher on the next registry
+ *  read) and then calls this, and the row goes for good.
+ *
+ *  It is the ONLY op here that ends something rather than recording it, and
+ *  the server will not act on a project the app has not already flagged - so
+ *  a daemon cannot forget a folder nobody asked it to, and this call is safe
+ *  to retry: a second one simply finds nothing pending. */
+export function forget({ projectIds }, options = {}) {
+  return call("forget", { projectIds }, options);
+}
+
+/** `realtime {}` -> `{url, anonKey, topic, expiresAt, renewAt}` (#811, #813).
+ *  The project's public address and key, and this account's private topic,
+ *  live until `expiresAt`. From `renewAt` the same ask hands out the next
+ *  topic. An older function answers "Unknown op", and the runner keeps its
+ *  10 s beat (lib/runnerRealtime.mjs). */
+export function realtime(options = {}) {
+  return call("realtime", {}, options);
+}
+
+/** Names-only discovery, requested by the person in Settings (#1132). */
+export function computerAppsTake(body, options = {}) { return call("computerAppsTake", body, options); }
+export function computerAppsResult(body, options = {}) { return call("computerAppsResult", body, options); }