@ravefox/space 0.0.0-stage → 0.2.0

package/src/lib/api.js

@@ -0,0 +1,205 @@
+/**
+ * CAP HTTP client — thin wrapper over fetch.
+ *
+ * Every method reads the active instance URL and token from config
+ * unless overridden. This is the only place that makes HTTP calls.
+ */
+
+import { resolveInstanceUrl, getToken, resolveInstance } from './config.js';
+import { CLI } from './cli-hint.js';
+
+const headers = (token, extra = {}) => ({
+  'Content-Type': 'application/json',
+  ...(token ? { Authorization: `Bearer ${token}` } : {}),
+  ...extra,
+});
+
+const knownSessionFailure = (body) => [body?.msg, body?.error, body?.message]
+  .some((value) => ['Token is not valid', 'Invalid API token', 'Account no longer exists'].includes(value));
+
+export const sessionExpiredMessage = ({ instanceKey, baseUrl }) => (
+  `Session for ${instanceKey} (${baseUrl}) has expired.\nRun: ${CLI} login --instance ${instanceKey}`
+);
+
+// A non-JSON error body is usually an edge proxy's HTML page; a Cloudflare
+// tunnel error is ~120 lines, and the message used to be all of them, so every
+// failed poll dumped a whole page into the agent log. The message names the
+// page by its <title>; err.body keeps the full text for callers that classify it.
+const MAX_TEXT_ERROR = 300;
+const summarizeTextError = (text, status) => {
+  const trimmed = String(text || '').trim();
+  if (!trimmed) return null;
+  if (/^<(?:!doctype|html)/i.test(trimmed) || /<html[\s>]/i.test(trimmed)) {
+    const title = trimmed.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1]?.replace(/\s+/g, ' ').trim();
+    return title ? `HTTP ${status}: ${title}` : `HTTP ${status} (HTML error page)`;
+  }
+  const line = trimmed.replace(/\s+/g, ' ');
+  return line.length > MAX_TEXT_ERROR ? `${line.slice(0, MAX_TEXT_ERROR)}…` : line;
+};
+
+const handleResponse = async (res, session = null) => {
+  const text = await res.text();
+  let body;
+  let isJson = true;
+  try { body = JSON.parse(text); } catch { body = { message: text }; isJson = false; }
+  if (!res.ok) {
+    const serverMessage = isJson
+      ? body?.error || body?.message || body?.msg
+      : summarizeTextError(text, res.status);
+    const msg = res.status === 401 && session && knownSessionFailure(body)
+      ? sessionExpiredMessage(session)
+      : serverMessage || `HTTP ${res.status}`;
+    const err = new Error(msg);
+    err.status = res.status;
+    err.body = body;
+    throw err;
+  }
+  return body;
+};
+
+// TASK-338: every CAP request carries a hard timeout. Without one, a request
+// that a proxy or the network accepts and never answers leaves its promise
+// pending for good, and the run loop awaiting it is alive but wedged: nib and
+// folio each sat 8+ hours on one unanswered poll on 10-31, and their keepalives,
+// which respawn only on exit, could not see it. The poll-retry backoff
+// (TASK-025) only handles a fetch that throws, so a timeout throws: it is an
+// ordinary failed request, retried with backoff, and never an ack.
+//
+// Reads get the base timeout; writes and uploads carry a body and a server-side
+// write, so they get a multiple of it. COMMONLY_CAP_TIMEOUT_MS sets the base.
+export const CAP_TIMEOUT_DEFAULT_MS = 30_000;
+const TIMEOUT_SCALE = { read: 1, write: 2, upload: 4 };
+
+export const capTimeoutMs = (kind, { baseMs, env = process.env } = {}) => {
+  const fromEnv = Number(env.COMMONLY_CAP_TIMEOUT_MS);
+  const base = [baseMs, fromEnv].find((value) => Number.isFinite(value) && value > 0)
+    ?? CAP_TIMEOUT_DEFAULT_MS;
+  return Math.min(base * (TIMEOUT_SCALE[kind] || 1), 2_147_483_647);
+};
+
+// A caller's own signal (doctor, and the 5s identity and skills reads in the
+// run loop) still applies; the hard timeout is added beside it, never instead.
+// AbortSignal.any is Node 20.3+, and `engines` allows 20.0, so the fallback
+// joins the two by hand. Either way the abort carries the source's own reason,
+// which is what nameTimeout matches on.
+// The fallback's listeners are removed when the request settles, so a caller
+// that reuses one long-lived signal does not collect one per request.
+const capSignal = (capTimeout, callerSignal) => {
+  if (!callerSignal) return { signal: capTimeout, release: () => {} };
+  if (typeof AbortSignal.any === 'function') {
+    return { signal: AbortSignal.any([callerSignal, capTimeout]), release: () => {} };
+  }
+  const joined = new AbortController();
+  const listeners = [];
+  for (const source of [callerSignal, capTimeout]) {
+    if (source.aborted) {
+      joined.abort(source.reason);
+      break;
+    }
+    const onAbort = () => joined.abort(source.reason);
+    source.addEventListener('abort', onAbort, { once: true });
+    listeners.push([source, onAbort]);
+  }
+  return {
+    signal: joined.signal,
+    release: () => listeners.forEach(([source, onAbort]) => source.removeEventListener('abort', onAbort)),
+  };
+};
+
+export const formatLimit = (ms) => (ms < 1000 ? `${ms}ms` : `${Math.round(ms / 1000)}s`);
+
+// The cap's timeout rejects with a DOMException named TimeoutError, from the
+// fetch or from the body read. Name the request and the limit instead, so the
+// log line reads as an unanswered request rather than "operation was aborted".
+// Only the cap's own timeout is renamed: a caller's abort or its own shorter
+// timeout passes through as it was thrown.
+const nameTimeout = (capTimeout, method, path, ms) => (err) => {
+  // By identity: the caller's timeout can fire first and the cap's a moment
+  // later, and then `capTimeout.aborted` alone would claim the caller's error.
+  if (err?.name !== 'TimeoutError' || err !== capTimeout.reason) throw err;
+  throw Object.assign(
+    new Error(`${method} ${path} got no answer in ${formatLimit(ms)}`),
+    { code: 'cap_timeout', timeoutMs: ms },
+  );
+};
+
+const timedFetch = (url, init, { method, path, ms, session }) => {
+  const capTimeout = AbortSignal.timeout(ms);
+  const { signal, release } = capSignal(capTimeout, init.signal);
+  return fetch(url, { ...init, signal })
+    .then((res) => handleResponse(res, session))
+    .catch(nameTimeout(capTimeout, method, path, ms))
+    .finally(release);
+};
+
+export const createClient = ({ instance = null, token = undefined, timeoutMs = undefined } = {}) => {
+  const baseUrl = resolveInstanceUrl(instance);
+  const resolved = resolveInstance(instance);
+  const authToken = token === undefined ? getToken(instance) : token;
+  const session = {
+    instanceKey: resolved?.key || (typeof instance === 'string' && instance && !/^https?:\/\//i.test(instance) ? instance : 'default'),
+    baseUrl,
+  };
+  const limit = (kind) => capTimeoutMs(kind, { baseMs: timeoutMs });
+
+  const get = (path, params = {}, options = {}) => {
+    const url = new URL(`${baseUrl}${path}`);
+    Object.entries(params).forEach(([k, v]) => v != null && url.searchParams.set(k, v));
+    return timedFetch(url.toString(), { headers: headers(authToken), ...options }, {
+      method: 'GET', path, ms: limit('read'), session,
+    });
+  };
+
+  const post = (path, body = {}) => timedFetch(`${baseUrl}${path}`, {
+    method: 'POST',
+    headers: headers(authToken),
+    body: JSON.stringify(body),
+  }, { method: 'POST', path, ms: limit('write'), session });
+
+  const patch = (path, body = {}) => timedFetch(`${baseUrl}${path}`, {
+    method: 'PATCH',
+    headers: headers(authToken),
+    body: JSON.stringify(body),
+  }, { method: 'PATCH', path, ms: limit('write'), session });
+
+  const del = (path, body) => timedFetch(`${baseUrl}${path}`, {
+    method: 'DELETE',
+    headers: headers(authToken),
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  }, { method: 'DELETE', path, ms: limit('write'), session });
+
+  // Multipart upload via native FormData/Blob (Node 18+) — no runtime deps.
+  // Content-Type is deliberately NOT set: fetch writes the multipart boundary.
+  const upload = (path, {
+    fileBuffer, fileName, contentType, fileField = 'file', fields = {},
+  }) => {
+    const form = new FormData();
+    form.append(
+      fileField,
+      new Blob([fileBuffer], { type: contentType || 'application/octet-stream' }),
+      fileName,
+    );
+    for (const [k, v] of Object.entries(fields)) {
+      if (v !== undefined && v !== null) form.append(k, String(v));
+    }
+    return timedFetch(`${baseUrl}${path}`, {
+      method: 'POST',
+      headers: authToken ? { Authorization: `Bearer ${authToken}` } : {},
+      body: form,
+    }, { method: 'POST', path, ms: limit('upload'), session });
+  };
+
+  return {
+    get, post, patch, del, upload, baseUrl,
+  };
+};
+
+// Convenience: login doesn't need a token
+export const login = (instanceUrl, email, password) => {
+  const ms = capTimeoutMs('write');
+  return timedFetch(`${instanceUrl}/api/auth/login`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email, password }),
+  }, { method: 'POST', path: '/api/auth/login', ms, session: null });
+};

