thaddeus 1.0.26 → 1.0.28

package/src/upstreamproxy/relay.js

@@ -0,0 +1,346 @@
+/* eslint-disable eslint-plugin-n/no-unsupported-features/node-builtins */
+/**
+ * CONNECT-over-WebSocket relay for CCR upstreamproxy.
+ *
+ * Listens on localhost TCP, accepts HTTP CONNECT from curl/gh/kubectl/etc,
+ * and tunnels bytes over WebSocket to the CCR upstreamproxy endpoint.
+ * The CCR server-side terminates the tunnel, MITMs TLS, injects org-configured
+ * credentials (e.g. DD-API-KEY), and forwards to the real upstream.
+ *
+ * WHY WebSocket and not raw CONNECT: CCR ingress is GKE L7 with path-prefix
+ * routing; there's no connect_matcher in cdk-constructs. The session-ingress
+ * tunnel (sessions/tunnel/v1alpha/tunnel.proto) already uses this pattern.
+ *
+ * Protocol: bytes are wrapped in UpstreamProxyChunk protobuf messages
+ * (`message UpstreamProxyChunk { bytes data = 1; }`) for compatibility with
+ * gateway.NewWebSocketStreamAdapter on the server side.
+ */
+import { createServer } from 'node:net';
+import { logForDebugging } from '../utils/debug.js';
+import { getWebSocketTLSOptions } from '../utils/mtls.js';
+import { getWebSocketProxyAgent, getWebSocketProxyUrl } from '../utils/proxy.js';
+let nodeWSCtor;
+// Envoy per-request buffer cap. Week-1 Datadog payloads won't hit this, but
+// design for it so git-push doesn't need a relay rewrite.
+const MAX_CHUNK_BYTES = 512 * 1024;
+// Sidecar idle timeout is 50s; ping well inside that.
+const PING_INTERVAL_MS = 30_000;
+/**
+ * Encode an UpstreamProxyChunk protobuf message by hand.
+ *
+ * For `message UpstreamProxyChunk { bytes data = 1; }` the wire format is:
+ *   tag = (field_number << 3) | wire_type = (1 << 3) | 2 = 0x0a
+ *   followed by varint length, followed by the bytes.
+ *
+ * protobufjs would be the general answer; for a single-field bytes message
+ * the hand encoding is 10 lines and avoids a runtime dep in the hot path.
+ */
+export function encodeChunk(data) {
+    const len = data.length;
+    // varint encoding of length — most chunks fit in 1–3 length bytes
+    const varint = [];
+    let n = len;
+    while (n > 0x7f) {
+        varint.push((n & 0x7f) | 0x80);
+        n >>>= 7;
+    }
+    varint.push(n);
+    const out = new Uint8Array(1 + varint.length + len);
+    out[0] = 0x0a;
+    out.set(varint, 1);
+    out.set(data, 1 + varint.length);
+    return out;
+}
+/**
+ * Decode an UpstreamProxyChunk. Returns the data field, or null if malformed.
+ * Tolerates the server sending a zero-length chunk (keepalive semantics).
+ */
+export function decodeChunk(buf) {
+    if (buf.length === 0)
+        return new Uint8Array(0);
+    if (buf[0] !== 0x0a)
+        return null;
+    let len = 0;
+    let shift = 0;
+    let i = 1;
+    while (i < buf.length) {
+        const b = buf[i];
+        len |= (b & 0x7f) << shift;
+        i++;
+        if ((b & 0x80) === 0)
+            break;
+        shift += 7;
+        if (shift > 28)
+            return null;
+    }
+    if (i + len > buf.length)
+        return null;
+    return buf.subarray(i, i + len);
+}
+function newConnState() {
+    return {
+        connectBuf: Buffer.alloc(0),
+        pending: [],
+        wsOpen: false,
+        established: false,
+        closed: false,
+    };
+}
+/**
+ * Start the relay. Returns the ephemeral port it bound and a stop function.
+ * Uses Bun.listen when available, otherwise Node's net.createServer — the CCR
+ * container runs the CLI under Node, not Bun.
+ */
+export async function startUpstreamProxyRelay(opts) {
+    const authHeader = 'Basic ' + Buffer.from(`${opts.sessionId}:${opts.token}`).toString('base64');
+    // WS upgrade itself is auth-gated (proto authn: PRIVATE_API) — the gateway
+    // wants the session-ingress JWT on the upgrade request, separate from the
+    // Proxy-Authorization that rides inside the tunneled CONNECT.
+    const wsAuthHeader = `Bearer ${opts.token}`;
+    const relay = typeof Bun !== 'undefined'
+        ? startBunRelay(opts.wsUrl, authHeader, wsAuthHeader)
+        : await startNodeRelay(opts.wsUrl, authHeader, wsAuthHeader);
+    logForDebugging(`[upstreamproxy] relay listening on 127.0.0.1:${relay.port}`);
+    return relay;
+}
+function startBunRelay(wsUrl, authHeader, wsAuthHeader) {
+    // eslint-disable-next-line custom-rules/require-bun-typeof-guard -- caller dispatches on typeof Bun
+    const server = Bun.listen({
+        hostname: '127.0.0.1',
+        port: 0,
+        socket: {
+            open(sock) {
+                sock.data = { ...newConnState(), writeBuf: [] };
+            },
+            data(sock, data) {
+                const st = sock.data;
+                const adapter = {
+                    write: payload => {
+                        const bytes = typeof payload === 'string'
+                            ? Buffer.from(payload, 'utf8')
+                            : payload;
+                        if (st.writeBuf.length > 0) {
+                            st.writeBuf.push(bytes);
+                            return;
+                        }
+                        const n = sock.write(bytes);
+                        if (n < bytes.length)
+                            st.writeBuf.push(bytes.subarray(n));
+                    },
+                    end: () => sock.end(),
+                };
+                handleData(adapter, st, data, wsUrl, authHeader, wsAuthHeader);
+            },
+            drain(sock) {
+                const st = sock.data;
+                while (st.writeBuf.length > 0) {
+                    const chunk = st.writeBuf[0];
+                    const n = sock.write(chunk);
+                    if (n < chunk.length) {
+                        st.writeBuf[0] = chunk.subarray(n);
+                        return;
+                    }
+                    st.writeBuf.shift();
+                }
+            },
+            close(sock) {
+                cleanupConn(sock.data);
+            },
+            error(sock, err) {
+                logForDebugging(`[upstreamproxy] client socket error: ${err.message}`);
+                cleanupConn(sock.data);
+            },
+        },
+    });
+    return {
+        port: server.port,
+        stop: () => server.stop(true),
+    };
+}
+// Exported so tests can exercise the Node path directly — the test runner is
+// Bun, so the runtime dispatch in startUpstreamProxyRelay always picks Bun.
+export async function startNodeRelay(wsUrl, authHeader, wsAuthHeader) {
+    nodeWSCtor = (await import('ws')).default;
+    const states = new WeakMap();
+    const server = createServer(sock => {
+        const st = newConnState();
+        states.set(sock, st);
+        // Node's sock.write() buffers internally — a false return signals
+        // backpressure but the bytes are already queued, so no tail-tracking
+        // needed for correctness. Week-1 payloads won't stress the buffer.
+        const adapter = {
+            write: payload => {
+                sock.write(typeof payload === 'string' ? payload : Buffer.from(payload));
+            },
+            end: () => sock.end(),
+        };
+        sock.on('data', data => handleData(adapter, st, data, wsUrl, authHeader, wsAuthHeader));
+        sock.on('close', () => cleanupConn(states.get(sock)));
+        sock.on('error', err => {
+            logForDebugging(`[upstreamproxy] client socket error: ${err.message}`);
+            cleanupConn(states.get(sock));
+        });
+    });
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            if (addr === null || typeof addr === 'string') {
+                reject(new Error('upstreamproxy: server has no TCP address'));
+                return;
+            }
+            resolve({
+                port: addr.port,
+                stop: () => server.close(),
+            });
+        });
+    });
+}
+/**
+ * Shared per-connection data handler. Phase 1 accumulates the CONNECT request;
+ * phase 2 forwards client bytes over the WS tunnel.
+ */
+function handleData(sock, st, data, wsUrl, authHeader, wsAuthHeader) {
+    // Phase 1: accumulate until we've seen the full CONNECT request
+    // (terminated by CRLF CRLF). curl/gh send this in one packet, but
+    // don't assume that.
+    if (!st.ws) {
+        st.connectBuf = Buffer.concat([st.connectBuf, data]);
+        const headerEnd = st.connectBuf.indexOf('\r\n\r\n');
+        if (headerEnd === -1) {
+            // Guard against a client that never sends CRLFCRLF.
+            if (st.connectBuf.length > 8192) {
+                sock.write('HTTP/1.1 400 Bad Request\r\n\r\n');
+                sock.end();
+            }
+            return;
+        }
+        const reqHead = st.connectBuf.subarray(0, headerEnd).toString('utf8');
+        const firstLine = reqHead.split('\r\n')[0] ?? '';
+        const m = firstLine.match(/^CONNECT\s+(\S+)\s+HTTP\/1\.[01]$/i);
+        if (!m) {
+            sock.write('HTTP/1.1 405 Method Not Allowed\r\n\r\n');
+            sock.end();
+            return;
+        }
+        // Stash any bytes that arrived after the CONNECT header so
+        // openTunnel can flush them once the WS is open.
+        const trailing = st.connectBuf.subarray(headerEnd + 4);
+        if (trailing.length > 0) {
+            st.pending.push(Buffer.from(trailing));
+        }
+        st.connectBuf = Buffer.alloc(0);
+        openTunnel(sock, st, firstLine, wsUrl, authHeader, wsAuthHeader);
+        return;
+    }
+    // Phase 2: WS exists. If it isn't OPEN yet, buffer; ws.onopen will
+    // flush. Once open, pump client bytes to WS in chunks.
+    if (!st.wsOpen) {
+        st.pending.push(Buffer.from(data));
+        return;
+    }
+    forwardToWs(st.ws, data);
+}
+function openTunnel(sock, st, connectLine, wsUrl, authHeader, wsAuthHeader) {
+    // core/websocket/stream.go picks JSON vs binary-proto from the upgrade
+    // request's Content-Type header (defaults to JSON). Without application/proto
+    // the server protojson.Unmarshals our hand-encoded binary chunks and fails
+    // silently with EOF.
+    const headers = {
+        'Content-Type': 'application/proto',
+        Authorization: wsAuthHeader,
+    };
+    let ws;
+    if (nodeWSCtor) {
+        ws = new nodeWSCtor(wsUrl, {
+            headers,
+            agent: getWebSocketProxyAgent(wsUrl),
+            ...getWebSocketTLSOptions(),
+        });
+    }
+    else {
+        ws = new globalThis.WebSocket(wsUrl, {
+            // @ts-expect-error — Bun extension; not in lib.dom WebSocket types
+            headers,
+            proxy: getWebSocketProxyUrl(wsUrl),
+            tls: getWebSocketTLSOptions() || undefined,
+        });
+    }
+    ws.binaryType = 'arraybuffer';
+    st.ws = ws;
+    ws.onopen = () => {
+        // First chunk carries the CONNECT line plus Proxy-Authorization so the
+        // server can auth the tunnel and know the target host:port. Server
+        // responds with its own "HTTP/1.1 200" over the tunnel; we just pipe it.
+        const head = `${connectLine}\r\n` + `Proxy-Authorization: ${authHeader}\r\n` + `\r\n`;
+        ws.send(encodeChunk(Buffer.from(head, 'utf8')));
+        // Flush anything that arrived while the WS handshake was in flight —
+        // trailing bytes from the CONNECT packet and any data() callbacks that
+        // fired before onopen.
+        st.wsOpen = true;
+        for (const buf of st.pending) {
+            forwardToWs(ws, buf);
+        }
+        st.pending = [];
+        // Not all WS implementations expose ping(); empty chunk works as an
+        // application-level keepalive the server can ignore.
+        st.pinger = setInterval(sendKeepalive, PING_INTERVAL_MS, ws);
+    };
+    ws.onmessage = ev => {
+        const raw = ev.data instanceof ArrayBuffer
+            ? new Uint8Array(ev.data)
+            : new Uint8Array(Buffer.from(ev.data));
+        const payload = decodeChunk(raw);
+        if (payload && payload.length > 0) {
+            st.established = true;
+            sock.write(payload);
+        }
+    };
+    ws.onerror = ev => {
+        const msg = 'message' in ev ? String(ev.message) : 'websocket error';
+        logForDebugging(`[upstreamproxy] ws error: ${msg}`);
+        if (st.closed)
+            return;
+        st.closed = true;
+        if (!st.established) {
+            sock.write('HTTP/1.1 502 Bad Gateway\r\n\r\n');
+        }
+        sock.end();
+        cleanupConn(st);
+    };
+    ws.onclose = () => {
+        if (st.closed)
+            return;
+        st.closed = true;
+        sock.end();
+        cleanupConn(st);
+    };
+}
+function sendKeepalive(ws) {
+    if (ws.readyState === WebSocket.OPEN) {
+        ws.send(encodeChunk(new Uint8Array(0)));
+    }
+}
+function forwardToWs(ws, data) {
+    if (ws.readyState !== WebSocket.OPEN)
+        return;
+    for (let off = 0; off < data.length; off += MAX_CHUNK_BYTES) {
+        const slice = data.subarray(off, off + MAX_CHUNK_BYTES);
+        ws.send(encodeChunk(slice));
+    }
+}
+function cleanupConn(st) {
+    if (!st)
+        return;
+    if (st.pinger)
+        clearInterval(st.pinger);
+    if (st.ws && st.ws.readyState <= WebSocket.OPEN) {
+        try {
+            st.ws.close();
+        }
+        catch {
+            // already closing
+        }
+    }
+    st.ws = undefined;
+}

