@struktoai/mirage-agents 0.0.3 → 0.0.4

package/README.md

@@ -60,7 +60,7 @@ await ws.execute('cat /s3/events/2026-05-06.parquet | jq .user')
 - **Around 50 built-in backends:** RAM, Disk, Redis, S3 / R2 / OCI / Supabase / GCS, Gmail / GDrive / GDocs / GSheets / GSlides, GitHub / Linear / Notion / Trello, Slack / Discord / Email, MongoDB / Postgres / LanceDB, SSH, and more, mounted side-by-side under a single root.
 - **Portable workspaces:** clone, snapshot, and version a workspace; agent runs move between machines without restarting or reconfiguring the system.
 - **Embeddable:** the Python and TypeScript SDKs run in-process inside FastAPI, Express, browser apps, or any async runtime; no separate process required.
-- **Agent integrations:** OpenAI Agents SDK, Vercel AI SDK, LangChain, Pydantic AI, CAMEL, and OpenHands via the SDKs; coding agents like Claude Code and Codex via the lightweight CLI + daemon.
+- **Agent integrations:** OpenAI Agents SDK, Vercel AI SDK, LangChain, Pydantic AI, CAMEL, and OpenHands via the SDKs; coding agents through native adapters, installable plugins, MCP, or FUSE.
 
 ## Architecture
 
