@terminus-ai/cli 0.0.1

package/bin/vendor/appd/node-harness.mjs

@@ -0,0 +1,209 @@
+// The appd node-lane boot shim (docs/app-server.md B6). The backend embeds
+// this file verbatim (include_str), substitutes __ENTRYPOINT__, and sends it
+// as the exec's `code`; bashd's agentOS lane runs it as an ES module from
+// /tmp. It therefore never leans on the runtime's module resolver: stdlib
+// arrives through ESM imports, and the developer's entry file is evaluated
+// HERE, in a CommonJS wrapper whose require() serves a fixed stdlib table
+// plus ./ siblings inside the server tree — so `exports.ops` works no matter
+// what any package.json nearby says.
+//
+// Results ride a FILE, not stdout: bashd keeps only the first 64 KiB of
+// stdout (head-truncated), so the op's return value is written to
+// .terminus_result.json under the server base and read back out of the
+// exec's `writes` diff. stdout belongs entirely to the app's own logging.
+//
+// TERMINUS_SERVER_BASE exists for the behavioral test suite
+// (bashd/harness/harness.test.js); inside the isolate the env is denied, so
+// the agentOS mount default always applies.
+import { spawnSync } from "node:child_process";
+import * as fsMod from "node:fs";
+import * as pathMod from "node:path";
+import * as cryptoMod from "node:crypto";
+import * as utilMod from "node:util";
+import * as bufferMod from "node:buffer";
+
+const fs = fsMod;
+const { Buffer } = bufferMod;
+const posix = pathMod.posix || pathMod;
+const SERVER_BASE =
+  (typeof process !== "undefined" && process.env && process.env.TERMINUS_SERVER_BASE) ||
+  "/home/agentos/server";
+const RESULT_FILE = SERVER_BASE + "/.terminus_result.json";
+const MAX_RESULT_BYTES = 1024 * 1024;
+
+const inv = JSON.parse(fs.readFileSync(SERVER_BASE + "/.terminus_invocation.json", "utf8"));
+
+// A failed syscall arrives on stderr as the binding host framed it
+// (server-protocol.json `errors`): "<action> failed [<code> <status>]:
+// <message>". The code and status become fields of the thrown Error, so ops
+// branch on error.code, never on message text; the message keeps the
+// platform's words. Anything unframed is the platform's own failure.
+const FAILURE = /([a-z][a-z0-9_]*) failed \[([a-z][a-z0-9_]*) ([1-5][0-9][0-9])\]: ([\s\S]*)/;
+
+function syscallError(binding, text) {
+  const raw = String(text || "").trim();
+  const framed = FAILURE.exec(raw);
+  const error = new Error(framed ? framed[1] + " failed: " + framed[4].trim() : raw || binding + " failed");
+  error.code = framed ? framed[2] : "internal_error";
+  error.status = framed ? Number(framed[3]) : 500;
+  return error;
+}
+
+function call(binding, args) {
+  const spawned = spawnSync("agentos-terminus", [binding, ...args], {
+    maxBuffer: 7 * 1024 * 1024,
+    encoding: "utf8",
+  });
+  if (spawned.error) {
+    const error = syscallError(binding, binding + " failed: " + spawned.error.message);
+    error.cause = spawned.error;
+    throw error;
+  }
+  const raw = String(spawned.stdout || "");
+  // Handler failures surface on stderr with a non-zero status, not in the
+  // ok-envelope.
+  if (spawned.status !== 0 || !raw.trim()) throw syscallError(binding, spawned.stderr);
+  const parsed = JSON.parse(raw);
+  if (!parsed.ok) throw syscallError(binding, parsed.error);
+  return parsed.result;
+}
+
+const b64 = (value) => Buffer.from(value, "utf8").toString("base64");
+
+// Syscall shapes are pinned by bashd/server-protocol.json `returns`:
+// put -> {version}, delete -> {deleted}, get -> {found, doc: DATA, version},
+// query -> {documents: [{doc: ID, data, version}], next_cursor}. Passed
+// through unshaped.
+const terminus = {
+  records: {
+    get: (scope, collection, doc) =>
+      call("records-get", ["--scope", scope, "--collection", collection, "--doc", doc]),
+    put: (scope, collection, doc, data, version) =>
+      call("records-put", [
+        "--scope", scope, "--collection", collection, "--doc", doc,
+        "--data", JSON.stringify(data),
+        ...(version == null ? [] : ["--version", String(version)]),
+      ]),
+    delete: (scope, collection, doc, version) =>
+      call("records-delete", [
+        "--scope", scope, "--collection", collection, "--doc", doc,
+        ...(version == null ? [] : ["--version", String(version)]),
+      ]),
+    // One page: `sort` is a top-level field ("-field" descending), `after`
+    // the previous page's next_cursor, `limit` 1-100 (default 100).
+    query: (scope, collection, opts = {}) =>
+      call("records-query", [
+        "--scope", scope, "--collection", collection,
+        ...(opts.where ? ["--where", JSON.stringify(opts.where)] : []),
+        ...(opts.sort ? ["--sort", String(opts.sort)] : []),
+        ...(opts.after ? ["--after", String(opts.after)] : []),
+        ...(opts.limit == null ? [] : ["--limit", String(opts.limit)]),
+      ]),
+    // Compare-and-set in one call (docs/app-server.md B6): read the record,
+    // ask fn for the next value, write it against the version read (absent =
+    // "must not exist"), and on version_conflict read again - at most
+    // 1 + retries tries. fn is synchronous like every syscall and gets the
+    // current value (null when absent); returning undefined writes nothing.
+    update: (scope, collection, doc, fn, { retries = 5 } = {}) => {
+      if (typeof fn !== "function") {
+        throw new TypeError("records.update needs a function from the current value to the next");
+      }
+      if (!Number.isInteger(retries) || retries < 0) {
+        throw new TypeError("records.update retries must be a whole number of at least 0");
+      }
+      for (let attempt = 0; ; attempt += 1) {
+        const current = terminus.records.get(scope, collection, doc);
+        const value = current.found ? current.doc : null;
+        const next = fn(value, { version: current.version });
+        if (next && typeof next.then === "function") {
+          throw new TypeError("records.update's fn must return the next value, not a promise");
+        }
+        if (next === undefined) return { written: false, doc: value, version: current.version };
+        if (next === null) {
+          throw new TypeError(
+            "records.update's fn returned null: return undefined to leave the record as it is, or call records.delete",
+          );
+        }
+        try {
+          const written = terminus.records.put(
+            scope, collection, doc, next, current.found ? current.version : 0,
+          );
+          return { written: true, doc: next, version: written.version };
+        } catch (error) {
+          if (!error || error.code !== "version_conflict" || attempt >= retries) throw error;
+        }
+      }
+    },
+  },
+  capsule: {
+    read: (path) => {
+      const r = call("capsule-read", ["--path", path]);
+      return Buffer.from(r.content_b64, "base64");
+    },
+    readText: (path) => {
+      const r = call("capsule-read", ["--path", path]);
+      return Buffer.from(r.content_b64, "base64").toString("utf8");
+    },
+    write: (path, content) =>
+      call("capsule-write", [
+        "--path", path,
+        "--content", b64(typeof content === "string" ? content : Buffer.from(content).toString("utf8")),
+      ]),
+  },
+  webFetch: (url) => call("web-fetch", ["--url", url]),
+  egress: (template, params = {}) =>
+    call("egress-invoke", ["--template", template, "--params", JSON.stringify(params)]),
+  collect: {
+    submit: (channel, payload) =>
+      call("collect-submit", ["--channel", channel, "--payload", JSON.stringify(payload)]),
+  },
+};
+
+const BUILTINS = {
+  fs: fsMod, "node:fs": fsMod,
+  path: pathMod, "node:path": pathMod,
+  crypto: cryptoMod, "node:crypto": cryptoMod,
+  util: utilMod, "node:util": utilMod,
+  buffer: bufferMod, "node:buffer": bufferMod,
+};
+const moduleCache = new Map();
+function loadLocal(request, fromDir) {
+  if (Object.prototype.hasOwnProperty.call(BUILTINS, request)) return BUILTINS[request];
+  if (!request.startsWith("./") && !request.startsWith("../")) {
+    throw new Error("require('" + request + "') is not available - stdlib and server/ siblings only");
+  }
+  let resolved = posix.normalize(posix.join(fromDir, request));
+  if (!resolved.startsWith(SERVER_BASE + "/")) {
+    throw new Error("require escapes server/: " + request);
+  }
+  if (!resolved.endsWith(".js") && !resolved.endsWith(".cjs") && !resolved.endsWith(".mjs")) {
+    resolved += ".js";
+  }
+  const cached = moduleCache.get(resolved);
+  if (cached) return cached.exports;
+  const source = fs.readFileSync(resolved, "utf8");
+  const localModule = { exports: {} };
+  moduleCache.set(resolved, localModule);
+  const dir = posix.dirname(resolved);
+  const requireFrom = (next) => loadLocal(next, dir);
+  const wrapped = new Function("module", "exports", "require", "__dirname", "__filename", source);
+  wrapped(localModule, localModule.exports, requireFrom, dir, resolved);
+  return localModule.exports;
+}
+
+const entry = loadLocal("./__ENTRYPOINT__", SERVER_BASE);
+(async () => {
+  const handler = (entry.ops || {})[inv.op];
+  if (typeof handler !== "function") throw new Error("no server op '" + inv.op + "'");
+  const result = await handler(inv.input, { terminus, ctx: inv.ctx });
+  const serialized = JSON.stringify(result === undefined ? null : result);
+  if (Buffer.byteLength(serialized, "utf8") > MAX_RESULT_BYTES) {
+    throw new Error("op result exceeds the " + MAX_RESULT_BYTES + "-byte budget");
+  }
+  // Written LAST, after the handler returns, so app code can never leave a
+  // spoofed result behind: the harness's write wins.
+  fs.writeFileSync(RESULT_FILE, serialized);
+})().catch((error) => {
+  console.error((error && error.stack) || String(error));
+  process.exit(1);
+});

