@terminus-ai/cli 0.0.1

package/bin/dev-server-ops.mjs

@@ -0,0 +1,1086 @@
+/**
+ * An app's server code (`capabilities.server`) under `terminus dev`, run the
+ * way the platform runs it, so what works here works once published.
+ *
+ * Every op runs in a fresh process through the platform's own harness,
+ * vendored byte for byte in vendor/appd/: the same CommonJS wrapper and
+ * stdlib-only require table, the invocation and result files, and syscalls
+ * made by running an `agentos-terminus` command. That command relays its
+ * command line (by curl, or dev-server-binding.mjs without it) to the
+ * binding host below, which stands where the platform's does — outside the
+ * op's sandbox — and shapes each call and answer as the platform's binding
+ * host does, while the broker behind it answers with the platform's rules,
+ * limits and messages (terminus-backend: docs/app-server.md,
+ * bashd/server.js, src/routes/app_server/).
+ *
+ * The sandbox is Node's permission model: the op reads only its own files,
+ * writes only its copy of server/, has no network and next to no
+ * environment, and each call starts from a clean copy, so nothing carries
+ * from one call to the next except what the op stored through the
+ * platform. Records live in the dev data space: one pool per app (global)
+ * and one per member's installation.
+ */
+
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { accessSync, constants as fsConstants } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { readServerProgram } from "./apps.mjs";
+import { CliError } from "./client.mjs";
+import { fetchPublicPage } from "./dev-net.mjs";
+import { SERVER_PROTOCOL, runServerHarness, stopGroup } from "./server-sandbox.mjs";
+import { compareJson, compareStrings, jsonContains } from "./vendor/where.mjs";
+
+export { SERVER_PROTOCOL };
+
+const BINDING_SCRIPT = fileURLToPath(new URL("./dev-server-binding.mjs", import.meta.url));
+
+const LIMITS = SERVER_PROTOCOL.limits;
+const SYNC_OP_TIMEOUT_MS = LIMITS.sync_op_timeout_ms;
+/** The broker's own bound on a record id (records.rs MAX_DOC_ID_BYTES). */
+const MAX_DOC_ID_BYTES = 200;
+/** No cursor the records plane mints comes near this; anything longer is not one. */
+const MAX_CURSOR_CHARS = 4096;
+/** The broker ticket outlives the op's window by this margin (B5). */
+const TICKET_GRACE_MS = 60_000;
+/** A `server.run` step keeps the tail of the op's logs in the job result. */
+const JOB_LOG_TAIL_CHARS = 2000;
+/** The binding host's per-execution budget for bytes read out of the capsule. */
+const MAX_HYDRATION_TOTAL_BYTES = 16 * 1024 * 1024;
+/** The binding host's per-call deadline, inside the op's own window. */
+const BROKER_CALL_TIMEOUT_MS = 15_000;
+const BROKER_TIMED_OUT = Symbol("broker call timed out");
+/** One file handed to the op must fit the sandbox's captured output. */
+const MAX_HYDRATION_FILE_BYTES = 4 * 1024 * 1024;
+/**
+ * The sandbox's cap on one command line (`maxProcessArgvBytes` on the
+ * platform's server tier: its 256 KiB script budget + 4 KiB). A syscall's
+ * arguments ride its command line, so a bigger `records.put` or
+ * `capsule.write` never starts — well before those actions' own limits.
+ * (On a Linux host the kernel refuses any one argument over 128 KiB first.)
+ */
+const MAX_PROCESS_ARGV_BYTES = 256 * 1024 + 4096;
+const MAX_RELAY_BODY_BYTES = 8 * 1024 * 1024;
+/** The chat lane's model cap, which server web fetches share. */
+const WEB_FETCH_BODY_CHARS = 48 * 1024;
+/** Who the server-op lane's fetches say they are. */
+const SERVER_FETCH_USER_AGENT = "terminus-appd-fetch/1.0";
+
+/** A coded failure, answered with the platform's `{error: {code, message}}`. */
+export function serverError(status, code, message) {
+  return Object.assign(new CliError(message), { status, apiCode: code });
+}
+
+/** A member's installation, as `terminus dev` names it everywhere. */
+export function devInstallationId(member) {
+  return `dev-${member}`;
+}
+
+/**
+ * The platform re-serializes every JSON value through a sorted map, so
+ * objects reach app code with their keys in byte order at every depth.
+ */
+export function sortKeysBytewise(value) {
+  if (Array.isArray(value)) return value.map(sortKeysBytewise);
+  if (value && typeof value === "object") {
+    const sorted = {};
+    for (const key of Object.keys(value).sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)))) {
+      sorted[key] = sortKeysBytewise(value[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+/** A number as PostgreSQL's numeric prints it: plain digits, no exponent. */
+function jsonbNumber(number) {
+  if (!Number.isFinite(number)) return "null";
+  const text = String(number);
+  if (!/e/i.test(text)) return text;
+  const [mantissa, exponentText] = text.toLowerCase().split("e");
+  const negative = mantissa.startsWith("-");
+  const unsigned = negative ? mantissa.slice(1) : mantissa;
+  const dot = unsigned.indexOf(".");
+  const digits = unsigned.replace(".", "");
+  const point = (dot === -1 ? unsigned.length : dot) + Number(exponentText);
+  let plain;
+  if (point <= 0) plain = `0.${"0".repeat(-point)}${digits}`;
+  else if (point >= digits.length) plain = digits + "0".repeat(point - digits.length);
+  else plain = `${digits.slice(0, point)}.${digits.slice(point)}`;
+  return negative ? `-${plain}` : plain;
+}
+
+function compareJsonbKeys(left, right) {
+  const leftBytes = Buffer.from(left);
+  const rightBytes = Buffer.from(right);
+  if (leftBytes.length !== rightBytes.length) return leftBytes.length - rightBytes.length;
+  return Buffer.compare(leftBytes, rightBytes);
+}
+
+/**
+ * A value as `jsonb::text` prints it — the length the platform counts a
+ * stored record at when it is replaced or deleted (`octet_length(data::text)`).
+ */
+export function jsonbText(value) {
+  if (value === null || value === undefined) return "null";
+  if (Array.isArray(value)) return `[${value.map(jsonbText).join(", ")}]`;
+  switch (typeof value) {
+    case "string":
+      return JSON.stringify(value);
+    case "number":
+      return jsonbNumber(value);
+    case "boolean":
+      return value ? "true" : "false";
+    case "object": {
+      const keys = Object.keys(value).sort(compareJsonbKeys);
+      return `{${keys.map((key) => `${JSON.stringify(key)}: ${jsonbText(value[key])}`).join(", ")}}`;
+    }
+    default:
+      return "null";
+  }
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", "'\\''")}'`;
+}
+
+/** The last `count` characters of the op's logs. */
+function logTail(logs, count) {
+  const characters = [...logs];
+  return characters.length <= count ? logs : characters.slice(-count).join("");
+}
+
+/** The `capabilities.collect` channels a server op may submit on. */
+function documentsChannels(capabilities) {
+  const channels = capabilities?.collect?.channels;
+  if (!isPlainObject(channels)) return [];
+  return Object.entries(channels)
+    .filter(([, channel]) => channel?.kind === "documents")
+    .map(([name]) => name);
+}
+
+/**
+ * A refused syscall as the binding host frames it on the op's stderr
+ * (server-protocol.json `errors.format`): "<action> failed [<code> <status>]:
+ * <message>". The platform's harness parses the frame back into the Error it
+ * throws, so an op branches on `error.code` and `error.status`, never on the
+ * message; a failure nobody framed reaches it as internal_error / 500.
+ */
+export function bindingFailure(action, code, status, message) {
+  return new Error(`${action} failed [${code} ${status}]: ${message}`);
+}
+
+// ── the records plane's queries ───────────────────────────────────────────
+// terminus-backend src/routes/app_server/records.rs: one page of a pool's
+// collection, filtered by containment, in doc-id order or by one top-level
+// field, cut at `limit` documents and 4 MiB, resumed by an opaque cursor.
+
+/** Echo a caller's string back in an error without echoing a novel. */
+function shown(raw) {
+  const characters = [...raw];
+  return characters.length <= 64 ? raw : `${characters.slice(0, 64).join("")}...`;
+}
+
+const queryRefusal = (message) => serverError(400, "bad_request", message);
+
+/**
+ * The order a query reads in: `field` ascending, `-field` descending — ONE
+ * top-level key of 1-64 letters, digits, '_', '-' or '.' (dots are literal
+ * characters, never a path) — and nothing for the doc-id order. `spec` is
+ * the spelling a cursor is bound to.
+ */
+export function parseRecordSort(raw) {
+  const text = typeof raw === "string" ? raw.trim() : "";
+  if (!text) return { spec: "", field: null, descending: false };
+  const descending = text.startsWith("-");
+  const field = descending ? text.slice(1) : text;
+  if (!field || field.length > 64 || !/^[A-Za-z0-9_.-]+$/u.test(field)) {
+    throw queryRefusal(
+      `invalid sort '${shown(text)}': sort names one top-level field (\`field\` ascending, \`-field\` descending) of 1-64 letters, digits, '_', '-' or '.'`,
+    );
+  }
+  return { spec: text, field, descending };
+}
+
+/** Where a page stopped, as callers carry it: base64url of `{s, k?, d}` —
+ * the sort it pages, the last document's sort value as JSON text (absent in
+ * the id order and for a document that lacked the field) and its doc id. */
+function encodeCursor(spec, key, docId) {
+  const cursor = key === null ? { s: spec, d: docId } : { s: spec, k: key, d: docId };
+  return Buffer.from(JSON.stringify(cursor)).toString("base64url");
+}
+
+const UTF8 = new TextDecoder("utf-8", { fatal: true });
+
+/** A cursor this plane minted for `sort`, or a bad_request naming why not. */
+function decodeCursor(raw, sort) {
+  const refused = () => queryRefusal("'after' is not a cursor a records query returned");
+  if (raw.length > MAX_CURSOR_CHARS || !/^[A-Za-z0-9_-]*$/u.test(raw)) throw refused();
+  const bytes = Buffer.from(raw, "base64url");
+  // Canonical unpadded base64url only: the platform's decoder takes nothing else.
+  if (bytes.toString("base64url") !== raw) throw refused();
+  let cursor;
+  try {
+    cursor = JSON.parse(UTF8.decode(bytes));
+  } catch {
+    throw refused();
+  }
+  if (!isPlainObject(cursor) || typeof cursor.s !== "string" || typeof cursor.d !== "string"
+    || (cursor.k !== undefined && cursor.k !== null && typeof cursor.k !== "string")) {
+    throw refused();
+  }
+  if (cursor.s !== sort.spec) {
+    throw queryRefusal(`'after' continues the sort '${shown(cursor.s)}', not '${sort.spec}'; start again without 'after'`);
+  }
+  if (!cursor.d || Buffer.byteLength(cursor.d) > MAX_DOC_ID_BYTES) throw refused();
+  const key = cursor.k ?? null;
+  if (key === null) return { docId: cursor.d, key: null };
+  // Only a scalar's JSON text is ever minted into a cursor.
+  if (!sort.field || Buffer.byteLength(key) > LIMITS.records_sort_value_bytes || /^\s*[[{]/u.test(key)) throw refused();
+  let value;
+  try {
+    value = JSON.parse(key);
+  } catch {
+    throw refused();
+  }
+  return { docId: cursor.d, key, value };
+}
+
+/** At most `limit` documents and — past the first — at most 4 MiB of their
+ * data; whether rows remain after the page. */
+function cutPage(rows, limit) {
+  const page = [];
+  let bytes = 0;
+  for (const row of rows) {
+    if (page.length >= limit) break;
+    const size = Buffer.byteLength(JSON.stringify(row.data));
+    if (page.length && bytes + size > LIMITS.records_query_page_bytes) break;
+    bytes += size;
+    page.push(row);
+  }
+  return { page, more: rows.length > page.length };
+}
+
+/**
+ * One page of `rows` (one pool's collection: `{docId, data, version}`) the
+ * way the platform reads it. `where` is a containment filter; `sort` orders
+ * by one top-level field as JSONB orders values (JSON null lowest, strings,
+ * numbers numerically, booleans), a record lacking the field after every
+ * record holding it in either direction, ties by doc id; a record whose sort
+ * field holds an object, an array or a value whose JSON text passes 1 KiB
+ * fails the query on every page. `limit` is 1-100 (100 when absent), never
+ * clamped. Answers `{documents: [{doc_id, data, version}], next_cursor}`.
+ */
+export function queryServerRecords(rows, { where = null, sort = null, after = null, limit = null } = {}) {
+  if (where !== null && !isPlainObject(where)) {
+    throw queryRefusal("'where' must be a JSON object (containment match)");
+  }
+  const order = parseRecordSort(sort);
+  let size = LIMITS.records_query_limit;
+  if (limit !== null) {
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > LIMITS.records_query_limit) {
+      throw queryRefusal(
+        `limit ${limit} is out of range: a page holds 1-${LIMITS.records_query_limit} records; read on with next_cursor`,
+      );
+    }
+    size = limit;
+  }
+  const resume = typeof after === "string" && after.trim() ? decodeCursor(after.trim(), order) : null;
+  const matching = rows.filter((row) => where === null || jsonContains(row.data, where));
+  const byDocId = (left, right) => compareStrings(left.docId, right.docId);
+  let read;
+  let keyOf = () => null;
+  if (!order.field) {
+    read = matching
+      .filter((row) => !resume || compareStrings(row.docId, resume.docId) > 0)
+      .sort(byDocId);
+  } else {
+    // 0: a value no page can order by; 1: a sortable value; 2: no field.
+    const ranked = matching.map((row) => {
+      const value = isPlainObject(row.data) && Object.hasOwn(row.data, order.field) ? row.data[order.field] : undefined;
+      if (value === undefined) return { row, rank: 2, value };
+      const text = jsonbText(value);
+      const unorderable = Array.isArray(value) || isPlainObject(value)
+        || Buffer.byteLength(text) > LIMITS.records_sort_value_bytes;
+      return { row, rank: unorderable ? 0 : 1, value, text };
+    });
+    const direction = order.descending ? -1 : 1;
+    const afterResume = (item) => {
+      if (!resume || item.rank === 0) return true;
+      if (resume.key === null) return item.rank === 2 && compareStrings(item.row.docId, resume.docId) > 0;
+      if (item.rank === 2) return true;
+      const compared = compareJson(item.value, resume.value) * direction;
+      return compared > 0 || (compared === 0 && compareStrings(item.row.docId, resume.docId) > 0);
+    };
+    const ordered = ranked.filter(afterResume).sort((left, right) => (left.rank - right.rank)
+      || (left.rank === 2 ? 0 : compareJson(left.value, right.value) * direction)
+      || byDocId(left.row, right.row));
+    const first = ordered[0];
+    if (first?.rank === 0) {
+      const type = Array.isArray(first.value) ? "array" : isPlainObject(first.value) ? "object"
+        : first.value === null ? "null" : typeof first.value;
+      const holds = type === "object" ? "an object" : type === "array" ? "an array"
+        : `a ${type} longer than ${LIMITS.records_sort_value_bytes} bytes as JSON`;
+      throw queryRefusal(
+        `record '${first.row.docId}' holds ${holds} in sort field '${order.field}'; sort by a field holding strings, numbers, booleans or null`,
+      );
+    }
+    const keys = new Map(ordered.map((item) => [item.row, item.rank === 1 ? item.text : null]));
+    keyOf = (row) => keys.get(row);
+    read = ordered.map((item) => item.row);
+  }
+  const { page, more } = cutPage(read.slice(0, size + 1), size);
+  const last = page.at(-1);
+  return {
+    documents: page.map((row) => ({ data: sortKeysBytewise(row.data), doc_id: row.docId, version: row.version })),
+    next_cursor: more && last ? encodeCursor(order.spec, keyOf(last), last.docId) : null,
+  };
+}
+
+// ── the server-op fetch lane ──────────────────────────────────────────────
+
+/**
+ * The broker's `web_fetch`, as the platform's server-op lane makes it
+ * (terminus-backend `web_fetch_for_server_op`): the one guarded public-text
+ * fetch the app's own `net.fetch` door uses (dev-net.mjs, `fetch_public_text`
+ * upstream) under the server lane's user agent — the whole page, or a refusal
+ * past 512 KiB, never its start. Its refusals are the platform's typed ones
+ * (url_not_allowed 400, upstream_failed 502, payload_too_large 413,
+ * deadline_exceeded 504), which the binding host frames for the op like any
+ * broker refusal. `options` are the net door's test seams (`fetchImpl`,
+ * `timeoutMs`).
+ */
+export function fetchPublicText(rawUrl, options = {}) {
+  return fetchPublicPage(rawUrl, { ...options, partial: false, userAgent: SERVER_FETCH_USER_AGENT });
+}
+
+// ── the sync door ─────────────────────────────────────────────────────────
+
+async function readLimitedBody(request, limit) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > limit) return null;
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * `POST /_terminus/server/{op}` with `{"input": value}` → `{"result": value}`.
+ * The dev host reads the body the way every JSON door does (content type,
+ * body limit, an object with no unknown field) and hands it here parsed.
+ */
+export async function answerServerDoor(tier, member, opName, body, response) {
+  const { output } = await tier.invoke(member, opName, body.input === undefined ? null : body.input, "sync");
+  response.writeHead(200, { "content-type": "application/json" });
+  response.end(JSON.stringify({ result: output }));
+}
+
+// ── the binding host ──────────────────────────────────────────────────────
+
+function parseBindingFlags(binding, args) {
+  const input = {};
+  for (let index = 0; index < args.length; index += 2) {
+    const flag = args[index];
+    if (!flag.startsWith("--") || index + 1 >= args.length) {
+      throw new Error(`invalid arguments for ${binding}`);
+    }
+    input[flag.slice(2)] = args[index + 1];
+  }
+  return input;
+}
+
+function requireBindingFields(input, required) {
+  for (const field of required) {
+    if (typeof input[field] !== "string") throw new Error(`invalid input: '${field}' must be a string`);
+  }
+  return input;
+}
+
+/** A binding's JSON argument; text that is not JSON is refused before any
+ * broker call, framed like the broker's own refusals. */
+function parseJsonArgument(action, name, text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw bindingFailure(action, "bad_request", 400, `'${name}' must be valid JSON text`);
+  }
+}
+
+/** The bytes one command line takes: every argument and its terminator. */
+function commandLineBytes(args) {
+  return ["agentos-terminus", ...args].reduce((total, arg) => total + Buffer.byteLength(arg) + 1, 0);
+}
+
+/** The first curl on PATH that can relay (--fail-with-body needs 7.76), or null. */
+function findRelayCurl() {
+  for (const directory of String(process.env.PATH ?? "").split(path.delimiter)) {
+    if (!directory || !path.isAbsolute(directory)) continue;
+    const candidate = path.join(directory, "curl");
+    try {
+      accessSync(candidate, fsConstants.X_OK);
+    } catch {
+      continue;
+    }
+    const probe = spawnSync(candidate, ["--version"], { encoding: "utf8" });
+    const version = /^curl (\d+)\.(\d+)/.exec(String(probe.stdout ?? ""));
+    if (!version) continue;
+    const [major, minor] = [Number(version[1]), Number(version[2])];
+    if (major > 7 || (major === 7 && minor >= 76)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * The server-op syscalls exactly as the platform's binding host defines
+ * them (terminus-backend bashd/server.js): the flags each takes, the one
+ * broker action each makes, and the fields each answers with.
+ */
+export const SERVER_BINDINGS = {
+  "records-get": {
+    capability: "records",
+    required: ["scope", "collection", "doc"],
+    async run(call, { scope, collection, doc }) {
+      const payload = await call("records_get", { scope, collection, doc_id: doc });
+      return {
+        found: payload.found === true,
+        doc: payload.found === true ? (payload.doc ?? null) : null,
+        version: Number(payload.version) || 0,
+      };
+    },
+  },
+  "records-put": {
+    capability: "records",
+    required: ["scope", "collection", "doc", "data"],
+    async run(call, { scope, collection, doc, data, version }) {
+      const parsed = parseJsonArgument("records_put", "data", data);
+      const payload = await call("records_put", {
+        scope,
+        collection,
+        doc_id: doc,
+        data: parsed,
+        ...(version == null ? {} : { if_version: Number(version) || 0 }),
+      });
+      return { version: Number(payload.version) || 0 };
+    },
+  },
+  "records-delete": {
+    capability: "records",
+    required: ["scope", "collection", "doc"],
+    async run(call, { scope, collection, doc, version }) {
+      const payload = await call("records_delete", {
+        scope,
+        collection,
+        doc_id: doc,
+        ...(version == null ? {} : { if_version: Number(version) || 0 }),
+      });
+      return { deleted: payload.deleted === true };
+    },
+  },
+  "records-query": {
+    capability: "records",
+    required: ["scope", "collection"],
+    async run(call, { scope, collection, where, sort, after, limit }) {
+      const filter = where == null ? null : parseJsonArgument("records_query", "where", where);
+      const payload = await call("records_query", {
+        scope,
+        collection,
+        ...(filter == null ? {} : { where: filter }),
+        ...(sort == null ? {} : { sort }),
+        ...(after == null ? {} : { after }),
+        ...(limit == null ? {} : { limit: Number(limit) || 0 }),
+      });
+      const documents = Array.isArray(payload.documents) ? payload.documents : [];
+      return {
+        documents: documents.map((row) => ({
+          doc: String(row && row.doc_id != null ? row.doc_id : ""),
+          data: row && row.data !== undefined ? row.data : null,
+          version: Number(row && row.version) || 0,
+        })),
+        next_cursor: typeof payload.next_cursor === "string" ? payload.next_cursor : null,
+      };
+    },
+  },
+  "capsule-read": {
+    capability: "capsule",
+    required: ["path"],
+    async run(call, { path: requested }, ticket) {
+      const payload = await call("capsule_read", { path: String(requested || "") });
+      const bytes = Buffer.from(String(payload.content_b64 || ""), "base64");
+      if (bytes.length > MAX_HYDRATION_FILE_BYTES) {
+        throw bindingFailure("capsule_read", "payload_too_large", 413, "capsule file exceeds the hydration budget");
+      }
+      ticket.hydratedBytes += bytes.length;
+      if (ticket.hydratedBytes > MAX_HYDRATION_TOTAL_BYTES) {
+        throw bindingFailure(
+          "capsule_read",
+          "payload_too_large",
+          413,
+          "the hydration byte budget for this execution is exhausted",
+        );
+      }
+      return {
+        path: typeof payload.path === "string" ? payload.path : String(requested || ""),
+        size_bytes: bytes.length,
+        content_b64: bytes.toString("base64"),
+      };
+    },
+  },
+  "capsule-write": {
+    capability: "capsule",
+    required: ["path", "content"],
+    async run(call, { path: requested, content }) {
+      const payload = await call("capsule_write", {
+        path: String(requested || ""),
+        content_b64: String(content || ""),
+      });
+      return {
+        path: typeof payload.path === "string" ? payload.path : String(requested || ""),
+        size_bytes: Number(payload.size_bytes) || 0,
+      };
+    },
+  },
+  "web-fetch": {
+    capability: "web_fetch",
+    required: ["url"],
+    async run(call, { url }) {
+      const payload = await call("web_fetch", { url });
+      return {
+        status: Number(payload.status) || 0,
+        url: typeof payload.url === "string" ? payload.url : url,
+        content_type: typeof payload.content_type === "string" ? payload.content_type : "",
+        body: typeof payload.body === "string" ? payload.body : "",
+        truncated: payload.truncated === true,
+      };
+    },
+  },
+  "egress-invoke": {
+    capability: "egress",
+    required: ["template"],
+    async run(call, { template, params }) {
+      const parsedParams = params == null ? {} : parseJsonArgument("egress_invoke", "params", params);
+      const payload = await call("egress_invoke", { template: String(template || ""), params: parsedParams });
+      return {
+        status: Number(payload.status) || 0,
+        content_type: typeof payload.content_type === "string" ? payload.content_type : "",
+        body: typeof payload.body === "string" ? payload.body : "",
+        body_b64: typeof payload.body_b64 === "string" ? payload.body_b64 : "",
+        truncated: payload.truncated === true,
+      };
+    },
+  },
+  "collect-submit": {
+    capability: "collect",
+    required: ["channel", "payload"],
+    async run(call, { channel, payload: payloadText }) {
+      const parsed = parseJsonArgument("collect_submit", "payload", payloadText);
+      const payload = await call("collect_submit", { channel: String(channel || ""), payload: parsed });
+      return {
+        id: typeof payload.id === "string" ? payload.id : "",
+        delivered: payload.delivered === true,
+      };
+    },
+  },
+};
+
+// ── the tier ──────────────────────────────────────────────────────────────
+
+/**
+ * The server tier for one `terminus dev` session.
+ *
+ * - `manifest`: the compiled package manifest (`capabilities.server` is the
+ *   contract, exactly as a release pins it).
+ * - `store`: the dev system store (the records plane).
+ * - `capsule`: `{read(member, path) → Buffer, write(member, path, bytes)}` over
+ *   the member's private data, as the app's own data doors see it.
+ * - `collect(member, channel, payload)` → `{id, delivered}`.
+ * - `fetchText(url)`: the web fetch lane, `fetchPublicText` (the dev host
+ *   hands it the net doors' stand-in for the public web in tests).
+ * - `log(line)`: where op logs and outcomes are printed.
+ * - `relay`: "auto" (curl when it can, else node), or "curl"/"node" (tests).
+ */
+export function createDevServerTier({
+  dir,
+  manifest,
+  store,
+  capsule,
+  collect,
+  fetchText = fetchPublicText,
+  log = (line) => console.log(line),
+  relay = "auto",
+}) {
+  const capabilities = manifest.capabilities ?? {};
+  const tickets = new Map();
+  /** Ops running now: closing the session stops them. */
+  const running = new Set();
+  let bindingHost = null;
+  let bindingHostUrl = null;
+  /** The curl that relays syscalls (null: none can), found on first use. */
+  let relayCurl;
+
+  function recordScope(raw) {
+    return raw === "global" || raw === "installation" ? raw : null;
+  }
+
+  function requireDeclaredRecords(scope, collection) {
+    const records = capabilities.server?.records;
+    const scopes = Array.isArray(records?.scopes) ? records.scopes : [];
+    const collections = Array.isArray(records?.collections) ? records.collections : [];
+    if (!scopes.includes(scope) || !collections.includes(collection)) {
+      throw serverError(403, "forbidden", `the release does not declare server records for '${scope}' / '${collection}'`);
+    }
+  }
+
+  function requireGrant(ticket, capability, what) {
+    if (!ticket.capabilities.has(capability)) {
+      throw serverError(403, "forbidden", `this execution's ticket does not grant ${what}`);
+    }
+  }
+
+  function trimmed(value) {
+    return typeof value === "string" ? value.trim() : "";
+  }
+
+  /** One broker action (terminus-backend src/routes/app_server/broker.rs). */
+  async function brokerAction(ticket, body) {
+    const action = String(body.action ?? "");
+    switch (action) {
+      case "records_get":
+      case "records_put":
+      case "records_delete":
+      case "records_query": {
+        requireGrant(ticket, "records", "records");
+        const scope = recordScope(body.scope);
+        if (!scope) throw serverError(400, "bad_request", "scope must be 'global' or 'installation'");
+        const collection = trimmed(body.collection);
+        if (!collection) throw serverError(400, "bad_request", "records actions require 'collection'");
+        requireDeclaredRecords(scope, collection);
+        const installationId = scope === "installation" ? ticket.installationId : null;
+        if (action === "records_query") {
+          return queryServerRecords(store.serverRecords({ scope, installationId, collection }), {
+            where: body.where ?? null,
+            sort: body.sort ?? null,
+            after: body.after ?? null,
+            limit: body.limit ?? null,
+          });
+        }
+        const docId = trimmed(body.doc_id);
+        if (!docId || Buffer.byteLength(docId) > 200) {
+          throw serverError(400, "bad_request", "records actions require 'doc_id'");
+        }
+        const key = { scope, installationId, collection, docId };
+        const ifVersion = body.if_version === undefined || body.if_version === null
+          ? null
+          : Math.trunc(Number(body.if_version));
+        if (action === "records_get") {
+          const found = store.serverRecord(key);
+          return found
+            ? { doc: sortKeysBytewise(found.data), found: true, version: found.version }
+            : { doc: null, found: false, version: 0 };
+        }
+        if (action === "records_put") {
+          if (body.data === undefined || body.data === null) {
+            throw serverError(400, "bad_request", "records_put requires 'data'");
+          }
+          const dataJson = JSON.stringify(body.data);
+          const newBytes = Buffer.byteLength(dataJson);
+          if (newBytes > LIMITS.record_doc_bytes) {
+            throw serverError(413, "payload_too_large", `record is ${newBytes} bytes; the per-record budget is ${LIMITS.record_doc_bytes}`);
+          }
+          const quotaBytes = scope === "global" ? LIMITS.records_global_quota_bytes : LIMITS.records_installation_quota_bytes;
+          const outcome = store.putServerRecord({
+            ...key,
+            dataJson,
+            newBytes,
+            storedBytes: Buffer.byteLength(jsonbText(body.data)),
+            ifVersion,
+            quotaBytes,
+          });
+          // A compare-and-set miss is a version_conflict (the words keep the
+          // phrases older server code matches on); a full pool is a quota,
+          // and the refused write never happened.
+          if (outcome.conflict) throw serverError(409, "version_conflict", outcome.conflict);
+          if (outcome.overQuota !== undefined) {
+            throw serverError(
+              402,
+              "quota_exceeded",
+              `this write would put the app's ${scope} records at ${outcome.overQuota} bytes; the quota is ${quotaBytes}`,
+            );
+          }
+          return { version: outcome.version };
+        }
+        const outcome = store.deleteServerRecord({ ...key, ifVersion });
+        if (outcome.conflict) throw serverError(409, "version_conflict", outcome.conflict);
+        return { deleted: outcome.deleted };
+      }
+      case "capsule_read":
+      case "capsule_write": {
+        requireGrant(ticket, "capsule", "capsule access");
+        const requested = trimmed(body.path);
+        if (!requested) throw serverError(400, "bad_request", "capsule actions require 'path'");
+        if (action === "capsule_read") {
+          const bytes = await capsule.read(ticket.member, requested);
+          if (bytes.length > LIMITS.capsule_file_bytes) {
+            throw serverError(413, "payload_too_large", `'${requested}' is ${bytes.length} bytes; server capsule reads are capped at ${LIMITS.capsule_file_bytes}`);
+          }
+          return { content_b64: bytes.toString("base64"), path: requested, size_bytes: bytes.length };
+        }
+        const encoded = typeof body.content_b64 === "string" ? body.content_b64 : "";
+        if (encoded.length % 4 !== 0 || !/^[A-Za-z0-9+/]*={0,2}$/.test(encoded)) {
+          throw serverError(400, "bad_request", "capsule_write requires base64 'content_b64'");
+        }
+        const bytes = Buffer.from(encoded, "base64");
+        if (bytes.length > LIMITS.capsule_file_bytes) {
+          throw serverError(413, "payload_too_large", `'${requested}' is ${bytes.length} bytes; server capsule writes are capped at ${LIMITS.capsule_file_bytes}`);
+        }
+        await capsule.write(ticket.member, requested, bytes);
+        return { path: requested, size_bytes: bytes.length };
+      }
+      case "web_fetch": {
+        requireGrant(ticket, "web_fetch", "web_fetch");
+        const url = trimmed(body.url);
+        if (!url) throw serverError(400, "bad_request", "web_fetch requires 'url'");
+        const day = new Date().toISOString().slice(0, 10);
+        if (store.bumpServerFetches(ticket.installationId, day) > LIMITS.web_fetches_per_installation_per_day) {
+          throw serverError(
+            429,
+            "rate_limited",
+            `this installation has used its ${LIMITS.web_fetches_per_installation_per_day} server web fetches for today`,
+          );
+        }
+        const fetched = await fetchText(url);
+        const characters = [...String(fetched.body ?? "")];
+        const truncated = characters.length > WEB_FETCH_BODY_CHARS;
+        return {
+          body: truncated ? characters.slice(0, WEB_FETCH_BODY_CHARS).join("") : String(fetched.body ?? ""),
+          content_type: fetched.content_type ?? "",
+          status: fetched.status ?? 0,
+          truncated,
+          url: fetched.url ?? url,
+        };
+      }
+      case "collect_submit": {
+        requireGrant(ticket, "collect", "collect");
+        const channel = trimmed(body.channel);
+        if (!channel) throw serverError(400, "bad_request", "collect_submit requires 'channel'");
+        const payload = body.payload === undefined ? null : body.payload;
+        if (Buffer.byteLength(JSON.stringify(payload)) > LIMITS.collect_payload_bytes) {
+          throw serverError(413, "payload_too_large", `a collect submission is capped at ${LIMITS.collect_payload_bytes} bytes`);
+        }
+        return collect(ticket.member, channel, payload);
+      }
+      case "egress_invoke":
+        throw serverError(403, "forbidden", "egress from server code is reserved and not yet enabled");
+      default:
+        throw serverError(400, "bad_request", `unknown server-broker action '${action}'`);
+    }
+  }
+
+  /** Each syscall is one broker call; an execution gets 600 a minute. */
+  function countBrokerCall(ticket) {
+    const minute = Math.floor(Date.now() / 60_000);
+    if (ticket.minute !== minute) {
+      ticket.minute = minute;
+      ticket.calls = 0;
+    }
+    ticket.calls += 1;
+    if (ticket.calls > LIMITS.broker_calls_per_minute) {
+      throw serverError(429, "rate_limited", `server broker is limited to ${LIMITS.broker_calls_per_minute} attempts per minute`);
+    }
+  }
+
+  /**
+   * One broker call as the binding host makes it: JSON on the wire, inside
+   * the op's window and 15 s at most, and a refusal reaching the op framed
+   * "<action> failed [<code> <status>]: <message>" — the broker's catalogue
+   * code and status, deadline_exceeded for a call past its deadline,
+   * upstream_failed for an answer that is not JSON, internal_error for the
+   * broker's own failure.
+   */
+  async function callBroker(ticket, action, payload) {
+    const budget = Math.max(1000, Math.min(BROKER_CALL_TIMEOUT_MS, ticket.deadlineAt - Date.now()));
+    let timer;
+    const expired = new Promise((resolve) => {
+      timer = setTimeout(() => resolve(BROKER_TIMED_OUT), budget);
+    });
+    try {
+      countBrokerCall(ticket);
+      const answer = await Promise.race([
+        brokerAction(ticket, JSON.parse(JSON.stringify({ action, ...payload }))),
+        expired,
+      ]);
+      if (answer === BROKER_TIMED_OUT) {
+        throw serverError(504, "deadline_exceeded", "the platform did not answer in time");
+      }
+      if (!answer || typeof answer !== "object") {
+        throw serverError(502, "upstream_failed", "the platform answered with invalid JSON");
+      }
+      return answer;
+    } catch (error) {
+      const coded = typeof error?.apiCode === "string" && Number.isInteger(error?.status);
+      throw bindingFailure(
+        action,
+        coded ? error.apiCode : "internal_error",
+        coded ? error.status : 500,
+        String(error?.message ?? error),
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  /** One `agentos-terminus <binding> --flag value ...` command, run for the op. */
+  async function runBinding(ticket, args) {
+    const [binding = "", ...flags] = args;
+    const definition = Object.hasOwn(SERVER_BINDINGS, binding) ? SERVER_BINDINGS[binding] : null;
+    // A binding exists only when the execution was granted its syscall.
+    if (!definition || !ticket.capabilities.has(definition.capability)) {
+      throw new Error(`Unknown binding "terminus:${binding}"`);
+    }
+    const input = requireBindingFields(parseBindingFlags(binding, flags), definition.required);
+    return definition.run((action, payload) => callBroker(ticket, action, payload), input, ticket);
+  }
+
+  /**
+   * The binding host's door: the relay posts the command line (each argument
+   * one form field `a`) and prints what comes back — the envelope on stdout,
+   * or the message on stderr with exit status 1.
+   */
+  async function answerBindingHost(request, response) {
+    const answer = (status, type, text) => {
+      response.writeHead(status, { "content-type": type });
+      response.end(text);
+    };
+    if (request.method !== "POST") return answer(405, "text/plain; charset=utf-8", "the binding host takes POST");
+    const raw = await readLimitedBody(request, MAX_RELAY_BODY_BYTES);
+    const args = raw === null ? null : new URLSearchParams(raw).getAll("a");
+    if (args === null || commandLineBytes(args) > MAX_PROCESS_ARGV_BYTES) {
+      // The sandbox's process table caps one command line: an oversized
+      // syscall never starts, and the harness says so as it says any failed
+      // spawn — unframed, so the op sees internal_error.
+      return answer(400, "text/plain; charset=utf-8", `${args?.[0] || "agentos-terminus"} failed: spawnSync agentos-terminus E2BIG`);
+    }
+    const header = String(request.headers.authorization ?? "");
+    const ticket = header.startsWith("Bearer ") ? tickets.get(header.slice("Bearer ".length)) : null;
+    if (!ticket || ticket.expiresAt < Date.now()) {
+      const binding = args[0] ?? "";
+      const action = Object.hasOwn(SERVER_PROTOCOL.bindings, binding) ? SERVER_PROTOCOL.bindings[binding] : binding;
+      return answer(401, "text/plain; charset=utf-8", bindingFailure(action, "unauthorized", 401, "valid bearer token required").message);
+    }
+    try {
+      const result = await runBinding(ticket, args);
+      answer(200, "application/json", JSON.stringify({ ok: true, result }));
+    } catch (error) {
+      answer(400, "text/plain; charset=utf-8", String(error?.message ?? error));
+    }
+  }
+
+  async function ensureBindingHost() {
+    if (bindingHostUrl) return bindingHostUrl;
+    bindingHost = createServer((request, response) => {
+      answerBindingHost(request, response).catch(() => {
+        if (!response.headersSent) response.writeHead(500);
+        response.end();
+      });
+    });
+    await new Promise((resolve, reject) => {
+      bindingHost.once("error", reject);
+      bindingHost.listen(0, "127.0.0.1", () => {
+        bindingHost.off("error", reject);
+        resolve();
+      });
+    });
+    bindingHostUrl = `http://127.0.0.1:${bindingHost.address().port}/`;
+    return bindingHostUrl;
+  }
+
+  /**
+   * The op's `agentos-terminus`: a relay to the binding host, which stays
+   * outside the sandbox. curl starts in a fraction of Node's time, so it
+   * carries the call when it can (--fail-with-body needs curl 7.76).
+   */
+  async function writeRelay(hostDir, token) {
+    const url = await ensureBindingHost();
+    if (relayCurl === undefined) relayCurl = relay === "node" ? null : findRelayCurl();
+    if (relay === "curl" && !relayCurl) throw serverError(503, "server_unavailable", "no curl (7.76 or later) to relay syscalls");
+    const relayPath = path.join(hostDir, "agentos-terminus");
+    if (relayCurl) {
+      const headerFile = path.join(hostDir, "authorization");
+      await writeFile(headerFile, `authorization: Bearer ${token}\n`, { mode: 0o600 });
+      await writeFile(relayPath, [
+        "#!/bin/sh",
+        // The binding's action (records-put → records_put), for a refusal the
+        // relay has to frame itself — from the protocol's own table, since
+        // the op's PATH holds nothing but this relay.
+        "case \"$1\" in",
+        ...Object.entries(SERVER_PROTOCOL.bindings).map(([binding, action]) => `  ${binding}) action=${action} ;;`),
+        "  *) action=$1 ;;",
+        "esac",
+        "n=$#",
+        "for a do set -- \"$@\" --data-urlencode \"a=$a\"; done",
+        "shift \"$n\"",
+        `out=$(${shellQuote(relayCurl)} -s --fail-with-body -X POST -H ${shellQuote(`@${headerFile}`)} "$@" ${shellQuote(url)})`,
+        "code=$?",
+        "if [ \"$code\" -eq 0 ]; then printf '%s' \"$out\"; exit 0; fi",
+        "if [ -n \"$out\" ]; then printf '%s\\n' \"$out\" >&2; else",
+        "  echo \"$action failed [service_unavailable 503]: the platform could not be reached\" >&2",
+        "fi",
+        "exit 1",
+        "",
+      ].join("\n"), { mode: 0o755 });
+      return;
+    }
+    const ticketPath = path.join(hostDir, "ticket.json");
+    await writeFile(ticketPath, JSON.stringify({ url, token }), { mode: 0o600 });
+    // Node hands its sandbox to child processes through NODE_OPTIONS; the
+    // relay is not part of the sandbox, so it drops it.
+    await writeFile(relayPath, [
+      "#!/bin/sh",
+      "unset NODE_OPTIONS",
+      `exec ${shellQuote(process.execPath)} ${shellQuote(BINDING_SCRIPT)} ${shellQuote(ticketPath)} "$@"`,
+      "",
+    ].join("\n"), { mode: 0o755 });
+  }
+
+  /** The syscalls an exec may make, minted as the platform mints them. */
+  function grantedCapabilities(runtime) {
+    if (runtime !== "node") return [];
+    const granted = [];
+    if ((capabilities.server?.records?.scopes ?? []).length) granted.push("records");
+    if (documentsChannels(capabilities).length) granted.push("collect");
+    granted.push("capsule", "web_fetch");
+    if (Array.isArray(capabilities.egress?.templates) && capabilities.egress.templates.length) granted.push("egress");
+    return granted;
+  }
+
+  async function execute({ runtime, entry, program, invocation, timeoutMs, granted, member }) {
+    let token = null;
+    try {
+      return await runServerHarness({
+        runtime,
+        entry,
+        program,
+        invocation,
+        timeoutMs,
+        running,
+        prepareHost: granted.length
+          ? async (hostDir) => {
+            token = randomBytes(32).toString("base64url");
+            tickets.set(token, {
+              member,
+              installationId: invocation.ctx.installation_id,
+              capabilities: new Set(granted),
+              deadlineAt: Date.now() + timeoutMs,
+              expiresAt: Date.now() + timeoutMs + TICKET_GRACE_MS,
+              minute: 0,
+              calls: 0,
+              hydratedBytes: 0,
+            });
+            await writeRelay(hostDir, token);
+          }
+          : null,
+      });
+    } finally {
+      if (token) tickets.delete(token);
+    }
+  }
+
+  /**
+   * Run one declared op (`run_server_op`). `trigger` is "sync" (the app
+   * called it: 10 s at most, background-only ops refused) or "background"
+   * (a `server.run` step: the op's whole budget). Answers `{output, logs}`.
+   *
+   * Refusals are the platform's (docs/app-server.md B4): an op the release
+   * does not declare, or no server code at all, is 404 not_found; a
+   * background-only op called from the app 400 bad_request; a tier that
+   * cannot run the op here (no python3, no sandbox on this OS) 503
+   * server_unavailable; an op out of time 504 deadline_exceeded; an op that
+   * threw 502 upstream_failed, its stderr the message. The local tier is
+   * never switched off, so it never answers server_disabled.
+   */
+  async function invoke(member, opName, input, trigger) {
+    const server = capabilities.server;
+    const ops = isPlainObject(server) && isPlainObject(server.ops) ? server.ops : {};
+    const declared = Object.hasOwn(ops, opName) && isPlainObject(ops[opName]) ? ops[opName] : null;
+    if (!declared) throw serverError(404, "not_found", `this app declares no server op '${opName}'`);
+    if (trigger === "sync" && declared.background_only === true) {
+      throw serverError(400, "bad_request", `server op '${opName}' is background-only and cannot be called from the app`);
+    }
+    const budget = Number.isSafeInteger(declared.timeout_ms) && declared.timeout_ms >= 0
+      ? declared.timeout_ms
+      : SYNC_OP_TIMEOUT_MS;
+    const timeoutMs = trigger === "sync" ? Math.min(budget, SYNC_OP_TIMEOUT_MS) : budget;
+    const runtime = server.language === "python" ? "python" : "node";
+    if (runtime === "node" && process.platform === "win32") {
+      throw serverError(503, "server_unavailable", "terminus dev runs node server ops on macOS and Linux");
+    }
+    let program;
+    try {
+      program = await readServerProgram(dir, server);
+    } catch (error) {
+      throw serverError(500, "internal_error", String(error?.message ?? error));
+    }
+    const entrypoint = String(server.entrypoint ?? "");
+    const entry = entrypoint.startsWith("server/") ? entrypoint.slice("server/".length) : entrypoint;
+    const invocation = sortKeysBytewise({
+      ctx: { installation_id: devInstallationId(member), trigger, user_id: member },
+      input,
+      op: opName,
+    });
+    const run = await execute({
+      runtime,
+      entry,
+      program,
+      invocation,
+      timeoutMs,
+      granted: grantedCapabilities(runtime),
+      member,
+    });
+    const label = `[server @${member} ${opName}]`;
+    for (const line of run.logs.split("\n")) if (line.trim()) log(`${label} ${line}`);
+    if (run.outcome !== "completed") {
+      log(`${label} ${run.outcome} after ${run.durationMs} ms: ${run.errorText.split("\n")[0]}`);
+      if (run.unavailable) throw serverError(503, "server_unavailable", run.errorText);
+      if (run.outcome === "timed_out") {
+        throw serverError(504, "deadline_exceeded", `server op '${opName}' did not finish within ${timeoutMs} ms`);
+      }
+      throw serverError(502, "upstream_failed", `server op '${opName}' ${run.outcome}: ${run.errorText || "no error output"}`);
+    }
+    log(`${label} ${trigger === "sync" ? "answered" : "ran"} in ${run.durationMs} ms`);
+    return { output: sortKeysBytewise(run.output), logs: run.logs };
+  }
+
+  /** A `server.run` automation step: `{op, input?}` → `{result, logs}`. */
+  async function runStep(member, params) {
+    const op = typeof params?.op === "string" ? params.op.trim() : "";
+    if (!op) throw serverError(400, "bad_request", "server.run params need 'op'");
+    const input = isPlainObject(params) && Object.hasOwn(params, "input") ? params.input : {};
+    const { output, logs } = await invoke(member, op, input, "background");
+    return { logs: logTail(logs, JOB_LOG_TAIL_CHARS), result: output };
+  }
+
+  async function close() {
+    for (const child of running) stopGroup(child);
+    running.clear();
+    tickets.clear();
+    if (bindingHost) {
+      bindingHost.closeAllConnections?.();
+      await new Promise((resolve) => bindingHost.close(() => resolve()));
+      bindingHost = null;
+      bindingHostUrl = null;
+    }
+  }
+
+  return { invoke, runStep, close };
+}