@@ -159,7 +159,7 @@ Mirage plugs into agent frameworks as a sandbox or tool layer. POSIX operations
 | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | Python        | [OpenAI Agents SDK](https://docs.mirage.strukto.ai/python/agents/openai-agents), [LangChain](https://docs.mirage.strukto.ai/python/agents/langchain), [Pydantic AI](https://docs.mirage.strukto.ai/python/agents/pydantic-ai), [CAMEL](https://docs.mirage.strukto.ai/python/agents/camel), [OpenHands](https://docs.mirage.strukto.ai/python/agents/openhands), [Agno](https://docs.mirage.strukto.ai/python/agents/agno) |
 | TypeScript    | [Vercel AI SDK](https://docs.mirage.strukto.ai/typescript/agents/vercel), [OpenAI Agents SDK](https://docs.mirage.strukto.ai/typescript/agents/openai), [LangChain](https://docs.mirage.strukto.ai/typescript/agents/langchain), [Mastra](https://docs.mirage.strukto.ai/typescript/agents/mastra)                                                                                                                         |
-| Coding agents | [Claude Code](https://docs.mirage.strukto.ai/python/agents/claude-code), [Codex](https://docs.mirage.strukto.ai/python/agents/codex), [OpenCode](https://docs.mirage.strukto.ai/typescript/agents/opencode), [Pi](https://docs.mirage.strukto.ai/typescript/agents/pi)                                                                                                                                                     |
+| Coding agents | [Claude Code](https://docs.mirage.strukto.ai/python/agents/claude-code), [Codex](https://docs.mirage.strukto.ai/typescript/agents/codex), [Grok Build](https://docs.mirage.strukto.ai/typescript/agents/grok-build), [OpenCode](https://docs.mirage.strukto.ai/typescript/agents/opencode), [Pi](https://docs.mirage.strukto.ai/typescript/agents/pi)                                                                      |
 
 ## Cache
 

package/dist/chunk-IMI7BLEG.js

@@ -0,0 +1,142 @@
+// src/read-file.ts
+import { detectFileType, FileType as FileType2 } from "@struktoai/mirage-core";
+
+// src/read-file/constants.ts
+import { FileType } from "@struktoai/mirage-core";
+var READ_FILE_MIME = Object.freeze({
+  BINARY: "application/octet-stream",
+  CSV: "text/csv",
+  HTML: "text/html",
+  IMAGE_GIF: "image/gif",
+  IMAGE_JPEG: "image/jpeg",
+  IMAGE_PNG: "image/png",
+  IMAGE_WEBP: "image/webp",
+  JSON: "application/json",
+  MARKDOWN: "text/markdown",
+  PDF: "application/pdf",
+  PLAIN_TEXT: "text/plain",
+  SVG: "image/svg+xml"
+});
+var TEXT_FILE_EXTENSIONS = /* @__PURE__ */ new Set([
+  "txt",
+  "yaml",
+  "yml",
+  "tsv",
+  "xml",
+  "js",
+  "mjs",
+  "cjs",
+  "ts",
+  "tsx",
+  "jsx",
+  "py",
+  "rb",
+  "rs",
+  "go",
+  "java",
+  "c",
+  "cpp",
+  "h",
+  "hpp",
+  "sh",
+  "bash",
+  "zsh",
+  "sql",
+  "log",
+  "env",
+  "ini",
+  "toml",
+  "conf",
+  "cfg"
+]);
+var MIME_FOR_EXTENSION = Object.freeze({
+  json: READ_FILE_MIME.JSON,
+  jsonl: READ_FILE_MIME.JSON,
+  csv: READ_FILE_MIME.CSV,
+  html: READ_FILE_MIME.HTML,
+  htm: READ_FILE_MIME.HTML,
+  md: READ_FILE_MIME.MARKDOWN,
+  svg: READ_FILE_MIME.SVG,
+  png: READ_FILE_MIME.IMAGE_PNG,
+  jpg: READ_FILE_MIME.IMAGE_JPEG,
+  jpeg: READ_FILE_MIME.IMAGE_JPEG,
+  gif: READ_FILE_MIME.IMAGE_GIF,
+  webp: READ_FILE_MIME.IMAGE_WEBP,
+  pdf: READ_FILE_MIME.PDF
+});
+var MIME_FOR_FILE_TYPE = Object.freeze({
+  [FileType.JSON]: READ_FILE_MIME.JSON,
+  [FileType.CSV]: READ_FILE_MIME.CSV,
+  [FileType.TEXT]: READ_FILE_MIME.PLAIN_TEXT,
+  [FileType.IMAGE_PNG]: READ_FILE_MIME.IMAGE_PNG,
+  [FileType.IMAGE_JPEG]: READ_FILE_MIME.IMAGE_JPEG,
+  [FileType.IMAGE_GIF]: READ_FILE_MIME.IMAGE_GIF,
+  [FileType.PDF]: READ_FILE_MIME.PDF
+});
+var MODEL_IMAGE_MIMES = /* @__PURE__ */ new Set([
+  READ_FILE_MIME.IMAGE_JPEG,
+  READ_FILE_MIME.IMAGE_PNG,
+  READ_FILE_MIME.IMAGE_GIF,
+  READ_FILE_MIME.IMAGE_WEBP
+]);
+
+// src/read-file.ts
+function extOf(path) {
+  const dot = path.lastIndexOf(".");
+  const slash = path.lastIndexOf("/");
+  if (dot < 0 || dot < slash) return "";
+  return path.slice(dot + 1).toLowerCase();
+}
+function filenameOf(path) {
+  const slash = path.lastIndexOf("/");
+  const filename = slash < 0 ? path : path.slice(slash + 1);
+  return filename === "" ? "file" : filename;
+}
+function mimeForExtension(path) {
+  const ext = extOf(path);
+  return MIME_FOR_EXTENSION[ext] ?? (TEXT_FILE_EXTENSIONS.has(ext) ? READ_FILE_MIME.PLAIN_TEXT : void 0);
+}
+function mimeForDetectedType(type) {
+  return MIME_FOR_FILE_TYPE[type] ?? READ_FILE_MIME.BINARY;
+}
+function mimeFor(path, bytes, stat) {
+  const extensionMime = mimeForExtension(path);
+  if (extensionMime !== void 0) return extensionMime;
+  if (extOf(path) !== "") return READ_FILE_MIME.BINARY;
+  return mimeForDetectedType(detectFileType(bytes, stat));
+}
+function isTextMime(mimeType) {
+  return mimeType.startsWith("text/") || mimeType === READ_FILE_MIME.JSON || mimeType === READ_FILE_MIME.SVG;
+}
+async function readWorkspaceFile(ws, path, reader) {
+  const stat = await ws.fs.stat(path);
+  if (stat.type === FileType2.DIRECTORY) {
+    throw new Error(`Cannot read directory as a file: ${path}`);
+  }
+  const data = reader === void 0 ? await ws.fs.readFile(path, { raw: true }) : await reader(path);
+  const mimeType = mimeFor(path, data, stat);
+  const base = { path, mimeType, bytes: data.byteLength };
+  if (isTextMime(mimeType)) {
+    return {
+      ...base,
+      kind: "text",
+      content: new TextDecoder("utf-8", { fatal: false }).decode(data)
+    };
+  }
+  if (MODEL_IMAGE_MIMES.has(mimeType)) {
+    return { ...base, kind: "image", data };
+  }
+  if (mimeType === READ_FILE_MIME.PDF) {
+    return { ...base, kind: "file", data, filename: filenameOf(path) };
+  }
+  return {
+    ...base,
+    kind: "binary",
+    note: `Binary file ${path} (${mimeType}, ${String(data.byteLength)} bytes). Use the execute tool with shell commands (head, file, wc, od) to inspect.`
+  };
+}
+
+export {
+  readWorkspaceFile
+};
+//# sourceMappingURL=chunk-IMI7BLEG.js.map

package/dist/chunk-IMI7BLEG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/read-file.ts","../src/read-file/constants.ts"],"sourcesContent":["import { detectFileType, FileType, type FileStat, type Workspace } from '@struktoai/mirage-core'\nimport {\n  MIME_FOR_EXTENSION,\n  MIME_FOR_FILE_TYPE,\n  MODEL_IMAGE_MIMES,\n  READ_FILE_MIME,\n  TEXT_FILE_EXTENSIONS,\n  type ReadFileMime,\n} from './read-file/constants.ts'\n\ninterface WorkspaceFileBase {\n  path: string\n  mimeType: ReadFileMime\n  bytes: number\n}\n\nexport type WorkspaceFileReadResult =\n  | (WorkspaceFileBase & { kind: 'text'; content: string })\n  | (WorkspaceFileBase & { kind: 'image'; data: Uint8Array })\n  | (WorkspaceFileBase & { kind: 'file'; data: Uint8Array; filename: string })\n  | (WorkspaceFileBase & { kind: 'binary'; note: string })\n\nexport type WorkspaceFileReader = (path: string) => Promise<Uint8Array>\n\nfunction extOf(path: string): string {\n  const dot = path.lastIndexOf('.')\n  const slash = path.lastIndexOf('/')\n  if (dot < 0 || dot < slash) return ''\n  return path.slice(dot + 1).toLowerCase()\n}\n\nfunction filenameOf(path: string): string {\n  const slash = path.lastIndexOf('/')\n  const filename = slash < 0 ? path : path.slice(slash + 1)\n  return filename === '' ? 'file' : filename\n}\n\nfunction mimeForExtension(path: string): ReadFileMime | undefined {\n  const ext = extOf(path)\n  return (\n    MIME_FOR_EXTENSION[ext] ??\n    (TEXT_FILE_EXTENSIONS.has(ext) ? READ_FILE_MIME.PLAIN_TEXT : undefined)\n  )\n}\n\nfunction mimeForDetectedType(type: FileType): ReadFileMime {\n  return MIME_FOR_FILE_TYPE[type] ?? READ_FILE_MIME.BINARY\n}\n\nfunction mimeFor(path: string, bytes: Uint8Array, stat: FileStat): ReadFileMime {\n  const extensionMime = mimeForExtension(path)\n  if (extensionMime !== undefined) return extensionMime\n  if (extOf(path) !== '') return READ_FILE_MIME.BINARY\n  return mimeForDetectedType(detectFileType(bytes, stat))\n}\n\nfunction isTextMime(mimeType: ReadFileMime): boolean {\n  return (\n    mimeType.startsWith('text/') ||\n    mimeType === READ_FILE_MIME.JSON ||\n    mimeType === READ_FILE_MIME.SVG\n  )\n}\n\nexport async function readWorkspaceFile(\n  ws: Workspace,\n  path: string,\n  reader?: WorkspaceFileReader,\n): Promise<WorkspaceFileReadResult> {\n  const stat = await ws.fs.stat(path)\n  if (stat.type === FileType.DIRECTORY) {\n    throw new Error(`Cannot read directory as a file: ${path}`)\n  }\n  const data = reader === undefined ? await ws.fs.readFile(path, { raw: true }) : await reader(path)\n  const mimeType = mimeFor(path, data, stat)\n  const base = { path, mimeType, bytes: data.byteLength }\n\n  if (isTextMime(mimeType)) {\n    return {\n      ...base,\n      kind: 'text',\n      content: new TextDecoder('utf-8', { fatal: false }).decode(data),\n    }\n  }\n  if (MODEL_IMAGE_MIMES.has(mimeType)) {\n    return { ...base, kind: 'image', data }\n  }\n  if (mimeType === READ_FILE_MIME.PDF) {\n    return { ...base, kind: 'file', data, filename: filenameOf(path) }\n  }\n  return {\n    ...base,\n    kind: 'binary',\n    note:\n      `Binary file ${path} (${mimeType}, ${String(data.byteLength)} bytes). ` +\n      'Use the execute tool with shell commands (head, file, wc, od) to inspect.',\n  }\n}\n","import { FileType, type FileType as MirageFileType } from '@struktoai/mirage-core'\n\nexport const READ_FILE_MIME = Object.freeze({\n  BINARY: 'application/octet-stream',\n  CSV: 'text/csv',\n  HTML: 'text/html',\n  IMAGE_GIF: 'image/gif',\n  IMAGE_JPEG: 'image/jpeg',\n  IMAGE_PNG: 'image/png',\n  IMAGE_WEBP: 'image/webp',\n  JSON: 'application/json',\n  MARKDOWN: 'text/markdown',\n  PDF: 'application/pdf',\n  PLAIN_TEXT: 'text/plain',\n  SVG: 'image/svg+xml',\n} as const)\n\nexport type ReadFileMime = (typeof READ_FILE_MIME)[keyof typeof READ_FILE_MIME]\n\nexport const TEXT_FILE_EXTENSIONS: ReadonlySet<string> = new Set([\n  'txt',\n  'yaml',\n  'yml',\n  'tsv',\n  'xml',\n  'js',\n  'mjs',\n  'cjs',\n  'ts',\n  'tsx',\n  'jsx',\n  'py',\n  'rb',\n  'rs',\n  'go',\n  'java',\n  'c',\n  'cpp',\n  'h',\n  'hpp',\n  'sh',\n  'bash',\n  'zsh',\n  'sql',\n  'log',\n  'env',\n  'ini',\n  'toml',\n  'conf',\n  'cfg',\n])\n\nexport const MIME_FOR_EXTENSION: Readonly<Record<string, ReadFileMime>> = Object.freeze({\n  json: READ_FILE_MIME.JSON,\n  jsonl: READ_FILE_MIME.JSON,\n  csv: READ_FILE_MIME.CSV,\n  html: READ_FILE_MIME.HTML,\n  htm: READ_FILE_MIME.HTML,\n  md: READ_FILE_MIME.MARKDOWN,\n  svg: READ_FILE_MIME.SVG,\n  png: READ_FILE_MIME.IMAGE_PNG,\n  jpg: READ_FILE_MIME.IMAGE_JPEG,\n  jpeg: READ_FILE_MIME.IMAGE_JPEG,\n  gif: READ_FILE_MIME.IMAGE_GIF,\n  webp: READ_FILE_MIME.IMAGE_WEBP,\n  pdf: READ_FILE_MIME.PDF,\n})\n\nexport const MIME_FOR_FILE_TYPE: Readonly<Partial<Record<MirageFileType, ReadFileMime>>> =\n  Object.freeze({\n    [FileType.JSON]: READ_FILE_MIME.JSON,\n    [FileType.CSV]: READ_FILE_MIME.CSV,\n    [FileType.TEXT]: READ_FILE_MIME.PLAIN_TEXT,\n    [FileType.IMAGE_PNG]: READ_FILE_MIME.IMAGE_PNG,\n    [FileType.IMAGE_JPEG]: READ_FILE_MIME.IMAGE_JPEG,\n    [FileType.IMAGE_GIF]: READ_FILE_MIME.IMAGE_GIF,\n    [FileType.PDF]: READ_FILE_MIME.PDF,\n  })\n\nexport const MODEL_IMAGE_MIMES: ReadonlySet<ReadFileMime> = new Set([\n  READ_FILE_MIME.IMAGE_JPEG,\n  READ_FILE_MIME.IMAGE_PNG,\n  READ_FILE_MIME.IMAGE_GIF,\n  READ_FILE_MIME.IMAGE_WEBP,\n])\n"],"mappings":"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","names":["FileType","FileType"]}

package/dist/chunk-OLFSAPC6.js

@@ -0,0 +1,139 @@
+import {
+  FileVersionTracker,
+  StaleMirageFileError
+} from "./chunk-XEQB7N3F.js";
+
+// src/tool-operations.ts
+import { gnuDirname } from "@struktoai/mirage-core";
+
+// src/io-text.ts
+function decode(value) {
+  if (value === null || value === void 0) return "";
+  return new TextDecoder("utf-8").decode(value);
+}
+function ioToStr(io) {
+  const stdout = io.stdoutText;
+  const stderr = io.stderrText;
+  if (stderr) return stdout ? `${stdout}
+${stderr}` : stderr;
+  return stdout;
+}
+
+// src/tool-operations.ts
+function textResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+function errorResult(text) {
+  return { content: [{ type: "text", text }], isError: true };
+}
+function ioResult(io) {
+  const result = textResult(ioToStr(io));
+  if (io.exitCode !== 0) result.isError = true;
+  return result;
+}
+function shQuote(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+async function ensureParents(ws, path) {
+  const parent = gnuDirname(path);
+  if (parent === "/" || parent === "" || parent === ".") return;
+  if (await ws.fs.exists(parent)) return;
+  await ensureParents(ws, parent);
+  try {
+    await ws.fs.mkdir(parent);
+  } catch (err) {
+    if (!await ws.fs.exists(parent)) throw err;
+  }
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+var MirageToolOperations = class {
+  constructor(ws, options = {}) {
+    this.ws = ws;
+    this.versions = new FileVersionTracker(ws, options.staleWriteProtection ?? true);
+  }
+  ws;
+  versions;
+  async execute(command) {
+    return ioResult(await this.ws.execute(command));
+  }
+  async read(path, offset = 0, limit = 2e3) {
+    let data;
+    try {
+      data = await this.versions.read(path);
+    } catch (err) {
+      if (!await this.ws.fs.exists(path)) {
+        return errorResult(`Error: file '${path}' not found`);
+      }
+      return errorResult(`Error: ${errorMessage(err)}`);
+    }
+    const text = decode(data);
+    const raw = text.length === 0 ? [] : text.split(/(?<=\n)/);
+    const lines = raw.length > 0 && raw[raw.length - 1] === "" ? raw.slice(0, -1) : raw;
+    const sliced = lines.slice(offset, offset + limit);
+    const numbered = sliced.map((line, i) => `${String(i + offset + 1).padStart(6)}	${line}`);
+    return textResult(numbered.join(""));
+  }
+  async write(path, content) {
+    if (await this.ws.fs.exists(path)) {
+      return errorResult(`Error: file '${path}' already exists`);
+    }
+    await ensureParents(this.ws, path);
+    await this.versions.write(path, content);
+    return textResult(`Written: ${path}`);
+  }
+  async edit(path, oldString, newString, replaceAll = false) {
+    let content;
+    try {
+      content = (await this.versions.readForEdit(path)).toString("utf8");
+    } catch (err) {
+      if (err instanceof StaleMirageFileError) return errorResult(`Error: ${err.message}`);
+      if (!await this.ws.fs.exists(path)) {
+        return errorResult(`Error: file '${path}' not found`);
+      }
+      return errorResult(`Error: ${errorMessage(err)}`);
+    }
+    const count = content.split(oldString).length - 1;
+    if (count === 0) {
+      return errorResult(`Error: string not found in file: '${oldString}'`);
+    }
+    if (count > 1 && !replaceAll) {
+      return errorResult(`Error: string appears ${String(count)} times. Pass replace_all=true`);
+    }
+    const newContent = replaceAll ? content.split(oldString).join(newString) : content.replace(oldString, newString);
+    try {
+      await this.versions.writeEdit(path, newContent);
+    } catch (err) {
+      return errorResult(`Error: ${errorMessage(err)}`);
+    }
+    const occurrences = replaceAll ? count : 1;
+    return textResult(`Edited: ${path} (${String(occurrences)} occurrence(s))`);
+  }
+  async ls(path) {
+    return ioResult(await this.ws.execute(`ls ${shQuote(path)}`));
+  }
+  async grep(pattern, path) {
+    const io = await this.ws.execute(`grep -rn ${shQuote(pattern)} ${shQuote(path)}`);
+    return textResult(ioToStr(io));
+  }
+};
+
+// src/tool-descriptions.ts
+var EXECUTE_DESCRIPTION = "Run a shell-style command on the Mirage virtual filesystem. Supports cat, grep, find, head, tail, ls, wc, sort, uniq, tee, pipe, and any other Unix command on mounted resources (S3, disk, RAM, etc.). Also supports reading structured files: cat on .parquet/.orc/.csv returns a table.";
+var READ_DESCRIPTION = "Read the contents of a file on the Mirage virtual filesystem. Returns line-numbered text. Optionally pass 'offset' (default 0) to start at a given line and 'limit' (default 2000) to cap the number of lines returned.";
+var WRITE_DESCRIPTION = "Write content to a new file on the Mirage virtual filesystem. Fails if the file already exists; use edit to modify an existing file.";
+var EDIT_DESCRIPTION = "Replace a string in an existing file on the Mirage virtual filesystem. Fails if the file changed since it was last read, old_string is not found, or old_string appears more than once. Pass replace_all=true (default false) to replace every occurrence.";
+var LS_DESCRIPTION = "List files and directories at the given path on the Mirage virtual filesystem.";
+var GREP_DESCRIPTION = "Search for a pattern in files on the Mirage virtual filesystem. Supports regex. Searches recursively under path.";
+
+export {
+  MirageToolOperations,
+  EXECUTE_DESCRIPTION,
+  READ_DESCRIPTION,
+  WRITE_DESCRIPTION,
+  EDIT_DESCRIPTION,
+  LS_DESCRIPTION,
+  GREP_DESCRIPTION
+};
+//# sourceMappingURL=chunk-OLFSAPC6.js.map

package/dist/chunk-OLFSAPC6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/tool-operations.ts","../src/io-text.ts","../src/tool-descriptions.ts"],"sourcesContent":["// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n//     http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========\n\nimport type { ExecuteResult, Workspace } from '@struktoai/mirage-core'\nimport { gnuDirname } from '@struktoai/mirage-core'\nimport { FileVersionTracker, StaleMirageFileError } from './file-version.ts'\nimport { decode, ioToStr } from './io-text.ts'\n\nexport interface ToolResult {\n  [key: string]: unknown\n  content: { type: 'text'; text: string }[]\n  isError?: boolean\n}\n\nexport interface MirageToolOperationsOptions {\n  staleWriteProtection?: boolean\n}\n\nfunction textResult(text: string): ToolResult {\n  return { content: [{ type: 'text', text }] }\n}\n\nfunction errorResult(text: string): ToolResult {\n  return { content: [{ type: 'text', text }], isError: true }\n}\n\nfunction ioResult(io: ExecuteResult): ToolResult {\n  const result = textResult(ioToStr(io))\n  if (io.exitCode !== 0) result.isError = true\n  return result\n}\n\nfunction shQuote(value: string): string {\n  return `'${value.replace(/'/g, \"'\\\\''\")}'`\n}\n\nasync function ensureParents(ws: Workspace, path: string): Promise<void> {\n  const parent = gnuDirname(path)\n  if (parent === '/' || parent === '' || parent === '.') return\n  if (await ws.fs.exists(parent)) return\n  await ensureParents(ws, parent)\n  try {\n    await ws.fs.mkdir(parent)\n  } catch (err) {\n    if (!(await ws.fs.exists(parent))) throw err\n  }\n}\n\nfunction errorMessage(error: unknown): string {\n  return error instanceof Error ? error.message : String(error)\n}\n\nexport class MirageToolOperations {\n  private readonly versions: FileVersionTracker\n\n  constructor(\n    private readonly ws: Workspace,\n    options: MirageToolOperationsOptions = {},\n  ) {\n    this.versions = new FileVersionTracker(ws, options.staleWriteProtection ?? true)\n  }\n\n  async execute(command: string): Promise<ToolResult> {\n    return ioResult(await this.ws.execute(command))\n  }\n\n  async read(path: string, offset = 0, limit = 2000): Promise<ToolResult> {\n    let data: Uint8Array\n    try {\n      data = await this.versions.read(path)\n    } catch (err) {\n      if (!(await this.ws.fs.exists(path))) {\n        return errorResult(`Error: file '${path}' not found`)\n      }\n      return errorResult(`Error: ${errorMessage(err)}`)\n    }\n    const text = decode(data)\n    const raw = text.length === 0 ? [] : text.split(/(?<=\\n)/)\n    const lines = raw.length > 0 && raw[raw.length - 1] === '' ? raw.slice(0, -1) : raw\n    const sliced = lines.slice(offset, offset + limit)\n    const numbered = sliced.map((line, i) => `${String(i + offset + 1).padStart(6)}\\t${line}`)\n    return textResult(numbered.join(''))\n  }\n\n  async write(path: string, content: string): Promise<ToolResult> {\n    if (await this.ws.fs.exists(path)) {\n      return errorResult(`Error: file '${path}' already exists`)\n    }\n    await ensureParents(this.ws, path)\n    await this.versions.write(path, content)\n    return textResult(`Written: ${path}`)\n  }\n\n  async edit(\n    path: string,\n    oldString: string,\n    newString: string,\n    replaceAll = false,\n  ): Promise<ToolResult> {\n    let content: string\n    try {\n      content = (await this.versions.readForEdit(path)).toString('utf8')\n    } catch (err) {\n      if (err instanceof StaleMirageFileError) return errorResult(`Error: ${err.message}`)\n      if (!(await this.ws.fs.exists(path))) {\n        return errorResult(`Error: file '${path}' not found`)\n      }\n      return errorResult(`Error: ${errorMessage(err)}`)\n    }\n    const count = content.split(oldString).length - 1\n    if (count === 0) {\n      return errorResult(`Error: string not found in file: '${oldString}'`)\n    }\n    if (count > 1 && !replaceAll) {\n      return errorResult(`Error: string appears ${String(count)} times. Pass replace_all=true`)\n    }\n    const newContent = replaceAll\n      ? content.split(oldString).join(newString)\n      : content.replace(oldString, newString)\n    try {\n      await this.versions.writeEdit(path, newContent)\n    } catch (err) {\n      return errorResult(`Error: ${errorMessage(err)}`)\n    }\n    const occurrences = replaceAll ? count : 1\n    return textResult(`Edited: ${path} (${String(occurrences)} occurrence(s))`)\n  }\n\n  async ls(path: string): Promise<ToolResult> {\n    return ioResult(await this.ws.execute(`ls ${shQuote(path)}`))\n  }\n\n  async grep(pattern: string, path: string): Promise<ToolResult> {\n    const io = await this.ws.execute(`grep -rn ${shQuote(pattern)} ${shQuote(path)}`)\n    return textResult(ioToStr(io))\n  }\n}\n","// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n//     http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========\n\nimport type { ExecuteResult } from '@struktoai/mirage-core'\n\nexport function decode(value: Uint8Array | null | undefined): string {\n  if (value === null || value === undefined) return ''\n  return new TextDecoder('utf-8').decode(value)\n}\n\nexport function ioToStr(io: ExecuteResult): string {\n  const stdout = io.stdoutText\n  const stderr = io.stderrText\n  if (stderr) return stdout ? `${stdout}\\n${stderr}` : stderr\n  return stdout\n}\n","// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n//     http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========\n\nexport const EXECUTE_DESCRIPTION =\n  'Run a shell-style command on the Mirage virtual filesystem. ' +\n  'Supports cat, grep, find, head, tail, ls, wc, sort, uniq, tee, pipe, ' +\n  'and any other Unix command on mounted resources (S3, disk, RAM, etc.). ' +\n  'Also supports reading structured files: cat on .parquet/.orc/.csv returns a table.'\n\nexport const READ_DESCRIPTION =\n  'Read the contents of a file on the Mirage virtual filesystem. ' +\n  'Returns line-numbered text. ' +\n  \"Optionally pass 'offset' (default 0) to start at a given line \" +\n  \"and 'limit' (default 2000) to cap the number of lines returned.\"\n\nexport const WRITE_DESCRIPTION =\n  'Write content to a new file on the Mirage virtual filesystem. ' +\n  'Fails if the file already exists; use edit to modify an existing file.'\n\nexport const EDIT_DESCRIPTION =\n  'Replace a string in an existing file on the Mirage virtual filesystem. ' +\n  'Fails if the file changed since it was last read, old_string is not found, ' +\n  'or old_string appears more than once. ' +\n  'Pass replace_all=true (default false) to replace every occurrence.'\n\nexport const LS_DESCRIPTION =\n  'List files and directories at the given path on the Mirage virtual filesystem.'\n\nexport const GREP_DESCRIPTION =\n  'Search for a pattern in files on the Mirage virtual filesystem. ' +\n  'Supports regex. Searches recursively under path.'\n"],"mappings":"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","names":[]}

package/dist/chunk-XEQB7N3F.js

@@ -0,0 +1,79 @@
+// src/file-version.ts
+import { createHash } from "crypto";
+var StaleMirageFileError = class extends Error {
+  path;
+  constructor(path) {
+    super(`File changed since it was last read: ${path}. Read the file again before modifying it.`);
+    this.name = "StaleMirageFileError";
+    this.path = path;
+  }
+};
+function fingerprint(content) {
+  return createHash("sha256").update(content).digest("base64url");
+}
+async function readBuffer(ws, path) {
+  const bytes = await ws.fs.readFile(path, { raw: true });
+  return Buffer.from(bytes);
+}
+var FileVersionTracker = class {
+  constructor(ws, enabled = true) {
+    this.ws = ws;
+    this.enabled = enabled;
+  }
+  ws;
+  enabled;
+  readVersions = /* @__PURE__ */ new Map();
+  editVersions = /* @__PURE__ */ new Map();
+  async currentVersion(path) {
+    if (!await this.ws.fs.exists(path)) return null;
+    return fingerprint(await readBuffer(this.ws, path));
+  }
+  async assertVersion(path, expected) {
+    if (await this.currentVersion(path) !== expected) {
+      throw new StaleMirageFileError(path);
+    }
+  }
+  recordWrite(path, content) {
+    if (!this.enabled) return;
+    this.readVersions.set(path, fingerprint(content));
+    this.editVersions.delete(path);
+  }
+  async read(path) {
+    const content = await readBuffer(this.ws, path);
+    if (this.enabled) this.readVersions.set(path, fingerprint(content));
+    return content;
+  }
+  async readForEdit(path) {
+    const content = await readBuffer(this.ws, path);
+    if (!this.enabled) return content;
+    const version = fingerprint(content);
+    const readVersion = this.readVersions.get(path);
+    if (readVersion !== void 0 && readVersion !== version) {
+      throw new StaleMirageFileError(path);
+    }
+    this.editVersions.set(path, version);
+    return content;
+  }
+  async write(path, content) {
+    if (this.enabled) {
+      const readVersion = this.readVersions.get(path);
+      if (readVersion !== void 0) await this.assertVersion(path, readVersion);
+    }
+    await this.ws.fs.writeFile(path, content);
+    this.recordWrite(path, content);
+  }
+  async writeEdit(path, content) {
+    if (this.enabled) {
+      const editVersion = this.editVersions.get(path);
+      if (editVersion !== void 0) await this.assertVersion(path, editVersion);
+    }
+    await this.ws.fs.writeFile(path, content);
+    this.recordWrite(path, content);
+  }
+};
+
+export {
+  StaleMirageFileError,
+  FileVersionTracker
+};
+//# sourceMappingURL=chunk-XEQB7N3F.js.map

package/dist/chunk-XEQB7N3F.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/file-version.ts"],"sourcesContent":["// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========\n// Licensed under the Apache License, Version 2.0 (the \"License\");\n// you may not use this file except in compliance with the License.\n// You may obtain a copy of the License at\n//\n//     http://www.apache.org/licenses/LICENSE-2.0\n//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n// ========= Copyright 2026 @ Strukto.AI All Rights Reserved. =========\n\nimport { createHash } from 'node:crypto'\nimport type { Workspace } from '@struktoai/mirage-core'\n\nexport class StaleMirageFileError extends Error {\n  readonly path: string\n\n  constructor(path: string) {\n    super(`File changed since it was last read: ${path}. Read the file again before modifying it.`)\n    this.name = 'StaleMirageFileError'\n    this.path = path\n  }\n}\n\nfunction fingerprint(content: Uint8Array | string): string {\n  return createHash('sha256').update(content).digest('base64url')\n}\n\nasync function readBuffer(ws: Workspace, path: string): Promise<Buffer> {\n  const bytes = await ws.fs.readFile(path, { raw: true })\n  return Buffer.from(bytes)\n}\n\nexport class FileVersionTracker {\n  private readonly readVersions = new Map<string, string>()\n  private readonly editVersions = new Map<string, string>()\n\n  constructor(\n    private readonly ws: Workspace,\n    private readonly enabled = true,\n  ) {}\n\n  private async currentVersion(path: string): Promise<string | null> {\n    if (!(await this.ws.fs.exists(path))) return null\n    return fingerprint(await readBuffer(this.ws, path))\n  }\n\n  private async assertVersion(path: string, expected: string): Promise<void> {\n    if ((await this.currentVersion(path)) !== expected) {\n      throw new StaleMirageFileError(path)\n    }\n  }\n\n  private recordWrite(path: string, content: string): void {\n    if (!this.enabled) return\n    this.readVersions.set(path, fingerprint(content))\n    this.editVersions.delete(path)\n  }\n\n  async read(path: string): Promise<Buffer> {\n    const content = await readBuffer(this.ws, path)\n    if (this.enabled) this.readVersions.set(path, fingerprint(content))\n    return content\n  }\n\n  async readForEdit(path: string): Promise<Buffer> {\n    const content = await readBuffer(this.ws, path)\n    if (!this.enabled) return content\n    const version = fingerprint(content)\n    const readVersion = this.readVersions.get(path)\n    if (readVersion !== undefined && readVersion !== version) {\n      throw new StaleMirageFileError(path)\n    }\n    this.editVersions.set(path, version)\n    return content\n  }\n\n  async write(path: string, content: string): Promise<void> {\n    if (this.enabled) {\n      const readVersion = this.readVersions.get(path)\n      if (readVersion !== undefined) await this.assertVersion(path, readVersion)\n    }\n    await this.ws.fs.writeFile(path, content)\n    this.recordWrite(path, content)\n  }\n\n  async writeEdit(path: string, content: string): Promise<void> {\n    if (this.enabled) {\n      const editVersion = this.editVersions.get(path)\n      if (editVersion !== undefined) await this.assertVersion(path, editVersion)\n    }\n    await this.ws.fs.writeFile(path, content)\n    this.recordWrite(path, content)\n  }\n}\n"],"mappings":";AAcA,SAAS,kBAAkB;AAGpB,IAAM,uBAAN,cAAmC,MAAM;AAAA,EACrC;AAAA,EAET,YAAY,MAAc;AACxB,UAAM,wCAAwC,IAAI,4CAA4C;AAC9F,SAAK,OAAO;AACZ,SAAK,OAAO;AAAA,EACd;AACF;AAEA,SAAS,YAAY,SAAsC;AACzD,SAAO,WAAW,QAAQ,EAAE,OAAO,OAAO,EAAE,OAAO,WAAW;AAChE;AAEA,eAAe,WAAW,IAAe,MAA+B;AACtE,QAAM,QAAQ,MAAM,GAAG,GAAG,SAAS,MAAM,EAAE,KAAK,KAAK,CAAC;AACtD,SAAO,OAAO,KAAK,KAAK;AAC1B;AAEO,IAAM,qBAAN,MAAyB;AAAA,EAI9B,YACmB,IACA,UAAU,MAC3B;AAFiB;AACA;AAAA,EAChB;AAAA,EAFgB;AAAA,EACA;AAAA,EALF,eAAe,oBAAI,IAAoB;AAAA,EACvC,eAAe,oBAAI,IAAoB;AAAA,EAOxD,MAAc,eAAe,MAAsC;AACjE,QAAI,CAAE,MAAM,KAAK,GAAG,GAAG,OAAO,IAAI,EAAI,QAAO;AAC7C,WAAO,YAAY,MAAM,WAAW,KAAK,IAAI,IAAI,CAAC;AAAA,EACpD;AAAA,EAEA,MAAc,cAAc,MAAc,UAAiC;AACzE,QAAK,MAAM,KAAK,eAAe,IAAI,MAAO,UAAU;AAClD,YAAM,IAAI,qBAAqB,IAAI;AAAA,IACrC;AAAA,EACF;AAAA,EAEQ,YAAY,MAAc,SAAuB;AACvD,QAAI,CAAC,KAAK,QAAS;AACnB,SAAK,aAAa,IAAI,MAAM,YAAY,OAAO,CAAC;AAChD,SAAK,aAAa,OAAO,IAAI;AAAA,EAC/B;AAAA,EAEA,MAAM,KAAK,MAA+B;AACxC,UAAM,UAAU,MAAM,WAAW,KAAK,IAAI,IAAI;AAC9C,QAAI,KAAK,QAAS,MAAK,aAAa,IAAI,MAAM,YAAY,OAAO,CAAC;AAClE,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,YAAY,MAA+B;AAC/C,UAAM,UAAU,MAAM,WAAW,KAAK,IAAI,IAAI;AAC9C,QAAI,CAAC,KAAK,QAAS,QAAO;AAC1B,UAAM,UAAU,YAAY,OAAO;AACnC,UAAM,cAAc,KAAK,aAAa,IAAI,IAAI;AAC9C,QAAI,gBAAgB,UAAa,gBAAgB,SAAS;AACxD,YAAM,IAAI,qBAAqB,IAAI;AAAA,IACrC;AACA,SAAK,aAAa,IAAI,MAAM,OAAO;AACnC,WAAO;AAAA,EACT;AAAA,EAEA,MAAM,MAAM,MAAc,SAAgC;AACxD,QAAI,KAAK,SAAS;AAChB,YAAM,cAAc,KAAK,aAAa,IAAI,IAAI;AAC9C,UAAI,gBAAgB,OAAW,OAAM,KAAK,cAAc,MAAM,WAAW;AAAA,IAC3E;AACA,UAAM,KAAK,GAAG,GAAG,UAAU,MAAM,OAAO;AACxC,SAAK,YAAY,MAAM,OAAO;AAAA,EAChC;AAAA,EAEA,MAAM,UAAU,MAAc,SAAgC;AAC5D,QAAI,KAAK,SAAS;AAChB,YAAM,cAAc,KAAK,aAAa,IAAI,IAAI;AAC9C,UAAI,gBAAgB,OAAW,OAAM,KAAK,cAAc,MAAM,WAAW;AAAA,IAC3E;AACA,UAAM,KAAK,GAAG,GAAG,UAAU,MAAM,OAAO;AACxC,SAAK,YAAY,MAAM,OAAO;AAAA,EAChC;AACF;","names":[]}

package/dist/claude-agent-sdk/index.d.ts

@@ -1,20 +1,15 @@
 import * as _anthropic_ai_claude_agent_sdk from '@anthropic-ai/claude-agent-sdk';
 import { Options } from '@anthropic-ai/claude-agent-sdk';
 import { Workspace } from '@struktoai/mirage-core';
+import { M as MirageToolOperationsOptions } from '../tool-descriptions-7CgIovZc.js';
+export { E as EDIT_DESCRIPTION, a as EXECUTE_DESCRIPTION, G as GREP_DESCRIPTION, L as LS_DESCRIPTION, R as READ_DESCRIPTION, W as WRITE_DESCRIPTION } from '../tool-descriptions-7CgIovZc.js';
 export { M as MIRAGE_SYSTEM_PROMPT, b as buildSystemPrompt } from '../prompt-Ca4hc1Ul.js';
 
-declare function MirageServer(workspace: Workspace): _anthropic_ai_claude_agent_sdk.McpSdkServerConfigWithInstance;
+declare function MirageServer(workspace: Workspace, options?: MirageToolOperationsOptions): _anthropic_ai_claude_agent_sdk.McpSdkServerConfigWithInstance;
 
 interface BuildOptionsOptions {
     systemPrompt?: string;
 }
 declare function buildOptions(workspace: Workspace, opts?: BuildOptionsOptions): Options;
 
-declare const EXECUTE_DESCRIPTION: string;
-declare const READ_DESCRIPTION: string;
-declare const WRITE_DESCRIPTION: string;
-declare const EDIT_DESCRIPTION: string;
-declare const LS_DESCRIPTION = "List files and directories at the given path on the Mirage virtual filesystem.";
-declare const GREP_DESCRIPTION: string;
-
-export { type BuildOptionsOptions, EDIT_DESCRIPTION, EXECUTE_DESCRIPTION, GREP_DESCRIPTION, LS_DESCRIPTION, MirageServer, READ_DESCRIPTION, WRITE_DESCRIPTION, buildOptions };
+export { type BuildOptionsOptions, MirageServer, buildOptions };

package/dist/claude-agent-sdk/index.js

@@ -1,115 +1,24 @@
+import {
+  EDIT_DESCRIPTION,
+  EXECUTE_DESCRIPTION,
+  GREP_DESCRIPTION,
+  LS_DESCRIPTION,
+  MirageToolOperations,
+  READ_DESCRIPTION,
+  WRITE_DESCRIPTION
+} from "../chunk-OLFSAPC6.js";
 import {
   MIRAGE_SYSTEM_PROMPT,
   buildSystemPrompt
 } from "../chunk-ODKR5YZI.js";
+import "../chunk-XEQB7N3F.js";
 
 // src/claude-agent-sdk/server.ts
-import { VERSION, gnuDirname } from "@struktoai/mirage-core";
+import { VERSION } from "@struktoai/mirage-core";
 import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
 import { z } from "zod";
-
-// src/io-text.ts
-function decode(value) {
-  if (value === null || value === void 0) return "";
-  return new TextDecoder("utf-8").decode(value);
-}
-function ioToStr(io) {
-  const stdout = io.stdoutText;
-  const stderr = io.stderrText;
-  if (stderr) return stdout ? `${stdout}
-${stderr}` : stderr;
-  return stdout;
-}
-
-// src/claude-agent-sdk/descriptions.ts
-var EXECUTE_DESCRIPTION = "Run a shell-style command on the Mirage virtual filesystem. Supports cat, grep, find, head, tail, ls, wc, sort, uniq, tee, pipe, and any other Unix command on mounted resources (S3, disk, RAM, etc.). Also supports reading structured files: cat on .parquet/.orc/.csv returns a table.";
-var READ_DESCRIPTION = "Read the contents of a file on the Mirage virtual filesystem. Returns line-numbered text. Optionally pass 'offset' (default 0) to start at a given line and 'limit' (default 2000) to cap the number of lines returned.";
-var WRITE_DESCRIPTION = "Write content to a new file on the Mirage virtual filesystem. Fails if the file already exists; use edit to modify an existing file.";
-var EDIT_DESCRIPTION = "Replace a string in an existing file on the Mirage virtual filesystem. Fails if old_string is not found or appears more than once. Pass replace_all=true (default false) to replace every occurrence.";
-var LS_DESCRIPTION = "List files and directories at the given path on the Mirage virtual filesystem.";
-var GREP_DESCRIPTION = "Search for a pattern in files on the Mirage virtual filesystem. Supports regex. Searches recursively under path.";
-
-// src/claude-agent-sdk/server.ts
-function textResult(text) {
-  return { content: [{ type: "text", text }] };
-}
-function errorResult(text) {
-  return { content: [{ type: "text", text }], isError: true };
-}
-function ioResult(io) {
-  const result = textResult(ioToStr(io));
-  if (io.exitCode !== 0) result.isError = true;
-  return result;
-}
-function shQuote(value) {
-  return `'${value.replace(/'/g, "'\\''")}'`;
-}
-async function ensureParents(ws, path) {
-  const parent = gnuDirname(path);
-  if (parent === "/" || parent === "" || parent === ".") return;
-  if (await ws.fs.exists(parent)) return;
-  await ensureParents(ws, parent);
-  try {
-    await ws.fs.mkdir(parent);
-  } catch (err) {
-    if (!await ws.fs.exists(parent)) throw err;
-  }
-}
-async function runExecute(ws, command) {
-  return ioResult(await ws.execute(command));
-}
-async function runRead(ws, path, offset = 0, limit = 2e3) {
-  let data;
-  try {
-    data = await ws.fs.readFile(path);
-  } catch (err) {
-    if (!await ws.fs.exists(path)) {
-      return errorResult(`Error: file '${path}' not found`);
-    }
-    return errorResult(`Error: ${err instanceof Error ? err.message : String(err)}`);
-  }
-  const text = decode(data);
-  const raw = text.length === 0 ? [] : text.split(/(?<=\n)/);
-  const lines = raw.length > 0 && raw[raw.length - 1] === "" ? raw.slice(0, -1) : raw;
-  const sliced = lines.slice(offset, offset + limit);
-  const numbered = sliced.map((line, i) => `${String(i + offset + 1).padStart(6)}	${line}`);
-  return textResult(numbered.join(""));
-}
-async function runWrite(ws, path, content) {
-  if (await ws.fs.exists(path)) {
-    return errorResult(`Error: file '${path}' already exists`);
-  }
-  await ensureParents(ws, path);
-  await ws.fs.writeFile(path, content);
-  return textResult(`Written: ${path}`);
-}
-async function runEdit(ws, path, oldString, newString, replaceAll = false) {
-  let content;
-  try {
-    content = await ws.fs.readFileText(path);
-  } catch {
-    return errorResult(`Error: file '${path}' not found`);
-  }
-  const count = content.split(oldString).length - 1;
-  if (count === 0) {
-    return errorResult(`Error: string not found in file: '${oldString}'`);
-  }
-  if (count > 1 && !replaceAll) {
-    return errorResult(`Error: string appears ${String(count)} times. Pass replace_all=true`);
-  }
-  const newContent = replaceAll ? content.split(oldString).join(newString) : content.replace(oldString, newString);
-  await ws.fs.writeFile(path, newContent);
-  const occurrences = replaceAll ? count : 1;
-  return textResult(`Edited: ${path} (${String(occurrences)} occurrence(s))`);
-}
-async function runLs(ws, path) {
-  return ioResult(await ws.execute(`ls ${shQuote(path)}`));
-}
-async function runGrep(ws, pattern, path) {
-  const io = await ws.execute(`grep -rn ${shQuote(pattern)} ${shQuote(path)}`);
-  return textResult(ioToStr(io));
-}
-function MirageServer(workspace) {
+function MirageServer(workspace, options = {}) {
+  const operations = new MirageToolOperations(workspace, options);
   return createSdkMcpServer({
     name: "mirage",
     version: VERSION,
@@ -119,20 +28,20 @@ function MirageServer(workspace) {
         "execute_command",
         EXECUTE_DESCRIPTION,
         { command: z.string() },
-        (args) => runExecute(workspace, args.command)
+        (args) => operations.execute(args.command)
       ),
       tool(
         "read",
         READ_DESCRIPTION,
         { path: z.string(), offset: z.number().optional(), limit: z.number().optional() },
-        (args) => runRead(workspace, args.path, args.offset, args.limit),
+        (args) => operations.read(args.path, args.offset, args.limit),
         { annotations: { readOnlyHint: true } }
       ),
       tool(
         "write",
         WRITE_DESCRIPTION,
         { path: z.string(), content: z.string() },
-        (args) => runWrite(workspace, args.path, args.content)
+        (args) => operations.write(args.path, args.content)
       ),
       tool(
         "edit",
@@ -143,16 +52,16 @@ function MirageServer(workspace) {
           new_string: z.string(),
           replace_all: z.boolean().optional()
         },
-        (args) => runEdit(workspace, args.path, args.old_string, args.new_string, args.replace_all)
+        (args) => operations.edit(args.path, args.old_string, args.new_string, args.replace_all)
       ),
-      tool("ls", LS_DESCRIPTION, { path: z.string() }, (args) => runLs(workspace, args.path), {
+      tool("ls", LS_DESCRIPTION, { path: z.string() }, (args) => operations.ls(args.path), {
         annotations: { readOnlyHint: true }
       }),
       tool(
         "grep",
         GREP_DESCRIPTION,
         { pattern: z.string(), path: z.string() },
-        (args) => runGrep(workspace, args.pattern, args.path),
+        (args) => operations.grep(args.pattern, args.path),
         { annotations: { readOnlyHint: true } }
       )
     ]