deepdebug-local-agent 1.0.23 → 1.1.0

package/src/siblings/burst-suppressor.js

@@ -0,0 +1,89 @@
+/**
+ * Local burst suppressor (queue-admission burst control).
+ *
+ * NOT deduplication. The gateway performs the authoritative dedup on ITS hash
+ * (error message + first stacktrace line). The adapter 6-key event carries no
+ * stacktrace (message + file only), so that hash is not computable agent-side —
+ * we deliberately do NOT approximate it. Instead this is a short-window burst
+ * limiter that collapses a log storm of the SAME error into one forward, while
+ * letting the error recur ACROSS windows (that recurrence is the signal the
+ * gateway needs to promote a KB entry unverified -> verified).
+ *
+ * The admission key is a SHA-256 signature over adapter | normalize(message) |
+ * file. It is never sent to the gateway, never persisted, and is deliberately
+ * never called "hash" anywhere (that word is reserved for the gateway's dedup
+ * key). Normalization is essential: without it, rotating ids make every storm
+ * line unique and nothing is suppressed.
+ */
+import crypto from 'crypto';
+
+/**
+ * Replace volatile tokens with fixed placeholders BEFORE signing, so repeats of
+ * the same logical error collapse to one signature.
+ */
+export function normalize(message) {
+    let s = String(message == null ? '' : message);
+    // ISO-8601 timestamps (with optional millis + Z/offset)
+    s = s.replace(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?/g, '#TS');
+    // UUIDs
+    s = s.replace(/[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}/g, '#UUID');
+    // 0x addresses
+    s = s.replace(/0x[0-9a-fA-F]+/g, '#ADDR');
+    // Path segments that look like identifiers (contain a digit or a long hex run)
+    s = s.replace(/\/[A-Za-z0-9._-]*(?:\d|[0-9a-fA-F]{8,})[A-Za-z0-9._-]*/g, '/#SEG');
+    // Standalone hex runs >= 8
+    s = s.replace(/\b[0-9a-fA-F]{8,}\b/g, '#HEX');
+    // Digit runs >= 4
+    s = s.replace(/\d{4,}/g, '#NUM');
+    return s;
+}
+
+/** SHA-256 signature over adapter | normalize(message) | file. */
+export function suppressionKey(evt) {
+    const adapter = evt && evt.adapter != null ? String(evt.adapter) : '';
+    const file = evt && evt.file != null ? String(evt.file) : '';
+    const msg = normalize(evt && evt.message);
+    return crypto.createHash('sha256').update(`${adapter}|${msg}|${file}`).digest('hex');
+}
+
+export class BurstSuppressor {
+    constructor(opts = {}) {
+        this.ttlMs = opts.ttlMs || Number(process.env.ADAPTER_SUPPRESS_TTL_MS) || 45000;
+        this.maxKeys = opts.maxKeys || 5000;
+        this.now = opts.now || (() => Date.now());
+        // key -> admission timestamp. Map preserves insertion order (LRU).
+        this.seen = new Map();
+    }
+
+    /**
+     * @returns {boolean} true if the event is within an active window for its
+     * signature and should be SUPPRESSED; false if it passes (and is recorded).
+     * The stored timestamp is the ADMISSION time and is NOT refreshed on
+     * suppressed hits, so the same error recurs (passes) once the TTL elapses.
+     */
+    shouldSuppress(evt) {
+        const key = suppressionKey(evt);
+        const t = this.now();
+        const first = this.seen.get(key);
+        if (first !== undefined && (t - first) < this.ttlMs) {
+            // Keep the admission timestamp; only refresh LRU recency.
+            this.seen.delete(key);
+            this.seen.set(key, first);
+            return true;
+        }
+        // New admission (or window expired): record and pass.
+        this.seen.delete(key);
+        this.seen.set(key, t);
+        this._evict();
+        return false;
+    }
+
+    _evict() {
+        while (this.seen.size > this.maxKeys) {
+            const oldest = this.seen.keys().next().value;
+            this.seen.delete(oldest);
+        }
+    }
+}
+
+export default BurstSuppressor;

package/src/siblings/capabilities.js

