@corenel/sidecar 0.1.3 → 0.1.5

package/README.md

@@ -25,7 +25,7 @@ match the site you're connecting from (the app fills it in for you).
 | `--allow-origin <url>` | _(none)_ | Browser origin allowed to connect. Required for a web page. Repeatable. |
 | `--port <n>` | `4858` | Port to listen on. |
 | `--root <dir>` | cwd | Root the file tools are confined to. |
-| `--allow-shell` | off | Enable the `shell_exec` tool (RCE on your machine — opt-in). |
+| `--allow-shell` | off | Enable the `sidecar_shell_exec` tool (RCE on your machine — opt-in). |
 | `--host <addr>` | `127.0.0.1` | Bind address. Non-loopback is reachable off-box; keep the token secret. |
 | `--tls-cert <f>` `--tls-key <f>` | _(none)_ | Serve `wss://` (needed for a remote sidecar from an https page). |
 
@@ -35,6 +35,6 @@ match the site you're connecting from (the app fills it in for you).
   allowed Origin.
 - The HTTP proxy (for local LLMs) only reaches **loopback** hosts — it can't be used as
   an SSRF pivot to internal services.
-- `shell_exec` is off unless you pass `--allow-shell`.
+- `sidecar_shell_exec` is off unless you pass `--allow-shell`.
 
 Licensed under Elastic-2.0.

package/dist/cli.js

@@ -10,6 +10,13 @@ import { spawn as spawn4 } from "node:child_process";
 import { WebSocketServer } from "ws";
 import { createServer as createHttpsServer } from "node:https";
 