package/bin/vendor/appd/python-harness.py

@@ -0,0 +1,12 @@
+# The appd python-lane shim (docs/app-server.md B6). Python server ops run as
+# pure compute in v1 (no broker bindings): the shim hands the entry the op,
+# input, and platform ctx via argv and runs it as __main__. The entry may
+# write its result to .terminus_result.json under the server base; the
+# backend reads it out of the exec's writes diff. The just-bash lane mounts
+# the tree at /server; TERMINUS_SERVER_BASE exists for the test suite only.
+import json, os, runpy, sys
+
+base = os.environ.get("TERMINUS_SERVER_BASE", "/server")
+inv = json.load(open(base + "/.terminus_invocation.json"))
+sys.argv = ["op", inv["op"], json.dumps(inv["input"]), json.dumps(inv.get("ctx", {}))]
+runpy.run_path(base + "/__ENTRYPOINT__", run_name="__main__")

package/bin/vendor/appd/server-protocol.json

@@ -0,0 +1,84 @@
+{
+  "comment": "Machine-readable half of docs/app-server.md. bashd/protocol.test.js, bashd/bindings.test.js, bashd/harness/harness.test.js and src/routes/app_server/{protocol.rs,tests.rs} lockstep-test their implementations against this file. Change the protocol here first.",
+  "version": 1,
+  "audience": "terminus-appd-exec",
+  "invocation_path": "server/.terminus_invocation.json",
+  "result_path": "server/.terminus_result.json",
+  "exec": {
+    "files_field": "content_b64",
+    "code_field": "code",
+    "cwd": "server",
+    "mount_base": "/home/agentos/server",
+    "diff_prefix_node": "home/"
+  },
+  "errors": {
+    "channel": "stderr",
+    "exit_status": 1,
+    "format": "<action> failed [<code> <status>]: <message>",
+    "example": "records_put failed [version_conflict 409]: the record already exists (if_version 0 requires absence)",
+    "thrown": ["code", "status"],
+    "untagged": { "code": "internal_error", "status": 500 },
+    "cas_retry_code": "version_conflict",
+    "conflict_substrings": ["reread and retry", "requires absence"]
+  },
+  "returns": {
+    "records_put": ["version"],
+    "records_delete": ["deleted"],
+    "records_get": ["found", "doc", "version"],
+    "records_query": ["documents", "next_cursor"],
+    "collect_submit": ["id", "delivered"]
+  },
+  "helpers": {
+    "records.update": { "retries": 5, "retry_on": "version_conflict", "returns": ["written", "doc", "version"] }
+  },
+  "broker_capabilities": ["web_fetch", "load_file", "records", "capsule", "egress", "collect"],
+  "server_capabilities": ["records", "capsule", "web_fetch", "egress", "collect"],
+  "scopes": {
+    "records": "appd:records",
+    "capsule": "appd:capsule",
+    "web_fetch": "appd:web_fetch",
+    "egress": "appd:egress",
+    "collect": "appd:collect",
+    "installation_prefix": "inst:"
+  },
+  "bindings": {
+    "records-get": "records_get",
+    "records-put": "records_put",
+    "records-delete": "records_delete",
+    "records-query": "records_query",
+    "capsule-read": "capsule_read",
+    "capsule-write": "capsule_write",
+    "web-fetch": "web_fetch",
+    "load-file": "load_file",
+    "egress-invoke": "egress_invoke",
+    "collect-submit": "collect_submit"
+  },
+  "actions": {
+    "records_get": { "request": ["scope", "collection", "doc_id"], "response": ["found", "doc", "version"] },
+    "records_put": { "request": ["scope", "collection", "doc_id", "data", "if_version?"], "response": ["version"] },
+    "records_delete": { "request": ["scope", "collection", "doc_id", "if_version?"], "response": ["deleted"] },
+    "records_query": { "request": ["scope", "collection", "where?", "sort?", "after?", "limit?"], "response": ["documents", "next_cursor"] },
+    "capsule_read": { "request": ["path"], "response": ["path", "size_bytes", "content_b64"] },
+    "capsule_write": { "request": ["path", "content_b64"], "response": ["path", "size_bytes"] },
+    "load_file": { "request": ["path"], "response": ["content_b64", "size_bytes", "content_sha256"] },
+    "web_fetch": { "request": ["url"], "response": ["status", "url", "content_type", "body", "truncated"] },
+    "egress_invoke": { "request": ["template", "params"], "response": ["status", "content_type", "body", "body_b64", "truncated"] },
+    "collect_submit": { "request": ["channel", "payload"], "response": ["id", "delivered"] }
+  },
+  "limits": {
+    "broker_calls_per_minute": 600,
+    "op_result_bytes": 1048576,
+    "web_fetches_per_installation_per_day": 2000,
+    "record_doc_bytes": 262144,
+    "records_global_quota_bytes": 67108864,
+    "records_installation_quota_bytes": 1048576,
+    "records_query_limit": 100,
+    "records_query_page_bytes": 4194304,
+    "records_sort_value_bytes": 1024,
+    "capsule_file_bytes": 1048576,
+    "collect_payload_bytes": 65536,
+    "collect_submissions_per_installation_per_day": 100,
+    "sync_op_timeout_ms": 10000,
+    "max_op_timeout_ms": 120000
+  }
+}