@buda-ai/connector 0.1.10 → 0.1.11

package/agent-templates/shared/TOOLS.md

@@ -73,7 +73,7 @@ To show a file preview card (thumbnail + download button) inline in the current
 
 1. Call the `send-file` script with the file path (relative to `/agent`):
    ```bash
-   node /system/.agents/skills/buda-machine-info/scripts/send-file.mjs uploads/photo.jpg
+   node "${BUDA_SYSTEM_ROOT:-/system}/.agents/skills/buda-machine-info/scripts/send-file.mjs" uploads/photo.jpg
    ```
 2. The script returns a `[send:uploads/photo.jpg]` marker if the file exists, or an empty string if it does not.
 3. Embed the returned marker directly in your reply — do not explain it to the user.
@@ -82,4 +82,3 @@ To show a file preview card (thumbnail + download button) inline in the current
 - Always call the script first to verify the file exists. Never emit `[send:…]` manually.
 - Path is relative to `/agent` (no leading slash): `uploads/photo.jpg` → `/agent/uploads/photo.jpg`.
 - You may also pass the full `/agent/…` path — the script normalises it automatically.
-

package/agent-templates/system-skills/buda-machine-info/scripts/send-file.mjs

@@ -2,18 +2,20 @@
 /**
  * send-file.mjs
  *
- * Resolves a file path relative to /agent and returns a [send:] marker
+ * Resolves a file path relative to the Agent workspace and returns a [send:] marker
  * if the file exists, or an empty string if it does not.
  *
  * Usage:
  *   node scripts/send-file.mjs <path>
  *
  * Path rules (mirrors the system prompt convention):
- *   - Relative path (no leading slash): resolved against /agent
+ *   - Relative path (no leading slash): resolved against the Agent workspace
  *     e.g. "uploads/photo.jpg" → /agent/uploads/photo.jpg
- *   - Absolute path starting with /agent: used as-is
+ *   - Logical absolute path starting with /agent: resolved against the Agent workspace
  *     e.g. "/agent/chart.png" → /agent/chart.png
- *   - Any other absolute path: used as-is (escape hatch)
+ *   - Connector physical absolute path: accepted only when it is inside BUDA_AGENT_ROOT
+ *   - Connector paths outside the Agent workspace: rejected
+ *   - Without BUDA_AGENT_ROOT, the existing Sandbox /agent behavior is preserved
  *
  * Output:
  *   [send:uploads/photo.jpg]   — file exists (path is relative to /agent)
@@ -21,42 +23,60 @@
  */
 
 import { existsSync } from "node:fs";
-import { isAbsolute, resolve } from "node:path";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 
-const AGENT_ROOT = "/agent";
+const LOGICAL_AGENT_ROOT = "/agent";
 
