@struktoai/mirage-agents 0.0.3 → 0.0.4

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

@@ -1 +1 @@
-{"version":3,"sources":["../../src/claude-agent-sdk/server.ts","../../src/io-text.ts","../../src/claude-agent-sdk/descriptions.ts","../../src/claude-agent-sdk/options.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 { VERSION, gnuDirname } from '@struktoai/mirage-core'\nimport { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'\nimport { z } from 'zod'\nimport { decode, ioToStr } from '../io-text.ts'\nimport {\n  EDIT_DESCRIPTION,\n  EXECUTE_DESCRIPTION,\n  GREP_DESCRIPTION,\n  LS_DESCRIPTION,\n  READ_DESCRIPTION,\n  WRITE_DESCRIPTION,\n} from './descriptions.ts'\n\nexport interface ToolResult {\n  [key: string]: unknown\n  content: { type: 'text'; text: string }[]\n  isError?: 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\nexport async function runExecute(ws: Workspace, command: string): Promise<ToolResult> {\n  return ioResult(await ws.execute(command))\n}\n\nexport async function runRead(\n  ws: Workspace,\n  path: string,\n  offset = 0,\n  limit = 2000,\n): Promise<ToolResult> {\n  let data: Uint8Array\n  try {\n    data = await ws.fs.readFile(path)\n  } catch (err) {\n    if (!(await ws.fs.exists(path))) {\n      return errorResult(`Error: file '${path}' not found`)\n    }\n    return errorResult(`Error: ${err instanceof Error ? err.message : String(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\nexport async function runWrite(ws: Workspace, path: string, content: string): Promise<ToolResult> {\n  if (await ws.fs.exists(path)) {\n    return errorResult(`Error: file '${path}' already exists`)\n  }\n  await ensureParents(ws, path)\n  await ws.fs.writeFile(path, content)\n  return textResult(`Written: ${path}`)\n}\n\nexport async function runEdit(\n  ws: Workspace,\n  path: string,\n  oldString: string,\n  newString: string,\n  replaceAll = false,\n): Promise<ToolResult> {\n  let content: string\n  try {\n    content = await ws.fs.readFileText(path)\n  } catch {\n    return errorResult(`Error: file '${path}' not found`)\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  await ws.fs.writeFile(path, newContent)\n  const occurrences = replaceAll ? count : 1\n  return textResult(`Edited: ${path} (${String(occurrences)} occurrence(s))`)\n}\n\nexport async function runLs(ws: Workspace, path: string): Promise<ToolResult> {\n  return ioResult(await ws.execute(`ls ${shQuote(path)}`))\n}\n\nexport async function runGrep(ws: Workspace, pattern: string, path: string): Promise<ToolResult> {\n  const io = await ws.execute(`grep -rn ${shQuote(pattern)} ${shQuote(path)}`)\n  return textResult(ioToStr(io))\n}\n\nexport function MirageServer(workspace: Workspace) {\n  return createSdkMcpServer({\n    name: 'mirage',\n    version: VERSION,\n    alwaysLoad: true,\n    tools: [\n      tool('execute_command', EXECUTE_DESCRIPTION, { command: z.string() }, (args) =>\n        runExecute(workspace, args.command),\n      ),\n      tool(\n        'read',\n        READ_DESCRIPTION,\n        { path: z.string(), offset: z.number().optional(), limit: z.number().optional() },\n        (args) => runRead(workspace, args.path, args.offset, args.limit),\n        { annotations: { readOnlyHint: true } },\n      ),\n      tool('write', WRITE_DESCRIPTION, { path: z.string(), content: z.string() }, (args) =>\n        runWrite(workspace, args.path, args.content),\n      ),\n      tool(\n        'edit',\n        EDIT_DESCRIPTION,\n        {\n          path: z.string(),\n          old_string: z.string(),\n          new_string: z.string(),\n          replace_all: z.boolean().optional(),\n        },\n        (args) => runEdit(workspace, args.path, args.old_string, args.new_string, args.replace_all),\n      ),\n      tool('ls', LS_DESCRIPTION, { path: z.string() }, (args) => runLs(workspace, args.path), {\n        annotations: { readOnlyHint: true },\n      }),\n      tool(\n        'grep',\n        GREP_DESCRIPTION,\n        { pattern: z.string(), path: z.string() },\n        (args) => runGrep(workspace, args.pattern, args.path),\n        { annotations: { readOnlyHint: true } },\n      ),\n    ],\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 old_string is not found or 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","// ========= 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 { Workspace } from '@struktoai/mirage-core'\nimport type { Options } from '@anthropic-ai/claude-agent-sdk'\nimport { buildSystemPrompt } from '../prompt.ts'\nimport { MirageServer } from './server.ts'\n\nexport interface BuildOptionsOptions {\n  systemPrompt?: string\n}\n\nexport function buildOptions(workspace: Workspace, opts: BuildOptionsOptions = {}): Options {\n  return {\n    mcpServers: { mirage: MirageServer(workspace) },\n    allowedTools: ['mcp__mirage__*'],\n    systemPrompt: opts.systemPrompt ?? buildSystemPrompt({ workspace }),\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/claude-agent-sdk/server.ts","../../src/claude-agent-sdk/options.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 { Workspace } from '@struktoai/mirage-core'\nimport { VERSION } from '@struktoai/mirage-core'\nimport { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk'\nimport { z } from 'zod'\nimport {\n  MirageToolOperations,\n  type MirageToolOperationsOptions,\n  type ToolResult,\n} from '../tool-operations.ts'\nimport {\n  EDIT_DESCRIPTION,\n  EXECUTE_DESCRIPTION,\n  GREP_DESCRIPTION,\n  LS_DESCRIPTION,\n  READ_DESCRIPTION,\n  WRITE_DESCRIPTION,\n} from './descriptions.ts'\n\nexport async function runExecute(ws: Workspace, command: string): Promise<ToolResult> {\n  return new MirageToolOperations(ws).execute(command)\n}\n\nexport async function runRead(\n  ws: Workspace,\n  path: string,\n  offset = 0,\n  limit = 2000,\n): Promise<ToolResult> {\n  return new MirageToolOperations(ws).read(path, offset, limit)\n}\n\nexport async function runWrite(ws: Workspace, path: string, content: string): Promise<ToolResult> {\n  return new MirageToolOperations(ws).write(path, content)\n}\n\nexport async function runEdit(\n  ws: Workspace,\n  path: string,\n  oldString: string,\n  newString: string,\n  replaceAll = false,\n): Promise<ToolResult> {\n  return new MirageToolOperations(ws).edit(path, oldString, newString, replaceAll)\n}\n\nexport async function runLs(ws: Workspace, path: string): Promise<ToolResult> {\n  return new MirageToolOperations(ws).ls(path)\n}\n\nexport async function runGrep(ws: Workspace, pattern: string, path: string): Promise<ToolResult> {\n  return new MirageToolOperations(ws).grep(pattern, path)\n}\n\nexport function MirageServer(workspace: Workspace, options: MirageToolOperationsOptions = {}) {\n  const operations = new MirageToolOperations(workspace, options)\n  return createSdkMcpServer({\n    name: 'mirage',\n    version: VERSION,\n    alwaysLoad: true,\n    tools: [\n      tool('execute_command', EXECUTE_DESCRIPTION, { command: z.string() }, (args) =>\n        operations.execute(args.command),\n      ),\n      tool(\n        'read',\n        READ_DESCRIPTION,\n        { path: z.string(), offset: z.number().optional(), limit: z.number().optional() },\n        (args) => operations.read(args.path, args.offset, args.limit),\n        { annotations: { readOnlyHint: true } },\n      ),\n      tool('write', WRITE_DESCRIPTION, { path: z.string(), content: z.string() }, (args) =>\n        operations.write(args.path, args.content),\n      ),\n      tool(\n        'edit',\n        EDIT_DESCRIPTION,\n        {\n          path: z.string(),\n          old_string: z.string(),\n          new_string: z.string(),\n          replace_all: z.boolean().optional(),\n        },\n        (args) => operations.edit(args.path, args.old_string, args.new_string, args.replace_all),\n      ),\n      tool('ls', LS_DESCRIPTION, { path: z.string() }, (args) => operations.ls(args.path), {\n        annotations: { readOnlyHint: true },\n      }),\n      tool(\n        'grep',\n        GREP_DESCRIPTION,\n        { pattern: z.string(), path: z.string() },\n        (args) => operations.grep(args.pattern, args.path),\n        { annotations: { readOnlyHint: true } },\n      ),\n    ],\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 { Workspace } from '@struktoai/mirage-core'\nimport type { Options } from '@anthropic-ai/claude-agent-sdk'\nimport { buildSystemPrompt } from '../prompt.ts'\nimport { MirageServer } from './server.ts'\n\nexport interface BuildOptionsOptions {\n  systemPrompt?: string\n}\n\nexport function buildOptions(workspace: Workspace, opts: BuildOptionsOptions = {}): Options {\n  return {\n    mcpServers: { mirage: MirageServer(workspace) },\n    allowedTools: ['mcp__mirage__*'],\n    systemPrompt: opts.systemPrompt ?? buildSystemPrompt({ workspace }),\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAeA,SAAS,eAAe;AACxB,SAAS,oBAAoB,YAAY;AACzC,SAAS,SAAS;AAkDX,SAAS,aAAa,WAAsB,UAAuC,CAAC,GAAG;AAC5F,QAAM,aAAa,IAAI,qBAAqB,WAAW,OAAO;AAC9D,SAAO,mBAAmB;AAAA,IACxB,MAAM;AAAA,IACN,SAAS;AAAA,IACT,YAAY;AAAA,IACZ,OAAO;AAAA,MACL;AAAA,QAAK;AAAA,QAAmB;AAAA,QAAqB,EAAE,SAAS,EAAE,OAAO,EAAE;AAAA,QAAG,CAAC,SACrE,WAAW,QAAQ,KAAK,OAAO;AAAA,MACjC;AAAA,MACA;AAAA,QACE;AAAA,QACA;AAAA,QACA,EAAE,MAAM,EAAE,OAAO,GAAG,QAAQ,EAAE,OAAO,EAAE,SAAS,GAAG,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE;AAAA,QAChF,CAAC,SAAS,WAAW,KAAK,KAAK,MAAM,KAAK,QAAQ,KAAK,KAAK;AAAA,QAC5D,EAAE,aAAa,EAAE,cAAc,KAAK,EAAE;AAAA,MACxC;AAAA,MACA;AAAA,QAAK;AAAA,QAAS;AAAA,QAAmB,EAAE,MAAM,EAAE,OAAO,GAAG,SAAS,EAAE,OAAO,EAAE;AAAA,QAAG,CAAC,SAC3E,WAAW,MAAM,KAAK,MAAM,KAAK,OAAO;AAAA,MAC1C;AAAA,MACA;AAAA,QACE;AAAA,QACA;AAAA,QACA;AAAA,UACE,MAAM,EAAE,OAAO;AAAA,UACf,YAAY,EAAE,OAAO;AAAA,UACrB,YAAY,EAAE,OAAO;AAAA,UACrB,aAAa,EAAE,QAAQ,EAAE,SAAS;AAAA,QACpC;AAAA,QACA,CAAC,SAAS,WAAW,KAAK,KAAK,MAAM,KAAK,YAAY,KAAK,YAAY,KAAK,WAAW;AAAA,MACzF;AAAA,MACA,KAAK,MAAM,gBAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,CAAC,SAAS,WAAW,GAAG,KAAK,IAAI,GAAG;AAAA,QACnF,aAAa,EAAE,cAAc,KAAK;AAAA,MACpC,CAAC;AAAA,MACD;AAAA,QACE;AAAA,QACA;AAAA,QACA,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,EAAE,OAAO,EAAE;AAAA,QACxC,CAAC,SAAS,WAAW,KAAK,KAAK,SAAS,KAAK,IAAI;AAAA,QACjD,EAAE,aAAa,EAAE,cAAc,KAAK,EAAE;AAAA,MACxC;AAAA,IACF;AAAA,EACF,CAAC;AACH;;;ACvFO,SAAS,aAAa,WAAsB,OAA4B,CAAC,GAAY;AAC1F,SAAO;AAAA,IACL,YAAY,EAAE,QAAQ,aAAa,SAAS,EAAE;AAAA,IAC9C,cAAc,CAAC,gBAAgB;AAAA,IAC/B,cAAc,KAAK,gBAAgB,kBAAkB,EAAE,UAAU,CAAC;AAAA,EACpE;AACF;","names":[]}

package/dist/file-version-Clij-pms.d.ts

@@ -0,0 +1,22 @@
+import { Workspace } from '@struktoai/mirage-core';
+
+declare class StaleMirageFileError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+declare class FileVersionTracker {
+    private readonly ws;
+    private readonly enabled;
+    private readonly readVersions;
+    private readonly editVersions;
+    constructor(ws: Workspace, enabled?: boolean);
+    private currentVersion;
+    private assertVersion;
+    private recordWrite;
+    read(path: string): Promise<Buffer>;
+    readForEdit(path: string): Promise<Buffer>;
+    write(path: string, content: string): Promise<void>;
+    writeEdit(path: string, content: string): Promise<void>;
+}
+
+export { FileVersionTracker as F, StaleMirageFileError as S };

package/dist/mcp/index.d.ts

@@ -0,0 +1,14 @@
+import { Workspace } from '@struktoai/mirage-core';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+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, b as MirageToolOperations, R as READ_DESCRIPTION, T as ToolResult, W as WRITE_DESCRIPTION } from '../tool-descriptions-7CgIovZc.js';
+export { F as FileVersionTracker, S as StaleMirageFileError } from '../file-version-Clij-pms.js';
+
+interface MirageMcpServerOptions extends MirageToolOperationsOptions {
+    name?: string;
+    version?: string;
+}
+declare function createMirageMcpServer(workspace: Workspace, options?: MirageMcpServerOptions): McpServer;
+declare function serveMirageMcp(workspace: Workspace, options?: MirageMcpServerOptions): Promise<McpServer>;
+
+export { type MirageMcpServerOptions, MirageToolOperationsOptions, createMirageMcpServer, serveMirageMcp };

