@sema-agent/server 7.147.0 → 7.149.0

package/scripts/embed-minimal.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+// embed-minimal.mjs — the smallest HTTP service assembled the way a library embedder assembles it.
+//
+//   node scripts/embed-minimal.mjs                 build every seat, listen on 127.0.0.1:0, print `EMBED-MINIMAL ok port=<n>`, exit 0
+//   node scripts/embed-minimal.mjs --omit <seat>   build every seat but <seat>, then call `createHttpServer`:
+//                                                  refused at construction → `EMBED-MINIMAL refused seat=<seat> message=<first line>`, exit 2
+//                                                  accepted at construction → `EMBED-MINIMAL accepted seat=<seat>`, exit 3 (the seat is not judged at construction)
+//   any other failure                              `EMBED-MINIMAL failed step=<step> message=<first line>`, exit 1; a bad command line exits 64.
+//                                                  `--omit` reads the omission against the complete assembly: when that does not construct either, the line is `failed step=baseline`,
+//                                                  and a clean-up that did not happen is `failed step=cleanup` — neither is ever reported as a refusal of the omitted seat.
+//
+// The assembly order is the README "Library embedding" chain: `declareServerWithheldEnv()` → `loadConfig()` → `composeExecutionLane(config, ctx)` →
+// `judgeServedModelRoute(config, { envTableIsPlaceholder })` (the route judge, once after the config-source apply; `loadConfig()` does not judge routes) →
+// the nine required `createHttpServer` seats (the type `ServiceCoreDeps`) → `createHttpServer(deps)`. It imports the package root `@sema-agent/server` and the
+// engine package `@sema-agent/core` (the server's pinned dependency, owner of the `Runner` class), never a path inside `dist/`.
+// The service it assembles runs on the host lane against a throwaway local data root and listens on a kernel-assigned loopback port; it takes no task,
+// calls no model and leaves nothing behind (the data root is removed on the way out). It sets the ten environment variables in the `env` block below
+// itself; every other service knob is read from the caller's environment as usual, so run it from a shell that does not carry a production deployment's variables.
+
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Runner } from "@sema-agent/core";
+import {
+  HTTP_SERVICE_LANE_ENTRY,
+  buildScenarios,
+  composeExecutionLane,
+  createAuthorizer,
+  createBrain,
+  createHttpServer,
+  createKeyResolver,
+  createLogger,
+  createPeerDesk,
+  createScenarioGate,
+  createSideQueryLane,
+  declareServerWithheldEnv,
+  judgeServedModelRoute,
+  loadConfig,
+} from "@sema-agent/server";
+
+/** The nine seats `createHttpServer` requires (the type `ServiceCoreDeps`); `--omit` takes exactly these names. */
+const SEATS = ["runner", "runnerFor", "sideQuery", "scenarioGate", "peerDesk", "deploymentMods", "config", "authorize", "resolveSpec"];
+
+const TAG = "EMBED-MINIMAL";
+const oneLine = (e) => String(e instanceof Error ? e.message : e).split("\n")[0].replace(/\s+/g, " ").slice(0, 400);
+
+// ── command line ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+let omit;
+if (args.length === 0) {
+  omit = undefined;
+} else if (args.length === 2 && args[0] === "--omit" && SEATS.includes(args[1])) {
+  omit = args[1];
+} else {
+  console.error(`usage: embed-minimal.mjs [--omit <${SEATS.join("|")}>]`);
+  process.exit(64);
+}
+
+let step = "env";
+let dataRoot;
+let runner;
+let server;
+let line;
+let code = 1;
+try {
+  // ── the deployment's own env: what a deployer would put in the service's environment ─────────────────────────────────────────────────────────
+  dataRoot = await mkdtemp(join(tmpdir(), "embed-minimal-"));
+  Object.assign(process.env, {
+    DB_BACKEND: "local", // file-backed local mode: no database
+    LOCAL_DATA_ROOT: dataRoot, // the store root (highest-priority data-root knob)
+    AGENT_DATA_DIR: dataRoot, // the engine's own default root follows the same directory
+    REMOTE_EXEC: "host", // every deployment names its execution lane; `host` = tools run on this machine
+    BIND_HOST: "127.0.0.1",
+    PORT: "0", // the kernel assigns the port; the bound one is read back from the server
+    OPERATOR_SINGLE_USER: "true", // a single-user process says who the operator is
+    ALLOW_UNAUTHED_WRITES: "true", // no service token: loopback only
+    MODEL_ID: "embed-minimal-model", // the model table needs one entry; nothing here calls it
+    MODEL_GATEWAY_BASEURL: "http://127.0.0.1:9/v1",
+  });
+
+  // ── seat: config (package root: declareServerWithheldEnv → loadConfig → composeExecutionLane) ─────────────────────────────────────────────
+  step = "config";
+  declareServerWithheldEnv(); // first, before `loadConfig()` and before any execution environment or child process
+  const logger = createLogger("error");
+  const config = await composeExecutionLane(loadConfig(), { configSource: undefined, localRoot: dataRoot, logger, entry: HTTP_SERVICE_LANE_ENTRY });
+  // The route judge runs after the config-source apply, never inside `loadConfig()`: a model row with no endpoint would otherwise travel to the first model call.
+  // No center here ⇒ the env table is the served table, not a placeholder awaiting a catalog.
+  const routeGap = judgeServedModelRoute(config, { envTableIsPlaceholder: false });
+  if (routeGap !== undefined) throw new Error(routeGap.reason);
+
+  // ── seats: peerDesk, deploymentMods (package root: createPeerDesk; `[]` = no mods) ────────────────────────────────────────────────────────
+  step = "seats";
+  const peerDesk = createPeerDesk(); // zero IO; the same desk goes to the server and, as `peerSeat`, to every Runner
+  const deploymentMods = []; // the very array the Runners carry as `mods`
+
+  // ── seat: runner (engine package: `Runner`; the brain comes from the package root's createBrain) ───────────────────────────────────────────
+  const brain = createBrain(config);
+  runner = new Runner({ brain, models: config.models, roles: config.roles, mods: deploymentMods, peerSeat: peerDesk.seat });
+
+  // ── seat: sideQuery (package root: createSideQueryLane + createKeyResolver, the same brain as the Runner's) ────────────────────────────────
+  const keyResolver = createKeyResolver(config.modelApiKeyEnv, process.env, config.modelApiKeys);
+  const sideQuery = createSideQueryLane({ brain, config, getKeyResolver: () => keyResolver });
+
+  // ── seat: scenarioGate (package root: buildScenarios → createScenarioGate, the read-face leg `peek`) ───────────────────────────────────────
+  const scenarios = buildScenarios({ runner, subRunner: runner, model: Object.keys(config.models)[0], skills: [], logger });
+  const scenarioGate = createScenarioGate({ config, scenarios, principalCaps: undefined, logger }, "peek");
+
+  // ── seats: authorize, runnerFor (package root: createAuthorizer; a single-Runner embedding says so with `() => runner`) ─────────────────────
+  const authorize = createAuthorizer(config, runner.sessions);
+  const runnerFor = () => runner;
+
+  // ── seat: resolveSpec (the embedder's own: request body + identity → the task spec; it returns no `sessionId`, the server stamps the root) ──
+  const resolveSpec = (body) => ({ objective: String(body?.objective ?? "") });
+
+  const deps = { runner, runnerFor, sideQuery, scenarioGate, peerDesk, deploymentMods, config, authorize, resolveSpec };
+
+  if (omit !== undefined) {
+    // An omission can only be read against a complete assembly that constructs: build that first, so a refusal that has nothing to do with the omitted seat
+    // (any other construction-time check of the deployment's configuration) is reported as `failed step=baseline`, never as `refused seat=…`.
+    step = "baseline";
+    createHttpServer(deps).close();
+    const partial = { ...deps };
+    delete partial[omit];
+    step = "createHttpServer";
+    createHttpServer(partial).close();
+    line = `${TAG} accepted seat=${omit}`;
+    code = 3;
+  } else {
+    step = "createHttpServer";
+    server = createHttpServer(deps);
+    step = "listen";
+    await new Promise((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(0, "127.0.0.1", () => resolve());
+    });
+    const port = server.address().port;
+    step = "health";
+    const res = await fetch(`http://127.0.0.1:${port}/health`);
+    if (res.status !== 200) throw new Error(`GET /health answered ${res.status}`);
+    line = `${TAG} ok port=${port}`;
+    code = 0;
+  }
+} catch (e) {
+  if (omit !== undefined && step === "createHttpServer") {
+    line = `${TAG} refused seat=${omit} message=${oneLine(e)}`;
+    code = 2;
+  } else {
+    line = `${TAG} failed step=${step} message=${oneLine(e)}`;
+    code = 1;
+  }
+}
+
+// ── leave nothing behind, and say so before the result is printed: a clean-up that did not happen is a failure, not a footnote ───────────────────
+const leftovers = [];
+if (server?.listening) {
+  try {
+    await new Promise((resolve) => (server.closeAllConnections?.(), server.close(() => resolve())));
+  } catch (e) {
+    leftovers.push(e);
+  }
+}
+try {
+  runner?.sessions.dispose();
+} catch (e) {
+  leftovers.push(e);
+}
+if (dataRoot !== undefined) {
+  try {
+    await rm(dataRoot, { recursive: true, force: true });
+  } catch (e) {
+    leftovers.push(e);
+  }
+}
+if (leftovers.length > 0) {
+  if (code === 1) {
+    console.error(`${TAG} clean-up also failed: ${oneLine(leftovers[0])}`); // the run had already failed; its own line stays the result
+  } else {
+    line = `${TAG} failed step=cleanup message=${oneLine(leftovers[0])}`;
+    code = 1;
+  }
+}
+console.log(line);
+process.exit(code);