package/src/lib/claim-outcome.js

@@ -0,0 +1,128 @@
+/**
+ * claimReleaseFor — the ONE decision about how a finished turn releases its
+ * ADR-018 attention claim.
+ *
+ * It lives here, extracted from two byte-identical copies in the run loop
+ * (single-event and batch release), for the reason a second copy is always a
+ * risk: the batch path is the one `message.posted` actually reaches, so a
+ * change applied to only one of them would pass review and do nothing.
+ *
+ * Three outcomes, and the KERNEL decides what each one does with the wake
+ * (TASK-099 ruling, corrected at 71194/71195/71210):
+ *
+ *   - `refused`   — the lease holder could not deliver. Nothing about the
+ *                   agent's CHOICE happened: the model never ran (an upstream
+ *                   429/502/401, named by TASK-096) or the server refused the
+ *                   post. On a HUMAN wake the kernel hands the message to one
+ *                   remaining listener exactly as it does for a decline — a
+ *                   per-seat budget failure must not make a human's message
+ *                   disappear — and records the refuser so the chain stays
+ *                   finite. On any other wake it is terminal. The routing is
+ *                   the kernel's: this module only names the outcome.
+ *   - `declined`  — a silent, normally completed human broadcast. The agent
+ *                   chose not to answer, or printed nothing (`empty-output`),
+ *                   so the kernel hands it to exactly one remaining original
+ *                   listener.
+ *   - `completed` — everything else that produced a result: a posted reply, or
+ *                   a skip with a reason (`no-prompt`, `claim-held`,
+ *                   `duplicate-delivery`) where nothing was refused.
+ *
+ * The refusal CLASS is an enum, not free text: `upstream-refused` (with the
+ * HTTP status), `cascade-cap`, `delivery-refused`. The kernel stores the class
+ * so refusals are countable, and rejects anything else with a 400. A producer
+ * that cannot classify itself maps to `delivery-refused` before sending — the
+ * mapping is here, in one place, rather than in each producer.
+ *
+ * A thrown turn returns no turnResult and releases with no outcome — the
+ * legacy holder-only DELETE whose at-least-once redelivery is the correct
+ * behaviour for a crashed spawn (the lid closed, the process died).
+ */
+
+/** The classes the kernel accepts. Mirrors `REFUSAL_REASONS` in agentsRuntime. */
+export const REFUSAL_REASONS = ['upstream-refused', 'cascade-cap', 'delivery-refused'];
+
+/** What an unclassifiable refusal is recorded as, rather than a fourth class. */
+export const DEFAULT_REFUSAL_REASON = 'delivery-refused';
+
+/**
+ * The reason a turn that printed nothing carries. It releases like a bare
+ * decline, so a human's message still reaches another listener, but it is not
+ * the `NO_REPLY` sentinel and does not mark a digest read.
+ */
+export const EMPTY_OUTPUT = 'empty-output';
+
+/**
+ * The range the kernel accepts for a refusal's `status` — its
+ * `MIN_UPSTREAM_STATUS` / `MAX_UPSTREAM_STATUS` in `messageClaimService`.
+ * A number outside it is not a refusal status the kernel will record: it
+ * answers 400, and the 400 fallback in `enforcement.release` re-releases as
+ * `completed` — which is terminal. So forwarding an out-of-range number does
+ * not merely lose the number, it loses the handoff: an upstream refusal on a
+ * human wake would be recorded as a clean completion. The sender's rule has to
+ * be the receiver's rule, which is why the bound lives here as well as there.
+ */
+export const MIN_UPSTREAM_STATUS = 400;
+export const MAX_UPSTREAM_STATUS = 599;
+
+/**
+ * @param {{type?: string, payload?: {senderIsHuman?: boolean}}} event
+ * @param {{refused?: {reason?: string, status?: number}|true, outcome?: string, reason?: string}|undefined} turnResult
+ * @returns {{outcome?: 'refused'|'declined'|'completed', reason?: string, status?: number}}
+ */
+export const claimReleaseFor = (event, turnResult) => {
+  if (!turnResult) return { outcome: undefined };
+  // `refused: true` is still honoured: it is what an older producer shape (and
+  // a third-party wrapper following TASK-096's docs) sends, and it means the
+  // same thing — `delivery-refused`, the class that claims the least.
+  if (turnResult.refused) {
+    const declared = typeof turnResult.refused === 'object' ? turnResult.refused : {};
+    const reason = REFUSAL_REASONS.includes(declared.reason)
+      ? declared.reason
+      : DEFAULT_REFUSAL_REASON;
+    // The status is the instance of the class, and only the upstream class has
+    // one: a cap refusal or a refused post never saw an upstream HTTP status,
+    // so sending its number would put a field on the record that cannot mean
+    // what a reader would assume. It is also bounded by what the kernel
+    // accepts — an out-of-range number keeps the class and drops only the
+    // number, so the refusal still hands off instead of falling back to
+    // `completed`.
+    const status = reason === 'upstream-refused'
+      && Number.isInteger(declared.status)
+      && declared.status >= MIN_UPSTREAM_STATUS
+      && declared.status <= MAX_UPSTREAM_STATUS
+      ? declared.status
+      : undefined;
+    return {
+      outcome: 'refused',
+      reason,
+      ...(status !== undefined ? { status } : {}),
+    };
+  }
+  if (event?.type === 'message.posted'
+      && event.payload?.senderIsHuman === true
+      && turnResult.outcome === 'no_action'
+      && (!turnResult.reason || turnResult.reason === EMPTY_OUTPUT)) {
+    return { outcome: 'declined' };
+  }
+  return { outcome: 'completed' };
+};
+
+/**
+ * `refused` is a LOCAL release marker: the producer sets it so the claim
+ * release can name the outcome (see `claimReleaseFor`), and nothing else reads
+ * it. The event ack is a wire payload with its own readers, and the information
+ * that belongs there already reaches them as `reason` — so the marker is
+ * dropped at the ack boundary rather than widening the ack with an internal
+ * flag. Returns the result unchanged when there is no marker, so the common
+ * path never sees a rebuilt object.
+ *
+ * @param {object|undefined} turnResult
+ */
+export const ackResultFor = (turnResult) => {
+  if (!turnResult || !turnResult.refused) return turnResult;
+  // ts-eslint's `arg`/`vars` ignore pattern is `^_`, and ignoreRestSiblings is
+  // off in this repo's config — so the dropped key is renamed rather than
+  // left to trip no-unused-vars.
+  const { refused: _refused, ...rest } = turnResult;
+  return rest;
+};