package/src/upstreamproxy/upstreamproxy.js

@@ -0,0 +1,234 @@
+/**
+ * CCR upstreamproxy — container-side wiring.
+ *
+ * When running inside a CCR session container with upstreamproxy configured,
+ * this module:
+ *   1. Reads the session token from /run/ccr/session_token
+ *   2. Sets prctl(PR_SET_DUMPABLE, 0) to block same-UID ptrace of the heap
+ *   3. Downloads the upstreamproxy CA cert and concatenates it with the
+ *      system bundle so curl/gh/python trust the MITM proxy
+ *   4. Starts a local CONNECT→WebSocket relay (see relay.ts)
+ *   5. Unlinks the token file (token stays heap-only; file is gone before
+ *      the agent loop can see it, but only after the relay is confirmed up
+ *      so a supervisor restart can retry)
+ *   6. Exposes HTTPS_PROXY / SSL_CERT_FILE env vars for all agent subprocesses
+ *
+ * Every step fails open: any error logs a warning and disables the proxy.
+ * A broken proxy setup must never break an otherwise-working session.
+ *
+ * Design doc: api-go/ccr/docs/plans/CCR_AUTH_DESIGN.md § "Week-1 pilot scope".
+ */
+import { mkdir, readFile, unlink, writeFile } from 'fs/promises';
+import { homedir } from 'os';
+import { join } from 'path';
+import { registerCleanup } from '../utils/cleanupRegistry.js';
+import { logForDebugging } from '../utils/debug.js';
+import { isEnvTruthy } from '../utils/envUtils.js';
+import { isENOENT } from '../utils/errors.js';
+import { startUpstreamProxyRelay } from './relay.js';
+export const SESSION_TOKEN_PATH = '/run/ccr/session_token';
+const SYSTEM_CA_BUNDLE = '/etc/ssl/certs/ca-certificates.crt';
+// Hosts the proxy must NOT intercept. Covers loopback, RFC1918, the IMDS
+// range, and the package registries + GitHub that CCR containers already
+// reach directly. Mirrors airlock/scripts/sandbox-shell-ccr.sh.
+const NO_PROXY_LIST = [
+    'localhost',
+    '127.0.0.1',
+    '::1',
+    '169.254.0.0/16',
+    '10.0.0.0/8',
+    '172.16.0.0/12',
+    '192.168.0.0/16',
+    // Delphi Labs API: no upstream route will ever match, and the MITM breaks
+    // non-Bun runtimes (Python httpx/certifi doesn't trust the forged CA).
+    // Three forms because NO_PROXY parsing differs across runtimes:
+    //   *.delphilabsinc.com  — Bun, curl, Go (glob match)
+    //   .delphilabsinc.com   — Python urllib/httpx (suffix match, strips leading dot)
+    //   delphilabsinc.com    — apex domain fallback
+    'delphilabsinc.com',
+    '.delphilabsinc.com',
+    '*.delphilabsinc.com',
+    'github.com',
+    'api.github.com',
+    '*.github.com',
+    '*.githubusercontent.com',
+    'registry.npmjs.org',
+    'pypi.org',
+    'files.pythonhosted.org',
+    'index.crates.io',
+    'proxy.golang.org',
+].join(',');
+let state = { enabled: false };
+/**
+ * Initialize upstreamproxy. Called once from init.ts. Safe to call when the
+ * feature is off or the token file is absent — returns {enabled: false}.
+ *
+ * Overridable paths are for tests; production uses the defaults.
+ */
+export async function initUpstreamProxy(opts) {
+    if (!isEnvTruthy(process.env.THADDEUS_REMOTE)) {
+        return state;
+    }
+    // CCR evaluates ccr_upstream_proxy_enabled server-side (where GrowthBook is
+    // warm) and injects this env var via StartupContext.EnvironmentVariables.
+    // Every CCR session is a fresh container with no GB cache, so a client-side
+    // GB check here always returned the default (false).
+    if (!isEnvTruthy(process.env.CCR_UPSTREAM_PROXY_ENABLED)) {
+        return state;
+    }
+    const sessionId = process.env.THADDEUS_REMOTE_SESSION_ID;
+    if (!sessionId) {
+        logForDebugging('[upstreamproxy] THADDEUS_REMOTE_SESSION_ID unset; proxy disabled', { level: 'warn' });
+        return state;
+    }
+    const tokenPath = opts?.tokenPath ?? SESSION_TOKEN_PATH;
+    const token = await readToken(tokenPath);
+    if (!token) {
+        logForDebugging('[upstreamproxy] no session token file; proxy disabled');
+        return state;
+    }
+    setNonDumpable();
+    // CCR injects ANTHROPIC_BASE_URL via StartupContext (sessionExecutor.ts /
+    // sessionHandler.ts). getOauthConfig() is wrong here: it keys off
+    // USER_TYPE + USE_{LOCAL,STAGING}_OAUTH, none of which the container sets,
+    // so it always returned the prod URL and the CA fetch 404'd.
+    const baseUrl = opts?.ccrBaseUrl ??
+        process.env.ANTHROPIC_BASE_URL ??
+        'https://api.delphilabsinc.com';
+    const caBundlePath = opts?.caBundlePath ?? join(homedir(), '.ccr', 'ca-bundle.crt');
+    const caOk = await downloadCaBundle(baseUrl, opts?.systemCaPath ?? SYSTEM_CA_BUNDLE, caBundlePath);
+    if (!caOk)
+        return state;
+    try {
+        const wsUrl = baseUrl.replace(/^http/, 'ws') + '/v1/code/upstreamproxy/ws';
+        const relay = await startUpstreamProxyRelay({ wsUrl, sessionId, token });
+        registerCleanup(async () => relay.stop());
+        state = { enabled: true, port: relay.port, caBundlePath };
+        logForDebugging(`[upstreamproxy] enabled on 127.0.0.1:${relay.port}`);
+        // Only unlink after the listener is up: if CA download or listen()
+        // fails, a supervisor restart can retry with the token still on disk.
+        await unlink(tokenPath).catch(() => {
+            logForDebugging('[upstreamproxy] token file unlink failed', {
+                level: 'warn',
+            });
+        });
+    }
+    catch (err) {
+        logForDebugging(`[upstreamproxy] relay start failed: ${err instanceof Error ? err.message : String(err)}; proxy disabled`, { level: 'warn' });
+    }
+    return state;
+}
+/**
+ * Env vars to merge into every agent subprocess. Empty when the proxy is
+ * disabled. Called from subprocessEnv() so Bash/MCP/LSP/hooks all inherit
+ * the same recipe.
+ */
+export function getUpstreamProxyEnv() {
+    if (!state.enabled || !state.port || !state.caBundlePath) {
+        // Child CLI processes can't re-initialize the relay (token file was
+        // unlinked by the parent), but the parent's relay is still running and
+        // reachable at 127.0.0.1:<port>. If we inherited proxy vars from the
+        // parent (HTTPS_PROXY + SSL_CERT_FILE both set), pass them through so
+        // our subprocesses also route through the parent's relay.
+        if (process.env.HTTPS_PROXY && process.env.SSL_CERT_FILE) {
+            const inherited = {};
+            for (const key of [
+                'HTTPS_PROXY',
+                'https_proxy',
+                'NO_PROXY',
+                'no_proxy',
+                'SSL_CERT_FILE',
+                'NODE_EXTRA_CA_CERTS',
+                'REQUESTS_CA_BUNDLE',
+                'CURL_CA_BUNDLE',
+            ]) {
+                if (process.env[key])
+                    inherited[key] = process.env[key];
+            }
+            return inherited;
+        }
+        return {};
+    }
+    const proxyUrl = `http://127.0.0.1:${state.port}`;
+    // HTTPS only: the relay handles CONNECT and nothing else. Plain HTTP has
+    // no credentials to inject, so routing it through the relay would just
+    // break the request with a 405.
+    return {
+        HTTPS_PROXY: proxyUrl,
+        https_proxy: proxyUrl,
+        NO_PROXY: NO_PROXY_LIST,
+        no_proxy: NO_PROXY_LIST,
+        SSL_CERT_FILE: state.caBundlePath,
+        NODE_EXTRA_CA_CERTS: state.caBundlePath,
+        REQUESTS_CA_BUNDLE: state.caBundlePath,
+        CURL_CA_BUNDLE: state.caBundlePath,
+    };
+}
+/** Test-only: reset module state between test cases. */
+export function resetUpstreamProxyForTests() {
+    state = { enabled: false };
+}
+async function readToken(path) {
+    try {
+        const raw = await readFile(path, 'utf8');
+        return raw.trim() || null;
+    }
+    catch (err) {
+        if (isENOENT(err))
+            return null;
+        logForDebugging(`[upstreamproxy] token read failed: ${err instanceof Error ? err.message : String(err)}`, { level: 'warn' });
+        return null;
+    }
+}
+/**
+ * prctl(PR_SET_DUMPABLE, 0) via libc FFI. Blocks same-UID ptrace of this
+ * process, so a prompt-injected `gdb -p $PPID` can't scrape the token from
+ * the heap. Linux-only; silently no-ops elsewhere.
+ */
+function setNonDumpable() {
+    if (process.platform !== 'linux' || typeof Bun === 'undefined')
+        return;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const ffi = require('bun:ffi');
+        const lib = ffi.dlopen('libc.so.6', {
+            prctl: {
+                args: ['int', 'u64', 'u64', 'u64', 'u64'],
+                returns: 'int',
+            },
+        });
+        const PR_SET_DUMPABLE = 4;
+        const rc = lib.symbols.prctl(PR_SET_DUMPABLE, 0n, 0n, 0n, 0n);
+        if (rc !== 0) {
+            logForDebugging('[upstreamproxy] prctl(PR_SET_DUMPABLE,0) returned nonzero', {
+                level: 'warn',
+            });
+        }
+    }
+    catch (err) {
+        logForDebugging(`[upstreamproxy] prctl unavailable: ${err instanceof Error ? err.message : String(err)}`, { level: 'warn' });
+    }
+}
+async function downloadCaBundle(baseUrl, systemCaPath, outPath) {
+    try {
+        // eslint-disable-next-line eslint-plugin-n/no-unsupported-features/node-builtins
+        const resp = await fetch(`${baseUrl}/v1/code/upstreamproxy/ca-cert`, {
+            // Bun has no default fetch timeout — a hung endpoint would block CLI
+            // startup forever. 5s is generous for a small PEM.
+            signal: AbortSignal.timeout(5000),
+        });
+        if (!resp.ok) {
+            logForDebugging(`[upstreamproxy] ca-cert fetch ${resp.status}; proxy disabled`, { level: 'warn' });
+            return false;
+        }
+        const ccrCa = await resp.text();
+        const systemCa = await readFile(systemCaPath, 'utf8').catch(() => '');
+        await mkdir(join(outPath, '..'), { recursive: true });
+        await writeFile(outPath, systemCa + '\n' + ccrCa, 'utf8');
+        return true;
+    }
+    catch (err) {
+        logForDebugging(`[upstreamproxy] ca-cert download failed: ${err instanceof Error ? err.message : String(err)}; proxy disabled`, { level: 'warn' });
+        return false;
+    }
+}

