@agilno-tech/rivet 0.1.0-alpha.0

package/src/status/server.js

@@ -0,0 +1,323 @@
+import { readFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { fileURLToPath } from 'node:url';
+
+import { buildStatusViewModel } from './view-model.js';
+
+const objectFreeze = Object.freeze;
+const getDescriptor = Object.getOwnPropertyDescriptor;
+const getPrototypeOf = Object.getPrototypeOf;
+const promiseThen = Promise.prototype.then;
+const reflectApply = Reflect.apply;
+const HOST = '127.0.0.1';
+const MAX_JSON_BYTES = 512 * 1024;
+const MAX_SSE_FRAME_BYTES = 32 * 1024;
+const MAX_SSE_BATCH_BYTES = 256 * 1024;
+const ASSETS = new Map([
+  ['/', { type: 'text/html; charset=utf-8', body: readFileSync(fileURLToPath(new URL('./public/index.html', import.meta.url))) }],
+  ['/app.js', { type: 'text/javascript; charset=utf-8', body: readFileSync(fileURLToPath(new URL('./public/app.js', import.meta.url))) }],
+  ['/styles.css', { type: 'text/css; charset=utf-8', body: readFileSync(fileURLToPath(new URL('./public/styles.css', import.meta.url))) }],
+]);
+const ROUTES = new Set(['/api/state', '/api/events', '/events']);
+const SECURITY_HEADERS = Object.freeze({
+  'content-security-policy': "default-src 'self'; connect-src 'self'; script-src 'self'; style-src 'self'; img-src 'self'; object-src 'none'; base-uri 'none'; frame-ancestors 'none'; form-action 'none'",
+  'x-content-type-options': 'nosniff',
+  'x-frame-options': 'DENY',
+  'referrer-policy': 'no-referrer',
+  'permissions-policy': 'camera=(), microphone=(), geolocation=(), payment=(), usb=()',
+  'cross-origin-resource-policy': 'same-origin',
+  'cross-origin-opener-policy': 'same-origin',
+});
+
+class StatusServerError extends Error {
+  constructor() {
+    super('Status unavailable');
+    this.name = 'StatusServerError';
+    this.code = 'ERR_STATUS_UNAVAILABLE';
+  }
+}
+
+function integer(value, minimum, maximum, fallback) {
+  return Number.isSafeInteger(value) && value >= minimum && value <= maximum ? value : fallback;
+}
+function send(response, status, body, headers = {}) {
+  if (response.destroyed || response.writableEnded) return;
+  const bytes = Buffer.isBuffer(body) ? body : Buffer.from(body);
+  response.writeHead(status, { ...SECURITY_HEADERS, 'content-length': bytes.length, ...headers });
+  response.end(bytes);
+}
+function sendUnavailable(response) {
+  send(response, 503, 'Status unavailable', { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' });
+}
+function sendJson(response, value) {
+  const body = Buffer.from(JSON.stringify(value));
+  if (body.length > MAX_JSON_BYTES) { sendUnavailable(response); return; }
+  send(response, 200, body, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+}
+function requestPath(request) {
+  const value = request.url;
+  if (typeof value !== 'string' || value.length > 64 || value.includes('%') || value.includes('?') || value.includes('#')) return null;
+  return ROUTES.has(value) || ASSETS.has(value) ? value : null;
+}
+function rawHeaderValues(request, target) {
+  const result = [];
+  const values = request.rawHeaders;
+  if (!Array.isArray(values) || values.length % 2 !== 0) return result;
+  for (let index = 0; index < values.length; index += 2) {
+    if (typeof values[index] === 'string' && values[index].toLowerCase() === target) result.push(values[index + 1]);
+  }
+  return result;
+}
+function reconnectCursor(request) {
+  const values = rawHeaderValues(request, 'last-event-id');
+  if (values.length === 0) return 0;
+  if (values.length !== 1 || typeof values[0] !== 'string' || !/^(?:0|[1-9][0-9]{0,9})$/.test(values[0])) return null;
+  return Number(values[0]);
+}
+
+export function createStatusServer(options = {}) {
+  if (!options || typeof options !== 'object' || Array.isArray(options) || typeof options.readState !== 'function') {
+    throw new TypeError('Status server requires a state reader.');
+  }
+  const now = typeof options.now === 'function' ? options.now : Date.now;
+  const pollIntervalMs = integer(options.pollIntervalMs, 25, 60_000, 1_000);
+  const readTimeoutMs = integer(options.readTimeoutMs, 10, 30_000, 2_000);
+  const maxSseClients = integer(options.maxSseClients, 1, 128, 16);
+  const clients = new Set();
+  const sockets = new Set();
+  let actualPort = null;
+  let started = false;
+  let closing = null;
+
+  function boundedStateRead(externalSignal) {
+    const controller = new AbortController();
+    return new Promise((resolvePromise, reject) => {
+      let settled = false;
+      const finish = (callback, value) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        externalSignal?.removeEventListener?.('abort', onAbort);
+        callback(value);
+      };
+      const fail = () => {
+        controller.abort();
+        finish(reject, new StatusServerError());
+      };
+      const onAbort = () => fail();
+      const timer = setTimeout(fail, readTimeoutMs);
+      timer.unref?.();
+      if (externalSignal?.aborted) { fail(); return; }
+      externalSignal?.addEventListener?.('abort', onAbort, { once: true });
+      let source;
+      try { source = options.readState({ signal: controller.signal }); }
+      catch { finish(reject, new StatusServerError()); return; }
+      const onFulfilled = value => finish(resolvePromise, value);
+      const onRejected = () => finish(reject, new StatusServerError());
+      try {
+        reflectApply(promiseThen, source, [onFulfilled, onRejected]);
+      } catch {
+        try {
+          const prototype = source !== null && typeof source === 'object' ? getPrototypeOf(source) : null;
+          const thenDescriptor = source !== null && (typeof source === 'object' || typeof source === 'function')
+            ? getDescriptor(source, 'then')
+            : undefined;
+          if ((prototype === Object.prototype || prototype === null) && !thenDescriptor) onFulfilled(source);
+          else onRejected();
+        } catch { onRejected(); }
+      }
+    });
+  }
+
+  async function readModel(signal) {
+    const state = await boundedStateRead(signal);
+    return buildStatusViewModel(state, { nowMs: now(), limits: options.limits });
+  }
+
+  function writeSse(client, payload) {
+    if (client.closed || Buffer.byteLength(payload) > MAX_SSE_FRAME_BYTES) return Promise.resolve(false);
+    if (client.response.write(payload)) return Promise.resolve(true);
+    return new Promise(resolvePromise => {
+      let settled = false;
+      const finish = value => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        client.response.off('drain', onDrain);
+        client.response.off('close', onClose);
+        resolvePromise(value);
+      };
+      const onDrain = () => finish(true);
+      const onClose = () => finish(false);
+      const timer = setTimeout(() => {
+        client.abort.abort();
+        client.response.destroy();
+        finish(false);
+      }, 1_000);
+      timer.unref?.();
+      client.response.once('drain', onDrain);
+      client.response.once('close', onClose);
+    });
+  }
+
+  async function sendSseEvents(client) {
+    if (client.closed || client.busy) return;
+    client.busy = true;
+    try {
+      const model = await readModel(client.abort.signal);
+      if (client.closed) return;
+      const firstAvailableSequence = model.events[0]?.sequence ?? 0;
+      const latestSequence = model.events.at(-1)?.sequence ?? 0;
+      let batchBytes = 0;
+      if (!client.resetChecked && client.cursor > 0
+        && (firstAvailableSequence === 0 || client.cursor < firstAvailableSequence - 1 || client.cursor > latestSequence)) {
+        const reset = `id:\nevent: reset\ndata: ${JSON.stringify({ firstAvailableSequence, latestSequence })}\n\n`;
+        if (!await writeSse(client, reset)) return;
+        batchBytes += Buffer.byteLength(reset);
+        client.cursor = Math.max(0, firstAvailableSequence - 1);
+      }
+      client.resetChecked = true;
+      let wrote = false;
+      for (const event of model.events) {
+        if (event.sequence <= client.cursor) continue;
+        const frame = `id: ${event.sequence}\nevent: status\ndata: ${JSON.stringify(event)}\n\n`;
+        const frameBytes = Buffer.byteLength(frame);
+        if (batchBytes + frameBytes > MAX_SSE_BATCH_BYTES || !await writeSse(client, frame)) break;
+        batchBytes += frameBytes;
+        client.cursor = event.sequence;
+        wrote = true;
+      }
+      if (!wrote && batchBytes === 0) await writeSse(client, ': heartbeat\n\n');
+    } catch {
+      if (!client.closed) await writeSse(client, 'event: unavailable\ndata: {}\n\n');
+    } finally { client.busy = false; }
+  }
+
+  const server = createServer(async (request, response) => {
+    for (const [key, value] of Object.entries(SECURITY_HEADERS)) response.setHeader(key, value);
+    const host = rawHeaderValues(request, 'host');
+    if (actualPort === null || host.length !== 1 || host[0] !== `${HOST}:${actualPort}`) {
+      send(response, 421, 'Misdirected Request', { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' });
+      return;
+    }
+    const origins = rawHeaderValues(request, 'origin');
+    if (origins.length > 1 || (origins.length === 1 && origins[0] !== `http://${HOST}:${actualPort}`)) {
+      send(response, 403, 'Forbidden', { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' });
+      return;
+    }
+    if (request.method !== 'GET') {
+      send(response, 405, 'Method Not Allowed', { allow: 'GET', 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' });
+      return;
+    }
+    const path = requestPath(request);
+    if (!path) {
+      send(response, 404, 'Not Found', { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' });
+      return;
+    }
+    try {
+      if (path === '/api/state' || path === '/api/events') {
+        const abort = new AbortController();
+        const disconnect = () => abort.abort();
+        request.once('aborted', disconnect);
+        response.once('close', disconnect);
+        try {
+          const model = await readModel(abort.signal);
+          if (path === '/api/state') sendJson(response, model);
+          else sendJson(response, { events: model.events, truncated: model.truncated.events });
+        } finally {
+          request.off('aborted', disconnect);
+          response.off('close', disconnect);
+        }
+        return;
+      }
+      if (path === '/events') {
+        const cursor = reconnectCursor(request);
+        if (cursor === null) {
+          send(response, 400, 'Invalid Last-Event-ID', { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' });
+          return;
+        }
+        if (clients.size >= maxSseClients) {
+          send(response, 503, 'Status stream capacity reached', { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store', 'retry-after': '2' });
+          return;
+        }
+        response.writeHead(200, { ...SECURITY_HEADERS, 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-store', connection: 'keep-alive' });
+        response.write('retry: 2000\n\n');
+        const client = { response, cursor, resetChecked: false, busy: false, closed: false, timer: null, abort: new AbortController() };
+        clients.add(client);
+        const closeClient = () => {
+          if (client.closed) return;
+          client.closed = true;
+          client.abort.abort();
+          clearInterval(client.timer);
+          clients.delete(client);
+        };
+        request.once('aborted', closeClient);
+        request.once('close', closeClient);
+        response.once('close', closeClient);
+        await sendSseEvents(client);
+        if (!client.closed) {
+          client.timer = setInterval(() => { void sendSseEvents(client); }, pollIntervalMs);
+          client.timer.unref?.();
+        }
+        return;
+      }
+      const asset = ASSETS.get(path);
+      send(response, 200, asset.body, { 'content-type': asset.type, 'cache-control': 'no-store' });
+    } catch {
+      if (!response.headersSent) sendUnavailable(response);
+      else if (!response.destroyed) response.destroy();
+    }
+  });
+  server.requestTimeout = 10_000;
+  server.headersTimeout = 5_000;
+  server.keepAliveTimeout = 2_000;
+  server.on('connection', socket => {
+    sockets.add(socket);
+    socket.once('close', () => sockets.delete(socket));
+  });
+
+  return Object.freeze({
+    async start(startOptions = {}) {
+      if (started || closing) throw new Error('Status server is already started.');
+      if (!startOptions || typeof startOptions !== 'object' || Array.isArray(startOptions)
+        || Object.keys(startOptions).some(key => key !== 'port')) throw new TypeError('Status server start options are invalid.');
+      const port = integer(startOptions.port ?? 0, 0, 65_535, null);
+      if (port === null) throw new TypeError('Status server port is invalid.');
+      await new Promise((resolvePromise, reject) => {
+        const onError = () => { server.off('listening', onListening); reject(new StatusServerError()); };
+        const onListening = () => { server.off('error', onError); resolvePromise(); };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, HOST);
+      });
+      const address = server.address();
+      if (!address || typeof address === 'string' || address.address !== HOST || !Number.isSafeInteger(address.port) || address.port < 1) {
+        await new Promise(resolvePromise => server.close(resolvePromise));
+        throw new StatusServerError();
+      }
+      actualPort = address.port;
+      started = true;
+      return objectFreeze({ host: HOST, port: actualPort, url: `http://${HOST}:${actualPort}` });
+    },
+    async close() {
+      if (closing) return closing;
+      if (!started) return;
+      closing = (async () => {
+        for (const client of clients) {
+          client.closed = true;
+          client.abort.abort();
+          clearInterval(client.timer);
+          client.response.destroy();
+        }
+        clients.clear();
+        const stopped = new Promise((resolvePromise, reject) => server.close(error => error ? reject(new StatusServerError()) : resolvePromise()));
+        server.closeAllConnections?.();
+        for (const socket of sockets) socket.destroy();
+        await stopped;
+        started = false;
+        actualPort = null;
+      })();
+      try { await closing; } finally { closing = null; }
+    },
+  });
+}

package/src/status/view-model.js

@@ -0,0 +1,356 @@
+import { isIP } from 'node:net';
+
+const DEFAULT_LIMITS = Object.freeze({ nodes: 256, agents: 256, events: 200, evidence: 512, stringLength: 256 });
+const INPUT_LIMITS = Object.freeze({ array: 4_096, events: 10_000, record: 4_096, ids: 512 });
+const ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const STATUS = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const ROLE = new Set(['boss', 'manager', 'worker', 'human', 'system']);
+const EVENT_TYPES = new Set([
+  'graph-created', 'state-transition', 'retry', 'heartbeat', 'evidence-recorded',
+  'approval-recorded', 'authority-adjusted', 'budget-adjusted', 'cancelled',
+]);
+const SECRET_TEXT = /(?:authorization\s*:|(?:bearer|basic)\s+[a-z0-9._~+/=-]{3,}|gh[pousr]_[a-z0-9_]{8,}|github_pat_[a-z0-9_]{8,}|glpat-[a-z0-9_-]{8,}|(?:npm|pypi|hf)_[a-z0-9_-]{8,}|akia[0-9a-z]{16}|aiza[0-9a-z_-]{16,}|(?:sk|xox[a-z]?)-[a-z0-9_-]{8,}|(?:password|passwd|secret|credential|token|api[-_ ]?key|private[-_ ]?key)\s*[:=]\s*\S+)/i;
+const PRIVATE_PATH = /(?:^|[\s"'(])(?:\/(?:Users|home|private|tmp|var|etc|opt|srv|Volumes)(?:\/|$)|[a-z]:[\\/]|\\\\[^\\/\s]+[\\/][^\\/\s]+|\/\/[^/\s]+\/[^/\s]+)/i;
+const ABSOLUTE_TEXT_PATH = /(?:^|[\s"'(])\/(?!\/)[^/\s]+\/[^\s]+/;
+const URL_TEXT = /\b[a-z][a-z0-9+.-]*:\/\//i;
+const CREDENTIAL_WORD = /\b(?:authorization|bearer|cookie|credential|password|passwd|private[-_ ]?key|secret|session(?:id)?|token)\b/i;
+const ENV_CREDENTIAL = /\b(?:aws_(?:secret_access_key|access_key_id|session_token)|[a-z][a-z0-9_]*(?:api_key|access_key|private_key|credential(?:s)?|cookie|password|passwd|secret|session|session_?id|token|url))\b\s*[:=]/i;
+const PUBLIC_REASON = /^[a-z0-9][a-z0-9 .,'()_:+-]*$/i;
+const SAFE_PATH_SEGMENT = /^[a-z0-9][a-z0-9._~-]{0,95}$/i;
+const CREDENTIAL_PATH_SEGMENT = /(?:^|[._~-])(?:access[-_]?key|api[-_]?key|auth(?:orization)?|bearer|cookie|credential|key|password|passwd|private[-_]?key|secret|session(?:id)?|token)(?:$|[._~-])/i;
+
+const arrayIsArray = Array.isArray;
+const getDescriptor = Object.getOwnPropertyDescriptor;
+const getPrototypeOf = Object.getPrototypeOf;
+const objectFreeze = Object.freeze;
+const ownKeys = Reflect.ownKeys;
+const stringNormalize = String.prototype.normalize;
+
+export class StatusViewError extends Error {
+  constructor() {
+    super('Status state is invalid.');
+    this.name = 'StatusViewError';
+    this.code = 'ERR_STATUS_VIEW_INVALID';
+  }
+}
+
+function invalid() { throw new StatusViewError(); }
+
+function snapshotContext() {
+  const records = new WeakMap();
+  const arrays = new WeakMap();
+  function record(value, { optional = false } = {}) {
+    if (value === undefined || value === null) {
+      if (optional) return objectFreeze(Object.create(null));
+      invalid();
+    }
+    if (typeof value !== 'object' || arrayIsArray(value)) invalid();
+    if (records.has(value)) return records.get(value);
+    const prototype = getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) invalid();
+    const keys = ownKeys(value);
+    if (keys.length > INPUT_LIMITS.record) invalid();
+    const copy = Object.create(null);
+    records.set(value, copy);
+    for (let index = 0; index < keys.length; index += 1) {
+      const key = keys[index];
+      if (typeof key !== 'string') invalid();
+      const descriptor = getDescriptor(value, key);
+      if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) invalid();
+      copy[key] = descriptor.value;
+    }
+    return objectFreeze(copy);
+  }
+  function array(value, { optional = false, maximum = INPUT_LIMITS.array } = {}) {
+    if (value === undefined || value === null) {
+      if (optional) return objectFreeze([]);
+      invalid();
+    }
+    if (!arrayIsArray(value)) invalid();
+    if (arrays.has(value)) {
+      const cached = arrays.get(value);
+      if (cached.length > maximum) invalid();
+      return cached.value;
+    }
+    const lengthDescriptor = getDescriptor(value, 'length');
+    if (!lengthDescriptor || !Number.isSafeInteger(lengthDescriptor.value)
+      || lengthDescriptor.value < 0 || lengthDescriptor.value > maximum) invalid();
+    const length = lengthDescriptor.value;
+    const keys = ownKeys(value);
+    if (keys.length !== length + 1) invalid();
+    const copy = new Array(length);
+    arrays.set(value, { value: copy, length });
+    for (let index = 0; index < length; index += 1) {
+      const key = String(index);
+      const descriptor = getDescriptor(value, key);
+      if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) invalid();
+      copy[index] = descriptor.value;
+    }
+    for (let index = 0; index < keys.length; index += 1) {
+      const key = keys[index];
+      if (key !== 'length' && (typeof key !== 'string' || !/^(?:0|[1-9][0-9]*)$/.test(key)
+        || Number(key) >= length || String(Number(key)) !== key)) invalid();
+    }
+    return objectFreeze(copy);
+  }
+  return objectFreeze({ record, array });
+}
+
+function safeId(value) { return typeof value === 'string' && value.length <= 96 && ID.test(value) ? value : null; }
+function safeStatus(value, fallback = 'unknown') { return typeof value === 'string' && value.length <= 48 && STATUS.test(value) ? value : fallback; }
+function safeRole(value) { return ROLE.has(value) ? value : 'system'; }
+function integer(value, fallback = 0) { return Number.isSafeInteger(value) && value >= 0 ? value : fallback; }
+function decimal(value) {
+  if (typeof value === 'number' && Number.isFinite(value) && value >= 0) return value;
+  return typeof value === 'string' && /^(?:0|[1-9][0-9]*)(?:\.[0-9]+)?$/.test(value) && value.length <= 32 ? value : '0';
+}
+function timestamp(value) {
+  if (typeof value !== 'string' || value.length > 40) return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) && new Date(parsed).toISOString() === value ? value : null;
+}
+function isoFromMs(value) { return Number.isSafeInteger(value) && value >= 0 ? new Date(value).toISOString() : null; }
+function publicText(value, maximum) {
+  if (typeof value !== 'string') return null;
+  const normalized = stringNormalize.call(value, 'NFKC').replace(/[\u0000-\u001f\u007f]/g, ' ').trim();
+  if (!normalized || SECRET_TEXT.test(normalized) || CREDENTIAL_WORD.test(normalized) || ENV_CREDENTIAL.test(normalized)
+    || PRIVATE_PATH.test(normalized) || ABSOLUTE_TEXT_PATH.test(normalized)
+    || URL_TEXT.test(normalized) || !PUBLIC_REASON.test(normalized)) return null;
+  return normalized.slice(0, maximum);
+}
+function ids(context, value, maximum = 64) {
+  const values = context.array(value, { optional: true, maximum: INPUT_LIMITS.ids });
+  const result = [];
+  for (let index = 0; index < Math.min(values.length, maximum); index += 1) {
+    const id = safeId(values[index]);
+    if (id) result.push(id);
+  }
+  return result;
+}
+function limits(context, input) {
+  const candidate = context.record(input, { optional: true });
+  const result = {};
+  for (const key of ['nodes', 'agents', 'events', 'evidence', 'stringLength']) {
+    const value = candidate[key];
+    const fallback = DEFAULT_LIMITS[key];
+    result[key] = Number.isSafeInteger(value) && value > 0 && value <= fallback ? value : fallback;
+  }
+  return objectFreeze(result);
+}
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  const values = Object.values(value);
+  for (let index = 0; index < values.length; index += 1) deepFreeze(values[index]);
+  return objectFreeze(value);
+}
+
+function projectEvents(context, source, { afterSequence, maxEvents, stringLength }) {
+  const events = context.array(source, { optional: true, maximum: INPUT_LIMITS.events });
+  const output = [];
+  for (let index = 0; index < events.length; index += 1) {
+    const input = context.record(events[index]);
+    const eventId = safeId(input.eventId);
+    const sequence = input.sequence;
+    const type = input.type;
+    const eventTimestamp = timestamp(input.timestamp);
+    if (!eventId || !Number.isSafeInteger(sequence) || sequence < 1 || !EVENT_TYPES.has(type) || !eventTimestamp) continue;
+    const actorInput = context.record(input.actor, { optional: true });
+    const actorId = safeId(actorInput.id);
+    const event = {
+      id: eventId, sequence, timestamp: eventTimestamp, type,
+      ...(safeId(input.nodeId) ? { nodeId: safeId(input.nodeId) } : {}),
+      actor: actorId ? { role: safeRole(actorInput.role), id: actorId } : { role: 'system', id: 'runtime' },
+    };
+    if (type === 'state-transition') {
+      event.priorState = safeStatus(input.priorState);
+      event.newState = safeStatus(input.newState);
+    } else if (type === 'retry') {
+      const reason = publicText(input.retryReason, stringLength);
+      if (reason) event.retryReason = reason;
+    } else if (type === 'heartbeat') {
+      event.heartbeatSequence = integer(input.heartbeatSequence);
+      event.heartbeatIntervalMs = integer(input.heartbeatIntervalMs);
+    } else if (type === 'evidence-recorded' || type === 'approval-recorded') {
+      event.evidenceRefs = ids(context, input.evidenceRefs);
+    } else if (type === 'cancelled') {
+      const reason = publicText(input.cancellationReason, stringLength);
+      if (reason) event.reason = reason;
+    }
+    if (sequence > afterSequence) output.push(event);
+  }
+  output.sort((left, right) => left.sequence - right.sequence);
+  return output.slice(-maxEvents);
+}
+
+export function projectStatusEvents(events, options = {}) {
+  try {
+    const context = snapshotContext();
+    const safeOptions = context.record(options, { optional: true });
+    const afterSequence = Number.isSafeInteger(safeOptions.afterSequence) && safeOptions.afterSequence >= 0 ? safeOptions.afterSequence : 0;
+    const maxEvents = Number.isSafeInteger(safeOptions.maxEvents) && safeOptions.maxEvents > 0 ? Math.min(safeOptions.maxEvents, DEFAULT_LIMITS.events) : DEFAULT_LIMITS.events;
+    const stringLength = Number.isSafeInteger(safeOptions.stringLength) && safeOptions.stringLength > 0 ? Math.min(safeOptions.stringLength, DEFAULT_LIMITS.stringLength) : DEFAULT_LIMITS.stringLength;
+    return deepFreeze(projectEvents(context, events, { afterSequence, maxEvents, stringLength }));
+  } catch { invalid(); }
+}
+
+function graphRows(context, allNodes, maximum) {
+  const rows = [];
+  const sources = new Map();
+  const agentIds = new Set();
+  for (let index = 0; index < allNodes.length; index += 1) {
+    const input = context.record(allNodes[index]);
+    const owner = context.record(input.owner, { optional: true });
+    const id = safeId(input.id) ?? 'unknown-node';
+    const ownerId = safeId(owner.id) ?? 'runtime';
+    if (safeId(owner.id)) agentIds.add(ownerId);
+    const row = { id, parentId: safeId(input.parentId), role: safeRole(owner.role), ownerId, status: safeStatus(input.status), dependencies: ids(context, input.dependencies) };
+    sources.set(id, input);
+    if (rows.length < maximum) rows.push(row);
+  }
+  return { rows, sources, agentIds };
+}
+function agentRows(context, nodes, state, nowMs, maximum) {
+  const intents = context.record(state.launchIntents, { optional: true });
+  const heartbeats = context.record(state.heartbeats, { optional: true });
+  const priority = new Map([['corrective', 0], ['running', 1], ['reserved', 2], ['ready', 3], ['blocked', 4], ['failed', 5], ['completed', 6]]);
+  const byAgent = new Map();
+  for (const node of nodes) {
+    const existing = byAgent.get(node.ownerId);
+    if (!existing || (priority.get(node.status) ?? 99) < (priority.get(existing.status) ?? 99)) byAgent.set(node.ownerId, node);
+  }
+  const result = [];
+  for (const node of byAgent.values()) {
+    if (result.length >= maximum) break;
+    const heartbeat = context.record(heartbeats[node.id], { optional: true });
+    const heartbeatMs = heartbeat.timestampMs;
+    const latestHeartbeatAt = isoFromMs(heartbeatMs);
+    const intent = context.record(intents[node.id], { optional: true });
+    const startedAtMs = intent.startedAtMs;
+    result.push({
+      id: node.ownerId, role: node.role, status: node.status, currentNodeId: node.id,
+      attempt: Math.max(1, integer(intent.attempt, 1)),
+      elapsedMs: Number.isSafeInteger(startedAtMs) && startedAtMs >= 0 && startedAtMs <= nowMs ? nowMs - startedAtMs : 0,
+      latestHeartbeatAt, heartbeatAgeMs: latestHeartbeatAt && heartbeatMs <= nowMs ? nowMs - heartbeatMs : null,
+    });
+  }
+  return result;
+}
+function worktreeRows(context, nodes, state) {
+  const byNode = new Map();
+  for (const node of nodes) byNode.set(node.id, node);
+  const intents = context.record(state.launchIntents, { optional: true });
+  const keys = Object.keys(intents).sort();
+  const rows = [];
+  for (const nodeId of keys) {
+    const node = byNode.get(nodeId);
+    const intent = context.record(intents[nodeId], { optional: true });
+    if (!node || intent.worktree === undefined || intent.worktree === null) continue;
+    context.record(intent.worktree);
+    rows.push({ nodeId, ownerId: node.ownerId, status: safeStatus(intent.status), displayPath: `.worktrees/${node.id}` });
+  }
+  return rows;
+}
+function publicHostname(hostname) {
+  const lower = hostname.toLowerCase();
+  if (!lower || lower === 'localhost' || lower.endsWith('.localhost') || lower.endsWith('.local') || lower.endsWith('.internal')) return false;
+  if (isIP(lower) !== 0) return false;
+  return lower.includes('.') && !lower.startsWith('.') && !lower.endsWith('.');
+}
+function safeEvidenceUrl(value) {
+  if (typeof value !== 'string' || value.length > 2_048) return null;
+  try {
+    const url = new URL(value);
+    if (url.protocol !== 'https:' || url.username || url.password || !publicHostname(url.hostname)) return null;
+    if (url.pathname.length > 1_024 || url.pathname.includes('%')) return null;
+    const segments = url.pathname === '/' ? [] : url.pathname.slice(1).split('/');
+    if (segments.some(segment => !SAFE_PATH_SEGMENT.test(segment)
+      || CREDENTIAL_PATH_SEGMENT.test(segment) || SECRET_TEXT.test(segment))) return null;
+    return `${url.origin}${url.pathname}`;
+  } catch { return null; }
+}
+function evidenceRows(context, state, maximum) {
+  const values = context.array(state.evidence, { optional: true });
+  const result = [];
+  for (let index = 0; index < Math.min(values.length, maximum); index += 1) {
+    const input = context.record(values[index]);
+    const row = { id: safeId(input.id) ?? 'unknown-evidence', nodeId: safeId(input.nodeId), type: safeStatus(input.type), approvalState: safeStatus(input.approvalState, 'pending') };
+    const url = safeEvidenceUrl(input.url);
+    if (url) row.url = url;
+    result.push(row);
+  }
+  return { rows: result, total: values.length };
+}
+function usageRecord(context, value) {
+  const input = context.record(value, { optional: true });
+  return { tokens: integer(input.tokens), costUsd: decimal(input.costUsd), retries: integer(input.retries), timeMinutes: integer(input.timeMinutes), taskLimit: integer(input.taskLimit) };
+}
+function earliestEventMs(events) {
+  for (const event of events) {
+    const value = Date.parse(event.timestamp);
+    if (Number.isFinite(value)) return value;
+  }
+  return null;
+}
+function currentStage(nodes) {
+  for (const status of ['corrective', 'running', 'reserved', 'ready']) for (const node of nodes) if (node.status === status) return node;
+  return nodes.length ? nodes[nodes.length - 1] : null;
+}
+
+function build(stateValue, optionsValue) {
+  const context = snapshotContext();
+  const state = context.record(stateValue);
+  const options = context.record(optionsValue, { optional: true });
+  const nowMs = Number.isSafeInteger(options.nowMs) && options.nowMs >= 0 ? options.nowMs : Date.now();
+  const configuredLimits = limits(context, options.limits);
+  const graph = context.record(state.graph);
+  const allNodes = context.array(graph.nodes, { optional: true });
+  const projectedGraph = graphRows(context, allNodes, configuredLimits.nodes);
+  const nodes = projectedGraph.rows;
+  const allEvents = context.array(state.events, { optional: true, maximum: INPUT_LIMITS.events });
+  const events = projectEvents(context, allEvents, { afterSequence: 0, maxEvents: configuredLimits.events, stringLength: configuredLimits.stringLength });
+  const agents = agentRows(context, nodes, state, nowMs, configuredLimits.agents);
+  const evidenceResult = evidenceRows(context, state, configuredLimits.evidence);
+  const evidence = evidenceResult.rows;
+  const gates = [];
+  for (const node of nodes) {
+    const source = projectedGraph.sources.get(node.id);
+    const gateId = safeId(source?.approvalGate);
+    if (gateId) gates.push({ id: gateId, nodeId: node.id, status: node.status, requiredEvidence: ids(context, source.requiredEvidenceTypes) });
+  }
+  const gateByNode = new Map();
+  for (const gate of gates) gateByNode.set(gate.nodeId, gate.id);
+  const humanDecisions = [];
+  for (const event of events) if (event.type === 'approval-recorded' && event.actor.role === 'human') humanDecisions.push({
+    id: event.id, gateId: gateByNode.get(event.nodeId) ?? 'activation', nodeId: event.nodeId ?? null,
+    decision: 'approved', decidedAt: event.timestamp, actorId: event.actor.id, evidenceRefs: event.evidenceRefs ?? [],
+  });
+  const attempts = context.record(state.attempts, { optional: true });
+  const correctiveWork = [];
+  for (const node of nodes) {
+    if (node.status !== 'corrective') continue;
+    let retry = null;
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+      if (events[index].type === 'retry' && events[index].nodeId === node.id) { retry = events[index]; break; }
+    }
+    correctiveWork.push({ nodeId: node.id, ownerId: node.ownerId, status: node.status, attempt: integer(attempts[node.id], 1), ...(retry?.retryReason ? { reason: retry.retryReason } : {}) });
+  }
+  const heartbeatTimes = [];
+  for (const agent of agents) if (agent.latestHeartbeatAt) heartbeatTimes.push(agent.latestHeartbeatAt);
+  heartbeatTimes.sort();
+  const startedAtMs = Number.isSafeInteger(state.startedAtMs) && state.startedAtMs >= 0 ? state.startedAtMs : earliestEventMs(events);
+  const stage = currentStage(nodes);
+  return deepFreeze({
+    schemaVersion: 1, generatedAt: new Date(nowMs).toISOString(),
+    goal: { id: safeId(graph.id) ?? 'unknown-goal', status: safeStatus(graph.status), version: integer(state.version), activated: state.activated === true, terminal: state.terminal === null ? null : safeStatus(state.terminal) },
+    currentStage: stage ? { nodeId: stage.id, status: stage.status } : null,
+    graph: { nodes }, agents, worktrees: worktreeRows(context, nodes, state), gates, correctiveWork, evidence, humanDecisions,
+    budget: { elapsedMs: startedAtMs !== null && startedAtMs <= nowMs ? nowMs - startedAtMs : 0, usage: usageRecord(context, state.usage), limits: usageRecord(context, state.limits) },
+    latestHeartbeatAt: heartbeatTimes.length ? heartbeatTimes[heartbeatTimes.length - 1] : null,
+    events,
+    truncated: { nodes: Math.max(0, allNodes.length - nodes.length), agents: Math.max(0, projectedGraph.agentIds.size - agents.length), events: Math.max(0, allEvents.length - events.length), evidence: Math.max(0, evidenceResult.total - evidence.length) },
+  });
+}
+
+export function buildStatusViewModel(state, options = {}) {
+  try { return build(state, options); } catch { invalid(); }
+}