package/src/lib/claimed-work-gate.js

@@ -0,0 +1,73 @@
+// Defer-while-claimed (TASK-640). While a seat holds a claimed board row in a
+// pod, a broadcast wake there that no person sent and that does not concern
+// its row is acked without a spawn. Measured on one seat, 2026-10-30: most of
+// its hourly wake-mode turns were pod broadcasts while it held one row, and
+// most of those ended in NO_REPLY.
+//
+// Mentions, DMs, human posts, heartbeats and digests are never deferred, and
+// neither is a broadcast about a row the seat holds. Every failure fails OPEN:
+// a kernel that does not mark `claimedByMe`, or a board read that errors,
+// means nothing is deferred.
+
+export const CLAIMED_WORK_TTL_MS = 60_000;
+
+// Pure: may this waking event wait while the seat holds `claimedTaskIds`?
+// `trigger` is classifyTrigger's verdict for the event.
+export const isDeferrableWhileClaimed = (event, trigger, claimedTaskIds) => {
+  if (!event || event.deliveryMode === 'digest') return false;
+  if (event.type !== 'message.posted') return false;
+  const payload = event.payload || {};
+  if (payload.addressed === true || payload.repliesToYourMessage === true) return false;
+  // A lease warning is about the seat's own row, though it names it differently.
+  if (payload.leaseWarningTaskId) return false;
+  // A board wake with a reason is a change the seat must see: a dependency of
+  // its row finished, an edit to its row folded into another row's wake (so
+  // taskId names the first row), or an agent assigned it a new row. Only the
+  // reasonless found-work nudge may wait.
+  if (payload.boardWake === true && payload.wakeReason) return false;
+  if (trigger !== 'agent' && trigger !== 'kernel') return false;
+  if (payload.taskId && claimedTaskIds?.has(String(payload.taskId))) return false;
+  return true;
+};
+
+export const createClaimedWorkGate = ({ client, ttlMs = CLAIMED_WORK_TTL_MS, now = () => Date.now() } = {}) => {
+  const cache = new Map();
+
+  // The ids of this seat's claimed rows in `podId`, or null when it holds none
+  // or the board cannot say.
+  const claimedTaskIds = async (podId) => {
+    if (!client || !podId) return null;
+    const cached = cache.get(podId);
+    if (cached && now() - cached.at < ttlMs) return cached.ids;
+    let ids = null;
+    try {
+      const { tasks = [] } = await client.get(`/api/v1/tasks/${podId}`, { status: 'claimed' });
+      // A lapsed lease still carries claimedBy; only a live one holds the seat.
+      const mine = tasks.filter((task) => task?.claimedByMe === true && task?.leaseState === 'held')
+        .map((task) => String(task.taskId));
+      ids = mine.length > 0 ? new Set(mine) : null;
+    } catch {
+      ids = null;
+    }
+    cache.set(podId, { at: now(), ids });
+    return ids;
+  };
+
+  // True when every waking event in the group may wait. An empty group is
+  // never deferred.
+  const shouldDefer = async (podId, wakes) => {
+    if (!Array.isArray(wakes) || wakes.length === 0) return false;
+    // Only read the board when the group could be deferred at all. A group
+    // that can't be deferred spawns a turn, and that turn may complete or
+    // release the row, so the next read must not trust the cached claim.
+    if (!wakes.every(({ event, trigger }) => isDeferrableWhileClaimed(event, trigger, null))) {
+      cache.delete(podId);
+      return false;
+    }
+    const ids = await claimedTaskIds(podId);
+    if (!ids) return false;
+    return wakes.every(({ event, trigger }) => isDeferrableWhileClaimed(event, trigger, ids));
+  };
+
+  return { shouldDefer };
+};

