@data-club/ai-hub-server 0.0.1

package/dist/letta/settingsFileSeed.js

@@ -0,0 +1,177 @@
+/**
+ * Seeds Letta Code's global agent-settings file (`~/.letta/settings.json`)
+ * with `{toolset: "none"}` for each ai-hub-registered Letta agent.
+ *
+ * **Why this matters.** Letta Code's bundled CLI auto-attaches a "toolset"
+ * (a set of file-edit / shell / search tools — `Read`, `Write`, `Edit`,
+ * `Bash`, etc.) to every agent at session start, based on the model handle.
+ * ai-hub doesn't want those tools — we want only the tools the ADE admin
+ * explicitly attached to the agent. The CLI honors a per-agent
+ * `toolset: "none"` preference stored in its global settings file, which
+ * suppresses the entire auto-toolset.
+ *
+ * **Why global, not project-local.** Letta Code's `SettingsManager` reads
+ * the toolset preference from `~/.letta/settings.json` (the global file),
+ * not `<cwd>/.letta/settings.local.json` (the project file). The global
+ * settings carry agent records keyed by `(agentId, normalizedBaseUrl)`
+ * where `normalizedBaseUrl` is the value of `LETTA_BASE_URL` with the
+ * scheme and trailing slash stripped, or `undefined` when the agent lives
+ * on Letta Cloud. Self-hosted Letta deployments always have a non-default
+ * `LETTA_BASE_URL` so the agent record always has the `baseUrl` field set.
+ *
+ * The `LETTA_CLI_PATH` shim (which injects `--tools ""`) is the primary
+ * mechanism that forces an empty tool registry; this settings-file seed
+ * is the defense-in-depth fallback the TUI also honors.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Path resolution                                                           */
+/* ────────────────────────────────────────────────────────────────────────── */
+/**
+ * Returns the absolute path to Letta Code's global settings file. Tests
+ * override `HOME` to point at a tmp dir.
+ *
+ * @returns the path. (Doesn't check existence — caller does.)
+ */
+export function resolveGlobalSettingsPath() {
+    return join(homedir(), ".letta", "settings.json");
+}
+/**
+ * Normalizes `LETTA_BASE_URL` to match the key Letta Code's CLI uses to
+ * look up agent settings AFTER ai-hub-server's `bootstrap.ts` runs its
+ * own `/v1` stripping. The CLI itself only strips scheme + trailing
+ * slash (so `http://host:p/v1` → `host:p/v1`), but bootstrap.ts mutates
+ * `process.env.LETTA_BASE_URL` at boot to drop the `/v1` (because the
+ * Letta Client SDK that the CLI uses internally appends `/v1` itself —
+ * leaving it in the env produces double-`/v1` requests that 404).
+ *
+ * So by the time the spawned CLI looks up the agent settings, its
+ * `getCurrentServerKey` reads `http://host:p` from env and produces
+ * `host:p`. The settings file entry must use the same key — hence the
+ * extra `/v1` strip here. If `bootstrap.ts` changes its policy, this
+ * helper has to change in lockstep.
+ *
+ * Returns `undefined` for the Letta Cloud default URL (so the agent
+ * record omits the `baseUrl` field, matching Letta Code's behavior on
+ * Cloud).
+ *
+ * @param baseUrl - raw `LETTA_BASE_URL` value.
+ * @returns the normalized form, or `undefined` for Letta Cloud.
+ */
+export function normalizeLettaBaseUrl(baseUrl) {
+    if (!baseUrl)
+        return undefined;
+    const stripped = baseUrl
+        .replace(/^https?:\/\//, "")
+        .replace(/\/v1\/?$/i, "")
+        .replace(/\/$/, "");
+    if (stripped === "api.letta.com")
+        return undefined;
+    return stripped;
+}
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Read + write                                                              */
+/* ────────────────────────────────────────────────────────────────────────── */
+/**
+ * Reads the settings file from disk. Returns an empty object if the file
+ * doesn't exist or is unparseable — both cases are recoverable by an
+ * idempotent upsert that recreates the file.
+ *
+ * @param path - the resolved settings path.
+ * @returns the parsed settings (or `{}`).
+ */
+export function readSettingsFile(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const raw = readFileSync(path, "utf8");
+        if (!raw.trim())
+            return {};
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        // Malformed file (concurrent write, disk corruption) — treat as empty
+        // so the seed proceeds. Worst case the operator's other settings (if
+        // any) are clobbered, which is acceptable when the file was already
+        // broken.
+        return {};
+    }
+}
+/**
+ * Writes the settings file atomically: write to `<path>.tmp` then rename.
+ * The rename is atomic on every filesystem the ai-hub-server supports
+ * (ext4, xfs, btrfs, apfs). Creates `~/.letta/` if missing.
+ *
+ * @param path - the resolved settings path.
+ * @param settings - the new contents.
+ */
+export function writeSettingsFile(path, settings) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(settings, null, 2), { encoding: "utf8", mode: 0o600 });
+    renameSync(tmp, path);
+}
+/**
+ * Idempotent upsert of `{toolset: "none"}` for a single agent in the
+ * global settings file.
+ *
+ * Matching is by `(agentId, baseUrl)` — same composite key Letta Code
+ * uses. If the agent record exists with a different toolset (`"auto"`,
+ * `"codex"`, etc.), it's replaced. If it exists already with `"none"`,
+ * we no-op (don't churn the file's mtime).
+ *
+ * @param opts.agentId - the Letta agent id (e.g. `agent-xxx`).
+ * @param opts.lettaBaseUrl - the raw `LETTA_BASE_URL` value (so the
+ *   helper can normalize it the same way Letta Code does). Pass
+ *   `process.env.LETTA_BASE_URL` from the caller.
+ * @param opts.settingsPath - override the settings-file path. Defaults to
+ *   `~/.letta/settings.json`. Tests inject a tmp path.
+ * @param opts.logger - optional pino logger for observability lines.
+ * @returns the outcome (created / updated / noop) so the caller can log.
+ */
+export function seedAgentToolsetNone(opts) {
+    const path = opts.settingsPath ?? resolveGlobalSettingsPath();
+    const normalizedBaseUrl = normalizeLettaBaseUrl(opts.lettaBaseUrl);
+    const settings = readSettingsFile(path);
+    const agents = Array.isArray(settings.agents) ? [...settings.agents] : [];
+    const matchIdx = agents.findIndex((a) => a.agentId === opts.agentId && (a.baseUrl ?? undefined) === normalizedBaseUrl);
+    let outcome;
+    if (matchIdx >= 0) {
+        const existing = agents[matchIdx];
+        const prev = existing.toolset;
+        if (prev === "none") {
+            outcome = { kind: "noop", previousToolset: "none" };
+            opts.logger?.debug({ agentId: opts.agentId, baseUrl: normalizedBaseUrl }, "letta_code_settings_seed_noop");
+            return outcome;
+        }
+        agents[matchIdx] = { ...existing, toolset: "none" };
+        outcome = { kind: "updated", previousToolset: prev };
+    }
+    else {
+        const entry = {
+            agentId: opts.agentId,
+            toolset: "none",
+        };
+        if (normalizedBaseUrl !== undefined)
+            entry.baseUrl = normalizedBaseUrl;
+        agents.push(entry);
+        outcome = { kind: "created", previousToolset: undefined };
+    }
+    const next = { ...settings, agents };
+    writeSettingsFile(path, next);
+    opts.logger?.info({
+        agentId: opts.agentId,
+        baseUrl: normalizedBaseUrl,
+        outcome: outcome.kind,
+        previousToolset: outcome.previousToolset,
+        settingsPath: path,
+    }, "letta_code_settings_seed");
+    return outcome;
+}
+//# sourceMappingURL=settingsFileSeed.js.map