package/dist/mcp/index.js

@@ -0,0 +1,100 @@
+import {
+  EDIT_DESCRIPTION,
+  EXECUTE_DESCRIPTION,
+  GREP_DESCRIPTION,
+  LS_DESCRIPTION,
+  MirageToolOperations,
+  READ_DESCRIPTION,
+  WRITE_DESCRIPTION
+} from "../chunk-OLFSAPC6.js";
+import {
+  FileVersionTracker,
+  StaleMirageFileError
+} from "../chunk-XEQB7N3F.js";
+
+// src/mcp/server.ts
+import { VERSION } from "@struktoai/mirage-core";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+function createMirageMcpServer(workspace, options = {}) {
+  const operations = new MirageToolOperations(workspace, options);
+  const server = new McpServer({
+    name: options.name ?? "mirage",
+    version: options.version ?? VERSION
+  });
+  server.registerTool(
+    "execute_command",
+    { description: EXECUTE_DESCRIPTION, inputSchema: { command: z.string() } },
+    (args) => operations.execute(args.command)
+  );
+  server.registerTool(
+    "read",
+    {
+      description: READ_DESCRIPTION,
+      inputSchema: {
+        path: z.string(),
+        offset: z.number().int().min(0).optional(),
+        limit: z.number().int().min(1).optional()
+      },
+      annotations: { readOnlyHint: true }
+    },
+    (args) => operations.read(args.path, args.offset, args.limit)
+  );
+  server.registerTool(
+    "write",
+    { description: WRITE_DESCRIPTION, inputSchema: { path: z.string(), content: z.string() } },
+    (args) => operations.write(args.path, args.content)
+  );
+  server.registerTool(
+    "edit",
+    {
+      description: EDIT_DESCRIPTION,
+      inputSchema: {
+        path: z.string(),
+        old_string: z.string(),
+        new_string: z.string(),
+        replace_all: z.boolean().optional()
+      }
+    },
+    (args) => operations.edit(args.path, args.old_string, args.new_string, args.replace_all)
+  );
+  server.registerTool(
+    "ls",
+    {
+      description: LS_DESCRIPTION,
+      inputSchema: { path: z.string() },
+      annotations: { readOnlyHint: true }
+    },
+    (args) => operations.ls(args.path)
+  );
+  server.registerTool(
+    "grep",
+    {
+      description: GREP_DESCRIPTION,
+      inputSchema: { pattern: z.string(), path: z.string() },
+      annotations: { readOnlyHint: true }
+    },
+    (args) => operations.grep(args.pattern, args.path)
+  );
+  return server;
+}
+async function serveMirageMcp(workspace, options = {}) {
+  const server = createMirageMcpServer(workspace, options);
+  await server.connect(new StdioServerTransport());
+  return server;
+}
+export {
+  EDIT_DESCRIPTION,
+  EXECUTE_DESCRIPTION,
+  FileVersionTracker,
+  GREP_DESCRIPTION,
+  LS_DESCRIPTION,
+  MirageToolOperations,
+  READ_DESCRIPTION,
+  StaleMirageFileError,
+  WRITE_DESCRIPTION,
+  createMirageMcpServer,
+  serveMirageMcp
+};
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/mcp/server.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 { Workspace } from '@struktoai/mirage-core'\nimport { VERSION } from '@struktoai/mirage-core'\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'\nimport { z } from 'zod'\nimport {\n  EDIT_DESCRIPTION,\n  EXECUTE_DESCRIPTION,\n  GREP_DESCRIPTION,\n  LS_DESCRIPTION,\n  READ_DESCRIPTION,\n  WRITE_DESCRIPTION,\n} from '../tool-descriptions.ts'\nimport { MirageToolOperations, type MirageToolOperationsOptions } from '../tool-operations.ts'\n\nexport interface MirageMcpServerOptions extends MirageToolOperationsOptions {\n  name?: string\n  version?: string\n}\n\nexport function createMirageMcpServer(\n  workspace: Workspace,\n  options: MirageMcpServerOptions = {},\n): McpServer {\n  const operations = new MirageToolOperations(workspace, options)\n  const server = new McpServer({\n    name: options.name ?? 'mirage',\n    version: options.version ?? VERSION,\n  })\n\n  server.registerTool(\n    'execute_command',\n    { description: EXECUTE_DESCRIPTION, inputSchema: { command: z.string() } },\n    (args) => operations.execute(args.command),\n  )\n  server.registerTool(\n    'read',\n    {\n      description: READ_DESCRIPTION,\n      inputSchema: {\n        path: z.string(),\n        offset: z.number().int().min(0).optional(),\n        limit: z.number().int().min(1).optional(),\n      },\n      annotations: { readOnlyHint: true },\n    },\n    (args) => operations.read(args.path, args.offset, args.limit),\n  )\n  server.registerTool(\n    'write',\n    { description: WRITE_DESCRIPTION, inputSchema: { path: z.string(), content: z.string() } },\n    (args) => operations.write(args.path, args.content),\n  )\n  server.registerTool(\n    'edit',\n    {\n      description: EDIT_DESCRIPTION,\n      inputSchema: {\n        path: z.string(),\n        old_string: z.string(),\n        new_string: z.string(),\n        replace_all: z.boolean().optional(),\n      },\n    },\n    (args) => operations.edit(args.path, args.old_string, args.new_string, args.replace_all),\n  )\n  server.registerTool(\n    'ls',\n    {\n      description: LS_DESCRIPTION,\n      inputSchema: { path: z.string() },\n      annotations: { readOnlyHint: true },\n    },\n    (args) => operations.ls(args.path),\n  )\n  server.registerTool(\n    'grep',\n    {\n      description: GREP_DESCRIPTION,\n      inputSchema: { pattern: z.string(), path: z.string() },\n      annotations: { readOnlyHint: true },\n    },\n    (args) => operations.grep(args.pattern, args.path),\n  )\n\n  return server\n}\n\nexport async function serveMirageMcp(\n  workspace: Workspace,\n  options: MirageMcpServerOptions = {},\n): Promise<McpServer> {\n  const server = createMirageMcpServer(workspace, options)\n  await server.connect(new StdioServerTransport())\n  return server\n}\n"],"mappings":";;;;;;;;;;;;;;;AAeA,SAAS,eAAe;AACxB,SAAS,iBAAiB;AAC1B,SAAS,4BAA4B;AACrC,SAAS,SAAS;AAgBX,SAAS,sBACd,WACA,UAAkC,CAAC,GACxB;AACX,QAAM,aAAa,IAAI,qBAAqB,WAAW,OAAO;AAC9D,QAAM,SAAS,IAAI,UAAU;AAAA,IAC3B,MAAM,QAAQ,QAAQ;AAAA,IACtB,SAAS,QAAQ,WAAW;AAAA,EAC9B,CAAC;AAED,SAAO;AAAA,IACL;AAAA,IACA,EAAE,aAAa,qBAAqB,aAAa,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE;AAAA,IACzE,CAAC,SAAS,WAAW,QAAQ,KAAK,OAAO;AAAA,EAC3C;AACA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,MACE,aAAa;AAAA,MACb,aAAa;AAAA,QACX,MAAM,EAAE,OAAO;AAAA,QACf,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,SAAS;AAAA,QACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,SAAS;AAAA,MAC1C;AAAA,MACA,aAAa,EAAE,cAAc,KAAK;AAAA,IACpC;AAAA,IACA,CAAC,SAAS,WAAW,KAAK,KAAK,MAAM,KAAK,QAAQ,KAAK,KAAK;AAAA,EAC9D;AACA,SAAO;AAAA,IACL;AAAA,IACA,EAAE,aAAa,mBAAmB,aAAa,EAAE,MAAM,EAAE,OAAO,GAAG,SAAS,EAAE,OAAO,EAAE,EAAE;AAAA,IACzF,CAAC,SAAS,WAAW,MAAM,KAAK,MAAM,KAAK,OAAO;AAAA,EACpD;AACA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,MACE,aAAa;AAAA,MACb,aAAa;AAAA,QACX,MAAM,EAAE,OAAO;AAAA,QACf,YAAY,EAAE,OAAO;AAAA,QACrB,YAAY,EAAE,OAAO;AAAA,QACrB,aAAa,EAAE,QAAQ,EAAE,SAAS;AAAA,MACpC;AAAA,IACF;AAAA,IACA,CAAC,SAAS,WAAW,KAAK,KAAK,MAAM,KAAK,YAAY,KAAK,YAAY,KAAK,WAAW;AAAA,EACzF;AACA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,MACE,aAAa;AAAA,MACb,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE;AAAA,MAChC,aAAa,EAAE,cAAc,KAAK;AAAA,IACpC;AAAA,IACA,CAAC,SAAS,WAAW,GAAG,KAAK,IAAI;AAAA,EACnC;AACA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,MACE,aAAa;AAAA,MACb,aAAa,EAAE,SAAS,EAAE,OAAO,GAAG,MAAM,EAAE,OAAO,EAAE;AAAA,MACrD,aAAa,EAAE,cAAc,KAAK;AAAA,IACpC;AAAA,IACA,CAAC,SAAS,WAAW,KAAK,KAAK,SAAS,KAAK,IAAI;AAAA,EACnD;AAEA,SAAO;AACT;AAEA,eAAsB,eACpB,WACA,UAAkC,CAAC,GACf;AACpB,QAAM,SAAS,sBAAsB,WAAW,OAAO;AACvD,QAAM,OAAO,QAAQ,IAAI,qBAAqB,CAAC;AAC/C,SAAO;AACT;","names":[]}

