hatcher-connect 0.1.0

package/README.md

@@ -0,0 +1,52 @@
+# Hatcher Workspace Connector
+
+Standalone connector that gives one Hatcher agent controlled access to one
+dedicated folder on the user's computer. It does not depend on the retired
+Hatcher CLI.
+
+## Install
+
+```bash
+npm install --global hatcher-connect
+```
+
+This installs the `hatcher-connect` command.
+
+## Connect a folder
+
+```bash
+hatcher-connect login
+hatcher-connect agents
+hatcher-connect connect --agent <agent-id> --folder ./agent-workspace
+```
+
+Use `--read-only` to allow listing, searching, and reading without file
+changes. The connector remains in the foreground; Ctrl+C disconnects the
+folder immediately.
+
+`HATCHER_API_KEY` and `HATCHER_API_URL` can replace saved credentials in
+automated environments. The API key is sent in an Authorization header and is
+never placed in the WebSocket URL.
+
+## File safety
+
+- Every path is relative to the selected canonical folder.
+- Absolute paths, traversal, root `.hatcher` access, and symbolic links are
+  rejected.
+- Files larger than 512 KiB are not read; writes are limited to 45 KiB.
+- Replacing a file requires the SHA-256 revision returned by the last read.
+- Previous contents are stored in `.hatcher/history`.
+- Deletes are moved to `.hatcher/trash` and remain recoverable.
+- The filesystem root and the user's home directory cannot be shared.
+
+Only file content requested by the agent is sent through Hatcher for model
+processing.
+
+## Development
+
+```bash
+npm install
+npm run build --workspace=hatcher-connect
+npm test --workspace=hatcher-connect
+node apps/workspace-connector/dist/index.js --help
+```

package/dist/index.js

