onion-bridge 0.1.0

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 Onion Bridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Onion Bridge is derived from GPT-Bridge:
+https://github.com/dreamurl/GPT-Bridge
+
+GPT-Bridge is identified by its project as MIT licensed.

package/README.md

@@ -0,0 +1,204 @@
+# 🧅 Onion Bridge
+
+양파쿵야 좋아함 
+
+Onion Bridge is a **CLI that exposes the current terminal directory as an MCP server, allowing ChatGPT to read and modify project files directly.**
+
+```text
+ChatGPT → OpenAI Secure MCP Tunnel ← tunnel-client → Onion Bridge → Current Directory
+```
+
+## Derived from GPT-Bridge
+
+Onion Bridge is derived from [GPT-Bridge](https://github.com/dreamurl/GPT-Bridge).
+
+## Features
+
+| Read | Write |
+|---|---|
+| `get_workspace_info` | `edit_file` |
+| `list_directory` | `write_file` |
+| `search_text` | `create_directory` |
+| `read_file` | `delete_path` |
+
+All file operations are restricted to the directory where Onion Bridge is started.
+
+Writes and deletions are applied directly to disk without a separate approval step.
+
+MCP activity is shown in the terminal in real time and is not persisted to a history file.
+
+## Requirements
+
+- Node.js 20 or later
+- OpenAI `tunnel-client`
+- OpenAI Secure MCP Tunnel ID
+- OpenAI API Key
+
+## Installation
+
+From the repository:
+
+```bash
+npm install
+npm pack
+npm install -g ./onion-bridge-0.1.0.tgz
+```
+
+Then run:
+
+```bash
+onion
+```
+
+If the command is not found, make sure the npm global bin directory is in your PATH.
+
+## Initial Setup
+
+If no configuration exists when you run `onion` for the first time, onboarding starts automatically.
+
+You will be asked for three values:
+
+| Item | Description |
+|---|---|
+| tunnel-client path | Path to the `tunnel-client` executable |
+| OpenAI Tunnel ID | Tunnel ID starting with `tunnel_` |
+| OpenAI API key | API key starting with `sk-` |
+
+After setup, Onion Bridge automatically configures the authentication token and the `onion` tunnel-client profile.
+
+Configuration is stored in `.onion-bridge/config.json` in your home directory and can be reused across projects.
+
+To change the configuration:
+
+```bash
+onion setup
+```
+
+Press Enter to keep an existing value.
+
+### Need help with setup?
+
+Copy the prompt below and paste it into a **new ChatGPT conversation**.
+
+ChatGPT will check the latest official OpenAI documentation and guide you step by step from creating a Secure MCP Tunnel to verifying the Onion Bridge connection.
+
+```text
+Guide me step by step through setting up Onion Bridge with OpenAI Secure MCP Tunnel.
+
+Use the latest official OpenAI documentation and verify the current setup process before giving me instructions.
+
+Please guide me through these steps:
+1. Create an OpenAI Secure MCP Tunnel.
+2. Find the Tunnel ID that starts with tunnel_.
+3. Create an OpenAI API key.
+4. Run Onion Bridge setup and enter the tunnel-client executable path, Tunnel ID, and OpenAI API key.
+5. Start Onion Bridge with the onion command.
+6. Create or configure the MCP/Connector in ChatGPT using the Secure MCP Tunnel.
+7. Verify that ChatGPT can call the Onion Bridge MCP tools.
+
+Important:
+- Explain each step in Korean.
+- Give me only one step at a time.
+- Wait until I confirm that I completed the current step before moving to the next step.
+- Use official OpenAI documentation as the source of truth because the UI and setup process may change.
+- Never ask me to paste API keys, bearer tokens, or other secret values into the ChatGPT conversation.
+- If I encounter an error, troubleshoot that error before continuing to the next step.
+```
+
+## Usage
+
+Go to the project you want to connect:
+
+```bash
+cd C:\workspace\my-project
+onion
+```
+
+Or explicitly:
+
+```bash
+onion start
+```
+
+The current directory becomes the MCP workspace.
+
+```text
+🧅 Onion Bridge
+
+workspace: C:\workspace\my-project
+MCP: http://127.0.0.1:3737/mcp
+tunnel: onion
+```
+
+Press `Ctrl+C` to stop Onion Bridge.
+
+## Activity Log
+
+When ChatGPT calls an MCP tool, the activity is shown in the terminal in real time.
+
+```text
+13:02:11  INFO    .
+13:02:12  LIST    src
+13:02:15  SEARCH  "loadConfig"
+13:02:18  READ    src/server.js
+13:02:22  EDIT    src/server.js
+13:02:25  WRITE   src/test.js
+13:02:30  DELETE  src/old.js
+```
+
+File contents are not printed, and activity logs are not persisted to disk.
+
+## Connecting ChatGPT
+
+Onion Bridge runs the MCP server locally at `127.0.0.1:3737/mcp`.
+
+It also starts `tunnel-client` using the saved `onion` profile and connects it to the OpenAI Secure MCP Tunnel.
+
+After registering an MCP Connector in ChatGPT that uses the same Tunnel, ChatGPT can use the tools from the project where `onion` is currently running.
+
+Once the Connector is configured, normal usage is simply running `onion` inside the project directory.
+
+## Security
+
+> ⚠️ **All Onion Bridge file operations are automatically approved.**
+>
+> File modifications, creations, and deletions requested by ChatGPT are written to disk immediately without an additional confirmation step. An incorrect or unexpected request can therefore modify your project immediately.
+
+For important projects, keep your work in a state that can be restored with Git or another version-control system. Check the terminal activity log and review actual file changes while Onion Bridge is running.
+
+Onion Bridge uses the directory where it was started as its workspace. Run it only inside the project you intend to expose. Do not run it from your home directory or an unnecessarily broad parent directory.
+
+Basic safeguards are still applied:
+
+- The MCP server binds only to `127.0.0.1`.
+- Tunnel requests are authenticated with an automatically generated Bearer Token.
+- File access is restricted to the workspace.
+- Absolute paths and paths that escape the workspace are rejected.
+- `.git` and `node_modules` are excluded from file traversal.
+- Activity is displayed only in the terminal and is not saved to a separate log file.
+
+The OpenAI API Key is stored in `~/.onion-bridge/config.json`. Do not share this file or commit it to Git.
+
+## CLI
+
+```bash
+onion          # Start MCP + Tunnel
+onion start    # Start MCP + Tunnel
+onion setup    # Create or update Tunnel configuration
+onion -v       # Show version
+onion --version
+```
+
+## Differences from GPT-Bridge
+
+GPT-Bridge is centered around a VS Code Extension. Onion Bridge uses only a CLI.
+
+VS Code and the Extension are not required. The directory where `onion` is started becomes the workspace. Editor-specific features such as the settings UI, approval UI, and change history are removed, leaving only the MCP connection and file-operation tools.
+
+## Philosophy
+
+None.
+
+## License
+
+MIT

package/bin/onionBridge.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { startBridge } from "../src/server.js";
+import { runSetup } from "../src/setup.js";
+import { readFile } from "node:fs/promises";
+
+const command = process.argv[2];
+if (["-v", "--version"].includes(command)) {
+	const { version } = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
+	console.log(version);
+	process.exit(0);
+}
+
+if (command && !["start", "setup"].includes(command)) {
+	console.error("Usage: onion [start|setup|-v|--version]");
+	process.exit(1);
+}
+
+const action = command === "setup" ? runSetup() : startBridge();
+
+action.catch((error) => {
+	console.error(
+		`[onionBridge] ${error instanceof Error ? error.message : String(error)}`,
+	);
+	process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "onion-bridge",
+  "version": "0.1.0",
+  "description": "Headless MCP bridge for exposing the current directory to ChatGPT.",
+  "type": "module",
+  "bin": {
+    "onion": "bin/onionBridge.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node ./bin/onionBridge.js",
+    "pack:local": "npm pack"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "express": "^5.2.1",
+    "zod": "^4.4.3"
+  },
+  "license": "MIT"
+}

package/src/config.js

@@ -0,0 +1,62 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { readSetup, runSetup } from "./setup.js";
+
+const DEFAULT_PROFILE = "onion";
+
+export function profilePath(profile = DEFAULT_PROFILE) {
+	const base =
+		process.platform === "win32"
+			? (process.env.APPDATA ?? path.join(os.homedir(), ".config"))
+			: path.join(os.homedir(), ".config");
+	return path.join(base, "tunnel-client", `${profile}.yaml`);
+}
+
+export async function loadConfig() {
+	const setup = (await readSetup()) ?? (await runSetup());
+	const profile =
+		process.env.ONION_BRIDGE_PROFILE || setup.profile || DEFAULT_PROFILE;
+	const port = Number(process.env.ONION_BRIDGE_PORT || setup.port || 3737);
+	const token = process.env.ONION_BRIDGE_TOKEN || setup.token;
+
+	await writeTunnelProfile({ profile, tunnelId: setup.tunnelId, token, port });
+	process.env.OPENAI_API_KEY = setup.apiKey;
+
+	return {
+		profile,
+		port,
+		token,
+		tunnelBin: process.env.ONION_BRIDGE_TUNNEL_BIN || setup.tunnelBin,
+	};
+}
+
+async function writeTunnelProfile({ profile, tunnelId, token, port }) {
+	const file = profilePath(profile);
+	await fs.mkdir(path.dirname(file), { recursive: true });
+	const yaml = `config_version: 1
+
+control_plane:
+  base_url: "https://api.openai.com"
+  tunnel_id: "${tunnelId}"
+  api_key: "env:OPENAI_API_KEY"
+
+health:
+  listen_addr: "127.0.0.1:8080"
+
+admin_ui:
+  open_browser: false
+
+log:
+  level: error
+  format: json
+
+mcp:
+  server_urls:
+    - channel: main
+      url: "http://127.0.0.1:${port}/mcp"
+  extra_headers:
+    Authorization: "Bearer ${token}"
+`;
+	await fs.writeFile(file, yaml, { encoding: "utf8", mode: 0o600 });
+}

package/src/server.js

@@ -0,0 +1,84 @@
+import { spawn } from "node:child_process";
+import express from "express";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { loadConfig } from "./config.js";
+import { registerTools } from "./tools.js";
+import { workspaceRoot } from "./workspace.js";
+
+function createMcp(root) {
+	const server = new McpServer(
+		{ name: "onion-bridge", version: "0.1.0" },
+		{
+			instructions:
+				"Headless workspace MCP server. Changes are written directly to disk without approval.",
+		},
+	);
+	registerTools(server, root);
+	return server;
+}
+
+export async function startBridge() {
+	const config = await loadConfig();
+	const root = workspaceRoot();
+	const app = express();
+	app.disable("x-powered-by");
+	app.use(express.json({ limit: "5mb" }));
+
+	app.get("/health", (_req, res) => res.json({ status: "ok" }));
+	app.post("/mcp", async (req, res) => {
+		if (req.headers.authorization !== `Bearer ${config.token}`) {
+			res.status(401).json({ error: "Unauthorized" });
+			return;
+		}
+
+		const server = createMcp(root);
+		const transport = new StreamableHTTPServerTransport({});
+		res.on("close", () => {
+			void transport.close().catch(() => undefined);
+			void server.close().catch(() => undefined);
+		});
+
+		try {
+			await server.connect(transport);
+			await transport.handleRequest(req, res, req.body);
+		} catch (error) {
+			if (!res.headersSent)
+				res.status(500).json({ error: "MCP request failed" });
+			console.error("[onionBridge]", error);
+		}
+	});
+
+	const http = await new Promise((resolve, reject) => {
+		const server = app.listen(config.port, "127.0.0.1", () => resolve(server));
+		server.once("error", reject);
+	});
+
+	console.log(`[onionBridge] workspace: ${root}`);
+	console.log(`[onionBridge] MCP: http://127.0.0.1:${config.port}/mcp`);
+	console.warn("[onionBridge] WARNING: OAuth is not used. File operations are auto-approved. Use at your own risk.");
+
+	const tunnel = spawn(config.tunnelBin, ["run", "--profile", config.profile], {
+		stdio: "inherit",
+		windowsHide: true,
+		env: process.env,
+	});
+
+	tunnel.once("spawn", () =>
+		console.log(`[onionBridge] tunnel: ${config.profile}`),
+	);
+	tunnel.on("error", (error) =>
+		console.error(`[onionBridge] tunnel failed: ${error.message}`),
+	);
+
+	let stopping = false;
+	const stop = () => {
+		if (stopping) return;
+		stopping = true;
+		tunnel.kill();
+		http.close(() => process.exit(0));
+	};
+
+	process.once("SIGINT", stop);
+	process.once("SIGTERM", stop);
+}

package/src/setup.js

@@ -0,0 +1,59 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+const DIR = path.join(os.homedir(), ".onion-bridge");
+const FILE = path.join(DIR, "config.json");
+
+export async function readSetup() {
+  try {
+    return JSON.parse(await fs.readFile(FILE, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+export async function runSetup() {
+  const current = await readSetup();
+  const rl = readline.createInterface({ input, output });
+
+  console.log("\n🧅 Onion Bridge setup");
+  console.log("Press Enter to keep the current value.\n");
+
+  const tunnelBin = await ask(rl, "tunnel-client path", current?.tunnelBin);
+  const tunnelId = await ask(rl, "OpenAI Tunnel ID", current?.tunnelId);
+  const apiKey = await ask(rl, "OpenAI API key", current?.apiKey, true);
+
+  rl.close();
+
+  if (!tunnelBin || !tunnelId || !apiKey) throw new Error("All setup values are required.");
+  if (!tunnelId.startsWith("tunnel_")) throw new Error("Tunnel ID must start with tunnel_.");
+  if (!apiKey.startsWith("sk-")) throw new Error("OpenAI API key must start with sk-.");
+
+  await fs.access(tunnelBin).catch(() => {
+    throw new Error("tunnel-client executable does not exist.");
+  });
+
+  const config = {
+    tunnelBin,
+    tunnelId,
+    apiKey,
+    token: current?.token || crypto.randomBytes(32).toString("hex"),
+    profile: "onion",
+    port: current?.port || 3737
+  };
+
+  await fs.mkdir(DIR, { recursive: true });
+  await fs.writeFile(FILE, JSON.stringify(config, null, 2), { encoding: "utf8", mode: 0o600 });
+  console.log(`\nSaved: ${FILE}\n`);
+  return config;
+}
+
+async function ask(rl, label, current, secret = false) {
+  const hint = current ? (secret ? " [********]" : ` [${current}]`) : "";
+  const value = (await rl.question(`${label}${hint}: `)).trim();
+  return value || current;
+}

package/src/tools.js

@@ -0,0 +1,229 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { readText, resolveInside, walkFiles } from "./workspace.js";
+
+const text = (value) => ({ content: [{ type: "text", text: value }] });
+
+function activity(action, target = "") {
+	const time = new Date().toLocaleTimeString("en-GB", { hour12: false });
+	console.log(`${time}  ${action.padEnd(7)} ${target}`.trimEnd());
+}
+
+function matchesGlob(file, glob) {
+	const escaped = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+	const pattern = escaped
+		.replaceAll("**", "::DOUBLE::")
+		.replaceAll("*", "[^/]*")
+		.replaceAll("::DOUBLE::", ".*");
+	return new RegExp(`^${pattern}$`).test(file);
+}
+
+export function registerTools(server, root) {
+	server.registerTool(
+		"get_workspace_info",
+		{
+			description: "Return the current Onion Bridge workspace.",
+			annotations: { readOnlyHint: true, openWorldHint: false },
+		},
+		async () => {
+			activity("INFO", ".");
+			return text(`Workspace: ${path.basename(root)}\nRoot: ${root}`);
+		},
+	);
+
+	server.registerTool(
+		"list_directory",
+		{
+			description: "List files below a workspace-relative directory.",
+			inputSchema: {
+				path: z.string().optional(),
+				depth: z.number().int().min(1).max(3).optional(),
+			},
+			annotations: { readOnlyHint: true, openWorldHint: false },
+		},
+		async ({ path: input = ".", depth = 1 }) => {
+			activity("LIST", input);
+			const base = resolveInside(root, input);
+			const files = await walkFiles(root, input);
+			const prefix = base.relative ? `${base.relative}/` : "";
+			const visible = new Set();
+			for (const file of files) {
+				const local =
+					prefix && file.startsWith(prefix) ? file.slice(prefix.length) : file;
+				const parts = local.split("/");
+				visible.add(
+					parts.slice(0, depth).join("/") + (parts.length > depth ? "/" : ""),
+				);
+			}
+			return text([...visible].sort().join("\n") || "(empty)");
+		},
+	);
+
+	server.registerTool(
+		"search_text",
+		{
+			description: "Search literal text across workspace files.",
+			inputSchema: {
+				query: z.string().min(1),
+				include: z.string().optional(),
+				max_results: z.number().int().min(1).max(500).optional(),
+				context_lines: z.number().int().min(0).max(5).optional(),
+			},
+			annotations: { readOnlyHint: true, openWorldHint: false },
+		},
+		async ({ query, include, max_results = 50, context_lines = 0 }) => {
+			activity("SEARCH", JSON.stringify(query));
+			const files = await walkFiles(root);
+			const results = [];
+			for (const file of files) {
+				if (results.length >= max_results) break;
+				if (include && !matchesGlob(file, include)) continue;
+				let content;
+				try {
+					content = (await readText(root, file)).text;
+				} catch {
+					continue;
+				}
+				const lines = content.split(/\r?\n/);
+				for (let i = 0; i < lines.length && results.length < max_results; i++) {
+					if (!lines[i].includes(query)) continue;
+					const from = Math.max(0, i - context_lines);
+					const to = Math.min(lines.length, i + context_lines + 1);
+					results.push(
+						`${file}:${i + 1}\n${lines
+							.slice(from, to)
+							.map((line, n) => `${from + n + 1}│ ${line}`)
+							.join("\n")}`,
+					);
+				}
+			}
+			return text(results.join("\n\n") || "No matches.");
+		},
+	);
+
+	server.registerTool(
+		"read_file",
+		{
+			description: "Read a workspace-relative UTF-8 file.",
+			inputSchema: {
+				path: z.string(),
+				start_line: z.number().int().min(1).optional(),
+				end_line: z.number().int().min(1).optional(),
+			},
+			annotations: { readOnlyHint: true, openWorldHint: false },
+		},
+		async ({ path: input, start_line, end_line }) => {
+			activity("READ", input);
+			const file = await readText(root, input);
+			const lines = file.text.split(/\r?\n/);
+			const start = start_line ?? 1;
+			const end = Math.min(end_line ?? lines.length, lines.length);
+			const body = lines
+				.slice(start - 1, end)
+				.map((line, i) => `${start + i}│ ${line}`)
+				.join("\n");
+			return text(
+				`<file_content path="${file.relative}" lines="${start}-${end}" total_lines="${lines.length}">\n${body}\n</file_content>`,
+			);
+		},
+	);
+
+	server.registerTool(
+		"edit_file",
+		{
+			description:
+				"Replace one exact occurrence in an existing file. Writes directly to disk without approval.",
+			inputSchema: {
+				path: z.string(),
+				old_string: z.string(),
+				new_string: z.string(),
+			},
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: false,
+				openWorldHint: false,
+			},
+		},
+		async ({ path: input, old_string, new_string }) => {
+			activity("EDIT", input);
+			const file = await readText(root, input);
+			const first = file.text.indexOf(old_string);
+			if (first < 0) throw new Error("old_string was not found.");
+			if (file.text.indexOf(old_string, first + old_string.length) >= 0)
+				throw new Error("old_string appears more than once.");
+			await fs.writeFile(
+				file.absolute,
+				file.text.slice(0, first) +
+					new_string +
+					file.text.slice(first + old_string.length),
+				"utf8",
+			);
+			return text(`Updated ${file.relative}.`);
+		},
+	);
+
+	server.registerTool(
+		"write_file",
+		{
+			description:
+				"Create or fully replace a file. Writes directly to disk without approval.",
+			inputSchema: { path: z.string(), content: z.string() },
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: true,
+				openWorldHint: false,
+			},
+		},
+		async ({ path: input, content }) => {
+			activity("WRITE", input);
+			const target = resolveInside(root, input);
+			await fs.mkdir(path.dirname(target.absolute), { recursive: true });
+			await fs.writeFile(target.absolute, content, "utf8");
+			return text(`Wrote ${target.relative}.`);
+		},
+	);
+
+	server.registerTool(
+		"create_directory",
+		{
+			description: "Create a directory recursively without approval.",
+			inputSchema: { path: z.string() },
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: false,
+				openWorldHint: false,
+			},
+		},
+		async ({ path: input }) => {
+			activity("MKDIR", input);
+			const target = resolveInside(root, input);
+			await fs.mkdir(target.absolute, { recursive: true });
+			return text(`Created ${target.relative}/.`);
+		},
+	);
+
+	server.registerTool(
+		"delete_path",
+		{
+			description: "Delete a file or directory directly without approval.",
+			inputSchema: { path: z.string(), recursive: z.boolean().optional() },
+			annotations: {
+				readOnlyHint: false,
+				destructiveHint: true,
+				openWorldHint: false,
+			},
+		},
+		async ({ path: input, recursive = false }) => {
+			activity("DELETE", input);
+			const target = resolveInside(root, input);
+			if (!target.relative)
+				throw new Error("Workspace root cannot be deleted.");
+			const stat = await fs.stat(target.absolute);
+			if (stat.isDirectory() && !recursive)
+				throw new Error("recursive=true is required for directories.");
+			await fs.rm(target.absolute, { recursive, force: false });
+			return text(`Deleted ${target.relative}.`);
+		},
+	);
+}

package/src/workspace.js

@@ -0,0 +1,46 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const EXCLUDED = new Set([".git", "node_modules"]);
+const MAX_READ_BYTES = 1024 * 1024;
+
+export function workspaceRoot() {
+  return path.resolve(process.cwd());
+}
+
+export function resolveInside(root, input = ".") {
+  if (path.isAbsolute(input)) throw new Error("Absolute paths are not allowed.");
+  const target = path.resolve(root, input);
+  const rel = path.relative(root, target);
+  if (rel === ".." || rel.startsWith(`..${path.sep}`)) throw new Error("Path escapes the workspace.");
+  return { absolute: target, relative: rel.split(path.sep).join("/") };
+}
+
+export async function readText(root, input) {
+  const target = resolveInside(root, input);
+  const stat = await fs.stat(target.absolute);
+  if (!stat.isFile()) throw new Error("Path is not a file.");
+  if (stat.size > MAX_READ_BYTES) throw new Error(`File exceeds ${MAX_READ_BYTES} bytes.`);
+  return { ...target, text: await fs.readFile(target.absolute, "utf8") };
+}
+
+export async function walkFiles(root, start = ".", max = 5000) {
+  const base = resolveInside(root, start);
+  const files = [];
+
+  async function walk(dir, relDir) {
+    if (files.length >= max) return;
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (files.length >= max) return;
+      if (EXCLUDED.has(entry.name)) continue;
+      const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) await walk(abs, rel);
+      else if (entry.isFile()) files.push(rel);
+    }
+  }
+
+  await walk(base.absolute, base.relative);
+  return files;
+}