package/dist/openai/index.d.ts

@@ -1,5 +1,7 @@
 import { Workspace } from '@struktoai/mirage-core';
-import { Editor, ApplyPatchOperation, ApplyPatchResult, Shell, ShellAction, ShellResult } from '@openai/agents';
+import * as _openai_agents from '@openai/agents';
+import { Editor, ApplyPatchOperation, ApplyPatchResult, ToolOutputText, ToolOutputImage, ToolOutputFileContent, Shell, ShellAction, ShellResult } from '@openai/agents';
+import { z } from 'zod';
 export { B as BuildSystemPromptOptions, M as MIRAGE_SYSTEM_PROMPT, b as buildSystemPrompt } from '../prompt-Ca4hc1Ul.js';
 
 declare class MirageEditor implements Editor {
@@ -16,10 +18,19 @@ declare class MirageEditor implements Editor {
     }>): Promise<ApplyPatchResult>;
 }
 
+declare function mirageExecuteTool(ws: Workspace): _openai_agents.FunctionTool<unknown, z.ZodObject<{
+    command: z.ZodString;
+}, z.core.$strip>, string>;
+
+type MirageReadFileOutput = ToolOutputText | ToolOutputImage | ToolOutputFileContent;
+declare function mirageReadFileTool(ws: Workspace): _openai_agents.FunctionTool<unknown, z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strip>, string>;
+
 declare class MirageShell implements Shell {
     private readonly ws;
     constructor(ws: Workspace);
     run(action: ShellAction): Promise<ShellResult>;
 }
 
