@skaile/forge-agent-runtime 1.0.0 → 1.1.0

package/dist/app-runner-host/index.mjs

@@ -0,0 +1,565 @@
+import { randomBytes } from 'node:crypto';
+import { join, resolve } from 'node:path';
+import { consola } from 'consola';
+import { P as ProcessManagerAdapter } from '../shared/forge-agent-runtime.B1LZr0Sl.mjs';
+import { rm, mkdir, writeFile } from 'node:fs/promises';
+import { registryEntries, isEntryEnabled, entryPolicyRefusal, providerCredentialEnvName, parseCredentialRef, writeProviderLayer } from '@skaile/forge-settings/server';
+import 'node:events';
+import 'node:child_process';
+import 'node:fs';
+import 'node:net';
+import 'node:url';
+import 'picocolors';
+import '@skaile/workspaces/sdk/client';
+import '@skaile/workspaces/sdk/transport/ws/client';
+
+const APP_MCP_AUTHORIZATION_ENV = "APP_MCP_AUTHORIZATION";
+const MCP_NAME = /^[A-Za-z0-9_-]+$/;
+function assertAppTools(tools) {
+  if (!MCP_NAME.test(tools.mcpName) || tools.mcpName.includes("__")) {
+    throw new TypeError(
+      "appTools.mcpName must contain only letters, digits, '_' and '-', and no '__'"
+    );
+  }
+  let url;
+  try {
+    url = new URL(tools.mcpUrl);
+  } catch {
+    throw new TypeError("appTools.mcpUrl must be an absolute URL");
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new TypeError("appTools.mcpUrl must be an http(s) URL");
+  }
+  for (const name of tools.browserActionNames) {
+    if (typeof name !== "string" || name === "" || name.includes("*") || name.startsWith("mcp__")) {
+      throw new TypeError(
+        "appTools.browserActionNames must be exact, non-empty names that do not start with 'mcp__'"
+      );
+    }
+  }
+}
+function hostAllowedFor(tools) {
+  return [`mcp__${tools.mcpName}__*`, ...tools.browserActionNames];
+}
+
+class RequestError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "RequestError";
+  }
+}
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isUuid(value) {
+  return typeof value === "string" && UUID.test(value);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireRecord(body) {
+  if (!isRecord(body)) throw new RequestError(400, "request body must be a JSON object");
+  return body;
+}
+function requireString(body, key) {
+  const value = body[key];
+  if (typeof value !== "string" || value === "") {
+    throw new RequestError(400, `'${key}' must be a non-empty string`);
+  }
+  return value;
+}
+function parseExpiry(value, now) {
+  let at = Number.NaN;
+  if (typeof value === "number") at = value;
+  else if (typeof value === "string" && /\d{4}-\d{2}-\d{2}T/.test(value)) at = Date.parse(value);
+  if (!Number.isFinite(at)) {
+    throw new RequestError(400, "'expiresAt' must be an ISO-8601 timestamp or epoch milliseconds");
+  }
+  if (at <= now) throw new RequestError(400, "'expiresAt' must be in the future");
+  return at;
+}
+function parseStartRequest(body, now) {
+  const record = requireRecord(body);
+  const id = record.id;
+  if (!isUuid(id)) throw new RequestError(400, "'id' must be a UUID");
+  const model = requireString(record, "model");
+  if (/\s/.test(model) || model.startsWith("-")) {
+    throw new RequestError(400, "'model' must be '<providerId>/<modelId>' without whitespace");
+  }
+  if (!isRecord(record.registry)) throw new RequestError(400, "'registry' must be an object");
+  const credentialEnv = record.credentialEnv;
+  if (!isRecord(credentialEnv)) throw new RequestError(400, "'credentialEnv' must be an object");
+  for (const [name, value] of Object.entries(credentialEnv)) {
+    if (typeof value !== "string") {
+      throw new RequestError(400, `'credentialEnv.${name}' must be a string`);
+    }
+  }
+  if (typeof record.systemPrompt !== "string") {
+    throw new RequestError(400, "'systemPrompt' must be a string");
+  }
+  const mcpAuthorization = requireString(record, "mcpAuthorization");
+  if (/[\u0000-\u001f\u007f]/.test(mcpAuthorization)) {
+    throw new RequestError(400, "'mcpAuthorization' must be a single header value");
+  }
+  return {
+    id,
+    model,
+    registry: record.registry,
+    credentialEnv: { ...credentialEnv },
+    systemPrompt: record.systemPrompt,
+    mcpAuthorization,
+    expiresAt: parseExpiry(record.expiresAt, now)
+  };
+}
+function parseLeaseRequest(body, now) {
+  return parseExpiry(requireRecord(body).expiresAt, now);
+}
+const RUN_COMMAND_TYPES = [
+  "prompt",
+  "cancel",
+  "reply",
+  "capability_register",
+  "capability_deregister",
+  "capability_result"
+];
+function optionalStrings(body, keys) {
+  const out = {};
+  for (const key of keys) {
+    const value = body[key];
+    if (value === void 0) continue;
+    if (typeof value !== "string") throw new RequestError(400, `'${key}' must be a string`);
+    out[key] = value;
+  }
+  return out;
+}
+function parseCommand(body, browserActionNames) {
+  const record = requireRecord(body);
+  const type = record.type;
+  if (typeof type !== "string" || !RUN_COMMAND_TYPES.includes(type)) {
+    throw new RequestError(400, `unknown command type; allowed: ${RUN_COMMAND_TYPES.join(", ")}`);
+  }
+  switch (type) {
+    case "prompt":
+      return {
+        type: "prompt",
+        prompt: requireString(record, "prompt"),
+        ...optionalStrings(record, ["messageId", "senderId", "turnId"])
+      };
+    case "cancel":
+      return { type: "cancel", ...optionalStrings(record, ["senderId"]) };
+    case "reply":
+      return {
+        type: "reply",
+        answer: requireString(record, "answer"),
+        ...optionalStrings(record, ["question", "requestId", "turnId"])
+      };
+    case "capability_register": {
+      const list = record.capabilities;
+      if (!Array.isArray(list) || list.length === 0) {
+        throw new RequestError(400, "'capabilities' must be a non-empty array");
+      }
+      const capabilities = list.map((entry) => {
+        if (!isRecord(entry) || typeof entry.name !== "string") {
+          throw new RequestError(400, "each capability needs a 'name'");
+        }
+        if (!browserActionNames.includes(entry.name)) {
+          throw new RequestError(
+            400,
+            `capability '${entry.name}' is not a declared browser action`
+          );
+        }
+        const { render: _render, ...rest } = entry;
+        return { ...rest, side: "client", origin: { kind: "client" } };
+      });
+      return { type: "capability_register", capabilities };
+    }
+    case "capability_deregister": {
+      const names = record.names;
+      if (!Array.isArray(names) || names.some((name) => typeof name !== "string")) {
+        throw new RequestError(400, "'names' must be an array of strings");
+      }
+      return { type: "capability_deregister", names };
+    }
+    case "capability_result":
+      return {
+        type: "capability_result",
+        callId: requireString(record, "callId"),
+        result: record.result
+      };
+  }
+}
+
+function runPaths(rootDir, runId) {
+  const root = join(rootDir, runId);
+  return {
+    root,
+    workspace: join(root, "workspace"),
+    home: join(root, "home"),
+    skaileHome: join(root, "skaile-home"),
+    tmp: join(root, "tmp")
+  };
+}
+async function createRunDirs(paths) {
+  await rm(paths.root, { recursive: true, force: true });
+  await mkdir(paths.root, { recursive: true, mode: 448 });
+  await Promise.all(
+    [paths.workspace, paths.home, paths.skaileHome, paths.tmp].map(
+      (dir) => mkdir(dir, { mode: 448 })
+    )
+  );
+}
+async function removeRunDirs(paths) {
+  await rm(paths.root, { recursive: true, force: true, maxRetries: 3 });
+}
+function requireRegistryShape(registry) {
+  if (!isRecord(registry)) throw new RequestError(400, "'registry' must be an object");
+  if (Array.isArray(registry.order) && !isRecord(registry.providers)) {
+    throw new RequestError(400, "'registry.providers' must be an object");
+  }
+  const view = registry;
+  for (const [id, entry] of registryEntries(view)) {
+    if (!isRecord(entry) || typeof entry.kind !== "string") {
+      throw new RequestError(400, `registry entry '${id}' needs a 'kind'`);
+    }
+    if (entry.credential !== void 0 && !isRecord(entry.credential)) {
+      throw new RequestError(400, `registry entry '${id}': 'credential' must be an object`);
+    }
+  }
+  return view;
+}
+function prepareProviderSnapshot(registry, credentialEnv) {
+  const providers = {};
+  const env = {};
+  const names = /* @__PURE__ */ new Set();
+  for (const [id, entry] of registryEntries(requireRegistryShape(registry))) {
+    if (entry.kind !== "llm" || !isEntryEnabled(entry)) continue;
+    const interpolation = entryPolicyRefusal(
+      { ...entry, credential: void 0 },
+      { envNames: [] }
+    );
+    if (interpolation) throw new RequestError(400, `registry entry '${id}': ${interpolation}`);
+    const canonical = providerCredentialEnvName(id);
+    if (names.has(canonical)) {
+      throw new RequestError(
+        400,
+        `registry entry '${id}' collides with another entry's credential name`
+      );
+    }
+    names.add(canonical);
+    const ref = entry.credential?.ref;
+    if (ref === void 0) {
+      providers[id] = { ...entry };
+      continue;
+    }
+    const parsed = parseCredentialRef(ref);
+    if (parsed?.form !== "env") {
+      throw new RequestError(
+        400,
+        `registry entry '${id}': only env: credential references are allowed`
+      );
+    }
+    const secret = credentialEnv[parsed.name];
+    if (secret) env[canonical] = secret;
+    providers[id] = {
+      ...entry,
+      credential: { ...entry.credential, ref: `env:${canonical}` }
+    };
+  }
+  const providerIds = Object.keys(providers);
+  if (providerIds.length === 0) {
+    throw new RequestError(400, "'registry' has no enabled llm provider");
+  }
+  return { providers, providerIds, credentialEnv: env };
+}
+async function writeRunWorkspace(paths, input) {
+  const { appTools } = input;
+  const skaileYaml = {
+    agent: { definition: "./agent", prompt: input.systemPrompt },
+    mcp_servers: [
+      {
+        id: appTools.mcpName,
+        transport: "http",
+        url: appTools.mcpUrl,
+        headers: { Authorization: `env:${APP_MCP_AUTHORIZATION_ENV}` }
+      }
+    ]
+  };
+  const agentYaml = {
+    name: "app-runner",
+    version: "1.0.0",
+    tools: { allowed: ["WebFetch"], host_allowed: hostAllowedFor(appTools) }
+  };
+  await mkdir(join(paths.workspace, "agent"), { recursive: true, mode: 448 });
+  await writeFile(join(paths.workspace, "skaile.yaml"), `${JSON.stringify(skaileYaml, null, 2)}
+`);
+  await writeFile(
+    join(paths.workspace, "agent", "agent.yaml"),
+    `${JSON.stringify(agentYaml, null, 2)}
+`
+  );
+  writeProviderLayer(join(paths.workspace, ".skaile", "providers.yml"), input.snapshot.providers);
+}
+function baseChildEnv(paths) {
+  return {
+    PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+    LANG: process.env.LANG ?? "C.UTF-8",
+    HOME: paths.home,
+    SKAILE_HOME: paths.skaileHome,
+    TMPDIR: paths.tmp
+  };
+}
+
+const log = consola.withTag("app-runner-host");
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+const MAX_TIMER_MS = 2 ** 31 - 1;
+const EXPIRY_GRACE_MS = 5e3;
+const CHILD_HOST = "127.0.0.1";
+function json(res, status, body) {
+  if (res.headersSent) {
+    res.end();
+    return;
+  }
+  if (body === void 0) {
+    res.writeHead(status).end();
+    return;
+  }
+  res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(body));
+}
+async function readJson(req) {
+  const declared = Number(req.headers["content-length"]);
+  if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+    throw new RequestError(413, "request body too large");
+  }
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.length;
+    if (size > MAX_BODY_BYTES) throw new RequestError(413, "request body too large");
+    chunks.push(buffer);
+  }
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  } catch {
+    throw new RequestError(400, "request body is not valid JSON");
+  }
+}
+function erase(record) {
+  for (const key of Object.keys(record)) delete record[key];
+}
+function createAppRunnerHost(options) {
+  assertAppTools(options.appTools);
+  const rootDir = resolve(options.rootDir);
+  const { appTools, authenticate, onEvent } = options;
+  const runs = /* @__PURE__ */ new Map();
+  let closed = false;
+  function tearDown(run) {
+    run.teardown ??= (async () => {
+      run.state = "closing";
+      clearTimeout(run.leaseTimer);
+      clearTimeout(run.reapTimer);
+      try {
+        await run.adapter.disconnect();
+      } catch (err) {
+        log.warn(`[${run.id}] disconnect failed: ${err.message}`);
+      }
+      await run.pump?.catch(() => {
+      });
+      for (const record of run.secrets) erase(record);
+      try {
+        await removeRunDirs(run.paths);
+      } catch (err) {
+        log.warn(`[${run.id}] scratch removal failed: ${err.message}`);
+      }
+      if (runs.get(run.id) === run) runs.delete(run.id);
+    })();
+    return run.teardown;
+  }
+  async function terminate(run) {
+    await run.startup?.catch(() => {
+    });
+    await tearDown(run);
+  }
+  async function pump(run) {
+    try {
+      for await (const event of run.adapter.listen()) {
+        if (run.teardown) return;
+        await onEvent(run.id, event);
+      }
+    } catch (err) {
+      log.error(`[${run.id}] event delivery failed; terminating: ${err.message}`);
+      void tearDown(run);
+    }
+  }
+  function armLease(run) {
+    clearTimeout(run.leaseTimer);
+    if (run.state !== "running") return;
+    const remaining = run.expiresAt - Date.now();
+    if (remaining <= 0) {
+      void expire(run);
+      return;
+    }
+    run.leaseTimer = setTimeout(() => armLease(run), Math.min(remaining, MAX_TIMER_MS));
+    run.leaseTimer.unref();
+  }
+  async function expire(run) {
+    if (run.state !== "running") return;
+    run.state = "expired";
+    log.info(`[${run.id}] lease expired`);
+    run.reapTimer = setTimeout(() => void tearDown(run), EXPIRY_GRACE_MS);
+    run.reapTimer.unref();
+    try {
+      await run.adapter.abort();
+    } catch (err) {
+      log.warn(`[${run.id}] cancel on expiry failed: ${err.message}`);
+    }
+  }
+  async function start(request) {
+    const snapshot = prepareProviderSnapshot(request.registry, request.credentialEnv);
+    const paths = runPaths(rootDir, request.id);
+    const wsAuthToken = randomBytes(32).toString("base64url");
+    const mcpEnv = { [APP_MCP_AUTHORIZATION_ENV]: request.mcpAuthorization };
+    const credentialEnv = { ...baseChildEnv(paths), ...snapshot.credentialEnv };
+    const run = {
+      id: request.id,
+      paths,
+      state: "starting",
+      expiresAt: request.expiresAt,
+      adapter: new ProcessManagerAdapter(),
+      secrets: [request.credentialEnv, snapshot.credentialEnv, credentialEnv, mcpEnv]
+    };
+    runs.set(run.id, run);
+    run.startup = (async () => {
+      await createRunDirs(paths);
+      await writeRunWorkspace(paths, {
+        systemPrompt: request.systemPrompt,
+        snapshot,
+        appTools
+      });
+      run.pump = pump(run);
+      await run.adapter.connect({
+        projectDir: paths.workspace,
+        harness: "omp",
+        model: request.model,
+        registry: snapshot.providers,
+        providers: snapshot.providerIds,
+        credentialEnv,
+        env: mcpEnv,
+        host: CHILD_HOST,
+        wsAuthToken
+      });
+      if (run.teardown) throw new Error("run was terminated while starting");
+      run.state = "running";
+      armLease(run);
+    })();
+    try {
+      await run.startup;
+    } catch (err) {
+      log.error(`[${run.id}] start failed: ${err.message}`);
+      await tearDown(run);
+      throw err;
+    }
+    return run;
+  }
+  async function startRun(req, res) {
+    const request = parseStartRequest(await readJson(req), Date.now());
+    if (runs.has(request.id)) throw new RequestError(409, "a run with this id is already active");
+    try {
+      const run = await start(request);
+      json(res, 201, { id: run.id, expiresAt: new Date(run.expiresAt).toISOString() });
+    } catch (err) {
+      if (err instanceof RequestError) throw err;
+      json(res, 503, { error: "runner could not be started" });
+    }
+  }
+  function findRun(id) {
+    const run = isUuid(id) ? runs.get(id) : void 0;
+    if (!run || run.teardown) throw new RequestError(404, "no such run");
+    return run;
+  }
+  async function sendCommand(req, res, id) {
+    const run = findRun(id);
+    const command = parseCommand(await readJson(req), appTools.browserActionNames);
+    if (run.state === "starting") throw new RequestError(409, "run is still starting");
+    if (run.state === "expired" && command.type !== "cancel") {
+      throw new RequestError(410, "run lease has expired");
+    }
+    try {
+      await run.adapter.sendCommand(command);
+    } catch {
+      throw new RequestError(409, "run process is not connected");
+    }
+    json(res, 202, { accepted: true });
+  }
+  async function renewLease(req, res, id) {
+    const run = findRun(id);
+    const expiresAt = parseLeaseRequest(await readJson(req), Date.now());
+    if (run.state === "starting") throw new RequestError(409, "run is still starting");
+    if (run.state === "expired") throw new RequestError(410, "run lease has expired");
+    run.expiresAt = expiresAt;
+    armLease(run);
+    json(res, 200, { expiresAt: new Date(expiresAt).toISOString() });
+  }
+  async function deleteRun(res, id) {
+    if (!isUuid(id)) throw new RequestError(404, "no such run");
+    const run = runs.get(id);
+    if (run) await terminate(run);
+    json(res, 204);
+  }
+  async function route(req, res) {
+    const segments = new URL(req.url ?? "/", "http://runner.invalid").pathname.split("/").filter((segment) => segment !== "");
+    const method = req.method ?? "GET";
+    const [root, id, leaf] = segments;
+    if (root !== "runs" || segments.length > 3) throw new RequestError(404, "not found");
+    if (id === void 0) {
+      if (method !== "POST") throw new RequestError(405, "method not allowed");
+      return startRun(req, res);
+    }
+    const runId = decodeURIComponent(id);
+    if (leaf === void 0) {
+      if (method !== "DELETE") throw new RequestError(405, "method not allowed");
+      return deleteRun(res, runId);
+    }
+    if (leaf === "commands") {
+      if (method !== "POST") throw new RequestError(405, "method not allowed");
+      return sendCommand(req, res, runId);
+    }
+    if (leaf === "lease") {
+      if (method !== "PATCH") throw new RequestError(405, "method not allowed");
+      return renewLease(req, res, runId);
+    }
+    throw new RequestError(404, "not found");
+  }
+  return {
+    async handler(req, res) {
+      let allowed;
+      try {
+        allowed = await authenticate(req);
+      } catch (err) {
+        log.error(`authenticate threw: ${err.message}`);
+        json(res, 500, { error: "authentication unavailable" });
+        return;
+      }
+      if (!allowed) {
+        json(res, 401, { error: "unauthorized" });
+        return;
+      }
+      try {
+        if (closed) throw new RequestError(503, "runner host is closed");
+        await route(req, res);
+      } catch (err) {
+        if (err instanceof RequestError) {
+          json(res, err.status, { error: err.message });
+          return;
+        }
+        log.error(`request failed: ${err.message}`);
+        json(res, 500, { error: "internal error" });
+      }
+    },
+    async close() {
+      closed = true;
+      await Promise.all([...runs.values()].map((run) => terminate(run)));
+    }
+  };
+}
+
+export { createAppRunnerHost };