@agent-native/core 0.113.0 → 0.114.1

package/src/server/builder-space.ts

@@ -0,0 +1,176 @@
+/**
+ * Resolve the human-readable Builder *space* a private key is scoped to.
+ *
+ * There is no public-key path to a space's display name; it comes from the
+ * Builder Admin GraphQL API (`https://builder.io/api/v2/admin`) authenticated
+ * with the private `bpk-…` key we already hold at user scope. A `bpk-` key is
+ * space-scoped, so today this resolves the single connected space — but the
+ * function returns a *list* so the multi-space drill-down can grow additively
+ * (multiple credentials → multiple spaces) without a restructure.
+ *
+ * The exact `settings` field holding the display name is undocumented, so the
+ * parser is deliberately defensive: it requests the whole `settings` JSON blob
+ * and pulls the first plausible name/id field. Callers fall back to the generic
+ * `orgName` when this returns nothing.
+ */
+
+import { createHash } from "node:crypto";
+
+export interface BuilderSpaceSummary {
+  id: string;
+  name: string;
+}
+
+interface BuilderAdminGraphQlResponse {
+  data?: { settings?: unknown } | null;
+  errors?: Array<{ message?: string }> | null;
+}
+
+interface SpaceCacheEntry {
+  expiresAt: number;
+  spaces: BuilderSpaceSummary[];
+}
+
+// The admin API is polled indirectly via the Builder status route, which the
+// client refetches often. Cache per key so a poll storm hits Builder once.
+// A resolved name is cached for a while; an empty/failed lookup is cached only
+// briefly so a transient Builder hiccup recovers without hammering the API.
+const SPACE_CACHE_TTL_MS = 5 * 60 * 1000;
+const SPACE_NEGATIVE_TTL_MS = 60 * 1000;
+const SPACE_CACHE_MAX_ENTRIES = 100;
+// Hard cap on the admin call — the status route must never block on Builder.
+const ADMIN_FETCH_TIMEOUT_MS = 4000;
+const spaceCache = new Map<string, SpaceCacheEntry>();
+
+// `query { settings }` selects the whole JSONObject scalar, so we don't have to
+// know the sub-field names up front — we parse the returned blob below.
+const BUILDER_SPACE_SETTINGS_QUERY =
+  "query AgentNativeSpaceSettings { settings }";
+
+const SPACE_NAME_FIELDS = [
+  "name",
+  "displayName",
+  "siteName",
+  "spaceName",
+  "title",
+  "organizationName",
+] as const;
+
+const SPACE_ID_FIELDS = ["id", "spaceId", "publicKey"] as const;
+
+function builderAdminApiHost() {
+  return (
+    process.env.BUILDER_ADMIN_API_HOST ?? "https://builder.io/api/v2/admin"
+  ).replace(/\/+$/, "");
+}
+
+function cacheKey(privateKey: string) {
+  return createHash("sha256").update(privateKey).digest("hex");
+}
+
+function setCachedSpaces(key: string, entry: SpaceCacheEntry) {
+  if (!spaceCache.has(key) && spaceCache.size >= SPACE_CACHE_MAX_ENTRIES) {
+    const [oldest] = spaceCache.keys();
+    if (oldest) spaceCache.delete(oldest);
+  }
+  spaceCache.set(key, entry);
+}
+
+function firstString(
+  record: Record<string, unknown>,
+  fields: readonly string[],
+): string | null {
+  for (const field of fields) {
+    const value = record[field];
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return null;
+}
+
+export function parseSpacesFromSettings(
+  json: BuilderAdminGraphQlResponse,
+): BuilderSpaceSummary[] {
+  const settings = json?.data?.settings;
+  if (!settings || typeof settings !== "object") return [];
+  const record = settings as Record<string, unknown>;
+  const name = firstString(record, SPACE_NAME_FIELDS);
+  if (!name) return [];
+  const id = firstString(record, SPACE_ID_FIELDS) ?? name;
+  return [{ id, name }];
+}
+
+/**
+ * Synchronously read the cached space list for a key, or null if there's no
+ * fresh entry. The status route uses this to stay non-blocking — it returns
+ * whatever is cached now and kicks `listBuilderSpaces` in the background to
+ * populate the cache for the next poll.
+ */
+export function getCachedBuilderSpaces(
+  privateKey: string,
+): BuilderSpaceSummary[] | null {
+  if (!privateKey) return null;
+  const cached = spaceCache.get(cacheKey(privateKey));
+  if (cached && Date.now() < cached.expiresAt) return cached.spaces;
+  return null;
+}
+
+/**
+ * List the Builder spaces reachable with this private key. Best-effort: returns
+ * `[]` on any network/auth/parse failure (caller should fall back to orgName).
+ */
+export async function listBuilderSpaces(
+  privateKey: string,
+  options?: { fetchImpl?: typeof fetch; signal?: AbortSignal },
+): Promise<BuilderSpaceSummary[]> {
+  if (!privateKey) return [];
+
+  const key = cacheKey(privateKey);
+  const cached = spaceCache.get(key);
+  if (cached && Date.now() < cached.expiresAt) {
+    return cached.spaces;
+  }
+
+  const fetchImpl = options?.fetchImpl ?? fetch;
+  // Cap the admin call ourselves so a stalled Builder can't hang the status
+  // route. If the caller passed its own signal, respect it instead.
+  const timeoutController = options?.signal ? null : new AbortController();
+  const timeout = timeoutController
+    ? setTimeout(() => timeoutController.abort(), ADMIN_FETCH_TIMEOUT_MS)
+    : null;
+  let spaces: BuilderSpaceSummary[] = [];
+  try {
+    const response = await fetchImpl(builderAdminApiHost(), {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${privateKey}`,
+      },
+      body: JSON.stringify({ query: BUILDER_SPACE_SETTINGS_QUERY }),
+      signal: options?.signal ?? timeoutController?.signal,
+    });
+    if (response.ok) {
+      const json = (await response.json()) as BuilderAdminGraphQlResponse;
+      spaces = parseSpacesFromSettings(json);
+    }
+  } catch {
+    // Network / timeout / admin API unavailable — fall through to the empty
+    // list; the caller falls back to orgName.
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+
+  // Cache a resolved name for the full TTL; cache an empty/failed lookup only
+  // briefly so a transient Builder hiccup recovers without per-poll hammering.
+  setCachedSpaces(key, {
+    expiresAt:
+      Date.now() +
+      (spaces.length > 0 ? SPACE_CACHE_TTL_MS : SPACE_NEGATIVE_TTL_MS),
+    spaces,
+  });
+  return spaces;
+}
+
+/** Test/maintenance hook — drop cached space lookups. */
+export function clearBuilderSpaceCache() {
+  spaceCache.clear();
+}

package/src/server/captcha.ts

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// Cloudflare Turnstile — server-side verification
+// ---------------------------------------------------------------------------
+
+export interface CaptchaVerifyResult {
+  success: boolean;
+  errorCodes?: string[];
+}
+
+const TURNSTILE_VERIFY_URL =
+  "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+
+/**
+ * Verify a Cloudflare Turnstile token server-side.
+ *
+ * - If no secret key is provided (param or env), returns success (captcha is opt-in).
+ * - In dev mode (NODE_ENV !== "production"), always returns success.
+ */
+export async function verifyCaptcha(
+  token: string,
+  secretKey?: string,
+): Promise<CaptchaVerifyResult> {
+  // Dev mode — skip captcha
+  if (process.env.NODE_ENV !== "production") {
+    return { success: true };
+  }
+
+  const secret = secretKey ?? process.env.TURNSTILE_SECRET_KEY;
+
+  // No secret configured — captcha is opt-in, allow through
+  if (!secret) {
+    console.warn(
+      "[captcha] TURNSTILE_SECRET_KEY is not set — captcha verification is disabled. " +
+        "Set TURNSTILE_SECRET_KEY and VITE_TURNSTILE_SITE_KEY to enable bot protection.",
+    );
+    return { success: true };
+  }
+
+  // No token provided by client
+  if (!token) {
+    return { success: false, errorCodes: ["missing-input-response"] };
+  }
+
+  try {
+    const res = await fetch(TURNSTILE_VERIFY_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ secret, response: token }),
+    });
+
+    const data = (await res.json()) as {
+      success: boolean;
+      "error-codes"?: string[];
+    };
+
+    return {
+      success: data.success,
+      errorCodes: data["error-codes"],
+    };
+  } catch {
+    return { success: false, errorCodes: ["network-error"] };
+  }
+}

package/src/server/capture-error.ts

@@ -0,0 +1,64 @@
+export interface CaptureErrorContext {
+  /** The request path or logical route, when known. */
+  route?: string;
+  /** HTTP method, when known. */
+  method?: string;
+  /** Caller's `User-Agent` header, when known. */
+  userAgent?: string;
+  /** Searchable low-cardinality tags. */
+  tags?: Record<string, string | undefined>;
+  /** Structured diagnostic payload shown on the captured event. */
+  extra?: Record<string, unknown>;
+  /** Grouped diagnostic cards shown on the captured event. */
+  contexts?: Record<string, Record<string, unknown>>;
+}
+
+export type CaptureErrorProvider = (
+  error: unknown,
+  context: CaptureErrorContext,
+) => string | undefined | void;
+
+const providers = new Map<string, CaptureErrorProvider>();
+
+/**
+ * Register a backend for the framework-level `captureError()` utility.
+ *
+ * The default Sentry plugin registers itself here when a DSN is configured.
+ * Keeping this registry Sentry-agnostic lets core runtime code report errors
+ * without importing a Node-only SDK in edge/client-adjacent modules.
+ */
+export function registerErrorCaptureProvider(
+  name: string,
+  provider: CaptureErrorProvider,
+): () => void {
+  providers.set(name, provider);
+  return () => {
+    if (providers.get(name) === provider) {
+      providers.delete(name);
+    }
+  };
+}
+
+/**
+ * Capture an error through every configured provider. No-ops when no provider
+ * is installed and never throws back into the application path.
+ */
+export function captureError(
+  error: unknown,
+  context: CaptureErrorContext = {},
+): string | undefined {
+  let eventId: string | undefined;
+  for (const provider of providers.values()) {
+    try {
+      const result = provider(error, context);
+      if (eventId === undefined && typeof result === "string") {
+        eventId = result;
+      }
+    } catch {
+      // Observability must never mask the original failure.
+    }
+  }
+  return eventId;
+}
+
+export const captureServerError = captureError;

package/src/server/cli-capture.ts

@@ -0,0 +1,141 @@
+/**
+ * Capture stdout/stderr/console output from CLI-style action handlers
+ * without globally swapping `console.log` / `process.stdout.write` /
+ * `process.exit` per-call.
+ *
+ * The previous pattern (save → swap → restore in finally) corrupts the
+ * globals when two CLI tool calls run concurrently — request B saves the
+ * already-swapped function, then both finally-blocks restore in interleaved
+ * order, leaving an arbitrary capture function permanently installed and
+ * silently swallowing all subsequent server logs.
+ *
+ * This module installs the global interceptors ONCE at module load. Each
+ * call dispatches to either the captured logs (when an AsyncLocalStorage
+ * store is active) or the original implementation. The wrappers are
+ * idempotent and safe under any number of concurrent runs.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+
+import { sanitizeToolErrorText } from "../agent/tool-error-redaction.js";
+
+interface CaptureStore {
+  logs: string[];
+}
+
+const captureStore = new AsyncLocalStorage<CaptureStore>();
+
+/** Sentinel thrown when an action calls `process.exit(...)`. */
+export class ExitIntercepted extends Error {
+  code: number;
+  constructor(code: number) {
+    super(`process.exit(${code})`);
+    this.code = code;
+  }
+}
+
+let installed = false;
+
+function installInterceptorsOnce(): void {
+  if (installed) return;
+  installed = true;
+
+  const origLog = console.log.bind(console);
+  const origError = console.error.bind(console);
+  const origStdoutWrite = process.stdout.write.bind(process.stdout);
+  const origExit = process.exit.bind(process);
+
+  console.log = (...args: unknown[]): void => {
+    const store = captureStore.getStore();
+    if (store) {
+      store.logs.push(args.map((a) => String(a)).join(" "));
+      return;
+    }
+    origLog(...(args as []));
+  };
+
+  console.error = (...args: unknown[]): void => {
+    const store = captureStore.getStore();
+    if (store) {
+      store.logs.push(args.map((a) => String(a)).join(" "));
+      return;
+    }
+    origError(...(args as []));
+  };
+
+  // process.stdout.write has a complex signature (string | Uint8Array, encoding?, callback?)
+  // We only need to capture chunks; preserve return value semantics by returning true.
+  process.stdout.write = ((chunk: any, ...rest: any[]) => {
+    const store = captureStore.getStore();
+    if (store) {
+      if (typeof chunk === "string") {
+        store.logs.push(chunk);
+      } else if (chunk && typeof (chunk as Buffer).toString === "function") {
+        store.logs.push((chunk as Buffer).toString());
+      }
+      // Honor the optional callback that streams expect.
+      const cb = rest.find((r) => typeof r === "function");
+      if (cb) (cb as (err?: Error | null) => void)(null);
+      return true;
+    }
+    return origStdoutWrite(chunk, ...rest);
+  }) as typeof process.stdout.write;
+
+  process.exit = ((code?: number) => {
+    const store = captureStore.getStore();
+    if (store) {
+      throw new ExitIntercepted(code ?? 0);
+    }
+    return origExit(code);
+  }) as typeof process.exit;
+}
+
+export interface CaptureCliOptions {
+  /**
+   * If `true` (default), errors thrown by `fn` (other than
+   * `ExitIntercepted`) are appended to the capture buffer as `"Error: ..."`
+   * and the resolved logs are returned. If `false`, errors propagate.
+   */
+  swallowErrors?: boolean;
+}
+
+/**
+ * Run `fn` with a fresh capture buffer. All console.log / console.error /
+ * process.stdout.write calls inside `fn` (including async descendants)
+ * append to the buffer instead of going to the server's stdout/stderr.
+ * Returns the joined logs (or `"(no output)"` if nothing was captured).
+ *
+ * `process.exit(code)` inside `fn` throws `ExitIntercepted` internally; it
+ * is caught here so the captured output (including any final logs the
+ * action wrote before exiting) is preserved.
+ */
+export async function captureCliOutput(
+  fn: () => Promise<unknown>,
+  options: CaptureCliOptions = {},
+): Promise<string> {
+  installInterceptorsOnce();
+  const store: CaptureStore = { logs: [] };
+  const swallowErrors = options.swallowErrors !== false;
+  try {
+    await captureStore.run(store, fn);
+  } catch (err) {
+    if (err instanceof ExitIntercepted) {
+      // process.exit() is treated as a clean termination of the CLI action.
+    } else if (swallowErrors) {
+      const msg = (err as Error)?.message ?? String(err);
+      store.logs.push(sanitizeToolErrorText(`Error: ${msg}`));
+    } else {
+      throw err;
+    }
+  }
+  return store.logs.join("\n") || "(no output)";
+}
+
+/**
+ * Append a string to the active capture buffer. No-op outside of a
+ * `captureCliOutput` scope — used by callers that catch errors from
+ * `fn` themselves and want to emit the message into the captured logs.
+ */
+export function appendCapturedLog(text: string): void {
+  const store = captureStore.getStore();
+  if (store) store.logs.push(text);
+}