-export { MirageEditor, MirageShell };
+export { MirageEditor, type MirageReadFileOutput, MirageShell, mirageExecuteTool, mirageReadFileTool };

package/dist/openai/index.js

@@ -2,6 +2,9 @@ import {
   MIRAGE_SYSTEM_PROMPT,
   buildSystemPrompt
 } from "../chunk-ODKR5YZI.js";
+import {
+  readWorkspaceFile
+} from "../chunk-IMI7BLEG.js";
 
 // src/openai/editor.ts
 import { applyDiff } from "@openai/agents";
@@ -48,6 +51,81 @@ var MirageEditor = class {
   }
 };
 
+// src/openai/execute.ts
+import { tool } from "@openai/agents";
+import { z } from "zod";
+function formatExecuteOutput(stdout, stderr, exitCode) {
+  const sections = [`exit code: ${String(exitCode)}`];
+  if (stdout !== "") sections.push(`stdout:
+${stdout}`);
+  if (stderr !== "") sections.push(`stderr:
+${stderr}`);
+  return sections.join("\n");
+}
+async function executeOutput(ws, command) {
+  try {
+    const result = await ws.execute(command);
+    return formatExecuteOutput(result.stdoutText, result.stderrText, result.exitCode);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return `Unable to execute command: ${message}`;
+  }
+}
+function mirageExecuteTool(ws) {
+  return tool({
+    name: "execute",
+    description: "Execute a shell command inside the Mirage workspace and return its stdout, stderr, and exit code.",
+    parameters: z.object({
+      command: z.string().describe("Shell command to execute inside the Mirage workspace.")
+    }),
+    execute: async ({ command }) => executeOutput(ws, command)
+  });
+}
+
+// src/openai/read-file.ts
+import {
+  tool as tool2
+} from "@openai/agents";
+import { z as z2 } from "zod";
+async function readFileOutput(ws, path) {
+  try {
+    const result = await readWorkspaceFile(ws, path);
+    if (result.kind === "text") {
+      return { type: "text", text: result.content };
+    }
+    if (result.kind === "image") {
+      return {
+        type: "image",
+        image: { data: Uint8Array.from(result.data), mediaType: result.mimeType }
+      };
+    }
+    if (result.kind === "file") {
+      return {
+        type: "file",
+        file: {
+          data: Uint8Array.from(result.data),
+          mediaType: result.mimeType,
+          filename: result.filename
+        }
+      };
+    }
+    return { type: "text", text: result.note };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { type: "text", text: `Unable to read ${path}: ${message}` };
+  }
+}
+function mirageReadFileTool(ws) {
+  return tool2({
+    name: "read_file",
+    description: "Read a file from the Mirage workspace. Returns UTF-8 text directly, images as model-visible image input, PDFs as model-visible file input, and a metadata description for other binary formats.",
+    parameters: z2.object({
+      path: z2.string().describe("Absolute path inside the Mirage workspace.")
+    }),
+    execute: async ({ path }) => readFileOutput(ws, path)
+  });
+}
+
 // src/openai/shell.ts
 var MirageShell = class {
   constructor(ws) {
@@ -71,6 +149,8 @@ export {
   MIRAGE_SYSTEM_PROMPT,
   MirageEditor,
   MirageShell,
-  buildSystemPrompt
+  buildSystemPrompt,
+  mirageExecuteTool,
+  mirageReadFileTool
 };
 //# sourceMappingURL=index.js.map

package/dist/openai/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/openai/editor.ts","../../src/openai/shell.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 { Workspace } from '@struktoai/mirage-core'\nimport { applyDiff } from '@openai/agents'\nimport type { ApplyPatchOperation, ApplyPatchResult, Editor } from '@openai/agents'\nimport { gnuDirname } from '@struktoai/mirage-core'\n\nasync function ensureParent(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 ensureParent(ws, parent)\n  try {\n    await ws.fs.mkdir(parent)\n  } catch (err) {\n    // Tolerate mkdir race: another caller may have created the dir between exists() and mkdir().\n    if (!(await ws.fs.exists(parent))) throw err\n  }\n}\n\nexport class MirageEditor implements Editor {\n  constructor(private readonly ws: Workspace) {}\n\n  async createFile(\n    op: Extract<ApplyPatchOperation, { type: 'create_file' }>,\n  ): Promise<ApplyPatchResult> {\n    await ensureParent(this.ws, op.path)\n    const content = applyDiff('', op.diff, 'create')\n    await this.ws.fs.writeFile(op.path, content)\n    return { status: 'completed' }\n  }\n\n  async updateFile(\n    op: Extract<ApplyPatchOperation, { type: 'update_file' }>,\n  ): Promise<ApplyPatchResult> {\n    let current: string\n    try {\n      current = await this.ws.fs.readFileText(op.path)\n    } catch {\n      return { status: 'failed', output: `File not found: ${op.path}` }\n    }\n    const next = applyDiff(current, op.diff)\n    await this.ws.fs.writeFile(op.path, next)\n    return { status: 'completed' }\n  }\n\n  async deleteFile(\n    op: Extract<ApplyPatchOperation, { type: 'delete_file' }>,\n  ): Promise<ApplyPatchResult> {\n    if (!(await this.ws.fs.exists(op.path))) {\n      return { status: 'failed', output: `File not found: ${op.path}` }\n    }\n    await this.ws.fs.unlink(op.path)\n    return { status: 'completed' }\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 { Workspace } from '@struktoai/mirage-core'\nimport type { Shell, ShellAction, ShellResult, ShellOutputResult } from '@openai/agents'\n\nexport class MirageShell implements Shell {\n  constructor(private readonly ws: Workspace) {}\n\n  async run(action: ShellAction): Promise<ShellResult> {\n    const output: ShellOutputResult[] = []\n    for (const cmd of action.commands) {\n      const io = await this.ws.execute(cmd)\n      output.push({\n        stdout: io.stdoutText,\n        stderr: io.stderrText,\n        outcome: { type: 'exit', exitCode: io.exitCode },\n      })\n    }\n    return { output }\n  }\n}\n"],"mappings":";;;;;;AAeA,SAAS,iBAAiB;AAE1B,SAAS,kBAAkB;AAE3B,eAAe,aAAa,IAAe,MAA6B;AACtE,QAAM,SAAS,WAAW,IAAI;AAC9B,MAAI,WAAW,OAAO,WAAW,MAAM,WAAW,IAAK;AACvD,MAAI,MAAM,GAAG,GAAG,OAAO,MAAM,EAAG;AAChC,QAAM,aAAa,IAAI,MAAM;AAC7B,MAAI;AACF,UAAM,GAAG,GAAG,MAAM,MAAM;AAAA,EAC1B,SAAS,KAAK;AAEZ,QAAI,CAAE,MAAM,GAAG,GAAG,OAAO,MAAM,EAAI,OAAM;AAAA,EAC3C;AACF;AAEO,IAAM,eAAN,MAAqC;AAAA,EAC1C,YAA6B,IAAe;AAAf;AAAA,EAAgB;AAAA,EAAhB;AAAA,EAE7B,MAAM,WACJ,IAC2B;AAC3B,UAAM,aAAa,KAAK,IAAI,GAAG,IAAI;AACnC,UAAM,UAAU,UAAU,IAAI,GAAG,MAAM,QAAQ;AAC/C,UAAM,KAAK,GAAG,GAAG,UAAU,GAAG,MAAM,OAAO;AAC3C,WAAO,EAAE,QAAQ,YAAY;AAAA,EAC/B;AAAA,EAEA,MAAM,WACJ,IAC2B;AAC3B,QAAI;AACJ,QAAI;AACF,gBAAU,MAAM,KAAK,GAAG,GAAG,aAAa,GAAG,IAAI;AAAA,IACjD,QAAQ;AACN,aAAO,EAAE,QAAQ,UAAU,QAAQ,mBAAmB,GAAG,IAAI,GAAG;AAAA,IAClE;AACA,UAAM,OAAO,UAAU,SAAS,GAAG,IAAI;AACvC,UAAM,KAAK,GAAG,GAAG,UAAU,GAAG,MAAM,IAAI;AACxC,WAAO,EAAE,QAAQ,YAAY;AAAA,EAC/B;AAAA,EAEA,MAAM,WACJ,IAC2B;AAC3B,QAAI,CAAE,MAAM,KAAK,GAAG,GAAG,OAAO,GAAG,IAAI,GAAI;AACvC,aAAO,EAAE,QAAQ,UAAU,QAAQ,mBAAmB,GAAG,IAAI,GAAG;AAAA,IAClE;AACA,UAAM,KAAK,GAAG,GAAG,OAAO,GAAG,IAAI;AAC/B,WAAO,EAAE,QAAQ,YAAY;AAAA,EAC/B;AACF;;;AClDO,IAAM,cAAN,MAAmC;AAAA,EACxC,YAA6B,IAAe;AAAf;AAAA,EAAgB;AAAA,EAAhB;AAAA,EAE7B,MAAM,IAAI,QAA2C;AACnD,UAAM,SAA8B,CAAC;AACrC,eAAW,OAAO,OAAO,UAAU;AACjC,YAAM,KAAK,MAAM,KAAK,GAAG,QAAQ,GAAG;AACpC,aAAO,KAAK;AAAA,QACV,QAAQ,GAAG;AAAA,QACX,QAAQ,GAAG;AAAA,QACX,SAAS,EAAE,MAAM,QAAQ,UAAU,GAAG,SAAS;AAAA,MACjD,CAAC;AAAA,IACH;AACA,WAAO,EAAE,OAAO;AAAA,EAClB;AACF;","names":[]}
+{"version":3,"sources":["../../src/openai/editor.ts","../../src/openai/execute.ts","../../src/openai/read-file.ts","../../src/openai/shell.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 { Workspace } from '@struktoai/mirage-core'\nimport { applyDiff } from '@openai/agents'\nimport type { ApplyPatchOperation, ApplyPatchResult, Editor } from '@openai/agents'\nimport { gnuDirname } from '@struktoai/mirage-core'\n\nasync function ensureParent(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 ensureParent(ws, parent)\n  try {\n    await ws.fs.mkdir(parent)\n  } catch (err) {\n    // Tolerate mkdir race: another caller may have created the dir between exists() and mkdir().\n    if (!(await ws.fs.exists(parent))) throw err\n  }\n}\n\nexport class MirageEditor implements Editor {\n  constructor(private readonly ws: Workspace) {}\n\n  async createFile(\n    op: Extract<ApplyPatchOperation, { type: 'create_file' }>,\n  ): Promise<ApplyPatchResult> {\n    await ensureParent(this.ws, op.path)\n    const content = applyDiff('', op.diff, 'create')\n    await this.ws.fs.writeFile(op.path, content)\n    return { status: 'completed' }\n  }\n\n  async updateFile(\n    op: Extract<ApplyPatchOperation, { type: 'update_file' }>,\n  ): Promise<ApplyPatchResult> {\n    let current: string\n    try {\n      current = await this.ws.fs.readFileText(op.path)\n    } catch {\n      return { status: 'failed', output: `File not found: ${op.path}` }\n    }\n    const next = applyDiff(current, op.diff)\n    await this.ws.fs.writeFile(op.path, next)\n    return { status: 'completed' }\n  }\n\n  async deleteFile(\n    op: Extract<ApplyPatchOperation, { type: 'delete_file' }>,\n  ): Promise<ApplyPatchResult> {\n    if (!(await this.ws.fs.exists(op.path))) {\n      return { status: 'failed', output: `File not found: ${op.path}` }\n    }\n    await this.ws.fs.unlink(op.path)\n    return { status: 'completed' }\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 { Workspace } from '@struktoai/mirage-core'\nimport { tool } from '@openai/agents'\nimport { z } from 'zod'\n\nfunction formatExecuteOutput(stdout: string, stderr: string, exitCode: number): string {\n  const sections = [`exit code: ${String(exitCode)}`]\n  if (stdout !== '') sections.push(`stdout:\\n${stdout}`)\n  if (stderr !== '') sections.push(`stderr:\\n${stderr}`)\n  return sections.join('\\n')\n}\n\nasync function executeOutput(ws: Workspace, command: string): Promise<string> {\n  try {\n    const result = await ws.execute(command)\n    return formatExecuteOutput(result.stdoutText, result.stderrText, result.exitCode)\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error)\n    return `Unable to execute command: ${message}`\n  }\n}\n\nexport function mirageExecuteTool(ws: Workspace) {\n  return tool({\n    name: 'execute',\n    description:\n      'Execute a shell command inside the Mirage workspace and return its stdout, stderr, and exit code.',\n    parameters: z.object({\n      command: z.string().describe('Shell command to execute inside the Mirage workspace.'),\n    }),\n    execute: async ({ command }) => executeOutput(ws, command),\n  })\n}\n","import type { Workspace } from '@struktoai/mirage-core'\nimport {\n  tool,\n  type ToolOutputFileContent,\n  type ToolOutputImage,\n  type ToolOutputText,\n} from '@openai/agents'\nimport { z } from 'zod'\nimport { readWorkspaceFile } from '../read-file.ts'\n\nexport type MirageReadFileOutput = ToolOutputText | ToolOutputImage | ToolOutputFileContent\n\nasync function readFileOutput(ws: Workspace, path: string): Promise<MirageReadFileOutput> {\n  try {\n    const result = await readWorkspaceFile(ws, path)\n    if (result.kind === 'text') {\n      return { type: 'text', text: result.content }\n    }\n    if (result.kind === 'image') {\n      return {\n        type: 'image',\n        image: { data: Uint8Array.from(result.data), mediaType: result.mimeType },\n      }\n    }\n    if (result.kind === 'file') {\n      return {\n        type: 'file',\n        file: {\n          data: Uint8Array.from(result.data),\n          mediaType: result.mimeType,\n          filename: result.filename,\n        },\n      }\n    }\n    return { type: 'text', text: result.note }\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error)\n    return { type: 'text', text: `Unable to read ${path}: ${message}` }\n  }\n}\n\nexport function mirageReadFileTool(ws: Workspace) {\n  return tool({\n    name: 'read_file',\n    description:\n      'Read a file from the Mirage workspace. Returns UTF-8 text directly, images as model-visible image input, PDFs as model-visible file input, and a metadata description for other binary formats.',\n    parameters: z.object({\n      path: z.string().describe('Absolute path inside the Mirage workspace.'),\n    }),\n    execute: async ({ path }) => readFileOutput(ws, path),\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 { Workspace } from '@struktoai/mirage-core'\nimport type { Shell, ShellAction, ShellResult, ShellOutputResult } from '@openai/agents'\n\nexport class MirageShell implements Shell {\n  constructor(private readonly ws: Workspace) {}\n\n  async run(action: ShellAction): Promise<ShellResult> {\n    const output: ShellOutputResult[] = []\n    for (const cmd of action.commands) {\n      const io = await this.ws.execute(cmd)\n      output.push({\n        stdout: io.stdoutText,\n        stderr: io.stderrText,\n        outcome: { type: 'exit', exitCode: io.exitCode },\n      })\n    }\n    return { output }\n  }\n}\n"],"mappings":"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","names":["tool","z","tool","z"]}

package/dist/opencode/index.d.ts

@@ -1,24 +1,14 @@
+import { ToolContext, Plugin, ToolDefinition } from '@opencode-ai/plugin';
 import { Workspace } from '@struktoai/mirage-node';
-import { z } from 'zod';
+export { S as StaleMirageFileError } from '../file-version-Clij-pms.js';
+import '@struktoai/mirage-core';
 
-interface ToolContext {
-    sessionID: string;
-    messageID: string;
-    agent: string;
-    abort: AbortSignal;
-}
 type WsResolver = (ctx: ToolContext) => Workspace | Promise<Workspace>;
 type WsLike = Workspace | WsResolver;
-interface ToolDefinition<Args extends z.ZodRawShape = z.ZodRawShape> {
-    description: string;
-    args: Args;
-    execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext): Promise<string>;
-}
-declare function mirageTools(ws: WsLike): Record<string, ToolDefinition>;
-interface Hooks {
-    tool?: Record<string, ToolDefinition>;
+interface MirageOpenCodeOptions {
+    staleWriteProtection?: boolean;
 }
-type PluginFn = (input: unknown) => Promise<Hooks>;
-declare function miragePlugin(ws: WsLike): PluginFn;
+declare function mirageTools(ws: WsLike, options?: MirageOpenCodeOptions): Record<string, ToolDefinition>;
+declare function miragePlugin(ws: WsLike, options?: MirageOpenCodeOptions): Plugin;
 
-export { type ToolContext, type WsLike, type WsResolver, miragePlugin, mirageTools };
+export { type MirageOpenCodeOptions, type WsLike, type WsResolver, miragePlugin, mirageTools };

package/dist/opencode/index.js

@@ -1,9 +1,15 @@
+import {
+  readWorkspaceFile
+} from "../chunk-IMI7BLEG.js";
+import {
+  FileVersionTracker,
+  StaleMirageFileError
+} from "../chunk-XEQB7N3F.js";
+
 // src/opencode/index.ts
-import { z } from "zod";
-import { gnuDirname } from "@struktoai/mirage-core";
-function tool(input) {
-  return input;
-}
+import { tool } from "@opencode-ai/plugin";
+import { encodeBase64, gnuDirname } from "@struktoai/mirage-core";
+var z = tool.schema;
 function isResolver(ws) {
   return typeof ws === "function";
 }
@@ -21,73 +27,54 @@ async function ensureParent(ws, path) {
     if (!await ws.fs.exists(parent)) throw err;
   }
 }
-var TEXT_EXTS = /* @__PURE__ */ new Set([
-  "txt",
-  "md",
-  "json",
-  "jsonl",
-  "yaml",
-  "yml",
-  "csv",
-  "tsv",
-  "xml",
-  "html",
-  "htm",
-  "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"
-]);
-function extOf(path) {
-  const dot = path.lastIndexOf(".");
-  if (dot < 0) return "";
-  return path.slice(dot + 1).toLowerCase();
-}
-function isLikelyText(path) {
-  return TEXT_EXTS.has(extOf(path));
-}
 function errMsg(err) {
   return err instanceof Error ? err.message : String(err);
 }
-function mirageTools(ws) {
+function trackerFor(trackers, ws, ctx, enabled) {
+  let sessions = trackers.get(ws);
+  if (sessions === void 0) {
+    sessions = /* @__PURE__ */ new Map();
+    trackers.set(ws, sessions);
+  }
+  let tracker = sessions.get(ctx.sessionID);
+  if (tracker === void 0) {
+    tracker = new FileVersionTracker(ws, enabled);
+    sessions.set(ctx.sessionID, tracker);
+  }
+  return tracker;
+}
+function mirageTools(ws, options = {}) {
+  const trackers = /* @__PURE__ */ new WeakMap();
+  const staleWriteProtection = options.staleWriteProtection ?? true;
   const read = tool({
-    description: "Read a file. Returns UTF-8 text for source/data files; for binary files returns a metadata stub. Use the bash tool to inspect binaries.",
+    description: "Read a file. Returns UTF-8 text for source/data files, attaches PDFs and images for multimodal models, and returns metadata for other binary files.",
     args: {
       filePath: z.string().describe("Absolute path of the file to read.")
     },
     execute: async ({ filePath }, ctx) => {
       const w = await resolveWs(ws, ctx);
-      let bytes;
+      const versions = trackerFor(trackers, w, ctx, staleWriteProtection);
       try {
-        bytes = await w.fs.readFile(filePath);
+        const result = await readWorkspaceFile(w, filePath, versions.read.bind(versions));
+        if (result.kind === "text") return result.content;
+        if (result.kind === "image" || result.kind === "file") {
+          const filename = result.path.split("/").pop() ?? result.path;
+          return {
+            output: `${result.path} (${result.mimeType}, ${String(result.bytes)} bytes)`,
+            attachments: [
+              {
+                type: "file",
+                mime: result.mimeType,
+                url: `data:${result.mimeType};base64,${encodeBase64(result.data)}`,
+                filename
+              }
+            ]
+          };
+        }
+        return result.note;
       } catch (err) {
         return `Error: ${errMsg(err)}`;
       }
-      if (isLikelyText(filePath)) {
-        return new TextDecoder("utf-8", { fatal: false }).decode(bytes);
-      }
-      return `Binary file ${filePath} (${String(bytes.length)} bytes). Use the bash tool with head/file/wc/od to inspect.`;
     }
   });
   const write = tool({
@@ -98,9 +85,14 @@ function mirageTools(ws) {
     },
     execute: async ({ filePath, content }, ctx) => {
       const w = await resolveWs(ws, ctx);
-      await ensureParent(w, filePath);
-      await w.fs.writeFile(filePath, content);
-      return `Wrote ${String(content.length)} bytes to ${filePath}`;
+      const versions = trackerFor(trackers, w, ctx, staleWriteProtection);
+      try {
+        await ensureParent(w, filePath);
+        await versions.write(filePath, content);
+        return `Wrote ${String(content.length)} bytes to ${filePath}`;
+      } catch (err) {
+        return `Error: ${errMsg(err)}`;
+      }
     }
   });
   const edit = tool({
@@ -113,10 +105,12 @@ function mirageTools(ws) {
     },
     execute: async ({ filePath, oldString, newString, replaceAll }, ctx) => {
       const w = await resolveWs(ws, ctx);
+      const versions = trackerFor(trackers, w, ctx, staleWriteProtection);
       let current;
       try {
-        current = await w.fs.readFileText(filePath);
-      } catch {
+        current = (await versions.readForEdit(filePath)).toString("utf8");
+      } catch (err) {
+        if (await w.fs.exists(filePath)) return `Error: ${errMsg(err)}`;
         return `Error: file '${filePath}' not found`;
       }
       const count = current.split(oldString).length - 1;
@@ -127,7 +121,11 @@ function mirageTools(ws) {
         return `Error: string '${oldString}' appears ${String(count)} times. Use replaceAll=true`;
       }
       const next = replaceAll === true ? current.split(oldString).join(newString) : current.replace(oldString, newString);
-      await w.fs.writeFile(filePath, next);
+      try {
+        await versions.writeEdit(filePath, next);
+      } catch (err) {
+        return `Error: ${errMsg(err)}`;
+      }
       const occurrences = replaceAll === true ? count : 1;
       return `Edited ${filePath} (${String(occurrences)} occurrence${occurrences === 1 ? "" : "s"})`;
     }
@@ -196,10 +194,11 @@ function mirageTools(ws) {
   });
   return { read, write, edit, ls, bash, glob, grep };
 }
-function miragePlugin(ws) {
-  return () => Promise.resolve({ tool: mirageTools(ws) });
+function miragePlugin(ws, options = {}) {
+  return () => Promise.resolve({ tool: mirageTools(ws, options) });
 }
 export {
+  StaleMirageFileError,
   miragePlugin,
   mirageTools
 };