@@ -0,0 +1,273 @@
+/**
+ * Boot-time capability preflight (sibling module).
+ *
+ * Reuses the existing (previously dead) EnvironmentDiagnostics (host toolchain
+ * probe) and RuntimeRegistry (registered build runtimes) to emit a capability
+ * manifest and derive EXACTLY ONE operating mode:
+ *
+ *   FULL_LOCAL   source on disk AND host can build AND test locally.
+ *   SPLIT_PLANE  partial: can do some work (clone/detect/partial build) and
+ *                offload the rest (git present, or some toolchain, or egress).
+ *   DETECT_ONLY  can only observe/detect — OR detection was inconclusive.
+ *
+ * Safety rule: never assume FULL_LOCAL. If detection is inconclusive we degrade
+ * to DETECT_ONLY and record why.
+ *
+ * buildManifest/deriveMode are pure and injectable so the mode logic is unit
+ * tested against fixtures without shelling out.
+ */
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import { EnvironmentDiagnostics } from '../utils/environment-diagnostics.js';
+import { getRuntimeRegistry, initializeRuntimes } from '../runtimes/runtime-registry.js';
+import { incidentForwarder } from './incident-forwarder.js';
+import { logger } from './logger.js';
+
+const TOOLCHAIN_LABEL = { python: 'python3' };
+
+/** Derive exactly one mode from an assembled manifest (+ hasGit hint). Pure. */
+export function deriveMode(m) {
+    if (m.conclusive === false) {
+        return {
+            mode: 'DETECT_ONLY',
+            reason: 'capability detection inconclusive; refusing to assume FULL_LOCAL',
+        };
+    }
+    if (m.source_available && m.build_capable && m.test_capable) {
+        return { mode: 'FULL_LOCAL', reason: 'source present and host can build + test locally' };
+    }
+    const canOffload = m.hasGit || m.build_capable || (m.egress && m.egress.gateway);
+    if (canOffload) {
+        const why = [];
+        if (!m.source_available) why.push('no source working tree on disk');
+        if (!m.build_capable) why.push('host not fully build-capable');
+        else if (!m.test_capable) why.push('host not test-capable');
+        return {
+            mode: 'SPLIT_PLANE',
+            reason: `partial local capability (${why.join(', ') || 'offload available'})`,
+        };
+    }
+    return { mode: 'DETECT_ONLY', reason: 'no source, no build toolchain, no git/egress to offload' };
+}
+
+/** Assemble the manifest from raw inputs and stamp the derived mode. Pure. */
+export function buildManifest({
+    diag, sourceAvailable, dockerSock, containerRuntime, egress, runtimeIds, conclusive,
+} = {}) {
+    const tools = (diag && diag.tools) || {};
+    const has = (t) => Boolean(tools[t] && tools[t].installed);
+    const toolchains = Object.keys(tools).filter(has).map((t) => TOOLCHAIN_LABEL[t] || t);
+
+    const buildCapable =
+        (has('java') && (has('maven') || has('gradle'))) ||
+        (has('node') && has('npm')) ||
+        has('go') || has('dotnet') ||
+        (has('python') && has('pip'));
+    // Test capability is narrower: python needs a runner we do not probe, so be
+    // conservative and tie it to the JVM/node/go/dotnet chains.
+    const testCapable =
+        (has('java') && (has('maven') || has('gradle'))) ||
+        (has('node') && has('npm')) ||
+        has('go') || has('dotnet');
+
+    const manifest = {
+        source_available: Boolean(sourceAvailable),
+        toolchains,
+        container_runtime: containerRuntime || null,
+        docker_sock: Boolean(dockerSock),
+        egress: egress || {},
+        build_capable: buildCapable,
+        test_capable: testCapable,
+        runtimes: runtimeIds || [],
+        conclusive: conclusive !== false,
+    };
+    const { mode, reason } = deriveMode({ ...manifest, hasGit: has('git') });
+    manifest.mode = mode;
+    manifest.reason = reason;
+    return manifest;
+}
+
+/** Is there a git working tree on disk at workspaceRoot? */
+function probeSource(workspaceRoot) {
+    try {
+        if (!workspaceRoot) return false;
+        return fs.existsSync(workspaceRoot) && fs.existsSync(path.join(workspaceRoot, '.git'));
+    } catch {
+        return false;
+    }
+}
+
+function probeDockerSock() {
+    try { return fs.existsSync('/var/run/docker.sock'); } catch { return false; }
+}
+
+function probeContainerRuntime() {
+    try {
+        if (fs.existsSync('/.dockerenv')) return 'docker';
+        const cg = fs.readFileSync('/proc/1/cgroup', 'utf-8');
+        if (/docker/.test(cg)) return 'docker';
+        if (/containerd/.test(cg)) return 'containerd';
+        if (/kubepods/.test(cg)) return 'kubernetes';
+        return null;
+    } catch {
+        return null;
+    }
+}
+
+async function reachable(url, timeoutMs = 2500) {
+    if (!url) return false;
+    try {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+        try {
+            await fetch(url, { method: 'HEAD', signal: ctrl.signal });
+            return true; // any HTTP response means egress works
+        } finally {
+            clearTimeout(timer);
+        }
+    } catch {
+        return false;
+    }
+}
+
+async function probeEgress(gatewayUrl) {
+    const [gateway, github] = await Promise.all([
+        reachable(gatewayUrl),
+        reachable('https://github.com'),
+    ]);
+    return { gateway, github };
+}
+
+/**
+ * Run the real preflight (host probes) and produce the manifest. All probe
+ * inputs are injectable via `probes` for tests.
+ */
+export async function computeCapabilityManifest({
+    workspaceRoot, gatewayUrl, diagnostics, runtimeRegistry, probes,
+} = {}) {
+    const diagInst = diagnostics || new EnvironmentDiagnostics();
+    let diag;
+    let conclusive = true;
+    try {
+        diag = await diagInst.diagnose();
+        if (!diag || !diag.tools) conclusive = false;
+    } catch (err) {
+        diag = { tools: {} };
+        conclusive = false;
+        logger.warn({ err: err.message }, '[capabilities] diagnostics failed; degrading to DETECT_ONLY');
+    }
+
+    let runtimeIds = [];
+    try {
+        const reg = runtimeRegistry || getRuntimeRegistry();
+        if (reg.runtimes && reg.runtimes.size === 0) await initializeRuntimes();
+        const reg2 = runtimeRegistry || getRuntimeRegistry();
+        runtimeIds = reg2.runtimes ? [...reg2.runtimes.keys()] : [];
+    } catch (err) {
+        logger.warn({ err: err.message }, '[capabilities] runtime registry init failed');
+    }
+
+    const p = probes || {};
+    const sourceAvailable = p.sourceAvailable != null ? p.sourceAvailable : probeSource(workspaceRoot);
+    const dockerSock = p.dockerSock != null ? p.dockerSock : probeDockerSock();
+    const containerRuntime = p.containerRuntime !== undefined ? p.containerRuntime : probeContainerRuntime();
+    const egress = p.egress != null ? p.egress : await probeEgress(gatewayUrl);
+
+    return buildManifest({ diag, sourceAvailable, dockerSock, containerRuntime, egress, runtimeIds, conclusive });
+}
+
+/** Constant-time bearer check against the configured agent API key. */
+export function isAuthorized(req, authToken) {
+    if (!authToken) return false; // fail closed: no key configured => never expose inventory
+    const h = req && req.headers ? (req.headers.authorization || req.headers.Authorization) : null;
+    if (!h || !/^Bearer\s+/i.test(h)) return false;
+    const presented = h.replace(/^Bearer\s+/i, '').trim();
+    const a = Buffer.from(presented);
+    const b = Buffer.from(String(authToken));
+    return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+/**
+ * UNAUTHENTICATED view: operational health only. Whoever runs the box must be
+ * able to see the agent is broken (mode + the C1 contract signal) WITHOUT holding
+ * credentials. No host/topology inventory.
+ */
+export function publicCapabilities(manifest, forwarderStatus, uptimeS) {
+    const cp = forwarderStatus && forwarderStatus.contract_preflight;
+    return {
+        authenticated: false,
+        mode: manifest.mode,
+        reason: manifest.reason,
+        contract: {
+            ok: forwarderStatus ? forwarderStatus.contract_ok : null,
+            preflight_reason: cp ? cp.reason : null, // coarse: e.g. missing_internal_token / auth_rejected
+        },
+        uptime_s: uptimeS,
+    };
+}
+
+/** AUTHENTICATED view: adds the client-infra topology inventory. */
+export function fullCapabilities(manifest, forwarderStatus, uptimeS) {
+    return {
+        ...publicCapabilities(manifest, forwarderStatus, uptimeS),
+        authenticated: true,
+        source_available: manifest.source_available,
+        toolchains: manifest.toolchains,
+        container_runtime: manifest.container_runtime,
+        docker_sock: manifest.docker_sock,
+        egress: manifest.egress,
+        build_capable: manifest.build_capable,
+        test_capable: manifest.test_capable,
+        runtimes: manifest.runtimes,
+        forwarder: forwarderStatus,
+    };
+}
+
+/**
+ * Compute the manifest, log the derived mode at startup, and expose it on
+ * GET /capabilities (registered on the main app — same 5055 process).
+ */
+export async function startCapabilityPreflight(app, { metrics, workspaceRoot, gatewayUrl, authToken } = {}) {
+    let manifest;
+    try {
+        manifest = await computeCapabilityManifest({ workspaceRoot, gatewayUrl });
+    } catch (err) {
+        // Absolute backstop: never crash, never assume FULL_LOCAL.
+        manifest = buildManifest({ diag: { tools: {} }, conclusive: false, egress: {} });
+        logger.error({ err: err.message }, '[capabilities] preflight crashed; forcing DETECT_ONLY');
+    }
+
+    logger.info(
+        {
+            mode: manifest.mode,
+            reason: manifest.reason,
+            source_available: manifest.source_available,
+            toolchains: manifest.toolchains,
+            build_capable: manifest.build_capable,
+            test_capable: manifest.test_capable,
+            container_runtime: manifest.container_runtime,
+            docker_sock: manifest.docker_sock,
+            egress: manifest.egress,
+        },
+        `[capabilities] derived mode = ${manifest.mode}`,
+    );
+
+    if (app && typeof app.get === 'function') {
+        // Built per-request: live forwarder/contract status (B2) + access control
+        // (B4). Unauthenticated callers see health only; the agent API key unlocks
+        // the client-infra inventory.
+        app.get('/capabilities', (req, res) => {
+            const status = incidentForwarder.getStatus();
+            const uptimeS = Math.round(process.uptime());
+            const view = isAuthorized(req, authToken)
+                ? fullCapabilities(manifest, status, uptimeS)
+                : publicCapabilities(manifest, status, uptimeS);
+            res.json(view);
+        });
+    }
+    if (metrics && typeof metrics.setMode === 'function') {
+        metrics.setMode(manifest.mode);
+    }
+    return manifest;
+}

package/src/siblings/env-compat.cjs

@@ -0,0 +1,58 @@
+/**
+ * env-compat preload (CommonJS).
+ *
+ * Maps legacy manifest env names to the canonical names src/server.js actually
+ * reads, ONLY when the canonical is unset. This must run BEFORE server.js is
+ * evaluated because the canonical names are read at module-eval time
+ * (GATEWAY_URL at server.js:73, WORKSPACE_ROOT at :637). server.js stays frozen.
+ *
+ * Wiring: NODE_OPTIONS="--require .../env-compat.cjs" (set in the Dockerfiles).
+ * Chosen over editing the Docker CMD/entrypoint because:
+ *   - --require runs before the entry module's evaluation (satisfies the
+ *     "before module-eval" requirement) without changing how the app is launched;
+ *   - it is CommonJS, which --require loads directly (ESM needs --import + is
+ *     evaluated later), so the mapping is guaranteed in place first;
+ *   - it composes with `node src/server.js`, `npm start`, and the pkg binaries
+ *     alike — no per-entrypoint edits.
+ *
+ * Backward-compatible: existing deployments that still set the legacy names keep
+ * working (with a deprecation warning); new deployments set the canonical names
+ * and this is a no-op.
+ */
+'use strict';
+
+const LEGACY_MAP = Object.freeze([
+    ['DEEPDEBUG_API_URL', 'GATEWAY_URL'],
+    ['DEEPDEBUG_TENANT_ID', 'TENANT_ID'],
+    ['DEEPDEBUG_WORKSPACE_PATH', 'WORKSPACE_ROOT'],
+]);
+
+const isSet = (v) => v !== undefined && v !== null && v !== '';
+
+/**
+ * Apply the legacy->canonical mapping to `env`. For each pair, map only when the
+ * canonical is unset and the legacy is set; emit exactly one deprecation warning
+ * per mapping actually applied (naming the legacy variable). Pure w.r.t. the
+ * passed-in env + warn function, so it is unit-testable without a subprocess.
+ *
+ * @returns {string[]} the canonical names that were populated from a legacy var.
+ */
+function applyEnvCompat(env, warn) {
+    const mapped = [];
+    for (const [legacy, canonical] of LEGACY_MAP) {
+        if (!isSet(env[canonical]) && isSet(env[legacy])) {
+            env[canonical] = env[legacy];
+            mapped.push(canonical);
+            if (typeof warn === 'function') {
+                warn(`[env-compat] DEPRECATION: ${legacy} is deprecated and will be removed; `
+                    + `use ${canonical}. Mapped ${legacy} -> ${canonical} for this run.\n`);
+            }
+        }
+    }
+    return mapped;
+}
+
+// Auto-apply to the real environment when preloaded (--require) or required.
+applyEnvCompat(process.env, (msg) => process.stderr.write(msg));
+
+module.exports = { applyEnvCompat, LEGACY_MAP };