package/src/utils/CircularBuffer.js

@@ -0,0 +1,75 @@
+/**
+ * A fixed-size circular buffer that automatically evicts the oldest items
+ * when the buffer is full. Useful for maintaining a rolling window of data.
+ */
+export class CircularBuffer {
+    capacity;
+    buffer;
+    head = 0;
+    size = 0;
+    constructor(capacity) {
+        this.capacity = capacity;
+        this.buffer = new Array(capacity);
+    }
+    /**
+     * Add an item to the buffer. If the buffer is full,
+     * the oldest item will be evicted.
+     */
+    add(item) {
+        this.buffer[this.head] = item;
+        this.head = (this.head + 1) % this.capacity;
+        if (this.size < this.capacity) {
+            this.size++;
+        }
+    }
+    /**
+     * Add multiple items to the buffer at once.
+     */
+    addAll(items) {
+        for (const item of items) {
+            this.add(item);
+        }
+    }
+    /**
+     * Get the most recent N items from the buffer.
+     * Returns fewer items if the buffer contains less than N items.
+     */
+    getRecent(count) {
+        const result = [];
+        const start = this.size < this.capacity ? 0 : this.head;
+        const available = Math.min(count, this.size);
+        for (let i = 0; i < available; i++) {
+            const index = (start + this.size - available + i) % this.capacity;
+            result.push(this.buffer[index]);
+        }
+        return result;
+    }
+    /**
+     * Get all items currently in the buffer, in order from oldest to newest.
+     */
+    toArray() {
+        if (this.size === 0)
+            return [];
+        const result = [];
+        const start = this.size < this.capacity ? 0 : this.head;
+        for (let i = 0; i < this.size; i++) {
+            const index = (start + i) % this.capacity;
+            result.push(this.buffer[index]);
+        }
+        return result;
+    }
+    /**
+     * Clear all items from the buffer.
+     */
+    clear() {
+        this.buffer.length = 0;
+        this.head = 0;
+        this.size = 0;
+    }
+    /**
+     * Get the current number of items in the buffer.
+     */
+    length() {
+        return this.size;
+    }
+}