package/dist/letta/settingsFileSeed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settingsFileSeed.js","sourceRoot":"","sources":["../../src/letta/settingsFileSeed.ts"],"names":[],"mappings":"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"}

package/dist/letta/subprocessThrottle.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Dynamic RAM-based concurrent-spawn throttle for Letta Code subprocesses.
+ *
+ * Every time we're about to spawn a Letta Code CLI subprocess (which happens
+ * once per chat turn — see `letta/client.ts` → `streamUserMessage`), we call
+ * `acquire()` first. If the host's *available* RAM has dropped below a
+ * configured threshold OR we've already got the configured hard-cap of live
+ * subprocesses, `acquire()` throws `ServerOverloadedError`. The chat route
+ * catches that and returns HTTP 503 with the `server_overloaded` SSE error
+ * event so the React client can surface a "server is busy" banner.
+ *
+ * **Why MemAvailable, not MemFree.** Linux uses unused RAM as page cache;
+ * `os.freemem()` / `/proc/meminfo`'s `MemFree` line reports memory that's
+ * *literally* unallocated, which on any healthy server is misleadingly low
+ * (often ~5% even when ~50% is actually allocatable without swapping).
+ * `/proc/meminfo`'s `MemAvailable` line is the kernel's own estimate of
+ * "memory that could be allocated without entering swap" — that's what we
+ * compare against the threshold.
+ *
+ * **Why two gates and not one.** The RAM gate is the primary throttle and
+ * adapts to whatever EC2 instance the deployment runs on. The hard-cap is a
+ * circuit breaker: if our `/proc/meminfo` math is ever wrong (kernel reports
+ * stale numbers under load, container cgroup limits trip earlier than host
+ * MemAvailable suggests, …), an unbounded subprocess pool would still be
+ * able to OOM-kill the box. The hard-cap is the floor on how bad it can get.
+ *
+ * @see ../../docs/operations/env-vars.md
+ */
+/** Default minimum percentage of total RAM that must be available before we'll
+ *  spawn a new subprocess. Overridable via env. */
+export declare const DEFAULT_RAM_THRESHOLD_PCT = 20;
+/** Default hard cap on concurrent live subprocesses. Overridable via env. */
+export declare const DEFAULT_HARD_CAP = 100;
+/**
+ * Resolved throttle config. Pulled from env at construction time; tests pass
+ * an explicit one to bypass env reading.
+ */
+export interface ThrottleConfig {
+    /** Minimum % of total RAM that must remain available to accept a spawn. */
+    ramThresholdPct: number;
+    /** Maximum concurrent live subprocesses, regardless of RAM. */
+    hardCap: number;
+}
+/**
+ * Reads throttle config from the process environment, with defaults.
+ *
+ * Env vars:
+ * - `AI_HUB_SUBPROCESS_RAM_THRESHOLD_PCT` — integer 0..100. Defaults to 20.
+ *   A value <= 0 disables the RAM gate (every acquire passes the RAM check).
+ *   A value >= 100 means every acquire fails the RAM check (useful for
+ *   testing the overload path).
+ * - `AI_HUB_SUBPROCESS_HARD_CAP` — positive integer. Defaults to 100.
+ *
+ * @returns the parsed config bundle.
+ */
+export declare function readThrottleConfigFromEnv(): ThrottleConfig;
+/**
+ * Reader for the host's MemAvailable + MemTotal. Returns kilobytes (matches
+ * `/proc/meminfo` units). Tests inject a fake reader so they don't depend on
+ * the host's actual memory state.
+ */
+export interface MemReader {
+    /** @returns `{availableKb, totalKb}` snapshot at the moment of call. */
+    read(): {
+        availableKb: number;
+        totalKb: number;
+    };
+}
+/**
+ * Default reader — parses `/proc/meminfo` directly. Falls back to
+ * `os.totalmem()` for `totalKb` when /proc is unreadable (non-Linux), and
+ * returns `MemTotal` as `availableKb` in that case so the RAM gate is
+ * effectively disabled there (the hard-cap still applies).
+ *
+ * This file lives at a stable kernel-exposed path on every Linux host
+ * (including in Docker without any special mounts) so no privileges are
+ * needed.
+ *
+ * @see https://www.kernel.org/doc/Documentation/filesystems/proc.txt — the
+ *   meminfo section documents MemAvailable's semantics ("estimate of how
+ *   much memory is available for starting new applications, without
+ *   swapping").
+ */
+export declare const procMeminfoReader: MemReader;
+/**
+ * Typed error thrown by `SubprocessThrottle.acquire()` when the host is too
+ * loaded to accept another subprocess. The chat route catches this and
+ * returns HTTP 503 with an `error {server_overloaded}` SSE event.
+ */
+export declare class ServerOverloadedError extends Error {
+    /** Stable error code for the SSE wire protocol's `error.code` field. */
+    readonly code: "server_overloaded";
+    /** Which gate tripped — useful for logs + the eventual operator playbook. */
+    readonly gate: "ram" | "hard_cap";
+    /** Snapshot of the trigger at the moment we rejected. */
+    readonly detail: {
+        /** MemAvailable as a fraction of MemTotal at the time of rejection. */
+        availablePct: number;
+        /** Live subprocess count at the time of rejection. */
+        liveCount: number;
+        /** Configured RAM threshold (percent). */
+        ramThresholdPct: number;
+        /** Configured hard cap. */
+        hardCap: number;
+    };
+    constructor(gate: "ram" | "hard_cap", detail: ServerOverloadedError["detail"]);
+}
+/**
+ * A leased slot in the throttle's live-subprocess counter. Returned by
+ * `acquire()`; callers must call `release()` exactly once (use try/finally).
+ */
+export interface ThrottleLease {
+    /** Releases the slot back to the throttle. Idempotent — calling twice
+     *  is a no-op. */
+    release(): void;
+}
+/**
+ * The throttle.
+ *
+ * Construct one per ai-hub-server process (it's stateful — the live-count
+ * counter is in-memory). Production wires this into `AIHubServerContext` via
+ * `createFetchHandler`; tests pass a fake `MemReader` to drive the RAM gate
+ * deterministically.
+ */
+export declare class SubprocessThrottle {
+    readonly config: ThrottleConfig;
+    private readonly memReader;
+    private liveCount;
+    /**
+     * @param config - resolved throttle config (use `readThrottleConfigFromEnv`).
+     * @param memReader - mem reader (defaults to /proc/meminfo).
+     */
+    constructor(config: ThrottleConfig, memReader?: MemReader);
+    /**
+     * Attempts to acquire a slot. Throws `ServerOverloadedError` synchronously
+     * if either gate trips; otherwise increments the live counter and returns
+     * a lease the caller must release when the subprocess exits.
+     *
+     * The acquire-then-spawn dance has a small race: between the RAM check
+     * here and the actual spawn, another concurrent acquire could land. That's
+     * acceptable for v1 — the next acquire will see the updated MemAvailable
+     * and the hard cap is the absolute backstop.
+     *
+     * @returns a lease the caller must `.release()` in finally.
+     * @throws `ServerOverloadedError` if either gate trips.
+     */
+    acquire(): ThrottleLease;
+    /** @returns the current live-subprocess count (for observability + tests). */
+    get currentLiveCount(): number;
+}
+//# sourceMappingURL=subprocessThrottle.d.ts.map