+// ../protocol/stateDir.ts
+var DEFAULT_STATE_DIR = ".corenel";
+var dirName = DEFAULT_STATE_DIR;
+function stateDirName() {
+  return dirName;
+}
+
 // ../protocol/sidecar.ts
 var SIDECAR_PROTOCOL = 1;
 function isLoopbackHost(host) {
@@ -39,6 +46,10 @@ var SidecarServer = class {
   authed = false;
   hostSeq = 0;
   hostPending = /* @__PURE__ */ new Map();
+  /** The connected host's dot-dir name, from `hello.stateDir` (informational —
+   * doesn't change any sidecar behavior yet; reserved for future workspace-state
+   * features that need to know the host's dir name). */
+  hostStateDir = ".corenel";
   constructor(opts) {
     this.opts = opts;
     this.ch = opts.channel;
@@ -88,7 +99,8 @@ var SidecarServer = class {
       return;
     }
     this.authed = true;
-    this.opts.log?.(`paired \u2014 ${this.tools.size} ${this.tools.size === 1 ? "tool" : "tools"} advertised`);
+    this.hostStateDir = m.stateDir ?? ".corenel";
+    this.opts.log?.(`paired \u2014 ${this.tools.size} ${this.tools.size === 1 ? "tool" : "tools"} advertised (host dir: ${this.hostStateDir})`);
     const tools = [...this.tools.values()].map(({ run: _run, ...decl }) => decl);
     this.ch.send({ t: "welcome", tools, features: ["http-proxy"], ...this.opts.info ? { info: this.opts.info } : {} });
   }
@@ -349,7 +361,7 @@ var MAX_READ_BYTES = 16 * 1024 * 1024;
 function nodeFsTools(roots) {
   return [
     {
-      name: "fs_read_file",
+      name: "sidecar_fs_read_file",
       description: "Read a UTF-8 text file from the sidecar machine, relative to a pre-approved root.",
       parameters: {
         type: "object",
@@ -368,7 +380,7 @@ function nodeFsTools(roots) {
       }
     },
     {
-      name: "fs_write_file",
+      name: "sidecar_fs_write_file",
       description: "Write a UTF-8 text file on the sidecar machine, relative to a pre-approved root.",
       parameters: {
         type: "object",
@@ -390,7 +402,7 @@ function nodeFsTools(roots) {
       }
     },
     {
-      name: "fs_read_bytes",
+      name: "sidecar_fs_read_bytes",
       description: "Read a file from the sidecar machine as base64 (for previewing media/binary the text read would mangle), relative to a pre-approved root.",
       parameters: {
         type: "object",
@@ -409,7 +421,7 @@ function nodeFsTools(roots) {
       }
     },
     {
-      name: "fs_list_dir",
+      name: "sidecar_fs_list_dir",
       description: "List the entries of a directory on the sidecar machine, relative to a pre-approved root.",
       parameters: {
         type: "object",
@@ -430,7 +442,7 @@ var MAX_TIMEOUT_MS = 3e5;
 var MAX_OUTPUT = 1e5;
 function nodeShellTool(roots) {
   return {
-    name: "shell_exec",
+    name: "sidecar_shell_exec",
     description: "Run a shell command on the sidecar machine (commands a browser cannot spawn). Runs in a pre-approved root by default; returns the exit status plus combined stdout/stderr.",
     parameters: {
       type: "object",
@@ -497,7 +509,7 @@ import { randomBytes } from "node:crypto";
 import { homedir } from "node:os";
 import { join } from "node:path";
 function corenelDir() {
-  return join(homedir(), ".corenel");
+  return join(homedir(), stateDirName());
 }
 function tokenPath() {
   return join(corenelDir(), "daemon.token");
@@ -701,10 +713,20 @@ function extractTunnelUrl(s) {
   const m = s.match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/i);
   return m ? m[0] : null;
 }
+function isRegisteredLine(s) {
+  return /Registered tunnel connection/.test(s);
+}
+function isTunnelGoneLine(s) {
+  return /Unauthorized: Tunnel not found/i.test(s);
+}
+var GONE_LINE_LIMIT = 3;
 var START_TIMEOUT_MS2 = 25e3;
 function tunnelArgs(port, host = "localhost") {
   return ["tunnel", "--no-autoupdate", "--protocol", "http2", "--url", `http://${host}:${port}`];
 }
+function namedTunnelArgs(name, port, host = "localhost") {
+  return ["tunnel", "--no-autoupdate", "--protocol", "http2", "run", "--url", `http://${host}:${port}`, name];
+}
 var tail2 = (s, n = 6) => s.trim().split("\n").slice(-n).join("\n");
 function cloudflaredBins() {
   const env = process.env.CLOUDFLARED_BIN?.trim();
@@ -735,24 +757,34 @@ function stopChild2(child) {
     }
   });
 }
-function startWith2(bin, port, host, log) {
+function startWith2(bin, mode, log, onDown) {
   return new Promise((resolveHandle, reject) => {
-    const child = spawn3(bin, tunnelArgs(port, host), { stdio: ["ignore", "pipe", "pipe"] });
+    const child = spawn3(bin, mode.argv, { stdio: ["ignore", "pipe", "pipe"] });
     let out = "";
     let settled = false;
     let tailBuf = "";
+    let goneLines = 0;
+    let downFired = false;
     const finish = (fn) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
       fn();
     };
+    const fireDown = (reason) => {
+      if (downFired) return;
+      downFired = true;
+      onDown?.(reason);
+    };
     const onData = (b) => {
       const text = b.toString();
       if (!settled) {
         out += text;
-        const url = extractTunnelUrl(out);
-        if (url) finish(() => resolveHandle({ url, stop: () => stopChild2(child) }));
+        const url = mode.ready(out);
+        if (url) finish(() => resolveHandle({ url, stop: () => {
+          downFired = true;
+          return stopChild2(child);
+        } }));
         return;
       }
       tailBuf += text;
@@ -760,7 +792,20 @@ function startWith2(bin, port, host, log) {
       while ((nl = tailBuf.indexOf("\n")) >= 0) {
         const line = tailBuf.slice(0, nl).replace(/\r$/, "").trim();
         tailBuf = tailBuf.slice(nl + 1);
-        if (line) log?.(`cloudflared: ${line}`);
+        if (!line) continue;
+        log?.(`cloudflared: ${line}`);
+        if (isRegisteredLine(line)) {
+          goneLines = 0;
+          continue;
+        }
+        if (isTunnelGoneLine(line)) {
+          goneLines++;
+          if (goneLines >= GONE_LINE_LIMIT && !downFired) {
+            log?.(`cloudflared: tunnel deregistered by the edge (${goneLines}x "Tunnel not found") \u2014 it can never re-register; replacing it`);
+            void stopChild2(child);
+            fireDown("quick tunnel deregistered by the edge");
+          }
+        }
       }
     };
     child.stdout?.on("data", onData);
@@ -769,14 +814,15 @@ function startWith2(bin, port, host, log) {
     child.on("exit", (code) => {
       if (settled) {
         log?.(`cloudflared exited (code ${code}) \u2014 the tunnel is down`);
+        fireDown(`cloudflared exited (code ${code})`);
         return;
       }
-      finish(() => reject(new Error(`${bin} exited (code ${code}) before a tunnel URL appeared.
+      finish(() => reject(new Error(`${bin} exited (code ${code}) before the tunnel came up.
 ${tail2(out)}`)));
     });
     const timer = setTimeout(() => finish(() => {
       void stopChild2(child);
-      reject(new Error(`${bin} produced no tunnel URL within ${START_TIMEOUT_MS2 / 1e3}s.
+      reject(new Error(`${bin} did not come up within ${START_TIMEOUT_MS2 / 1e3}s.
 ${tail2(out)}`));
     }), START_TIMEOUT_MS2);
   });
@@ -784,8 +830,21 @@ ${tail2(out)}`));
 var cloudflaredProvider = {
   id: "cloudflared",
   aliases: ["cloudflare"],
-  description: "Cloudflare quick tunnel (needs the `cloudflared` CLI installed \u2014 https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/ \u2014 no account, no interstitial; URL is ephemeral)",
-  start({ port, host, log }) {
+  description: "Cloudflare tunnel (needs the `cloudflared` CLI installed \u2014 https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/). Default: anonymous quick tunnel (no account, ephemeral URL). With --tunnel-name + --tunnel-hostname: your own NAMED tunnel (stable URL, auto-reconnects).",
+  start({ port, host, name, hostname, log, onDown }) {
+    const origin = host || "localhost";
+    let mode;
+    if (name) {
+      if (!hostname) {
+        return Promise.reject(new Error(
+          `a named cloudflared tunnel needs --tunnel-hostname <public-host> \u2014 the DNS route you created with \`cloudflared tunnel route dns ${name} <public-host>\` (one-time setup: \`cloudflared tunnel login\` then \`cloudflared tunnel create ${name}\`).`
+        ));
+      }
+      const url = `https://${hostname.replace(/^https?:\/\//, "")}`;
+      mode = { argv: namedTunnelArgs(name, port, origin), ready: (s) => isRegisteredLine(s) ? url : null };
+    } else {
+      mode = { argv: tunnelArgs(port, origin), ready: extractTunnelUrl };
+    }
     const bins = cloudflaredBins();
     const tryAt = (i) => {
       if (i >= bins.length) {
@@ -793,7 +852,7 @@ var cloudflaredProvider = {
           `cloudflared not found (tried: ${bins.join(", ")}). Install the cloudflared CLI (https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/), or set CLOUDFLARED_BIN to the binary name/path.`
         ));
       }
-      return startWith2(bins[i], port, host || "localhost", log).catch((e) => {
+      return startWith2(bins[i], mode, log, onDown).catch((e) => {
         if (e?.code === "ENOENT") return tryAt(i + 1);
         throw e;
       });
@@ -806,6 +865,66 @@ var cloudflaredProvider = {
 registerTunnel(cloudflaredProvider);
 registerTunnel(zrokProvider);
 
+// src/tunnel/supervisor.ts
+var DEFAULT_BACKOFF = [2e3, 5e3, 1e4, 3e4];
+async function superviseTunnel(opts) {
+  const backoff = opts.backoffMs ?? DEFAULT_BACKOFF;
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const log = opts.start.log;
+  let stopped = false;
+  let restarting = false;
+  let current = null;
+  let incarnation = 0;
+  const startOnce = () => {
+    const mine = ++incarnation;
+    return opts.provider.start({
+      ...opts.start,
+      onDown: (reason) => {
+        if (mine === incarnation) void restart(reason);
+      }
+    });
+  };
+  async function restart(reason) {
+    if (stopped || restarting) return;
+    restarting = true;
+    current = null;
+    log?.(`tunnel down (${reason}) \u2014 restarting`);
+    try {
+      for (let attempt = 0; !stopped; attempt++) {
+        await sleep(backoff[Math.min(attempt, backoff.length - 1)]);
+        if (stopped) return;
+        try {
+          const h = await startOnce();
+          if (stopped) {
+            void h.stop().catch(() => {
+            });
+            return;
+          }
+          current = h;
+          opts.onUp(h.url, true);
+          return;
+        } catch (e) {
+          log?.(`tunnel restart failed (${e instanceof Error ? e.message : String(e)}) \u2014 retrying`);
+        }
+      }
+    } finally {
+      restarting = false;
+    }
+  }
+  current = await startOnce();
+  opts.onUp(current.url, false);
+  return {
+    stop: async () => {
+      stopped = true;
+      incarnation++;
+      const c = current;
+      current = null;
+      if (c) await c.stop().catch(() => {
+      });
+    }
+  };
+}
+
 // src/cli.ts
 function parseArgs(argv) {
   const out = { port: 4858, host: "127.0.0.1", roots: [], allowOrigins: [], allowShell: false, allowLan: false, selfSigned: false, open: false, appUrl: "https://prompd.app" };
@@ -822,9 +941,10 @@ function parseArgs(argv) {
     else if (a === "--self-signed") out.selfSigned = true;
     else if (a === "--tunnel") out.tunnel = argv[++i];
     else if (a === "--tunnel-name") out.tunnelName = argv[++i];
+    else if (a === "--tunnel-hostname") out.tunnelHostname = argv[++i];
     else if (a === "--open") out.open = true;
     else if (a === "--app-url") out.appUrl = argv[++i];
-    else if (a === "--sidecar" || a === "start") {
+    else if (a === "--sidecar" || a === "start" || a === "--") {
     } else throw new Error(`unknown argument: ${a}
 valid flags: ${KNOWN_FLAGS.join(" ")}`);
   }
@@ -842,6 +962,7 @@ var KNOWN_FLAGS = [
   "--self-signed",
   "--tunnel",
   "--tunnel-name",
+  "--tunnel-hostname",
   "--open",
   "--app-url"
 ];
@@ -908,13 +1029,22 @@ async function main() {
     log: slog,
     allowLan: args.allowLan
   });
-  let tunnel = null;
+  let tunnelSup = null;
   let tunnelWss = null;
   if (tunnelProvider) {
-    process.stdout.write(`starting ${tunnelProvider.id} tunnel${args.tunnelName ? ` (reserved name "${args.tunnelName}")` : ""}\u2026
+    process.stdout.write(`starting ${tunnelProvider.id} tunnel${args.tunnelName ? ` (name "${args.tunnelName}")` : ""}\u2026
 `);
-    tunnel = await tunnelProvider.start({ port: handle.port, host: handle.host, name: args.tunnelName, log: slog });
-    tunnelWss = tunnel.url.replace(/^http/, "ws");
+    tunnelSup = await superviseTunnel({
+      provider: tunnelProvider,
+      start: { port: handle.port, host: handle.host, name: args.tunnelName, hostname: args.tunnelHostname, log: slog },
+      onUp: (url, restarted) => {
+        const wss = url.replace(/^http/, "ws");
+        const changed = tunnelWss !== null && wss !== tunnelWss;
+        tunnelWss = wss;
+        if (!restarted) return;
+        slog(changed ? `tunnel restored at a NEW URL: ${wss} \u2014 re-pair the app with this URL (the token is unchanged)` : "tunnel restored \u2014 same URL, existing pairings reconnect automatically");
+      }
+    });
   }
   const scheme = handle.secure ? "wss" : "ws";
   const exposed = handle.host !== "127.0.0.1" && handle.host !== "localhost";
@@ -924,7 +1054,7 @@ async function main() {
     [
       `corenel sidecar listening on ${scheme}://${handle.host}:${handle.port}`,
       args.roots.length === 1 ? `  root:  ${args.roots[0]}` : `  roots: ${args.roots.join("\n         ")}   (${args.roots.length} approved; pick the active one in the app)`,
-      `  tools: fs_read/write/list${args.allowShell ? " + shell_exec" : "  (shell off; pass --allow-shell to enable)"}`,
+      `  tools: sidecar_fs_read/write/list${args.allowShell ? " + sidecar_shell_exec" : "  (shell off; pass --allow-shell to enable)"}`,
       `  token: ${token}  (also at ${tokenPath()})`,
       tunnelWss ? `  connect at: ${tunnelWss}   (public ${args.tunnel} tunnel${args.tunnelName ? ", stable" : ""} \u2014 pair from any device with this URL + the token)` : `  connect at: ${connectUrls.join("  ")}`,
       `  origins: ${allowedOrigins.join(", ")}${args.allowLan ? "  + any private-LAN origin (--allow-lan)" : args.allowOrigins.length ? "" : "  (canonical defaults; pass --allow-origin to add dev/self-hosted)"}`,
@@ -943,7 +1073,7 @@ async function main() {
   }
   const shutdown = () => {
     const closeServer = () => handle.close().then(() => process.exit(0));
-    if (tunnel) void tunnel.stop().catch(() => {
+    if (tunnelSup) void tunnelSup.stop().catch(() => {
     }).then(closeServer);
     else void closeServer();
   };

package/package.json

@@ -1,41 +1,48 @@
-{
-  "name": "@corenel/sidecar",
-  "version": "0.1.3",
-  "type": "module",
-  "license": "Elastic-2.0",
-  "description": "Prompd sidecar — a local capability server. Run it next to Prompd (prompd.app) so the browser app can reach your machine: local LLMs (Ollama/LM Studio/vLLM) without CORS, your filesystem, and (opt-in) shell.",
-  "keywords": ["prompd", "corenel", "sidecar", "ollama", "local-llm", "cors"],
-  "bin": {
-    "corenel-sidecar": "dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "node build.mjs",
-    "prepublishOnly": "node build.mjs",
-    "start": "tsx src/cli.ts",
-    "typecheck": "tsc --noEmit",
-    "verify": "tsx src/verify.ts"
-  },
-  "dependencies": {
-    "selfsigned": "^2.4.1",
-    "ws": "^8.18.0"
-  },
-  "devDependencies": {
-    "@corenel/protocol": "workspace:*",
-    "@corenel/harness": "workspace:*",
-    "@types/node": "^24.13.1",
-    "@types/ws": "^8.5.13",
-    "esbuild": "^0.21.5",
-    "tsx": "^4.19.2",
-    "typescript": "^5.9.3"
-  }
-}
+{
+  "name": "@corenel/sidecar",
+  "version": "0.1.5",
+  "type": "module",
+  "license": "Elastic-2.0",
+  "description": "Prompd sidecar — a local capability server. Run it next to Prompd (prompd.app) so the browser app can reach your machine: local LLMs (Ollama/LM Studio/vLLM) without CORS, your filesystem, and (opt-in) shell.",
+  "keywords": [
+    "prompd",
+    "corenel",
+    "sidecar",
+    "ollama",
+    "local-llm",
+    "cors"
+  ],
+  "bin": {
+    "corenel-sidecar": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepublishOnly": "node build.mjs",
+    "start": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "verify": "tsx src/verify.ts"
+  },
+  "dependencies": {
+    "selfsigned": "^2.4.1",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@corenel/protocol": "workspace:*",
+    "@corenel/harness": "workspace:*",
+    "@types/node": "^24.13.1",
+    "@types/ws": "^8.5.13",
+    "esbuild": "^0.21.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3"
+  }
+}