package/src/lib/cli-hint.js

@@ -0,0 +1,33 @@
+// The commands this CLI prints for a person to type (F435).
+//
+// npm installs `commonly` and `npx` on Windows as three shims: a `.ps1`, a
+// `.cmd` and a bare sh script. PowerShell picks the `.ps1` first, and its
+// default execution policy (Restricted on a Windows client) refuses to run
+// it, so a printed `commonly daemon install` fails there before it starts.
+// The `.cmd` shim is not a script to PowerShell and runs under any policy, and
+// it runs the same in cmd.exe. So on win32 every hint names `commonly.cmd`,
+// `npx.cmd` or `npm.cmd`; elsewhere the bare name.
+//
+// Windows PowerShell 5.1 has no `&&`, and `;` would run the second step even
+// when the first failed, so steps that depend on each other print one per line
+// on win32 (`cliSteps`).
+//
+// The guard in __tests__/cli-hint.test.mjs fails on a `commonly <subcommand>`
+// written into a string anywhere else in cli/src: use `${CLI} <subcommand>`.
+
+export const cliName = (platform = process.platform) => (platform === 'win32' ? 'space.cmd' : 'space');
+export const npxName = (platform = process.platform) => (platform === 'win32' ? 'npx.cmd' : 'npx');
+export const npmName = (platform = process.platform) => (platform === 'win32' ? 'npm.cmd' : 'npm');
+
+export const CLI = cliName();
+export const NPX = npxName();
+export const NPM = npmName();
+
+// Commands that run one after another, each only if the one before succeeded.
+// Joined with ` && ` on POSIX shells; on win32, one command per line, each
+// indented by `indent`, so the reader runs them in order.
+export const cliSteps = (steps, { platform = process.platform, indent = '  ' } = {}) => (
+  platform === 'win32'
+    ? steps.map((step) => `\n${indent}${step}`).join('')
+    : steps.join(' && ')
+);