@@ -0,0 +1,824 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/index.ts
+var import_commander = require("commander");
+
+// src/api.ts
+var ApiError = class extends Error {
+  constructor(status, message, code) {
+    super(message);
+    this.status = status;
+    this.code = code;
+    this.name = "ApiError";
+  }
+  status;
+  code;
+};
+var ApiClient = class {
+  constructor(config) {
+    this.config = config;
+    this.baseUrl = config.baseUrl.replace(/\/+$/, "");
+  }
+  config;
+  baseUrl;
+  async request(path) {
+    const response = await fetch(`${this.baseUrl}/api/v1${path}`, {
+      headers: {
+        Authorization: `Bearer ${this.config.apiKey}`,
+        Accept: "application/json"
+      }
+    });
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      throw new ApiError(
+        response.status,
+        `Unexpected response from Hatcher (HTTP ${response.status})`
+      );
+    }
+    if (!response.ok || !body.success) {
+      const failure = body;
+      throw new ApiError(response.status, failure.error || `HTTP ${response.status}`, failure.code);
+    }
+    return body.data;
+  }
+  getAccount() {
+    return this.request("/me");
+  }
+  getAgent(id) {
+    return this.request(`/agents/${encodeURIComponent(id)}`);
+  }
+  async listAgents() {
+    const response = await this.request("/agents?limit=100");
+    return response.agents;
+  }
+};
+
+// src/config.ts
+var import_node_fs = require("fs");
+var import_node_os = require("os");
+var import_node_path = require("path");
+var DEFAULT_BASE_URL = "https://api.hatcher.host";
+var CONFIG_DIRECTORY = (0, import_node_path.join)((0, import_node_os.homedir)(), ".hatcher-connect");
+var CONFIG_FILE = (0, import_node_path.join)(CONFIG_DIRECTORY, "config.json");
+function normalizeBaseUrl(value) {
+  const url = new URL(value?.trim() || DEFAULT_BASE_URL);
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new Error("Hatcher API URL must use http or https");
+  }
+  url.pathname = url.pathname.replace(/\/+$/, "");
+  url.search = "";
+  url.hash = "";
+  return url.toString().replace(/\/$/, "");
+}
+function loadStoredConfig() {
+  if (!(0, import_node_fs.existsSync)(CONFIG_FILE)) return null;
+  try {
+    const parsed = JSON.parse((0, import_node_fs.readFileSync)(CONFIG_FILE, "utf8"));
+    if (!parsed.apiKey?.startsWith("hk_")) return null;
+    return { apiKey: parsed.apiKey, baseUrl: normalizeBaseUrl(parsed.baseUrl) };
+  } catch {
+    return null;
+  }
+}
+function loadConfig() {
+  const stored = loadStoredConfig();
+  const environmentKey = process.env.HATCHER_API_KEY?.trim();
+  if (environmentKey) {
+    return {
+      apiKey: environmentKey,
+      baseUrl: normalizeBaseUrl(process.env.HATCHER_API_URL ?? stored?.baseUrl)
+    };
+  }
+  return stored;
+}
+function saveConfig(config) {
+  (0, import_node_fs.mkdirSync)(CONFIG_DIRECTORY, { recursive: true, mode: 448 });
+  (0, import_node_fs.writeFileSync)(
+    CONFIG_FILE,
+    `${JSON.stringify({ ...config, baseUrl: normalizeBaseUrl(config.baseUrl) }, null, 2)}
+`,
+    { mode: 384 }
+  );
+}
+function removeConfig() {
+  if (!(0, import_node_fs.existsSync)(CONFIG_FILE)) return false;
+  (0, import_node_fs.unlinkSync)(CONFIG_FILE);
+  return true;
+}
+function requireConfig() {
+  const config = loadConfig();
+  if (!config) {
+    throw new Error("Not connected to Hatcher. Run `hatcher-connect login` first.");
+  }
+  if (!config.apiKey.startsWith("hk_")) {
+    throw new Error("HATCHER_API_KEY must start with hk_");
+  }
+  return config;
+}
+
+// src/commands/agents.ts
+function pad(value, width) {
+  return value.length >= width ? value.slice(0, width) : value.padEnd(width);
+}
+function registerAgentCommands(program2) {
+  program2.command("agents").description("List agents available to connect").action(async () => {
+    const agents = await new ApiClient(requireConfig()).listAgents();
+    if (agents.length === 0) {
+      console.log("No agents found in this Hatcher account.");
+      return;
+    }
+    console.log(`${pad("NAME", 25)} ${pad("FRAMEWORK", 12)} ${pad("STATUS", 10)} ID`);
+    for (const agent of agents) {
+      console.log(
+        `${pad(agent.name, 25)} ${pad(agent.framework, 12)} ${pad(agent.status, 10)} ${agent.id}`
+      );
+    }
+  });
+}
+
+// src/commands/auth.ts
+var import_promises = require("readline/promises");
+var import_node_process = require("process");
+async function promptHidden(question) {
+  if (!import_node_process.stdin.isTTY || !import_node_process.stdout.isTTY || typeof import_node_process.stdin.setRawMode !== "function") {
+    const readline = (0, import_promises.createInterface)({ input: import_node_process.stdin, output: import_node_process.stdout });
+    try {
+      return (await readline.question(question)).trim();
+    } finally {
+      readline.close();
+    }
+  }
+  import_node_process.stdout.write(question);
+  const previousRawMode = import_node_process.stdin.isRaw;
+  import_node_process.stdin.setRawMode(true);
+  import_node_process.stdin.resume();
+  import_node_process.stdin.setEncoding("utf8");
+  return new Promise((resolve2, reject) => {
+    let value = "";
+    const cleanup = () => {
+      import_node_process.stdin.removeListener("data", onData);
+      import_node_process.stdin.setRawMode(previousRawMode);
+      import_node_process.stdin.pause();
+    };
+    const onData = (chunk) => {
+      for (const character of chunk) {
+        if (character === "") {
+          cleanup();
+          import_node_process.stdout.write("\n");
+          reject(new Error("Login cancelled"));
+          return;
+        }
+        if (character === "\r" || character === "\n") {
+          cleanup();
+          import_node_process.stdout.write("\n");
+          resolve2(value.trim());
+          return;
+        }
+        if (character === "\x7F" || character === "\b") {
+          if (value.length > 0) {
+            value = value.slice(0, -1);
+            import_node_process.stdout.write("\b \b");
+          }
+          continue;
+        }
+        if (character >= " ") {
+          value += character;
+          import_node_process.stdout.write("*");
+        }
+      }
+    };
+    import_node_process.stdin.on("data", onData);
+  });
+}
+function registerAuthCommands(program2) {
+  program2.command("login").description("Authenticate the workspace connector with a Hatcher API key").option("--key <apiKey>", "Hatcher API key (or use HATCHER_API_KEY)").option("--url <baseUrl>", "Hatcher API URL", process.env.HATCHER_API_URL ?? DEFAULT_BASE_URL).action(async (options) => {
+    const apiKey = options.key?.trim() || process.env.HATCHER_API_KEY?.trim() || await promptHidden("Hatcher API key: ");
+    if (!apiKey.startsWith("hk_")) throw new Error("Hatcher API keys must start with hk_");
+    const config = { apiKey, baseUrl: options.url };
+    const account = await new ApiClient(config).getAccount();
+    saveConfig(config);
+    console.log(`Authenticated Hatcher account ${account.id}.`);
+    console.log(`Credentials saved to ${CONFIG_FILE}.`);
+  });
+  program2.command("logout").description("Remove the workspace connector credentials").action(
+    () => console.log(removeConfig() ? "Workspace connector logged out." : "No saved credentials.")
+  );
+  program2.command("whoami").description("Verify the current workspace connector credentials").action(async () => {
+    const config = loadConfig();
+    if (!config) throw new Error("Not connected to Hatcher. Run `hatcher-connect login` first.");
+    const account = await new ApiClient(config).getAccount();
+    console.log(`Account: ${account.id}`);
+    console.log(`API:     ${config.baseUrl}`);
+  });
+}
+
+// src/commands/connect.ts
+var import_node_path3 = require("path");
+var import_promises3 = require("timers/promises");
+var import_ws = __toESM(require("ws"));
+
+// src/local-workspace.ts
+var import_node_crypto = require("crypto");
+var import_promises2 = require("fs/promises");
+var import_node_os2 = require("os");
+var import_node_path2 = require("path");
+var META_DIRECTORY = ".hatcher";
+var MAX_LIST_ENTRIES = 1e3;
+var MAX_SEARCH_FILES = 1e3;
+var MAX_SEARCH_RESULTS = 100;
+var MAX_TEXT_FILE_BYTES = 512 * 1024;
+var MAX_WRITE_BYTES = 45 * 1024;
+var WorkspaceError = class extends Error {
+  constructor(message, code = "VALIDATION_ERROR") {
+    super(message);
+    this.code = code;
+    this.name = "WorkspaceError";
+  }
+  code;
+};
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new WorkspaceError("Tool arguments must be an object");
+  }
+  return value;
+}
+function requiredString(input, name, max = 4096) {
+  const value = input[name];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new WorkspaceError(`${name} must be a non-empty string`);
+  }
+  if (value.length > max) throw new WorkspaceError(`${name} is too long`);
+  return value;
+}
+function requiredContent(input, name, max) {
+  const value = input[name];
+  if (typeof value !== "string") throw new WorkspaceError(`${name} must be a string`);
+  if (value.length > max) throw new WorkspaceError(`${name} is too long`);
+  return value;
+}
+function optionalString(input, name) {
+  const value = input[name];
+  if (value === void 0) return void 0;
+  if (typeof value !== "string") throw new WorkspaceError(`${name} must be a string`);
+  return value;
+}
+function normalizeRelativePath(raw, allowRoot) {
+  const value = (raw ?? ".").trim().replaceAll("\\", "/");
+  if (value.includes("\0")) throw new WorkspaceError("Paths must not contain null bytes");
+  if ((0, import_node_path2.isAbsolute)(value) || import_node_path2.win32.isAbsolute(value)) {
+    throw new WorkspaceError(
+      "Only paths relative to the connected workspace are allowed",
+      "FORBIDDEN"
+    );
+  }
+  const normalized = import_node_path2.posix.normalize(value || ".");
+  if (normalized === ".." || normalized.startsWith("../")) {
+    throw new WorkspaceError("Path traversal outside the workspace is not allowed", "FORBIDDEN");
+  }
+  if (!allowRoot && normalized === ".")
+    throw new WorkspaceError("A file or directory path is required");
+  if (normalized === META_DIRECTORY || normalized.startsWith(`${META_DIRECTORY}/`)) {
+    throw new WorkspaceError("The .hatcher metadata directory is reserved", "FORBIDDEN");
+  }
+  return normalized;
+}
+function isWithinRoot(root, candidate) {
+  const rel = (0, import_node_path2.relative)(root, candidate);
+  return rel === "" || !rel.startsWith(`..${import_node_path2.sep}`) && rel !== ".." && !(0, import_node_path2.isAbsolute)(rel);
+}
+async function pathExists(path) {
+  try {
+    await (0, import_promises2.lstat)(path);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+async function assertNoSymlink(root, relativePath, allowMissingLeaf) {
+  if (relativePath === ".") return;
+  const segments = relativePath.split("/");
+  let current = root;
+  for (let index = 0; index < segments.length; index += 1) {
+    current = (0, import_node_path2.join)(current, segments[index]);
+    try {
+      const info = await (0, import_promises2.lstat)(current);
+      if (info.isSymbolicLink()) {
+        throw new WorkspaceError(
+          "Symbolic links are not accessible through a local workspace",
+          "FORBIDDEN"
+        );
+      }
+    } catch (error) {
+      if (error.code === "ENOENT" && allowMissingLeaf) return;
+      throw error;
+    }
+  }
+}
+async function resolveWorkspacePath(root, raw, options = {}) {
+  const normalized = normalizeRelativePath(raw, options.allowRoot ?? false);
+  const absolute = (0, import_node_path2.resolve)(root, ...normalized.split("/"));
+  if (!isWithinRoot(root, absolute)) {
+    throw new WorkspaceError("Path escapes the connected workspace", "FORBIDDEN");
+  }
+  await assertNoSymlink(root, normalized, options.allowMissing ?? false);
+  if (!options.allowMissing && !await pathExists(absolute)) {
+    throw new WorkspaceError(`Path not found: ${normalized}`, "NOT_FOUND");
+  }
+  return { absolute, relative: normalized };
+}
+function portablePath(root, absolute) {
+  const value = (0, import_node_path2.relative)(root, absolute).split(import_node_path2.sep).join("/");
+  return value || ".";
+}
+function sha256(content) {
+  return (0, import_node_crypto.createHash)("sha256").update(content).digest("hex");
+}
+function timestampDirectory() {
+  return (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
+}
+function isProbablyBinary(content) {
+  return content.subarray(0, Math.min(content.length, 8192)).includes(0);
+}
+async function listWorkspace(root, args) {
+  const requested = optionalString(args, "path");
+  const recursive = args.recursive === true;
+  const target = await resolveWorkspacePath(root, requested, { allowRoot: true });
+  const targetInfo = await (0, import_promises2.stat)(target.absolute);
+  if (!targetInfo.isDirectory()) throw new WorkspaceError(`${target.relative} is not a directory`);
+  const entries = [];
+  const queue = [target.absolute];
+  while (queue.length > 0 && entries.length < MAX_LIST_ENTRIES) {
+    const current = queue.shift();
+    const children = await import("fs/promises").then(
+      ({ readdir }) => readdir(current, { withFileTypes: true })
+    );
+    children.sort((left, right) => left.name.localeCompare(right.name));
+    for (const child of children) {
+      if (current === root && child.name === META_DIRECTORY) continue;
+      const absolute = (0, import_node_path2.join)(current, child.name);
+      const info = await (0, import_promises2.lstat)(absolute);
+      const type = info.isSymbolicLink() ? "symlink" : info.isDirectory() ? "directory" : "file";
+      entries.push({
+        path: portablePath(root, absolute),
+        type,
+        size: info.isFile() ? info.size : 0,
+        modifiedAt: info.mtime.toISOString()
+      });
+      if (entries.length >= MAX_LIST_ENTRIES) break;
+      if (recursive && type === "directory") queue.push(absolute);
+    }
+  }
+  return { path: target.relative, entries, truncated: entries.length >= MAX_LIST_ENTRIES };
+}
+async function readWorkspaceFile(root, args) {
+  const requested = requiredString(args, "path");
+  const target = await resolveWorkspacePath(root, requested);
+  const info = await (0, import_promises2.stat)(target.absolute);
+  if (!info.isFile()) throw new WorkspaceError(`${target.relative} is not a file`);
+  if (info.size > MAX_TEXT_FILE_BYTES) {
+    throw new WorkspaceError(`File is larger than ${MAX_TEXT_FILE_BYTES} bytes`);
+  }
+  const content = await (0, import_promises2.readFile)(target.absolute);
+  if (isProbablyBinary(content)) throw new WorkspaceError("Binary files are not supported");
+  return {
+    path: target.relative,
+    content: content.toString("utf8"),
+    sha256: sha256(content),
+    size: content.length,
+    modifiedAt: info.mtime.toISOString()
+  };
+}
+async function writeWorkspaceFile(root, args) {
+  const requested = requiredString(args, "path");
+  const content = requiredContent(args, "content", MAX_WRITE_BYTES);
+  const expectedSha256 = optionalString(args, "expectedSha256");
+  const target = await resolveWorkspacePath(root, requested, { allowMissing: true });
+  const parent = await resolveWorkspacePath(root, portablePath(root, (0, import_node_path2.dirname)(target.absolute)), {
+    allowRoot: true
+  });
+  const parentInfo = await (0, import_promises2.stat)(parent.absolute).catch(() => null);
+  if (!parentInfo?.isDirectory())
+    throw new WorkspaceError("Parent directory does not exist", "NOT_FOUND");
+  const exists = await pathExists(target.absolute);
+  let previousSha256 = null;
+  if (exists) {
+    const targetInfo = await (0, import_promises2.lstat)(target.absolute);
+    if (!targetInfo.isFile()) throw new WorkspaceError("Only regular files can be replaced");
+    const previous = await (0, import_promises2.readFile)(target.absolute);
+    previousSha256 = sha256(previous);
+    if (!expectedSha256) {
+      throw new WorkspaceError(
+        "expectedSha256 is required when replacing an existing file",
+        "CONFLICT"
+      );
+    }
+    if (expectedSha256 !== previousSha256) {
+      throw new WorkspaceError(
+        "File changed after it was read; read it again before writing",
+        "CONFLICT"
+      );
+    }
+    const historyPath = (0, import_node_path2.join)(
+      root,
+      META_DIRECTORY,
+      "history",
+      timestampDirectory(),
+      ...target.relative.split("/")
+    );
+    await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(historyPath), { recursive: true });
+    await (0, import_promises2.writeFile)(historyPath, previous);
+  } else if (expectedSha256) {
+    throw new WorkspaceError("File no longer exists; omit expectedSha256 to create it", "CONFLICT");
+  }
+  const next = Buffer.from(content, "utf8");
+  if (next.length > MAX_WRITE_BYTES)
+    throw new WorkspaceError(`Content is larger than ${MAX_WRITE_BYTES} bytes`);
+  const temporary = (0, import_node_path2.join)(
+    (0, import_node_path2.dirname)(target.absolute),
+    `.${(0, import_node_path2.basename)(target.absolute)}.hatcher-${(0, import_node_crypto.randomUUID)()}.tmp`
+  );
+  await (0, import_promises2.writeFile)(temporary, next, { flag: "wx" });
+  try {
+    await (0, import_promises2.rename)(temporary, target.absolute);
+  } catch (error) {
+    await import("fs/promises").then(({ rm }) => rm(temporary, { force: true })).catch(() => void 0);
+    throw error;
+  }
+  return {
+    path: target.relative,
+    created: !exists,
+    previousSha256,
+    sha256: sha256(next),
+    size: next.length
+  };
+}
+async function createWorkspaceDirectory(root, args) {
+  const requested = requiredString(args, "path");
+  const target = await resolveWorkspacePath(root, requested, { allowMissing: true });
+  await (0, import_promises2.mkdir)(target.absolute, { recursive: true });
+  await assertNoSymlink(root, target.relative, false);
+  return { path: target.relative, created: true };
+}
+async function moveWorkspacePath(root, args) {
+  const source = await resolveWorkspacePath(root, requiredString(args, "from"));
+  const destination = await resolveWorkspacePath(root, requiredString(args, "to"), {
+    allowMissing: true
+  });
+  if (await pathExists(destination.absolute))
+    throw new WorkspaceError("Destination already exists", "CONFLICT");
+  const destinationParent = await resolveWorkspacePath(
+    root,
+    portablePath(root, (0, import_node_path2.dirname)(destination.absolute)),
+    { allowRoot: true }
+  );
+  if (!(await (0, import_promises2.stat)(destinationParent.absolute)).isDirectory()) {
+    throw new WorkspaceError("Destination parent is not a directory");
+  }
+  await (0, import_promises2.rename)(source.absolute, destination.absolute);
+  return { from: source.relative, to: destination.relative };
+}
+async function deleteWorkspacePath(root, args) {
+  const target = await resolveWorkspacePath(root, requiredString(args, "path"));
+  const trashRelative = (0, import_node_path2.join)("trash", timestampDirectory(), ...target.relative.split("/"));
+  const trashAbsolute = (0, import_node_path2.join)(root, META_DIRECTORY, trashRelative);
+  await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(trashAbsolute), { recursive: true });
+  await (0, import_promises2.rename)(target.absolute, trashAbsolute);
+  return {
+    path: target.relative,
+    recoverable: true,
+    trashPath: `${META_DIRECTORY}/${trashRelative.split(import_node_path2.sep).join("/")}`
+  };
+}
+async function searchWorkspace(root, args) {
+  const query = requiredString(args, "query", 256);
+  const caseSensitive = args.caseSensitive === true;
+  const requested = optionalString(args, "path");
+  const target = await resolveWorkspacePath(root, requested, { allowRoot: true });
+  if (!(await (0, import_promises2.stat)(target.absolute)).isDirectory())
+    throw new WorkspaceError(`${target.relative} is not a directory`);
+  const needle = caseSensitive ? query : query.toLocaleLowerCase();
+  const matches = [];
+  const queue = [target.absolute];
+  let scannedFiles = 0;
+  while (queue.length > 0 && scannedFiles < MAX_SEARCH_FILES && matches.length < MAX_SEARCH_RESULTS) {
+    const current = queue.shift();
+    const children = await import("fs/promises").then(
+      ({ readdir }) => readdir(current, { withFileTypes: true })
+    );
+    for (const child of children) {
+      if (current === root && child.name === META_DIRECTORY) continue;
+      const absolute = (0, import_node_path2.join)(current, child.name);
+      const info = await (0, import_promises2.lstat)(absolute);
+      if (info.isSymbolicLink()) continue;
+      if (info.isDirectory()) {
+        queue.push(absolute);
+        continue;
+      }
+      if (!info.isFile() || info.size > MAX_TEXT_FILE_BYTES) continue;
+      scannedFiles += 1;
+      const content = await (0, import_promises2.readFile)(absolute);
+      if (isProbablyBinary(content)) continue;
+      const lines = content.toString("utf8").split(/\r?\n/);
+      for (let index = 0; index < lines.length; index += 1) {
+        const haystack = caseSensitive ? lines[index] : lines[index].toLocaleLowerCase();
+        if (haystack.includes(needle)) {
+          matches.push({
+            path: portablePath(root, absolute),
+            line: index + 1,
+            text: lines[index].slice(0, 500)
+          });
+          if (matches.length >= MAX_SEARCH_RESULTS) break;
+        }
+      }
+    }
+  }
+  return {
+    query,
+    matches,
+    scannedFiles,
+    truncated: scannedFiles >= MAX_SEARCH_FILES || matches.length >= MAX_SEARCH_RESULTS
+  };
+}
+async function prepareWorkspaceRoot(input) {
+  const absolute = (0, import_node_path2.resolve)(input);
+  await (0, import_promises2.mkdir)(absolute, { recursive: true });
+  const canonical = await (0, import_promises2.realpath)(absolute);
+  const canonicalHome = await (0, import_promises2.realpath)((0, import_node_os2.homedir)()).catch(() => (0, import_node_path2.resolve)((0, import_node_os2.homedir)()));
+  if (canonical === (0, import_node_path2.parse)(canonical).root || canonical === canonicalHome) {
+    throw new WorkspaceError(
+      "Connect a dedicated subfolder, not a filesystem root or your home directory",
+      "FORBIDDEN"
+    );
+  }
+  const info = await (0, import_promises2.stat)(canonical);
+  if (!info.isDirectory()) throw new WorkspaceError("Workspace path must be a directory");
+  await (0, import_promises2.mkdir)((0, import_node_path2.join)(canonical, META_DIRECTORY), { recursive: true });
+  return canonical;
+}
+async function executeWorkspaceTool(root, tool, rawArguments, readOnly) {
+  const args = asRecord(rawArguments);
+  if (readOnly && !["workspace.list", "workspace.search", "workspace.read"].includes(tool)) {
+    throw new WorkspaceError("This local workspace was connected in read-only mode", "FORBIDDEN");
+  }
+  switch (tool) {
+    case "workspace.list":
+      return listWorkspace(root, args);
+    case "workspace.search":
+      return searchWorkspace(root, args);
+    case "workspace.read":
+      return readWorkspaceFile(root, args);
+    case "workspace.write":
+      return writeWorkspaceFile(root, args);
+    case "workspace.mkdir":
+      return createWorkspaceDirectory(root, args);
+    case "workspace.move":
+      return moveWorkspacePath(root, args);
+    case "workspace.delete":
+      return deleteWorkspacePath(root, args);
+  }
+}
+
+// src/commands/connect.ts
+var PROTOCOL_VERSION = 1;
+var VALID_TOOLS = /* @__PURE__ */ new Set([
+  "workspace.list",
+  "workspace.search",
+  "workspace.read",
+  "workspace.write",
+  "workspace.mkdir",
+  "workspace.move",
+  "workspace.delete"
+]);
+var ConnectionError = class extends Error {
+  constructor(message, retryable) {
+    super(message);
+    this.retryable = retryable;
+    this.name = "ConnectionError";
+  }
+  retryable;
+};
+function websocketUrl(baseUrl, agentId) {
+  const url = new URL(
+    `/integrations/local-workspace/agents/${encodeURIComponent(agentId)}/ws`,
+    baseUrl
+  );
+  if (url.protocol === "https:") url.protocol = "wss:";
+  else if (url.protocol === "http:") url.protocol = "ws:";
+  else throw new Error("Hatcher API URL must use http or https");
+  return url.toString();
+}
+function parseRequest(raw) {
+  let payload;
+  try {
+    payload = JSON.parse(raw.toString());
+  } catch {
+    return null;
+  }
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  const frame = payload;
+  if (frame.type !== "request" || typeof frame.id !== "string" || typeof frame.tool !== "string")
+    return null;
+  if (!VALID_TOOLS.has(frame.tool)) return null;
+  return {
+    type: "request",
+    id: frame.id,
+    tool: frame.tool,
+    arguments: frame.arguments ?? {}
+  };
+}
+async function serveConnection(input) {
+  await new Promise((resolve2, reject) => {
+    const socket = new import_ws.default(input.url, {
+      headers: { Authorization: `Bearer ${input.apiKey}` },
+      maxPayload: 1024 * 1024
+    });
+    let authenticated = false;
+    let settled = false;
+    let operationChain = Promise.resolve();
+    const keepAlive = setInterval(() => {
+      if (socket.readyState === import_ws.default.OPEN) socket.ping();
+    }, 25e3);
+    keepAlive.unref?.();
+    socket.on("open", () => {
+      socket.send(
+        JSON.stringify({
+          type: "hello",
+          protocolVersion: PROTOCOL_VERSION,
+          workspaceName: (0, import_node_path3.basename)(input.root),
+          readOnly: input.readOnly
+        })
+      );
+    });
+    socket.on("message", (raw) => {
+      let control = null;
+      try {
+        const parsed = JSON.parse(raw.toString());
+        control = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+      } catch {
+        control = null;
+      }
+      if (control?.type === "ready") {
+        authenticated = true;
+        console.log(`Connected to agent ${input.agentId}. Press Ctrl+C to disconnect.`);
+        return;
+      }
+      if (control?.type === "error" && typeof control.error === "string") {
+        if (!authenticated) reject(new ConnectionError(control.error, false));
+        else console.error(`Hatcher: ${control.error}`);
+        socket.close();
+        return;
+      }
+      const request = parseRequest(raw);
+      if (!request) return;
+      operationChain = operationChain.then(async () => {
+        try {
+          const result = await executeWorkspaceTool(
+            input.root,
+            request.tool,
+            request.arguments,
+            input.readOnly
+          );
+          if (socket.readyState === import_ws.default.OPEN) {
+            socket.send(JSON.stringify({ type: "result", id: request.id, result }));
+          }
+        } catch (error) {
+          const workspaceError = error instanceof WorkspaceError ? error : new WorkspaceError(error instanceof Error ? error.message : String(error));
+          if (socket.readyState === import_ws.default.OPEN) {
+            socket.send(
+              JSON.stringify({
+                type: "error",
+                id: request.id,
+                error: workspaceError.message,
+                code: workspaceError.code
+              })
+            );
+          }
+        }
+      });
+    });
+    socket.on("error", (error) => {
+      if (!authenticated && !settled) {
+        settled = true;
+        clearInterval(keepAlive);
+        reject(new ConnectionError(error.message, true));
+      }
+    });
+    socket.on("close", (code, reason) => {
+      clearInterval(keepAlive);
+      if (settled) return;
+      settled = true;
+      if (!input.stopped() && (code === 1008 || code === 4009)) {
+        reject(new ConnectionError(reason.toString() || `Connection closed (${code})`, false));
+      } else if (!authenticated && !input.stopped()) {
+        reject(new ConnectionError(reason.toString() || `Connection closed (${code})`, true));
+      } else {
+        resolve2();
+      }
+    });
+    const close = () => {
+      if (socket.readyState === import_ws.default.OPEN || socket.readyState === import_ws.default.CONNECTING) {
+        socket.close(1e3, "User disconnected");
+      }
+    };
+    process.once("SIGINT", close);
+    process.once("SIGTERM", close);
+    socket.once("close", () => {
+      process.removeListener("SIGINT", close);
+      process.removeListener("SIGTERM", close);
+    });
+  });
+}
+function registerConnectCommand(program2) {
+  program2.command("connect").description("Connect a dedicated local folder to one Hatcher agent").requiredOption("--agent <id>", "Agent ID that can access the folder").requiredOption("--folder <path>", "Dedicated local folder to connect").option("--read-only", "Allow listing, searching, and reading only").action(async (options) => {
+    const config = requireConfig();
+    const client = new ApiClient(config);
+    const root = await prepareWorkspaceRoot(options.folder);
+    const agent = await client.getAgent(options.agent);
+    const readOnly = options.readOnly === true;
+    console.log(`Local folder: ${root}`);
+    console.log(`Agent:        ${agent.name} (${agent.id})`);
+    console.log(
+      `Access:       ${readOnly ? "read only" : "read, create, edit, move, and recoverable delete"}`
+    );
+    console.log("Only content requested by the agent is sent to Hatcher for processing.");
+    let stopped = false;
+    const reconnectAbort = new AbortController();
+    const stop = () => {
+      stopped = true;
+      reconnectAbort.abort();
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    let attempt = 0;
+    try {
+      while (!stopped) {
+        try {
+          await serveConnection({
+            url: websocketUrl(config.baseUrl, agent.id),
+            apiKey: config.apiKey,
+            agentId: agent.id,
+            root,
+            readOnly,
+            stopped: () => stopped
+          });
+          if (stopped) break;
+        } catch (error) {
+          if (error instanceof ConnectionError && !error.retryable) throw error;
+          if (attempt === 0)
+            console.error(
+              `Connection failed: ${error instanceof Error ? error.message : String(error)}`
+            );
+        }
+        attempt += 1;
+        const waitMs = Math.min(3e4, 1e3 * 2 ** Math.min(attempt, 5));
+        console.log(`Disconnected. Reconnecting in ${Math.round(waitMs / 1e3)}s...`);
+        await (0, import_promises3.setTimeout)(waitMs, void 0, { signal: reconnectAbort.signal, ref: true }).catch(
+          (error) => {
+            if (!stopped) throw error;
+          }
+        );
+      }
+    } finally {
+      process.removeListener("SIGINT", stop);
+      process.removeListener("SIGTERM", stop);
+    }
+    console.log("Local workspace disconnected.");
+  });
+}
+
+// src/index.ts
+var program = new import_commander.Command();
+program.name("hatcher-connect").description("Connect a dedicated local folder to a Hatcher agent").version("0.1.0");
+registerAuthCommands(program);
+registerAgentCommands(program);
+registerConnectCommand(program);
+program.parseAsync(process.argv).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "hatcher-connect",
+  "version": "0.1.0",
+  "description": "Standalone local workspace connector for Hatcher agents",
+  "bin": {
+    "hatcher-connect": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs --clean",
+    "prepack": "npm run build",
+    "test": "vitest run --config vitest.config.ts",
+    "type-check": "tsc --noEmit"
+  },
+  "keywords": [
+    "hatcher",
+    "agent",
+    "workspace",
+    "connector"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.0.0",
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.18.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.11"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HatcherLabs/Hatcher.git",
+    "directory": "apps/workspace-connector"
+  },
+  "homepage": "https://hatcher.host",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}