-function resolveAgentPath(input) {
+function resolveSandboxPath(input) {
+  if (input.startsWith(`${LOGICAL_AGENT_ROOT}/`)) {
+    return { abs: input, rel: input.slice(`${LOGICAL_AGENT_ROOT}/`.length) };
+  }
+  if (isAbsolute(input)) {
+    return { abs: input, rel: input };
+  }
+  return { abs: resolve(LOGICAL_AGENT_ROOT, input), rel: input };
+}
+
+function resolveConnectorPath(input, agentRoot) {
   if (!input) return null;
+  const physicalRoot = resolve(agentRoot);
+  let absolutePath;
 
-  // Strip a leading /agent prefix so the returned marker stays relative
-  if (input.startsWith("/agent/")) {
-    return { abs: input, rel: input.slice("/agent/".length) };
+  if (input === LOGICAL_AGENT_ROOT || input.startsWith(`${LOGICAL_AGENT_ROOT}/`)) {
+    const logicalRelative = input.slice(LOGICAL_AGENT_ROOT.length).replace(/^\/+/, "");
+    absolutePath = resolve(physicalRoot, logicalRelative);
+  } else {
+    absolutePath = isAbsolute(input) ? resolve(input) : resolve(physicalRoot, input);
   }
 
-  // Other absolute paths — use as-is, keep the full path in the marker
-  if (isAbsolute(input)) {
-    return { abs: input, rel: input };
+  const relativePath = relative(physicalRoot, absolutePath);
+  if (
+    !relativePath ||
+    relativePath === ".." ||
+    relativePath.startsWith(`..${sep}`) ||
+    isAbsolute(relativePath)
+  ) {
+    return null;
   }
 
-  // Relative path — resolve against /agent
-  const abs = resolve(AGENT_ROOT, input);
-  return { abs, rel: input };
+  return { abs: absolutePath, rel: relativePath.split(sep).join("/") };
 }
 
-const input = process.argv[2];
-
-if (!input) {
-  // No argument — print nothing (empty result)
-  process.exit(0);
+export function resolveAgentPath(input, agentRoot = process.env.BUDA_AGENT_ROOT) {
+  if (!input) return null;
+  return agentRoot ? resolveConnectorPath(input, agentRoot) : resolveSandboxPath(input);
 }
 
-const resolved = resolveAgentPath(input);
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
 
-if (!resolved || !existsSync(resolved.abs)) {
-  // File does not exist — return empty string
-  process.stdout.write("");
-  process.exit(0);
-}
+if (isMain) {
+  const input = process.argv[2];
+  const resolved = resolveAgentPath(input);
 
-// File exists — emit the [send:] marker
-process.stdout.write(`[send:${resolved.rel}]`);
+  if (!resolved || !existsSync(resolved.abs)) {
+    process.stdout.write("");
+  } else {
+    process.stdout.write(`[send:${resolved.rel}]`);
+  }
+}

package/dist/cli.js

@@ -517,7 +517,7 @@ import path2 from "path";
 // package.json
 var package_default = {
   name: "@buda-ai/connector",
-  version: "0.1.10",
+  version: "0.1.11",
   private: false,
   type: "module",
   publishConfig: {
@@ -584,6 +584,7 @@ var writeMetadata = async (metadataPath, metadata) => {
 };
 var publicStatus = (metadata) => ({
   connectorId: metadata.connectorId,
+  ...typeof metadata.heartbeatHealthy === "boolean" ? { heartbeatHealthy: metadata.heartbeatHealthy } : {},
   idle: metadata.idle,
   instanceId: metadata.instanceId,
   ...metadata.lastHeartbeatAt ? { lastHeartbeatAt: metadata.lastHeartbeatAt } : {},
@@ -640,6 +641,7 @@ async function startDaemonControlServer(options) {
         return;
       }
       metadata.idle = options.isIdle?.() ?? metadata.idle;
+      metadata.heartbeatHealthy = options.isHeartbeatHealthy?.() ?? metadata.heartbeatHealthy;
       metadata.lastHeartbeatAt = options.getLastHeartbeatAt?.() ?? metadata.lastHeartbeatAt;
       metadata.relayConnected = options.isRelayConnected?.() ?? metadata.relayConnected;
       if (request.command === "persist") {
@@ -682,6 +684,7 @@ async function startDaemonControlServer(options) {
     throw new Error("Failed to bind daemon control port");
   metadata = {
     connectorId: options.config.connectorId,
+    ...options.isHeartbeatHealthy ? { heartbeatHealthy: options.isHeartbeatHealthy() } : {},
     idle: options.isIdle?.() ?? true,
     instanceId: randomUUID3(),
     mode: options.mode,
@@ -2678,11 +2681,11 @@ var streamDaemonLogs = (options) => {
 var toDashboardConnector = (config, status) => ({
   agent: status ? status.idle ? "Ready" : "Busy" : "Stopped",
   connectorId: config.connectorId,
-  heartbeat: status?.lastHeartbeatAt ? `OK ${new Date(status.lastHeartbeatAt).toLocaleTimeString("en-GB", { hour12: false })}` : status ? "Waiting" : "Stopped",
+  heartbeat: status?.heartbeatHealthy === false ? "Failed" : status?.lastHeartbeatAt ? `OK ${new Date(status.lastHeartbeatAt).toLocaleTimeString("en-GB", { hour12: false })}` : status ? "Waiting" : "Stopped",
   relay: status?.relayConnected ? "Connected" : "Disconnected",
   serverUrl: config.serverUrl,
   spaceId: config.spaceId ?? "Unknown",
-  status: status ? status.relayConnected ? "Online" : "Running" : "Stopped"
+  status: status ? status.relayConnected && status.heartbeatHealthy !== false ? "Online" : "Running" : "Stopped"
 });
 async function readLocalConnectorDashboardRows(configRoot = getConfigRoot()) {
   const configs = await listDeviceConfigs(configRoot);
@@ -3857,7 +3860,8 @@ var corrupt = (message) => new LegacyWorkspaceMigrationError("MIGRATION_CORRUPT"
 var errorMessage = (error) => error instanceof Error ? error.message : String(error);
 
 // src/relay.ts
-import path11 from "path";
+import { realpathSync } from "fs";
+import path12 from "path";
 import { createNextHandler } from "@bunny-agent/daemon/nextjs";
 import WebSocket2 from "ws";
 
@@ -4024,6 +4028,219 @@ function isNonEmptyString(value) {
   return typeof value === "string" && value.trim().length > 0;
 }
 
+// src/html-preview.ts
+import { readFile as readFile8, realpath as realpath2, stat as stat4 } from "fs/promises";
+import { createServer as createServer2 } from "http";
+import path10 from "path";
+var PREVIEW_HOST = "127.0.0.1";
+var MIN_PREVIEW_PORT = 3100;
+var MAX_PREVIEW_PORT = 3900;
+var MIME_TYPES = {
+  ".avif": "image/avif",
+  ".css": "text/css; charset=utf-8",
+  ".gif": "image/gif",
+  ".htm": "text/html; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".ico": "image/x-icon",
+  ".jpeg": "image/jpeg",
+  ".jpg": "image/jpeg",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".png": "image/png",
+  ".svg": "image/svg+xml",
+  ".txt": "text/plain; charset=utf-8",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2"
+};
+var HtmlPreviewServerRegistry = class {
+  servers = /* @__PURE__ */ new Map();
+  async open(input) {
+    const htmlFile = await resolveWorkspaceFile(input);
+    const folder = path10.dirname(htmlFile);
+    let pending = this.servers.get(folder);
+    if (!pending) {
+      pending = startStaticServer(folder);
+      this.servers.set(folder, pending);
+      void pending.catch(() => {
+        if (this.servers.get(folder) === pending) this.servers.delete(folder);
+      });
+    }
+    const { port } = await pending;
+    const previewUrl = new URL(`http://${PREVIEW_HOST}:${port}`);
+    previewUrl.pathname = `/${path10.basename(htmlFile)}`;
+    return {
+      url: previewUrl.toString(),
+      port,
+      htmlPath: previewUrl.pathname
+    };
+  }
+  async closeAll() {
+    const pending = [...this.servers.values()];
+    this.servers.clear();
+    const entries = await Promise.all(pending.map((entry) => entry.catch(() => void 0)));
+    await Promise.all(
+      entries.map(
+        (entry) => new Promise((resolve) => {
+          if (!entry?.server.listening) return resolve();
+          entry.server.close(() => resolve());
+        })
+      )
+    );
+  }
+};
+var handleHtmlPreviewRequest = async (request, mounts, registry) => {
+  if (request.method !== "POST") {
+    return Response.json({ error: "HTML preview requires POST." }, { status: 405 });
+  }
+  if (!request.body || typeof request.body !== "object" || Array.isArray(request.body)) {
+    return Response.json({ error: "Invalid HTML preview request." }, { status: 400 });
+  }
+  const body = request.body;
+  if (typeof body.filePath !== "string" || body.filePath.length === 0) {
+    return Response.json({ error: "HTML preview requires a file path." }, { status: 400 });
+  }
+  if (body.rootVolume !== "agent" && body.rootVolume !== "space") {
+    return Response.json({ error: "HTML preview requires a valid root volume." }, { status: 400 });
+  }
+  try {
+    return Response.json(
+      await registry.open({ filePath: body.filePath, rootVolume: body.rootVolume, mounts })
+    );
+  } catch (error) {
+    return Response.json(
+      { error: error instanceof Error ? error.message : "Unable to open HTML preview." },
+      { status: 400 }
+    );
+  }
+};
+var resolveWorkspaceFile = async (input) => {
+  const virtualPath = input.filePath.replaceAll("\\", "/");
+  if (virtualPath.includes("\0")) throw new Error("HTML preview path contains invalid data.");
+  const mountPath = path10.resolve(input.mounts[input.rootVolume]);
+  const root = await realpath2(mountPath);
+  let relativePath = virtualPath;
+  let explicitVolume;
+  for (const volume of ["agent", "space"]) {
+    const prefix = `/${volume}`;
+    if (virtualPath === prefix || virtualPath.startsWith(`${prefix}/`)) {
+      explicitVolume = volume;
+      relativePath = virtualPath.slice(prefix.length).replace(/^\/+/, "");
+      break;
+    }
+  }
+  if (explicitVolume && explicitVolume !== input.rootVolume) {
+    throw new Error("HTML preview path does not match the requested root volume.");
+  }
+  if (!explicitVolume && (path10.isAbsolute(virtualPath) || /^[A-Za-z]:\//.test(virtualPath))) {
+    const physicalPath = path10.normalize(virtualPath);
+    const physicalRoot = [mountPath, root].find(
+      (candidateRoot) => isContained(candidateRoot, physicalPath)
+    );
+    if (!physicalRoot) {
+      throw new Error("HTML preview path must stay inside the requested workspace volume.");
+    }
+    relativePath = path10.relative(physicalRoot, physicalPath).split(path10.sep).join("/");
+  }
+  const segments = relativePath.split("/").filter(Boolean);
+  if (segments.length === 0 || segments.some((segment) => segment === "." || segment === "..")) {
+    throw new Error("HTML preview path must not contain traversal segments.");
+  }
+  const candidate = path10.resolve(root, ...segments);
+  assertContained(root, candidate);
+  const canonicalFile = await realpath2(candidate);
+  assertContained(root, canonicalFile);
+  const fileStat = await stat4(canonicalFile);
+  if (!fileStat.isFile()) throw new Error("HTML preview path must identify a file.");
+  if (![".htm", ".html"].includes(path10.extname(canonicalFile).toLowerCase())) {
+    throw new Error("HTML preview path must identify an HTML file.");
+  }
+  return canonicalFile;
+};
+var startStaticServer = async (folder) => {
+  for (let port = MIN_PREVIEW_PORT; port <= MAX_PREVIEW_PORT; port += 1) {
+    const server = createServer2((request, response) => {
+      void serveStaticFile(folder, request.method ?? "GET", request.url ?? "/").then((result) => {
+        response.writeHead(result.status, result.headers);
+        response.end(request.method === "HEAD" ? void 0 : result.body);
+      }).catch(() => {
+        response.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" });
+        response.end("HTML preview failed.");
+      });
+    });
+    const listening = await listen(server, port);
+    if (listening) {
+      server.unref();
+      return { server, port };
+    }
+  }
+  throw new Error(
+    `No free HTML preview port is available (${MIN_PREVIEW_PORT}-${MAX_PREVIEW_PORT}).`
+  );
+};
+var listen = (server, port) => new Promise((resolve, reject) => {
+  const onError = (error) => {
+    server.removeListener("listening", onListening);
+    if (error.code === "EADDRINUSE") resolve(false);
+    else reject(error);
+  };
+  const onListening = () => {
+    server.removeListener("error", onError);
+    resolve(true);
+  };
+  server.once("error", onError);
+  server.once("listening", onListening);
+  server.listen(port, PREVIEW_HOST);
+});
+var serveStaticFile = async (folder, method, requestUrl) => {
+  if (method !== "GET" && method !== "HEAD") {
+    return { status: 405, headers: { Allow: "GET, HEAD" } };
+  }
+  let decodedPath;
+  try {
+    decodedPath = decodeURIComponent(requestUrl.split("?", 1)[0] ?? "/").replaceAll("\\", "/");
+  } catch {
+    return { status: 400, headers: {} };
+  }
+  if (decodedPath.includes("\0")) return { status: 400, headers: {} };
+  const segments = decodedPath.split("/").filter(Boolean);
+  if (segments.some((segment) => segment === "." || segment === "..")) {
+    return { status: 403, headers: {} };
+  }
+  try {
+    const candidate = path10.resolve(folder, ...segments);
+    assertContained(folder, candidate);
+    let canonicalFile = await realpath2(candidate);
+    assertContained(folder, canonicalFile);
+    if ((await stat4(canonicalFile)).isDirectory()) {
+      canonicalFile = await realpath2(path10.join(canonicalFile, "index.html"));
+      assertContained(folder, canonicalFile);
+    }
+    if (!(await stat4(canonicalFile)).isFile()) throw new Error("Not a file");
+    const body = method === "HEAD" ? void 0 : await readFile8(canonicalFile);
+    return {
+      status: 200,
+      headers: {
+        "Cache-Control": "no-store",
+        "Content-Type": MIME_TYPES[path10.extname(canonicalFile).toLowerCase()] ?? "application/octet-stream",
+        "X-Content-Type-Options": "nosniff"
+      },
+      body
+    };
+  } catch {
+    return { status: 404, headers: { "Content-Type": "text/plain; charset=utf-8" } };
+  }
+};
+var assertContained = (root, candidate) => {
+  if (isContained(root, candidate)) return;
+  throw new Error("HTML preview path escapes its allowed root.");
+};
+var isContained = (root, candidate) => {
+  const relative = path10.relative(root, candidate);
+  return relative === "" || !relative.startsWith("..") && !path10.isAbsolute(relative);
+};
+
 // src/workspace-volume-lifecycle.ts
 import { constants as constants3 } from "fs";
 import {
@@ -4031,13 +4248,13 @@ import {
   lstat as lstat2,
   mkdir as mkdir9,
   readdir as readdir5,
-  readFile as readFile8,
-  realpath as realpath2,
+  readFile as readFile9,
+  realpath as realpath3,
   rm as rm3,
   symlink as symlink2,
   writeFile as writeFile4
 } from "fs/promises";
-import path10 from "path";
+import path11 from "path";
 var MOUNT_DIRECTORY = "mount";
 var ARCHIVE_MARKER = "archived.json";
 var AGENT_CONTEXT_TEMPLATE_FILES = [
@@ -4049,8 +4266,8 @@ var AGENT_CONTEXT_TEMPLATE_FILES = [
   "BOOTSTRAP.md",
   "MEMORY.md"
 ];
-var deriveSystemVolume = (descriptor) => path10.join(
-  path10.dirname(path10.dirname(path10.dirname(path10.dirname(descriptor.sharedVolume)))),
+var deriveSystemVolume = (descriptor) => path11.join(
+  path11.dirname(path11.dirname(path11.dirname(path11.dirname(descriptor.sharedVolume)))),
   "system"
 );
 var WorkspaceVolumeLifecycle = class {
@@ -4062,14 +4279,14 @@ var WorkspaceVolumeLifecycle = class {
   async mount() {
     await this.ensureVolumes();
     await this.bootstrapAgentTemplates((await readBundledManifest()).sharedDir);
-    const mountRoot = path10.join(this.descriptor.stateVolume, MOUNT_DIRECTORY);
+    const mountRoot = path11.join(this.descriptor.stateVolume, MOUNT_DIRECTORY);
     await mkdir9(mountRoot, { recursive: true, mode: 448 });
     const mounts = {
       mountRoot,
-      agent: path10.join(mountRoot, "agent"),
-      space: path10.join(mountRoot, "space"),
-      system: path10.join(mountRoot, "system"),
-      temporary: path10.join(mountRoot, "tmp")
+      agent: path11.join(mountRoot, "agent"),
+      space: path11.join(mountRoot, "space"),
+      system: path11.join(mountRoot, "system"),
+      temporary: path11.join(mountRoot, "tmp")
     };
     await Promise.all([
       ensureVolumeLink(this.descriptor.privateVolume, mounts.agent),
@@ -4077,18 +4294,18 @@ var WorkspaceVolumeLifecycle = class {
       ensureVolumeLink(this.systemVolume, mounts.system),
       ensureVolumeLink(this.descriptor.temporaryVolume, mounts.temporary)
     ]);
-    const daemonVolumes = path10.join(mountRoot, "volumes");
+    const daemonVolumes = path11.join(mountRoot, "volumes");
     await mkdir9(daemonVolumes, { recursive: true, mode: 448 });
     await Promise.all([
-      ensureVolumeLink(this.descriptor.privateVolume, path10.join(daemonVolumes, "agent")),
-      ensureVolumeLink(this.descriptor.sharedVolume, path10.join(daemonVolumes, "space")),
-      ensureVolumeLink(this.systemVolume, path10.join(daemonVolumes, "system")),
-      ensureVolumeLink(this.descriptor.temporaryVolume, path10.join(daemonVolumes, "tmp"))
+      ensureVolumeLink(this.descriptor.privateVolume, path11.join(daemonVolumes, "agent")),
+      ensureVolumeLink(this.descriptor.sharedVolume, path11.join(daemonVolumes, "space")),
+      ensureVolumeLink(this.systemVolume, path11.join(daemonVolumes, "system")),
+      ensureVolumeLink(this.descriptor.temporaryVolume, path11.join(daemonVolumes, "tmp"))
     ]);
     return mounts;
   }
   async unmount() {
-    await rm3(path10.join(this.descriptor.stateVolume, MOUNT_DIRECTORY), {
+    await rm3(path11.join(this.descriptor.stateVolume, MOUNT_DIRECTORY), {
       recursive: true,
       force: true
     });
@@ -4097,33 +4314,33 @@ var WorkspaceVolumeLifecycle = class {
     await this.unmount();
     await mkdir9(this.descriptor.stateVolume, { recursive: true, mode: 448 });
     await writeFile4(
-      path10.join(this.descriptor.stateVolume, ARCHIVE_MARKER),
+      path11.join(this.descriptor.stateVolume, ARCHIVE_MARKER),
       `${JSON.stringify({ archivedAt: (/* @__PURE__ */ new Date()).toISOString() })}
 `,
       { encoding: "utf8", mode: 384 }
     );
   }
   async restoreAgent() {
-    await rm3(path10.join(this.descriptor.stateVolume, ARCHIVE_MARKER), { force: true });
+    await rm3(path11.join(this.descriptor.stateVolume, ARCHIVE_MARKER), { force: true });
     return this.mount();
   }
   async deleteAgent(options) {
     requireConfirmation(options);
     await this.unmount();
-    const agentRoot = path10.dirname(this.descriptor.privateVolume);
+    const agentRoot = path11.dirname(this.descriptor.privateVolume);
     await rm3(agentRoot, { recursive: true, force: true });
   }
   async archiveSpace() {
     await mkdir9(this.descriptor.sharedVolume, { recursive: true, mode: 448 });
     await writeFile4(
-      path10.join(this.descriptor.sharedVolume, ARCHIVE_MARKER),
+      path11.join(this.descriptor.sharedVolume, ARCHIVE_MARKER),
       `${JSON.stringify({ archivedAt: (/* @__PURE__ */ new Date()).toISOString() })}
 `,
       { encoding: "utf8", mode: 384 }
     );
   }
   async restoreSpace() {
-    await rm3(path10.join(this.descriptor.sharedVolume, ARCHIVE_MARKER), { force: true });
+    await rm3(path11.join(this.descriptor.sharedVolume, ARCHIVE_MARKER), { force: true });
   }
   async deleteSpace(options) {
     requireConfirmation(options);
@@ -4139,7 +4356,7 @@ var WorkspaceVolumeLifecycle = class {
     );
     for (const filename of AGENT_CONTEXT_TEMPLATE_FILES) {
       if (!entries.has(filename)) continue;
-      const destination = path10.join(this.descriptor.privateVolume, filename);
+      const destination = path11.join(this.descriptor.privateVolume, filename);
       try {
         await lstat2(destination);
         skipped.push(filename);
@@ -4147,7 +4364,7 @@ var WorkspaceVolumeLifecycle = class {
         if (!isMissingFile(error)) throw error;
         try {
           await copyFile2(
-            path10.join(templateDirectory, filename),
+            path11.join(templateDirectory, filename),
             destination,
             constants3.COPYFILE_EXCL
           );
@@ -4170,7 +4387,7 @@ var WorkspaceVolumeLifecycle = class {
     ]) {
       await mkdir9(volume, { recursive: true, mode: 448 });
       const info = await lstat2(volume);
-      if (info.isSymbolicLink() || !info.isDirectory() || await realpath2(volume) !== volume) {
+      if (info.isSymbolicLink() || !info.isDirectory() || await realpath3(volume) !== volume) {
         throw new Error("Workspace volume must be a canonical real directory");
       }
     }
@@ -4183,7 +4400,7 @@ var isMissingFile = (error) => error instanceof Error && "code" in error && erro
 var ensureVolumeLink = async (target, linkPath) => {
   try {
     const info = await lstat2(linkPath);
-    if (!info.isSymbolicLink() || await realpath2(linkPath) !== target) {
+    if (!info.isSymbolicLink() || await realpath3(linkPath) !== target) {
       throw new Error("Workspace mount link does not match its canonical volume");
     }
   } catch (error) {
@@ -4193,7 +4410,7 @@ var ensureVolumeLink = async (target, linkPath) => {
     } catch (createError) {
       if (!isAlreadyExists3(createError)) throw createError;
       const info = await lstat2(linkPath);
-      if (!info.isSymbolicLink() || await realpath2(linkPath) !== target) {
+      if (!info.isSymbolicLink() || await realpath3(linkPath) !== target) {
         throw new Error("Workspace mount link raced with an invalid target");
       }
     }
@@ -4255,6 +4472,7 @@ function startConnectorRelay(config, bunnyDaemon, relayProtocol, workspaceRegist
   let currentInflight = /* @__PURE__ */ new Map();
   let activeTerminalTunnels = 0;
   const replayGuard = new ConnectorExecutionReplayGuard();
+  const htmlPreviews = new HtmlPreviewServerRegistry();
   const clearTimers = () => {
     if (pingTimer) {
       clearInterval(pingTimer);
@@ -4361,13 +4579,15 @@ function startConnectorRelay(config, bunnyDaemon, relayProtocol, workspaceRegist
           onTerminalClose: () => {
             activeTerminalTunnels = Math.max(0, activeTerminalTunnels - 1);
           }
-        }
+        },
+        htmlPreviews
       );
     });
     ws.on("close", (code) => {
       detach();
       if (!shouldReconnectConnectorRelay(code)) {
         clearTimers();
+        void htmlPreviews.closeAll();
         if (code === CONNECTOR_SOCKET_REPLACED_CLOSE_CODE) {
           stopped = true;
           void writeLog("warn", "relay replaced by another process for this connector");
@@ -4427,10 +4647,11 @@ function startConnectorRelay(config, bunnyDaemon, relayProtocol, workspaceRegist
       }
       clearTimers();
       socket?.close();
+      void htmlPreviews.closeAll();
     }
   };
 }
-async function handleRelayMessage(socket, bunnyDaemon, raw, inflight, expectedConnectorId, relayProtocol, replayGuard, workspaceRegistry, serverUrl, localDaemonBaseUrl, activity) {
+async function handleRelayMessage(socket, bunnyDaemon, raw, inflight, expectedConnectorId, relayProtocol, replayGuard, workspaceRegistry, serverUrl, localDaemonBaseUrl, activity, htmlPreviews) {
   if (!socket || socket.readyState !== WebSocket2.OPEN) return;
   let message;
   try {
@@ -4534,6 +4755,7 @@ async function handleRelayMessage(socket, bunnyDaemon, raw, inflight, expectedCo
     const requestPath = message.request.path;
     const isBrowserRequest = requestPath.startsWith("/browser/") || requestPath === "/browser";
     const isWorkspaceDescriptorRequest = requestPath === "/workspace/descriptor";
+    const isHtmlPreviewRequest = new URL(requestPath, "http://connector.workspace").pathname === "/api/preview/html";
     const isAgentRequest = isBrowserRequest || requestPath.startsWith("/api/") || isWorkspaceDescriptorRequest;
     if (isAgentRequest && (!executionIdentity || !workspaceRegistry)) {
       throw new ConnectorRelayProtocolError("IDENTITY_INVALID");
@@ -4566,6 +4788,8 @@ async function handleRelayMessage(socket, bunnyDaemon, raw, inflight, expectedCo
           workdirRoot: mounts?.mountRoot
         }
       );
+    } else if (isHtmlPreviewRequest && mounts && htmlPreviews) {
+      response = await handleHtmlPreviewRequest(message.request, mounts, htmlPreviews);
     } else if (descriptor && mounts) {
       response = await handleWorkspaceDaemonRequest(message.request, mounts, controller.signal);
     } else {
@@ -4606,7 +4830,8 @@ async function handleRelayMessage(socket, bunnyDaemon, raw, inflight, expectedCo
     });
     if (response.body) {
       const reader = response.body.getReader();
-      const decoder = new TextDecoder();
+      const binaryResponse = getHeaderValue(message.request.headers, "x-buda-relay-response-encoding") === "base64";
+      const decoder = binaryResponse ? null : new TextDecoder();
       const cancelReader = () => {
         void reader.cancel().catch(() => {
         });
@@ -4620,10 +4845,11 @@ async function handleRelayMessage(socket, bunnyDaemon, raw, inflight, expectedCo
           sendRelayMessage(socket, {
             type: "chunk",
             requestId: message.requestId,
-            data: decoder.decode(value, { stream: true })
+            data: binaryResponse ? Buffer.from(value).toString("base64") : decoder?.decode(value, { stream: true }) ?? "",
+            ...binaryResponse ? { encoding: "base64" } : {}
           });
         }
-        const tail = decoder.decode();
+        const tail = decoder?.decode() ?? "";
         if (tail) {
           sendRelayMessage(socket, {
             type: "chunk",
@@ -4663,6 +4889,29 @@ async function handleRelayMessage(socket, bunnyDaemon, raw, inflight, expectedCo
 var handleWorkspaceDaemonRequest = async (request, mounts, signal) => {
   const normalized = normalizeWorkspaceRequest(request, mounts);
   const handler = createNextHandler({ root: mounts.mountRoot });
+  if (getHeaderValue(normalized.headers, "x-buda-relay-body-encoding") === "base64") {
+    if (new URL(normalized.path, "http://connector.workspace").pathname !== "/api/fs/write-stream") {
+      throw new Error("Base64 relay bodies are only supported for filesystem write streams.");
+    }
+    if (typeof normalized.body !== "string") {
+      throw new Error("Invalid base64 filesystem write body.");
+    }
+    const content = Buffer.from(normalized.body, "base64");
+    if (content.toString("base64") !== normalized.body) {
+      throw new Error("Invalid base64 filesystem write content.");
+    }
+    const headers = new Headers(normalized.headers);
+    headers.delete("x-buda-relay-body-encoding");
+    headers.set("Content-Type", "application/octet-stream");
+    return handler(
+      new Request(new URL(normalized.path, "http://connector.workspace"), {
+        method: normalized.method,
+        headers,
+        body: content,
+        signal
+      })
+    );
+  }
   return handler(
     new Request(new URL(normalized.path, "http://connector.workspace"), {
       method: normalized.method,
@@ -4673,18 +4922,60 @@ var handleWorkspaceDaemonRequest = async (request, mounts, signal) => {
   );
 };
 var normalizeWorkspaceRequest = (request, mounts) => {
-  if (request.path !== "/api/coding/run") return request;
+  if (request.path !== "/api/coding/run") {
+    return normalizeConnectorFilesystemRequest(request, mounts);
+  }
   if (!request.body || typeof request.body !== "object" || Array.isArray(request.body)) {
     throw new ConnectorRelayProtocolError("WORKSPACE_MISMATCH");
   }
   const body = request.body;
   const cwd = typeof body.cwd === "string" ? body.cwd : "/agent";
-  const normalized = path11.posix.normalize(cwd);
+  const normalized = path12.posix.normalize(cwd);
   const [mount, relative] = normalized === "/agent" || normalized.startsWith("/agent/") ? [mounts.agent, normalized.slice("/agent".length)] : normalized === "/space" || normalized.startsWith("/space/") ? [mounts.space, normalized.slice("/space".length)] : [];
   if (!mount || relative === void 0) {
     throw new ConnectorRelayProtocolError("WORKSPACE_MISMATCH");
   }
-  return { ...request, body: { ...body, cwd: path11.join(mount, relative) } };
+  const env = body.env && typeof body.env === "object" && !Array.isArray(body.env) ? body.env : {};
+  return {
+    ...request,
+    body: {
+      ...body,
+      cwd: path12.join(mount, relative),
+      env: {
+        ...env,
+        BUDA_AGENT_ROOT: mounts.agent,
+        BUDA_SPACE_ROOT: mounts.space,
+        BUDA_SYSTEM_ROOT: mounts.system
+      }
+    }
+  };
+};
+var normalizeConnectorFilesystemRequest = (request, mounts) => {
+  const url = new URL(request.path, "http://connector.workspace");
+  if (!url.pathname.startsWith("/api/fs/")) return request;
+  const filePath = url.searchParams.get("path");
+  if (!filePath) return request;
+  const mount = url.searchParams.get("volume") === "space" ? mounts.space : mounts.agent;
+  const roots = [mount];
+  try {
+    const canonicalRoot = realpathSync(mount);
+    if (canonicalRoot !== mount) roots.push(canonicalRoot);
+  } catch {
+  }
+  const normalizedFilePath = path12.normalize(filePath);
+  for (const root of roots) {
+    const normalizedRoot = path12.normalize(root);
+    const candidates = [normalizedRoot, normalizedRoot.replace(/^[/\\]+/, "")];
+    for (const candidate of candidates) {
+      if (normalizedFilePath !== candidate && !normalizedFilePath.startsWith(`${candidate}${path12.sep}`)) {
+        continue;
+      }
+      const relativePath = path12.relative(candidate, normalizedFilePath).split(path12.sep).join("/");
+      url.searchParams.set("path", relativePath);
+      return { ...request, path: `${url.pathname}${url.search}` };
+    }
+  }
+  return request;
 };
 function sendRelayError(socket, requestId, error) {
   sendRelayMessage(socket, {
@@ -4716,13 +5007,13 @@ function getHeaderValue(headers, name) {
 
 // src/workdir-layout.ts
 import { lstat as lstat3, mkdir as mkdir10, symlink as symlink3, unlink as unlink6 } from "fs/promises";
-import path12 from "path";
+import path13 from "path";
 async function provisionWorkdirLayout(workdirRoot) {
   const manifest = await readBundledManifest();
   await mkdir10(workdirRoot, { recursive: true });
-  await mkdir10(path12.join(workdirRoot, "system", ".agents"), { recursive: true });
-  const systemSkillsLink = path12.join(workdirRoot, "system", ".agents", "skills");
-  const systemScriptsLink = path12.join(workdirRoot, "system", "scripts");
+  await mkdir10(path13.join(workdirRoot, "system", ".agents"), { recursive: true });
+  const systemSkillsLink = path13.join(workdirRoot, "system", ".agents", "skills");
+  const systemScriptsLink = path13.join(workdirRoot, "system", "scripts");
   await ensureSymlink(manifest.systemSkillsDir, systemSkillsLink);
   await ensureSymlink(manifest.scriptsDir, systemScriptsLink);
   await writeLog("info", "workdir layout provisioned", {
@@ -4754,7 +5045,7 @@ async function ensureSymlink(target, linkPath) {
     }
   } catch {
   }
-  await mkdir10(path12.dirname(linkPath), { recursive: true });
+  await mkdir10(path13.dirname(linkPath), { recursive: true });
   await symlink3(target, linkPath, "dir");
 }
 
@@ -4765,13 +5056,13 @@ import {
   lstat as lstat4,
   mkdir as mkdir11,
   open as open3,
-  readFile as readFile9,
-  realpath as realpath3,
+  readFile as readFile10,
+  realpath as realpath4,
   rename as rename6,
   statfs,
   unlink as unlink7
 } from "fs/promises";
-import path13 from "path";
+import path14 from "path";
 var REGISTRY_VERSION = 1;
 var REGISTRY_DIRECTORY = ".buda";
 var REGISTRY_FILENAME = "workspace-registry.json";
@@ -4795,13 +5086,13 @@ var LocalWorkspaceRegistry = class _LocalWorkspaceRegistry {
     await mkdir11(storageRoot, { recursive: true, mode: 448 });
     await rejectUnsafeFilesystem(storageRoot);
     const canonicalRoot = await canonicalDirectory(storageRoot, "storage root");
-    const registryDirectory = path13.join(canonicalRoot, REGISTRY_DIRECTORY);
+    const registryDirectory = path14.join(canonicalRoot, REGISTRY_DIRECTORY);
     await ensurePrivateDirectory2(registryDirectory);
-    const registryPath = path13.join(registryDirectory, REGISTRY_FILENAME);
+    const registryPath = path14.join(registryDirectory, REGISTRY_FILENAME);
     const document = await withExclusiveFileLock(registryPath, async () => {
       let current;
       try {
-        current = parseRegistry(await readFile9(registryPath, "utf8"));
+        current = parseRegistry(await readFile10(registryPath, "utf8"));
       } catch (error) {
         if (isMissingFile2(error)) {
           current = { version: REGISTRY_VERSION, storageRoot: canonicalRoot, workspaces: {} };
@@ -4866,23 +5157,23 @@ var LocalWorkspaceRegistry = class _LocalWorkspaceRegistry {
 };
 var readRegistryDocument = async (registryPath) => {
   try {
-    return parseRegistry(await readFile9(registryPath, "utf8"));
+    return parseRegistry(await readFile10(registryPath, "utf8"));
   } catch (error) {
     if (error instanceof WorkspaceRegistryError) throw error;
     throw corrupt2(`Cannot read local workspace registry: ${errorMessage2(error)}`);
   }
 };
 var deriveWorkspace = (storageRoot, spaceId, agentId) => {
-  const spaceRoot = path13.join(storageRoot, REGISTRY_DIRECTORY, "spaces", spaceId);
-  const agentRoot = path13.join(spaceRoot, "agents", agentId);
+  const spaceRoot = path14.join(storageRoot, REGISTRY_DIRECTORY, "spaces", spaceId);
+  const agentRoot = path14.join(spaceRoot, "agents", agentId);
   return {
     workspaceKey: `${spaceId}:${agentId}`,
     spaceId,
     agentId,
-    privateVolume: path13.join(agentRoot, "workspace"),
-    sharedVolume: path13.join(spaceRoot, "shared"),
-    stateVolume: path13.join(agentRoot, "state"),
-    temporaryVolume: path13.join(agentRoot, "tmp")
+    privateVolume: path14.join(agentRoot, "workspace"),
+    sharedVolume: path14.join(spaceRoot, "shared"),
+    stateVolume: path14.join(agentRoot, "state"),
+    temporaryVolume: path14.join(agentRoot, "tmp")
   };
 };
 var parseRegistry = (raw) => {
@@ -4928,9 +5219,9 @@ var reconcileWorkspace = async (workspace, storageRoot) => {
     workspace.temporaryVolume
   ];
   for (const volume of volumes) {
-    assertContained(storageRoot, volume);
+    assertContained2(storageRoot, volume);
     await ensurePrivateDirectory2(volume);
-    const canonical = await realpath3(volume);
+    const canonical = await realpath4(volume);
     if (canonical !== volume) throw corrupt2("Workspace path resolves through a symbolic link");
   }
 };
@@ -4976,7 +5267,7 @@ var canonicalDirectory = async (directory, label) => {
   if (info.isSymbolicLink() || !info.isDirectory()) {
     throw new WorkspaceRegistryError("STORAGE_UNSAFE", `${label} must be a real directory`);
   }
-  return realpath3(directory);
+  return realpath4(directory);
 };
 var rejectUnsafeFilesystem = async (storageRoot) => {
   const stats = await statfs(storageRoot, { bigint: true });
@@ -5025,12 +5316,12 @@ var validateStoredId = (label, value) => {
     throw corrupt2(errorMessage2(error));
   }
 };
-var assertContained = (root, candidate) => {
+var assertContained2 = (root, candidate) => {
   if (!isPathInside2(root, candidate)) throw corrupt2("Workspace path escapes the storage root");
 };
 var isPathInside2 = (parent, child) => {
-  const relative = path13.relative(parent, child);
-  return relative !== "" && relative !== ".." && !relative.startsWith(`..${path13.sep}`) && !path13.isAbsolute(relative);
+  const relative = path14.relative(parent, child);
+  return relative !== "" && relative !== ".." && !relative.startsWith(`..${path14.sep}`) && !path14.isAbsolute(relative);
 };
 var toDescriptor = (workspace) => ({
   workspaceKey: workspace.workspaceKey,
@@ -5202,7 +5493,7 @@ async function runOnboard(launchConfig, options = {}) {
 
 // src/runtime.ts
 import { mkdir as mkdir12 } from "fs/promises";
-import path14 from "path";
+import path15 from "path";
 var RECOVERED_DAEMON_STOP_TIMEOUT_MS = 1e4;
 var RECOVERED_DAEMON_STOP_POLL_MS = 100;
 var wait3 = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
@@ -5258,7 +5549,7 @@ async function runConnectorDaemon(launchConfig, options = {}) {
     config.connectorId,
     configRoot
   );
-  await mkdir12(path14.dirname(daemonLockTarget), { recursive: true, mode: 448 });
+  await mkdir12(path15.dirname(daemonLockTarget), { recursive: true, mode: 448 });
   let daemonLock = await acquireExclusiveFileLock(daemonLockTarget, { timeoutMs: 0 }).catch(() => {
     throw new Error(
       `Another Buda Connector daemon is already running for this profile on ${config.serverUrl}. Stop it before starting another instance.`
@@ -5268,6 +5559,7 @@ async function runConnectorDaemon(launchConfig, options = {}) {
   let bunnyDaemon;
   let relayProtocol;
   let control;
+  let heartbeatHealthy = true;
   let lastHeartbeatAt;
   try {
     await migrateLegacyWorkspaceRoot(config.workdirRoot);
@@ -5291,7 +5583,7 @@ async function runConnectorDaemon(launchConfig, options = {}) {
         registration.connectorId,
         configRoot
       );
-      await mkdir12(path14.dirname(registeredLockTarget), { recursive: true, mode: 448 });
+      await mkdir12(path15.dirname(registeredLockTarget), { recursive: true, mode: 448 });
       const registeredLock = await acquireExclusiveFileLock(registeredLockTarget, {
         timeoutMs: 0
       }).catch(() => {
@@ -5346,6 +5638,7 @@ async function runConnectorDaemon(launchConfig, options = {}) {
     };
     interval = setInterval(() => {
       heartbeatConnector(config, launchConfig, activeBunnyDaemon).then(({ relayProtocol: nextRelayProtocol }) => {
+        heartbeatHealthy = true;
         lastHeartbeatAt = (/* @__PURE__ */ new Date()).toISOString();
         relay.updateRelayProtocol(nextRelayProtocol);
         relay.resumeAfterAccessRestore();
@@ -5353,6 +5646,7 @@ async function runConnectorDaemon(launchConfig, options = {}) {
           heartbeat: `OK ${(/* @__PURE__ */ new Date()).toLocaleTimeString("en-GB", { hour12: false })}`
         });
       }).catch((error) => {
+        heartbeatHealthy = false;
         if (error instanceof ConnectorDeletedError) {
           void writeLog("warn", "connector deleted remotely; stopping daemon");
           void shutdown({ unregister: false });
@@ -5368,6 +5662,7 @@ async function runConnectorDaemon(launchConfig, options = {}) {
       config,
       configRoot,
       getLastHeartbeatAt: () => lastHeartbeatAt,
+      isHeartbeatHealthy: () => heartbeatHealthy,
       isIdle: () => relay.isIdle(),
       isRelayConnected: () => relay.isConnected(),
       mode: options.mode ?? "persistent",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buda-ai/connector",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "private": false,
   "type": "module",
   "publishConfig": {