package/dist/letta/subprocessThrottle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocessThrottle.d.ts","sourceRoot":"","sources":["../../src/letta/subprocessThrottle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AASH;mDACmD;AACnD,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAC5C,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,2EAA2E;IAC3E,eAAe,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,IAAI,cAAc,CAO1D;AAaD;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,wEAAwE;IACxE,IAAI,IAAI;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAClD;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAe/B,CAAC;AAMF;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAG,mBAAmB,CAAU;IAC7C,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,UAAU,CAAC;IAClC,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE;QACf,uEAAuE;QACvE,YAAY,EAAE,MAAM,CAAC;QACrB,sDAAsD;QACtD,SAAS,EAAE,MAAM,CAAC;QAClB,0CAA0C;QAC1C,eAAe,EAAE,MAAM,CAAC;QACxB,2BAA2B;QAC3B,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;gBAEU,IAAI,EAAE,KAAK,GAAG,UAAU,EAAE,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC;CAU9E;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;sBACkB;IAClB,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;GAOG;AACH,qBAAa,kBAAkB;IAC7B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,SAAS,CAAK;IAEtB;;;OAGG;gBACS,MAAM,EAAE,cAAc,EAAE,SAAS,GAAE,SAA6B;IAK5E;;;;;;;;;;;;OAYG;IACH,OAAO,IAAI,aAAa;IAoCxB,8EAA8E;IAC9E,IAAI,gBAAgB,IAAI,MAAM,CAE7B;CACF"}

