deepdebug-local-agent 1.3.0 → 1.5.0

package/src/la-protocol-v2/runtime.js

@@ -0,0 +1,81 @@
+/**
+ * runtime.js - wires the v2 link into the running agent (server.js calls buildV2Link once per tunnel, only
+ * when LOCAL_AGENT_PROTOCOL_V2=true). Nothing of this module (nor Ajv, nor the schemas) is loaded otherwise.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { createV2Link } from "./link.js";
+import { resolveContentHandlersConfig } from "./content-handlers/config.js";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const WORKSPACE_ID = /^[A-Za-z0-9_.-]{0,64}$/;
+
+function agentVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json"), "utf8"));
+        return /^[0-9]{1,4}\.[0-9]{1,4}\.[0-9]{1,4}$/.test(pkg.version) ? pkg.version : "0.0.0";
+    } catch {
+        return "0.0.0";
+    }
+}
+
+async function diskFreeBytes(dir) {
+    try {
+        if (typeof fs.promises.statfs !== "function") return 0;
+        const s = await fs.promises.statfs(dir);
+        const free = Number(s.bavail) * Number(s.bsize);
+        return Number.isSafeInteger(free) && free >= 0 ? free : 0;
+    } catch {
+        return 0;
+    }
+}
+
+/**
+ * @returns {Promise} the link, or null (with a warning) when v2 cannot run here: then the tunnel is the plain v1 client.
+ */
+export async function buildV2Link({ tenantId, agentId, signing, wsManager, getWorkspaceRoot, log = console, env = process.env }) {
+    const tenant = String(tenantId || "").toLowerCase();
+    if (!UUID.test(tenant)) { log.warn("[la-v2] off: the tenant id is not a UUID"); return null; }
+    if (!agentId) { log.warn("[la-v2] off: no agent id (authorizationId in ~/.deepdebug/config.json or LOCAL_AGENT_ID)"); return null; }
+    const identityWs = String(signing.identity?.workspaceId || "");
+    let lastDisk = 0;
+    const refreshDisk = () => diskFreeBytes(getWorkspaceRoot() || process.cwd()).then((v) => { lastDisk = v; });
+    refreshDisk();
+    // F3-07: content.request handlers, behind LOCAL_AGENT_CONTENT_HANDLERS (default off: nothing below changes anything)
+    const contentCfg = resolveContentHandlersConfig(env, (m) => log.warn(m));
+    const contentCaps = contentCfg.enabled ? ["content.diff", "content.file"] : [];
+    const link = createV2Link({
+        log,
+        sessionOptions: {
+            tenantId: tenant,
+            agentId,
+            workspaceId: WORKSPACE_ID.test(identityWs) ? identityWs : "",
+            signing,
+            laVersion: agentVersion(),
+            // only what this build implements: the transport, the handshake and the v1 commands on the same connection
+            capabilities: ["protocol.v2", "v1.commands", "chunk.base64", ...contentCaps],
+            getWorkspaces: () => {
+                const open = (wsManager?.list?.() || []).map((w) => ({
+                    workspaceId: String(w.id || ""),
+                    pathSha256: crypto.createHash("sha256").update(String(w.root || "")).digest("hex"),
+                }));
+                const root = getWorkspaceRoot();
+                if (open.length === 0 && root) open.push({ workspaceId: "default", pathSha256: crypto.createHash("sha256").update(String(root)).digest("hex") });
+                return open;
+            },
+            getHealth: () => { refreshDisk(); return { diskFreeBytes: lastDisk }; },
+            options: {
+                // tuning knobs, clamped: frames in flight (default 8) and how long to wait for `ready` before falling back to v1 (default 10 s)
+                ...(env.LOCAL_AGENT_V2_MAX_IN_FLIGHT ? { maxInFlight: Math.min(32, Math.max(1, Number(env.LOCAL_AGENT_V2_MAX_IN_FLIGHT) || 8)) } : {}),
+                ...(env.LOCAL_AGENT_V2_HANDSHAKE_MS ? { handshakeTimeoutMs: Math.min(30_000, Math.max(100, Number(env.LOCAL_AGENT_V2_HANDSHAKE_MS) || 10_000)) } : {}),
+            },
+        },
+    });
+    if (contentCfg.enabled) {
+        const { installContentHandlers } = await import("./content-handlers/install.js");
+        installContentHandlers({ link, tenantId: tenant, wsManager, getWorkspaceRoot, config: contentCfg, env, log });
+    }
+    return link;
+}