viewable-one 0.0.0-stage → 0.12.2

package/lib/authenticatedHttp.mjs

@@ -0,0 +1,75 @@
+// Shared authenticated JSON transport for the MCP and runner endpoints.
+// The deadline covers token refresh and response-body consumption, not just
+// receiving headers. A stalled endpoint must not wedge runner settlement.
+import { REAUTH_REQUIRED_HINT, hostedToken, noteCredentialRejected, reauthRequired } from './auth.mjs';
+
+export const NOT_SIGNED_IN_HINT =
+  'Not signed in to the hosted board. Run `viewable login`, or for a script set ' +
+  'VIEWABLE_BOARD_TOKEN to a personal access token minted in Viewable ' +
+  '(Settings, Connection, Access tokens).';
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+
+export async function authenticatedJsonPost(url, body, options = {}) {
+  const { env = process.env, fetchImpl = fetch, forceRefresh = false, headers = {}, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS, signal } = options;
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error('Request timeout must be a positive number.');
+  const controller = new AbortController();
+  let timer;
+  let onAbort;
+  const deadline = new Promise((_, reject) => {
+    onAbort = () => {
+      controller.abort(signal.reason);
+      reject(signal.reason);
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    if (signal?.aborted) onAbort();
+    timer = setTimeout(() => {
+      const error = new Error(`Request timed out after ${timeoutMs}ms`);
+      controller.abort(error);
+      reject(error);
+    }, timeoutMs);
+  });
+  const boundedFetch = (target, init = {}) => {
+    if (controller.signal.aborted) {
+      // Only this pre-dispatch boundary can prove a rotating token was not sent.
+      throw Object.assign(new Error('Request canceled before fetch.'), { requestNotSent: true });
+    }
+    return fetchImpl(target, { ...init, signal: init.signal ? AbortSignal.any([init.signal, controller.signal]) : controller.signal });
+  };
+  const post = async bearer => {
+    const response = await boundedFetch(url, {
+      method: 'POST',
+      headers: { ...headers, Authorization: `Bearer ${bearer}`, 'Content-Type': 'application/json', Accept: 'application/json' },
+      body: JSON.stringify(body),
+    });
+    const text = await response.text();
+    let payload = null;
+    try { payload = JSON.parse(text); } catch { /* Callers report their protocol's malformed-response error. */ }
+    return { response, text, payload };
+  };
+  const execute = async () => {
+    controller.signal.throwIfAborted();
+    // The shared refresh owns its finite deadline. This caller only stops
+    // waiting; it must not cancel another caller's rotating-token exchange.
+    const token = await hostedToken({ env, fetchImpl, forceRefresh });
+    controller.signal.throwIfAborted();
+    if (!token) return { authError: await reauthRequired(env) ? REAUTH_REQUIRED_HINT : NOT_SIGNED_IN_HINT };
+    let result = await post(token);
+    let lastBearer = token;
+    if (result.response.status === 401 && !forceRefresh) {
+      controller.signal.throwIfAborted();
+      const refreshed = await hostedToken({ env, fetchImpl, forceRefresh: true });
+      controller.signal.throwIfAborted();
+      if (refreshed && refreshed !== token) {
+        // A failed retry is a transport failure, not proof that the fresh
+        // credential was rejected. Never mark it dead based on the old 401.
+        result = await post(refreshed);
+        lastBearer = refreshed;
+      }
+    }
+    controller.signal.throwIfAborted();
+    if (result.response.status === 401) await noteCredentialRejected({ env, token: lastBearer });
+    return result;
+  };
+  try { return await Promise.race([execute(), deadline]); }
+  finally { clearTimeout(timer); signal?.removeEventListener('abort', onAbort); }
+}

package/lib/boardside.mjs

@@ -0,0 +1,225 @@
+// TELLING THE BOARD ABOUT A SESSION, over rows (brief 30 Move 2, 2026-09-11).
+//
+// What is NOT retired: telling the board what happened WHILE a session runs
+// or after it ends - a note on the run's own idea, and a question note when
+// something needs a human ruling (a failed merge). Those still go through
+// the SAME board API vocabulary (INBOX_OPS.md's `addComment`/`addQuestion`),
+// just over `hosted.callTool`'s `propose`/`ask_user` instead of an ops file,
+// under the run's own session key (`X-Glytch-Session`) so they read as this
+// run's own words rather than the runner's OAuth identity.
+//
+// `askedAndNeverReported`/`silenceNote` are gone, and that is a real
+// loss rather than a rename: they read `inbox/ops/*.json` (via
+// opsFilesForKey) and `inbox/tell/*.json` (via tellFilesForKey) to notice a
+// session that asked questions, got them answered, and then reported
+// nothing - "Why it didnt output anything?!". Move 2's contract has no rows
+// op that lists a session's own board writes (the closest, `collect_session`,
+// answers "what came back", not "what did this session ask"), so there is
+// nothing this file can read to reconstruct that account any more. Flagged
+// as a deviation rather than silently dropped; a rows-based equivalent needs
+// its own op (e.g. a `session_asks` view) and is not in this contract.
+
+import { classifyExit } from "./exitClass.mjs";
+import { callTool as hostedCallTool } from "./hosted.mjs";
+
+/** The verdict, in words. The default set is the receipt's own (`finished` /
+ * `ended with an error result` / `killed at wall clock` / `exited N`): the app
+ * parses it out of the row's `result`, and acp.test.mjs and codex.test.mjs pin
+ * it, so it never changes. `card` is the person-facing word for the one reply
+ * the bridge files, which is only ever a clean finish: "Finished". Every other
+ * ending is written by the app from the row. */
+function verdictWord(outcome, { card = false } = {}) {
+  if (card) return "Finished";
+  if (outcome.finished && !outcome.finishedWithError) return "finished";
+  if (outcome.finishedWithError) return "ended with an error result";
+  if (outcome.stalled) return "stopped responding";
+  if (outcome.timedOut) return "killed at wall clock";
+  if (outcome.code !== undefined) {
+    const cls = classifyExit(outcome.code, outcome.signal);
+    return cls.isCrash ? cls.description : outcome.signal ? `ended on ${outcome.signal}` : `exited ${outcome.code}`;
+  }
+  return "ended";
+}
+
+/** The figures an envelope carries: turns, duration, and (receipt only)
+ * how full the context got. Neither carries a price: the app never shows
+ * what a session cost (#151, #281); the cost stays in the sidecar for the
+ * ledger. `card` keeps only the duration: the card says "Took 4 minutes"
+ * (#470, #735), and turns and context are developer counts. */
+function figuresOf(outcome, { card = false } = {}) {
+  const env = outcome.envelope;
+  const figures = [];
+  if (!card && env?.num_turns !== undefined) {
+    figures.push(`${env.num_turns} turn${env.num_turns === 1 ? "" : "s"}`);
+  }
+  if (env?.duration_ms !== undefined) {
+    // Under a minute in seconds, rounded up (QA 2026-10-01, e4): a 27 s
+    // Codex run read "0m".
+    const ms = Number(env.duration_ms);
+    figures.push(ms < 60_000 ? `${Math.max(1, Math.ceil(ms / 1000))}s` : `${Math.round(ms / 60_000)}m`);
+  }
+  if (!card && outcome.contextFill) {
+    const k = Math.round(outcome.contextFill / 1000);
+    figures.push(`context ${k}k`);
+  }
+  return figures;
+}
+
+/** Format the verdict line from the envelope and outcome, then the figures:
+ * "finished; 41 turns, 38m, context 212k". The receipt reads it as it
+ * is; `{card: true}` gives the person-facing words (see `verdictWord`).
+ * It reads only `outcome`, never the board. */
+export function formatVerdict(outcome, options = {}) {
+  const figures = figuresOf(outcome, options);
+  const verdict = verdictWord(outcome, options);
+  return figures.length > 0 ? `${verdict}; ${figures.join(", ")}` : verdict;
+}
+
+/** The idea whose run this is: the FIRST id on the request, because a
+ * selection of several ideas files one request and a run belongs to one
+ * idea. Absent for a CLI request, which has no idea behind it.
+ * Unchanged from the file-based runner. */
+export function fromIdOf(request) {
+  const ids = request?.nodeIds;
+  return Array.isArray(ids) && ids.length > 0 ? String(ids[0]) : undefined;
+}
+
+/** One `propose` call, `ops` in the INBOX_OPS.md vocabulary, under the run's
+ * own session key. Never throws: a board write that fails is logged by the
+ * caller and must not take a session down - the run's own receipt (the row
+ * itself) is the durable record either way. */
+async function proposeOnBoard(session, ops, label, { callTool = hostedCallTool, env } = {}) {
+  const outcome = await callTool("propose", { ops, label }, { sessionKey: session.key, env });
+  return { ok: !outcome.isError, detail: outcome.text };
+}
+
+/** A note on the idea a session's run belongs to - the idea named
+ * by `frameId` (the run's `from_id`, carried since brief 26 retired the
+ * session frame). ROWS VERSION: `propose({ops:[{call:"addComment", ...}]})`
+ * instead of an ops file; same reasoning as ever for why this is a COMMENT
+ * and not a `report` - it cannot clobber whatever the session itself said
+ * with `report()`, where a second report keyed to the same session would.
+ *
+ * `options.fields` rides beside `id` and `text` on the op (brief 52: agentId,
+ * runId, summary, images and the links). Absent, the op is the two-field one
+ * it has always been. */
+export async function commentOnAnchor(session, frameId, text, options = {}) {
+  if (!frameId) return null;
+  const { fields, ...rest } = options;
+  const result = await proposeOnBoard(
+    session,
+    [{ call: "addComment", args: { id: frameId, text, ...(fields ?? {}) } }],
+    `Session ${session.key} outcome`,
+    rest,
+  );
+  return result.ok ? result.detail : null;
+}
+
+/** A question through `ask_user`, under the run's own session key. It lands as
+ * a question note on the idea named by `fromId` (the run's own idea), not as a
+ * circle of its own. Used for the one case the runner itself ever asks
+ * anything: a failed merge. Returns the question NOTE id parsed out of
+ * `ask_user`'s reply text (`pending (question_id: <noteId>)`), or null when the call failed or the id could not
+ * be found in the reply. */
+export async function askUserOnBoard(session, question, { why, fromId, options: choices, recommendation, images, purpose } = {}, options = {}) {
+  const outcome = await (options.callTool ?? hostedCallTool)(
+    "ask_user",
+    { question, why, ...(fromId ? { from_id: fromId } : {}), ...(choices ? { options: choices } : {}), ...(recommendation ? { recommendation } : {}), ...(images?.length > 0 ? { images } : {}), ...(purpose ? { purpose } : {}) },
+    { sessionKey: session.key, env: options.env },
+  );
+  if (outcome.isError) return { ok: false, detail: outcome.text };
+  const match = /question_id:\s*(\S+)\)/.exec(outcome.text ?? "");
+  return { ok: true, questionId: match?.[1] ?? null, detail: outcome.text };
+}
+
+// THE ONE REPLY AT THE END (brief 52, ruling 4 and 5.5). A session used to
+// leave an outcome comment of verdict lines beside whatever it said itself.
+// Now it leaves one reply on its idea: the engine's closing words first, then
+// one line of figures. The hosted `addComment` on an idea lands it as a
+// `reply` note carrying the agent, the run, a caption and the links.
+
+/** The closing words, capped at 2,000 characters with the END kept: the part
+ * of a long answer a person needs is the part that says where it landed. */
+export const CLOSING_TEXT_CAP = 2000;
+export function closingTextOf(outcome) {
+  const raw = typeof outcome.envelope?.result === "string" ? outcome.envelope.result.trim() : "";
+  return raw.length > CLOSING_TEXT_CAP ? `…${raw.slice(raw.length - (CLOSING_TEXT_CAP - 1)).trimStart()}` : raw;
+}
+
+/** The first sentence of the closing words, for the circle's caption. */
+export function firstSentenceOf(text) {
+  const clean = String(text ?? "").replace(/^[\s#>*_-]+/, "");
+  const line = clean.split("\n")[0].trim();
+  const stop = /[.!?](\s|$)/.exec(line);
+  const sentence = (stop ? line.slice(0, stop.index + 1) : line).trim();
+  return sentence.length > 160 ? `${sentence.slice(0, 159).trimEnd()}…` : sentence;
+}
+
+/** Did this run finish cleanly, so that the bridge files its closing reply?
+ * The app writes the ending for everything else (a stop, a session that died,
+ * a timeout, a binary that would not start) from the row. */
+export function finishedCleanly(outcome, { stopped = false } = {}) {
+  if (stopped || outcome.spawnError) return false;
+  if (outcome.finishedWithError || outcome.stalled || outcome.timedOut && !outcome.finished) return false;
+  return (outcome.finished === true || outcome.code === 0) && outcome.ok !== false;
+}
+
+/** The sentence a run that worked in a non-git folder itself and changed
+ *  files there ends with (#483): no copy was made, so Throw away is not
+ *  offered and the reply says why. Kept word for word with the issue. */
+export const IN_PLACE_NOTICE = "This ran in your folder itself, so Throw away cannot undo it.";
+
+/** The reply's text and caption for a run that finished. Pure.
+ *
+ * The closing words first (capped, the end kept), then ONE line led by
+ * "Finished" that carries only how long it took: "Finished; 4m". The card
+ * footer reads "Took 4 minutes" (#470, #735); turns, the branch and the file
+ * count are developer words and stay on the session screen.
+ * A run with no closing words still says it finished. */
+export function composeReply(outcome, { inPlace } = {}) {
+  const said = closingTextOf(outcome);
+  const closing = inPlace ? [said, IN_PLACE_NOTICE].filter(Boolean).join("\n\n") : said;
+  const figures = figuresOf(outcome, { card: true });
+  const verdict = verdictWord(outcome, { card: true });
+  const line = figures.length > 0 ? `${verdict}; ${figures.join(", ")}` : verdict;
+  return {
+    text: closing ? `${closing}\n\n${line}` : line,
+    summary: closing ? firstSentenceOf(closing) || undefined : undefined,
+  };
+}
+
+/** File the run's ONE closing reply on its own idea, and only when the run
+ * finished (`finishedCleanly`). The caller (runnerCompletion.mjs) flips the
+ * run row to its ending status with `runnerApi.update`; this only posts the
+ * reply, so a run with no idea behind it (`frameId` null) still gets its row
+ * updated although nothing is drawn. Every other ending writes nothing here:
+ * the app reads the row and writes it.
+ *
+ * `options`: `{callTool, env}` plus the run's own facts - `request` (its
+ * agentId), `stopped`, `worktree` ({branch, files} of the copy it made),
+ * `inPlace` (it changed files in a non-git folder itself, #483), `preview` (the dev
+ * server's address), `report` (a report frame's id) and `images` (pictures to
+ * show under the reply). Every one is optional. */
+export async function reportOutcomeOnBoard(session, outcome, frameId, options = {}) {
+  if (!frameId) return null;
+  const { request, stopped, worktree, inPlace, preview, report, images, agentId, ...rest } = options;
+  if (!finishedCleanly(outcome, { stopped })) return null;
+  const { text, summary } = composeReply(outcome, { inPlace });
+  const who = typeof agentId === "string" && agentId.trim() !== "" ? agentId.trim()
+    : typeof request?.agentId === "string" && request.agentId.trim() !== "" ? request.agentId.trim() : undefined;
+  const fields = {
+    ...(outcome.result ? { result: outcome.result } : {}),
+    ...(who ? { agentId: who } : {}),
+    runId: session.key,
+    ...(summary ? { summary } : {}),
+    ...(Array.isArray(images) && images.length > 0 ? { images: images.slice(0, 6) } : {}),
+    ...(worktree?.branch ? { branch: worktree.branch } : {}),
+    ...(Number.isInteger(worktree?.files) ? { files: worktree.files } : {}),
+    ...(typeof preview === "string" && preview !== "" ? { preview } : {}),
+    ...(typeof report === "string" && report !== "" ? { report } : {}),
+  };
+  // The plain line when a screen changed but no pictures could be taken (#2194).
+  const lines = [text, outcome.result?.fixAttempted && "Coding tried one fix.", outcome.picturesNote].filter(Boolean);
+  const closing = lines.join("\n\n");
+  return commentOnAnchor(session, frameId, closing, { ...rest, fields });
+}