package/dist/letta/subprocessThrottle.js

@@ -0,0 +1,195 @@
+/**
+ * Dynamic RAM-based concurrent-spawn throttle for Letta Code subprocesses.
+ *
+ * Every time we're about to spawn a Letta Code CLI subprocess (which happens
+ * once per chat turn — see `letta/client.ts` → `streamUserMessage`), we call
+ * `acquire()` first. If the host's *available* RAM has dropped below a
+ * configured threshold OR we've already got the configured hard-cap of live
+ * subprocesses, `acquire()` throws `ServerOverloadedError`. The chat route
+ * catches that and returns HTTP 503 with the `server_overloaded` SSE error
+ * event so the React client can surface a "server is busy" banner.
+ *
+ * **Why MemAvailable, not MemFree.** Linux uses unused RAM as page cache;
+ * `os.freemem()` / `/proc/meminfo`'s `MemFree` line reports memory that's
+ * *literally* unallocated, which on any healthy server is misleadingly low
+ * (often ~5% even when ~50% is actually allocatable without swapping).
+ * `/proc/meminfo`'s `MemAvailable` line is the kernel's own estimate of
+ * "memory that could be allocated without entering swap" — that's what we
+ * compare against the threshold.
+ *
+ * **Why two gates and not one.** The RAM gate is the primary throttle and
+ * adapts to whatever EC2 instance the deployment runs on. The hard-cap is a
+ * circuit breaker: if our `/proc/meminfo` math is ever wrong (kernel reports
+ * stale numbers under load, container cgroup limits trip earlier than host
+ * MemAvailable suggests, …), an unbounded subprocess pool would still be
+ * able to OOM-kill the box. The hard-cap is the floor on how bad it can get.
+ *
+ * @see ../../docs/operations/env-vars.md
+ */
+import { readFileSync } from "node:fs";
+import { totalmem } from "node:os";
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Config                                                                    */
+/* ────────────────────────────────────────────────────────────────────────── */
+/** Default minimum percentage of total RAM that must be available before we'll
+ *  spawn a new subprocess. Overridable via env. */
+export const DEFAULT_RAM_THRESHOLD_PCT = 20;
+/** Default hard cap on concurrent live subprocesses. Overridable via env. */
+export const DEFAULT_HARD_CAP = 100;
+/**
+ * Reads throttle config from the process environment, with defaults.
+ *
+ * Env vars:
+ * - `AI_HUB_SUBPROCESS_RAM_THRESHOLD_PCT` — integer 0..100. Defaults to 20.
+ *   A value <= 0 disables the RAM gate (every acquire passes the RAM check).
+ *   A value >= 100 means every acquire fails the RAM check (useful for
+ *   testing the overload path).
+ * - `AI_HUB_SUBPROCESS_HARD_CAP` — positive integer. Defaults to 100.
+ *
+ * @returns the parsed config bundle.
+ */
+export function readThrottleConfigFromEnv() {
+    const rawPct = process.env.AI_HUB_SUBPROCESS_RAM_THRESHOLD_PCT;
+    const rawCap = process.env.AI_HUB_SUBPROCESS_HARD_CAP;
+    return {
+        ramThresholdPct: parseIntInRange(rawPct, 0, 100, DEFAULT_RAM_THRESHOLD_PCT),
+        hardCap: parseIntInRange(rawCap, 1, 10_000, DEFAULT_HARD_CAP),
+    };
+}
+function parseIntInRange(raw, min, max, fallback) {
+    if (raw === undefined || raw === "")
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < min || parsed > max)
+        return fallback;
+    return parsed;
+}
+/**
+ * Default reader — parses `/proc/meminfo` directly. Falls back to
+ * `os.totalmem()` for `totalKb` when /proc is unreadable (non-Linux), and
+ * returns `MemTotal` as `availableKb` in that case so the RAM gate is
+ * effectively disabled there (the hard-cap still applies).
+ *
+ * This file lives at a stable kernel-exposed path on every Linux host
+ * (including in Docker without any special mounts) so no privileges are
+ * needed.
+ *
+ * @see https://www.kernel.org/doc/Documentation/filesystems/proc.txt — the
+ *   meminfo section documents MemAvailable's semantics ("estimate of how
+ *   much memory is available for starting new applications, without
+ *   swapping").
+ */
+export const procMeminfoReader = {
+    read() {
+        try {
+            const raw = readFileSync("/proc/meminfo", "utf8");
+            const total = raw.match(/^MemTotal:\s+(\d+)\s+kB/m);
+            const available = raw.match(/^MemAvailable:\s+(\d+)\s+kB/m);
+            if (total && available) {
+                return { totalKb: Number(total[1]), availableKb: Number(available[1]) };
+            }
+        }
+        catch {
+            // Fall through to the os.totalmem fallback.
+        }
+        const totalKb = Math.round(totalmem() / 1024);
+        return { totalKb, availableKb: totalKb };
+    },
+};
+/* ────────────────────────────────────────────────────────────────────────── */
+/*  Throttle                                                                  */
+/* ────────────────────────────────────────────────────────────────────────── */
+/**
+ * Typed error thrown by `SubprocessThrottle.acquire()` when the host is too
+ * loaded to accept another subprocess. The chat route catches this and
+ * returns HTTP 503 with an `error {server_overloaded}` SSE event.
+ */
+export class ServerOverloadedError extends Error {
+    /** Stable error code for the SSE wire protocol's `error.code` field. */
+    code = "server_overloaded";
+    /** Which gate tripped — useful for logs + the eventual operator playbook. */
+    gate;
+    /** Snapshot of the trigger at the moment we rejected. */
+    detail;
+    constructor(gate, detail) {
+        super(gate === "ram"
+            ? `Server overloaded: only ${detail.availablePct.toFixed(1)}% RAM available (< ${detail.ramThresholdPct}% required).`
+            : `Server overloaded: ${detail.liveCount} live subprocesses (>= ${detail.hardCap} hard cap).`);
+        this.name = "ServerOverloadedError";
+        this.gate = gate;
+        this.detail = detail;
+    }
+}
+/**
+ * The throttle.
+ *
+ * Construct one per ai-hub-server process (it's stateful — the live-count
+ * counter is in-memory). Production wires this into `AIHubServerContext` via
+ * `createFetchHandler`; tests pass a fake `MemReader` to drive the RAM gate
+ * deterministically.
+ */
+export class SubprocessThrottle {
+    config;
+    memReader;
+    liveCount = 0;
+    /**
+     * @param config - resolved throttle config (use `readThrottleConfigFromEnv`).
+     * @param memReader - mem reader (defaults to /proc/meminfo).
+     */
+    constructor(config, memReader = procMeminfoReader) {
+        this.config = config;
+        this.memReader = memReader;
+    }
+    /**
+     * Attempts to acquire a slot. Throws `ServerOverloadedError` synchronously
+     * if either gate trips; otherwise increments the live counter and returns
+     * a lease the caller must release when the subprocess exits.
+     *
+     * The acquire-then-spawn dance has a small race: between the RAM check
+     * here and the actual spawn, another concurrent acquire could land. That's
+     * acceptable for v1 — the next acquire will see the updated MemAvailable
+     * and the hard cap is the absolute backstop.
+     *
+     * @returns a lease the caller must `.release()` in finally.
+     * @throws `ServerOverloadedError` if either gate trips.
+     */
+    acquire() {
+        // Hard cap check first — it's cheap and the more deterministic gate.
+        if (this.liveCount >= this.config.hardCap) {
+            throw new ServerOverloadedError("hard_cap", {
+                availablePct: 100, // unknown but irrelevant; the cap gate fired
+                liveCount: this.liveCount,
+                ramThresholdPct: this.config.ramThresholdPct,
+                hardCap: this.config.hardCap,
+            });
+        }
+        // RAM gate. ramThresholdPct=0 disables this gate entirely.
+        if (this.config.ramThresholdPct > 0) {
+            const { availableKb, totalKb } = this.memReader.read();
+            const availablePct = totalKb > 0 ? (availableKb / totalKb) * 100 : 100;
+            if (availablePct < this.config.ramThresholdPct) {
+                throw new ServerOverloadedError("ram", {
+                    availablePct,
+                    liveCount: this.liveCount,
+                    ramThresholdPct: this.config.ramThresholdPct,
+                    hardCap: this.config.hardCap,
+                });
+            }
+        }
+        this.liveCount++;
+        let released = false;
+        return {
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                this.liveCount--;
+            },
+        };
+    }
+    /** @returns the current live-subprocess count (for observability + tests). */
+    get currentLiveCount() {
+        return this.liveCount;
+    }
+}
+//# sourceMappingURL=subprocessThrottle.js.map

package/dist/letta/subprocessThrottle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocessThrottle.js","sourceRoot":"","sources":["../../src/letta/subprocessThrottle.ts"],"names":[],"mappings":"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"}