@mastra/core 1.2.1-alpha.0 → 1.3.0-alpha.2

package/dist/{chunk-ENCTSDWC.js → chunk-2GWTJFVM.js}

@@ -1,13 +1,14 @@
-import { createTool } from './chunk-IW3BNL7A.js';
-import { MastraBase } from './chunk-JIT2OY3X.js';
+import { createTool } from './chunk-RS6CZXGA.js';
+import { MastraBase } from './chunk-WCAFTXGK.js';
 import { RegisteredLogger } from './chunk-X2WMFSPB.js';
+import { constants } from 'fs';
 import * as fs2 from 'fs/promises';
 import * as nodePath from 'path';
-import { constants } from 'fs';
+import * as crypto from 'crypto';
+import { createHash } from 'crypto';
 import matter from 'gray-matter';
 import * as childProcess from 'child_process';
 import { execFileSync } from 'child_process';
-import * as crypto from 'crypto';
 import * as os from 'os';
 import os__default from 'os';
 import { z } from 'zod';
@@ -114,1495 +115,2521 @@ var FileReadRequiredError = class extends FilesystemError {
     this.name = "FileReadRequiredError";
   }
 };
-
-// src/workspace/filesystem/mastra-filesystem.ts
-var MastraFilesystem = class extends MastraBase {
-  constructor(options) {
-    super({ name: options.name, component: RegisteredLogger.WORKSPACE });
-  }
-};
-
-// src/workspace/sandbox/mastra-sandbox.ts
-var MastraSandbox = class extends MastraBase {
-  constructor(options) {
-    super({ name: options.name, component: RegisteredLogger.WORKSPACE });
+var FilesystemNotReadyError = class extends FilesystemError {
+  constructor(id) {
+    super(`Filesystem "${id}" is not ready. Call init() first or use ensureReady().`, "ENOTREADY", id);
+    this.name = "FilesystemNotReadyError";
   }
 };
 
-// src/workspace/line-utils.ts
-function extractLines(content, startLine, endLine) {
-  const allLines = content.split("\n");
-  const totalLines = allLines.length;
-  const start = Math.max(1, startLine ?? 1);
-  const end = Math.min(totalLines, endLine ?? totalLines);
-  const extractedLines = allLines.slice(start - 1, end);
-  return {
-    content: extractedLines.join("\n"),
-    lines: { start, end },
-    totalLines
-  };
-}
-function extractLinesWithLimit(content, offset, limit) {
-  const startLine = offset ?? 1;
-  const endLine = limit ? startLine + limit - 1 : void 0;
-  return extractLines(content, startLine, endLine);
-}
-function formatWithLineNumbers(content, startLineNumber = 1) {
-  const lines = content.split("\n");
-  const maxLineNum = startLineNumber + lines.length - 1;
-  const padWidth = Math.max(6, String(maxLineNum).length + 1);
-  return lines.map((line, i) => {
-    const lineNum = startLineNumber + i;
-    return `${String(lineNum).padStart(padWidth)}\u2192${line}`;
-  }).join("\n");
-}
-function countOccurrences(content, searchString) {
-  if (!searchString) return 0;
-  let count = 0;
-  let position = 0;
-  while ((position = content.indexOf(searchString, position)) !== -1) {
-    count++;
-    position += searchString.length;
-  }
-  return count;
-}
-function replaceString(content, oldString, newString, replaceAll = false) {
-  const count = countOccurrences(content, oldString);
-  if (count === 0) {
-    throw new StringNotFoundError(oldString);
-  }
-  if (!replaceAll && count > 1) {
-    throw new StringNotUniqueError(oldString, count);
-  }
-  if (replaceAll) {
-    const result = content.split(oldString).join(newString);
-    return { content: result, replacements: count };
+// src/workspace/lifecycle.ts
+async function callLifecycle(provider, method) {
+  const wrapped = `_${method}`;
+  const wrappedFn = provider[wrapped];
+  if (typeof wrappedFn === "function") {
+    await wrappedFn.call(provider);
   } else {
-    const result = content.replace(oldString, newString);
-    return { content: result, replacements: 1 };
+    const plainFn = provider[method];
+    if (typeof plainFn === "function") {
+      await plainFn.call(provider);
+    }
   }
 }
-var StringNotFoundError = class extends Error {
-  constructor(searchString) {
-    super(`The specified text was not found. Make sure you use the exact text from the file.`);
-    this.searchString = searchString;
-    this.name = "StringNotFoundError";
-  }
-};
-var StringNotUniqueError = class extends Error {
-  constructor(searchString, occurrences) {
-    super(
-      `The specified text appears ${occurrences} times. Provide more surrounding context to make the match unique, or use replace_all to replace all occurrences.`
-    );
-    this.searchString = searchString;
-    this.occurrences = occurrences;
-    this.name = "StringNotUniqueError";
-  }
-};
 
-// src/workspace/search/bm25.ts
-var DEFAULT_STOPWORDS = /* @__PURE__ */ new Set([
-  "a",
-  "an",
-  "and",
-  "are",
-  "as",
-  "at",
-  "be",
-  "by",
-  "for",
-  "from",
-  "has",
-  "he",
-  "in",
-  "is",
-  "it",
-  "its",
-  "of",
-  "on",
-  "or",
-  "that",
-  "the",
-  "to",
-  "was",
-  "were",
-  "will",
-  "with"
-]);
-var DEFAULT_TOKENIZE_OPTIONS = {
-  lowercase: true,
-  removePunctuation: true,
-  minLength: 2,
-  stopwords: DEFAULT_STOPWORDS,
-  splitPattern: /\s+/
-};
-function tokenize(text, options = {}) {
-  const opts = { ...DEFAULT_TOKENIZE_OPTIONS, ...options };
-  let processed = text;
-  if (opts.lowercase) {
-    processed = processed.toLowerCase();
-  }
-  if (opts.removePunctuation) {
-    processed = processed.replace(/[^\w\s]/g, " ");
-  }
-  const tokens = processed.split(opts.splitPattern).filter((token) => {
-    if (token.length < opts.minLength) {
-      return false;
-    }
-    if (opts.stopwords?.has(token)) {
-      return false;
-    }
-    return true;
-  });
-  return tokens;
-}
-function findLineRange(content, queryTerms, options = {}) {
-  if (queryTerms.length === 0) return void 0;
-  const lines = content.split("\n");
-  const defaultOpts = { lowercase: true, removePunctuation: true, minLength: 2 };
-  const opts = { ...defaultOpts, ...options };
-  const normalizedTerms = new Set(queryTerms.map((t) => opts.lowercase ? t.toLowerCase() : t));
-  let firstMatchLine;
-  let lastMatchLine;
-  for (let i = 0; i < lines.length; i++) {
-    const lineTokens = tokenize(lines[i], options);
-    for (const token of lineTokens) {
-      if (normalizedTerms.has(token)) {
-        const lineNum = i + 1;
-        if (firstMatchLine === void 0) {
-          firstMatchLine = lineNum;
+// src/workspace/filesystem/composite-filesystem.ts
+var CompositeFilesystem = class {
+  id;
+  name = "CompositeFilesystem";
+  provider = "composite";
+  status = "ready";
+  _mounts;
+  constructor(config) {
+    this.id = `cfs-${Date.now().toString(36)}`;
+    this._mounts = /* @__PURE__ */ new Map();
+    for (const [path4, fs5] of Object.entries(config.mounts)) {
+      const normalized = this.normalizePath(path4);
+      this._mounts.set(normalized, fs5);
+    }
+    if (this._mounts.size === 0) {
+      throw new Error("CompositeFilesystem requires at least one mount");
+    }
+    const mountPaths = [...this._mounts.keys()];
+    for (const a of mountPaths) {
+      for (const b of mountPaths) {
+        if (a !== b && b.startsWith(a + "/")) {
+          throw new Error(`Nested mount paths are not supported: "${b}" is nested under "${a}"`);
         }
-        lastMatchLine = lineNum;
-        break;
       }
     }
   }
-  if (firstMatchLine !== void 0 && lastMatchLine !== void 0) {
-    return { start: firstMatchLine, end: lastMatchLine };
-  }
-  return void 0;
-}
-function computeTermFrequencies(tokens) {
-  const frequencies = /* @__PURE__ */ new Map();
-  for (const token of tokens) {
-    frequencies.set(token, (frequencies.get(token) || 0) + 1);
+  /**
+   * Get all mount paths.
+   */
+  get mountPaths() {
+    return Array.from(this._mounts.keys());
   }
-  return frequencies;
-}
-var BM25Index = class _BM25Index {
-  /** BM25 k1 parameter */
-  k1;
-  /** BM25 b parameter */
-  b;
-  /** Documents in the index */
-  #documents = /* @__PURE__ */ new Map();
-  /** Inverted index: term -> document IDs containing the term */
-  #invertedIndex = /* @__PURE__ */ new Map();
-  /** Document frequency: term -> number of documents containing the term */
-  #documentFrequency = /* @__PURE__ */ new Map();
-  /** Average document length */
-  #avgDocLength = 0;
-  /** Total number of documents */
-  #docCount = 0;
-  /** Tokenization options */
-  #tokenizeOptions;
-  constructor(config = {}, tokenizeOptions = {}) {
-    this.k1 = config.k1 ?? 1.5;
-    this.b = config.b ?? 0.75;
-    this.#tokenizeOptions = tokenizeOptions;
+  /**
+   * Get the mounts map.
+   */
+  get mounts() {
+    return this._mounts;
   }
   /**
-   * Add a document to the index
+   * Get the underlying filesystem for a given path.
+   * Returns undefined if the path doesn't resolve to any mount.
    */
-  add(id, content, metadata) {
-    if (this.#documents.has(id)) {
-      this.remove(id);
-    }
-    const tokens = tokenize(content, this.#tokenizeOptions);
-    const termFrequencies = computeTermFrequencies(tokens);
-    const doc = {
-      id,
-      content,
-      tokens,
-      termFrequencies,
-      length: tokens.length,
-      metadata
-    };
-    this.#documents.set(id, doc);
-    this.#docCount++;
-    for (const term of termFrequencies.keys()) {
-      if (!this.#invertedIndex.has(term)) {
-        this.#invertedIndex.set(term, /* @__PURE__ */ new Set());
-      }
-      this.#invertedIndex.get(term).add(id);
-      this.#documentFrequency.set(term, (this.#documentFrequency.get(term) || 0) + 1);
-    }
-    this.#updateAvgDocLength();
+  getFilesystemForPath(path4) {
+    const resolved = this.resolveMount(path4);
+    return resolved?.fs;
   }
   /**
-   * Remove a document from the index
+   * Get the mount path for a given path.
+   * Returns undefined if the path doesn't resolve to any mount.
    */
-  remove(id) {
-    const doc = this.#documents.get(id);
-    if (!doc) {
-      return false;
+  getMountPathForPath(path4) {
+    const resolved = this.resolveMount(path4);
+    return resolved?.mountPath;
+  }
+  normalizePath(path4) {
+    if (!path4 || path4 === "/") return "/";
+    let n = path4.startsWith("/") ? path4 : `/${path4}`;
+    if (n.length > 1 && n.endsWith("/")) n = n.slice(0, -1);
+    return n;
+  }
+  resolveMount(path4) {
+    const normalized = this.normalizePath(path4);
+    let best = null;
+    for (const [mountPath, fs5] of this._mounts) {
+      if (normalized === mountPath || normalized.startsWith(mountPath + "/")) {
+        if (!best || mountPath.length > best.mountPath.length) {
+          best = { mountPath, fs: fs5 };
+        }
+      }
     }
-    for (const term of doc.termFrequencies.keys()) {
-      const docIds = this.#invertedIndex.get(term);
-      if (docIds) {
-        docIds.delete(id);
-        if (docIds.size === 0) {
-          this.#invertedIndex.delete(term);
-          this.#documentFrequency.delete(term);
-        } else {
-          this.#documentFrequency.set(term, (this.#documentFrequency.get(term) || 1) - 1);
+    if (!best) return null;
+    let fsPath = normalized.slice(best.mountPath.length);
+    if (!fsPath) fsPath = "/";
+    if (!fsPath.startsWith("/")) fsPath = "/" + fsPath;
+    return { fs: best.fs, fsPath, mountPath: best.mountPath };
+  }
+  getVirtualEntries(path4) {
+    const normalized = this.normalizePath(path4);
+    if (this.resolveMount(normalized)) return null;
+    const entriesMap = /* @__PURE__ */ new Map();
+    for (const [mountPath, fs5] of this._mounts.entries()) {
+      const isUnder = normalized === "/" ? mountPath.startsWith("/") : mountPath.startsWith(normalized + "/");
+      if (isUnder) {
+        const remaining = normalized === "/" ? mountPath.slice(1) : mountPath.slice(normalized.length + 1);
+        const next = remaining.split("/")[0];
+        if (next && !entriesMap.has(next)) {
+          const isDirectMount = remaining === next;
+          const entry = { name: next, type: "directory" };
+          if (isDirectMount) {
+            entry.mount = {
+              provider: fs5.provider,
+              icon: fs5.icon,
+              displayName: fs5.displayName,
+              description: fs5.description,
+              status: fs5.status,
+              error: fs5.error
+            };
+          }
+          entriesMap.set(next, entry);
         }
       }
     }
-    this.#documents.delete(id);
-    this.#docCount--;
-    this.#updateAvgDocLength();
-    return true;
+    return entriesMap.size > 0 ? Array.from(entriesMap.values()) : null;
   }
-  /**
-   * Clear all documents from the index
-   */
-  clear() {
-    this.#documents.clear();
-    this.#invertedIndex.clear();
-    this.#documentFrequency.clear();
-    this.#docCount = 0;
-    this.#avgDocLength = 0;
+  isVirtualPath(path4) {
+    const normalized = this.normalizePath(path4);
+    if (normalized === "/" && !this._mounts.has("/")) return true;
+    for (const mountPath of this._mounts.keys()) {
+      if (mountPath.startsWith(normalized + "/")) return true;
+    }
+    return false;
   }
   /**
-   * Search for documents matching the query
+   * Assert that a filesystem is writable (not read-only).
+   * @throws {PermissionError} if the filesystem is read-only
    */
-  search(query, topK = 10, minScore = 0) {
-    const queryTokens = tokenize(query, this.#tokenizeOptions);
-    if (queryTokens.length === 0 || this.#docCount === 0) {
-      return [];
+  assertWritable(fs5, path4, operation) {
+    if (fs5.readOnly) {
+      throw new PermissionError(path4, `${operation} (filesystem is read-only)`);
     }
-    const scores = /* @__PURE__ */ new Map();
-    for (const queryTerm of queryTokens) {
-      const docIds = this.#invertedIndex.get(queryTerm);
-      if (!docIds) {
-        continue;
-      }
-      const df = this.#documentFrequency.get(queryTerm) || 0;
-      const idf = this.#computeIDF(df);
-      for (const docId of docIds) {
-        const doc = this.#documents.get(docId);
-        const tf = doc.termFrequencies.get(queryTerm) || 0;
-        const termScore = this.#computeTermScore(tf, doc.length, idf);
-        scores.set(docId, (scores.get(docId) || 0) + termScore);
+  }
+  // ===========================================================================
+  // WorkspaceFilesystem Implementation
+  // ===========================================================================
+  async init() {
+    this.status = "initializing";
+    for (const [mountPath, fs5] of this._mounts.entries()) {
+      try {
+        await callLifecycle(fs5, "init");
+      } catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        console.warn(`[CompositeFilesystem] Mount "${mountPath}" failed to initialize: ${message}`);
       }
     }
-    const results = [];
-    for (const [docId, score] of scores.entries()) {
-      if (score >= minScore) {
-        const doc = this.#documents.get(docId);
-        results.push({
-          id: docId,
-          content: doc.content,
-          score,
-          metadata: doc.metadata
-        });
+    this.status = "ready";
+  }
+  async destroy() {
+    this.status = "destroying";
+    const errors = [];
+    for (const fs5 of this._mounts.values()) {
+      try {
+        await callLifecycle(fs5, "destroy");
+      } catch (e) {
+        errors.push(e instanceof Error ? e : new Error(String(e)));
       }
     }
-    results.sort((a, b) => b.score - a.score);
-    return results.slice(0, topK);
+    if (errors.length > 0) {
+      this.status = "error";
+      throw new AggregateError(errors, "Some filesystems failed to destroy");
+    }
+    this.status = "destroyed";
   }
-  /**
-   * Get a document by ID
-   */
-  get(id) {
-    return this.#documents.get(id);
+  async readFile(path4, options) {
+    const r = this.resolveMount(path4);
+    if (!r) throw new Error(`No mount for path: ${path4}`);
+    return r.fs.readFile(r.fsPath, options);
   }
-  /**
-   * Check if a document exists in the index
-   */
-  has(id) {
-    return this.#documents.has(id);
+  async writeFile(path4, content, options) {
+    const r = this.resolveMount(path4);
+    if (!r) throw new Error(`No mount for path: ${path4}`);
+    this.assertWritable(r.fs, path4, "writeFile");
+    return r.fs.writeFile(r.fsPath, content, options);
   }
-  /**
-   * Get the number of documents in the index
-   */
-  get size() {
-    return this.#docCount;
+  async appendFile(path4, content) {
+    const r = this.resolveMount(path4);
+    if (!r) throw new Error(`No mount for path: ${path4}`);
+    this.assertWritable(r.fs, path4, "appendFile");
+    return r.fs.appendFile(r.fsPath, content);
   }
-  /**
-   * Get all document IDs
-   */
-  get documentIds() {
-    return Array.from(this.#documents.keys());
+  async deleteFile(path4, options) {
+    const r = this.resolveMount(path4);
+    if (!r) throw new Error(`No mount for path: ${path4}`);
+    this.assertWritable(r.fs, path4, "deleteFile");
+    return r.fs.deleteFile(r.fsPath, options);
   }
-  /**
-   * Serialize the index to a JSON-compatible object
-   */
-  serialize() {
-    const documents = [];
-    for (const [id, doc] of this.#documents.entries()) {
-      documents.push({
-        id,
-        content: doc.content,
-        tokens: doc.tokens,
-        termFrequencies: Object.fromEntries(doc.termFrequencies),
-        length: doc.length,
-        metadata: doc.metadata
-      });
+  async copyFile(src, dest, options) {
+    const srcR = this.resolveMount(src);
+    const destR = this.resolveMount(dest);
+    if (!srcR) throw new Error(`No mount for source: ${src}`);
+    if (!destR) throw new Error(`No mount for dest: ${dest}`);
+    this.assertWritable(destR.fs, dest, "copyFile");
+    if (srcR.mountPath === destR.mountPath) {
+      return srcR.fs.copyFile(srcR.fsPath, destR.fsPath, options);
     }
-    return {
-      k1: this.k1,
-      b: this.b,
-      documents,
-      avgDocLength: this.#avgDocLength
-    };
+    const content = await srcR.fs.readFile(srcR.fsPath);
+    await destR.fs.writeFile(destR.fsPath, content, { overwrite: options?.overwrite });
   }
-  /**
-   * Deserialize an index from a JSON object
-   */
-  static deserialize(data, tokenizeOptions = {}) {
-    const index = new _BM25Index({ k1: data.k1, b: data.b }, tokenizeOptions);
-    for (const doc of data.documents) {
-      const termFrequencies = new Map(Object.entries(doc.termFrequencies));
-      const document = {
-        id: doc.id,
-        content: doc.content,
-        tokens: doc.tokens,
-        termFrequencies,
-        length: doc.length,
-        metadata: doc.metadata
+  async moveFile(src, dest, options) {
+    const srcR = this.resolveMount(src);
+    const destR = this.resolveMount(dest);
+    if (!srcR) throw new Error(`No mount for source: ${src}`);
+    if (!destR) throw new Error(`No mount for dest: ${dest}`);
+    this.assertWritable(destR.fs, dest, "moveFile");
+    this.assertWritable(srcR.fs, src, "moveFile");
+    if (srcR.mountPath === destR.mountPath) {
+      return srcR.fs.moveFile(srcR.fsPath, destR.fsPath, options);
+    }
+    await this.copyFile(src, dest, options);
+    await srcR.fs.deleteFile(srcR.fsPath);
+  }
+  async readdir(path4, options) {
+    const virtual = this.getVirtualEntries(path4);
+    if (virtual) return virtual;
+    const r = this.resolveMount(path4);
+    if (!r) throw new Error(`No mount for path: ${path4}`);
+    return r.fs.readdir(r.fsPath, options);
+  }
+  async mkdir(path4, options) {
+    const r = this.resolveMount(path4);
+    if (!r) throw new Error(`No mount for path: ${path4}`);
+    this.assertWritable(r.fs, path4, "mkdir");
+    return r.fs.mkdir(r.fsPath, options);
+  }
+  async rmdir(path4, options) {
+    const r = this.resolveMount(path4);
+    if (!r) throw new Error(`No mount for path: ${path4}`);
+    this.assertWritable(r.fs, path4, "rmdir");
+    return r.fs.rmdir(r.fsPath, options);
+  }
+  async exists(path4) {
+    if (this.isVirtualPath(path4)) return true;
+    const r = this.resolveMount(path4);
+    if (!r) return false;
+    if (r.fsPath === "/") return true;
+    return r.fs.exists(r.fsPath);
+  }
+  async stat(path4) {
+    const normalized = this.normalizePath(path4);
+    if (this.isVirtualPath(path4)) {
+      const parts = normalized.split("/").filter(Boolean);
+      const now = /* @__PURE__ */ new Date();
+      return {
+        name: parts[parts.length - 1] || "",
+        path: normalized,
+        type: "directory",
+        size: 0,
+        createdAt: now,
+        modifiedAt: now
       };
-      index.#documents.set(doc.id, document);
-      index.#docCount++;
-      for (const term of termFrequencies.keys()) {
-        if (!index.#invertedIndex.has(term)) {
-          index.#invertedIndex.set(term, /* @__PURE__ */ new Set());
-        }
-        index.#invertedIndex.get(term).add(doc.id);
-        index.#documentFrequency.set(term, (index.#documentFrequency.get(term) || 0) + 1);
-      }
     }
-    index.#avgDocLength = data.avgDocLength;
-    return index;
+    const r = this.resolveMount(path4);
+    if (!r) throw new Error(`No mount for path: ${path4}`);
+    if (r.fsPath === "/") {
+      const parts = normalized.split("/").filter(Boolean);
+      const now = /* @__PURE__ */ new Date();
+      return {
+        name: parts[parts.length - 1] || "",
+        path: normalized,
+        type: "directory",
+        size: 0,
+        createdAt: now,
+        modifiedAt: now
+      };
+    }
+    return r.fs.stat(r.fsPath);
+  }
+  async isFile(path4) {
+    if (this.isVirtualPath(path4)) return false;
+    const r = this.resolveMount(path4);
+    if (!r) return false;
+    try {
+      const stat3 = await r.fs.stat(r.fsPath);
+      return stat3.type === "file";
+    } catch {
+      return false;
+    }
+  }
+  async isDirectory(path4) {
+    if (this.isVirtualPath(path4)) return true;
+    const r = this.resolveMount(path4);
+    if (!r) return false;
+    if (r.fsPath === "/") return true;
+    try {
+      const stat3 = await r.fs.stat(r.fsPath);
+      return stat3.type === "directory";
+    } catch {
+      return false;
+    }
   }
   /**
-   * Update average document length after add/remove operations
+   * Get instructions describing the mounted filesystems.
+   * Used by agents to understand available storage locations.
    */
-  #updateAvgDocLength() {
-    if (this.#docCount === 0) {
-      this.#avgDocLength = 0;
+  getInstructions() {
+    const mountDescriptions = Array.from(this._mounts.entries()).map(([mountPath, fs5]) => {
+      const name = fs5.displayName || fs5.provider;
+      const access2 = fs5.readOnly ? "(read-only)" : "(read-write)";
+      return `- ${mountPath}: ${name} ${access2}`;
+    }).join("\n");
+    return `Mounted filesystems:
+${mountDescriptions}
+Files written via workspace tools are accessible at the same paths in sandbox commands.`;
+  }
+};
+
+// src/workspace/filesystem/mastra-filesystem.ts
+var MastraFilesystem = class extends MastraBase {
+  /** Error message when status is 'error' */
+  error;
+  // ---------------------------------------------------------------------------
+  // Lifecycle Promise Tracking (prevents race conditions)
+  // ---------------------------------------------------------------------------
+  /** Promise for _init() to prevent race conditions from concurrent calls */
+  _initPromise;
+  /** Promise for _destroy() to prevent race conditions from concurrent calls */
+  _destroyPromise;
+  constructor(options) {
+    super({ name: options.name, component: RegisteredLogger.WORKSPACE });
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle Wrappers (race-condition-safe)
+  // ---------------------------------------------------------------------------
+  /**
+   * Initialize the filesystem (wrapper with status management and race-condition safety).
+   *
+   * This method is race-condition-safe - concurrent calls will return the same promise.
+   * Handles status management automatically.
+   *
+   * Subclasses override `init()` to provide their initialization logic.
+   */
+  async _init() {
+    if (this.status === "ready") {
       return;
     }
-    let totalLength = 0;
-    for (const doc of this.#documents.values()) {
-      totalLength += doc.length;
+    if (this._destroyPromise) {
+      try {
+        await this._destroyPromise;
+      } catch {
+      }
+    }
+    if (this._initPromise) {
+      return this._initPromise;
+    }
+    this._initPromise = this._executeInit();
+    try {
+      await this._initPromise;
+    } finally {
+      this._initPromise = void 0;
     }
-    this.#avgDocLength = totalLength / this.#docCount;
   }
   /**
-   * Compute IDF (Inverse Document Frequency) for a term
+   * Internal init execution - handles status.
    */
-  #computeIDF(df) {
-    return Math.log((this.#docCount - df + 0.5) / (df + 0.5) + 1);
+  async _executeInit() {
+    this.status = "initializing";
+    this.error = void 0;
+    try {
+      await this.init();
+      this.status = "ready";
+    } catch (error) {
+      this.status = "error";
+      this.error = error instanceof Error ? error.message : String(error);
+      this.logger.error("Failed to initialize filesystem", { error, id: this.id });
+      throw error;
+    }
   }
   /**
-   * Compute the BM25 score component for a single term
+   * Override this method to implement filesystem initialization logic.
+   *
+   * Called by `_init()` after status is set to 'initializing'.
+   * Status will be set to 'ready' on success, 'error' on failure.
+   *
+   * @example
+   * ```typescript
+   * async init(): Promise<void> {
+   *   this._client = new StorageClient({ ... });
+   *   await this._client.connect();
+   * }
+   * ```
    */
-  #computeTermScore(tf, docLength, idf) {
-    const numerator = tf * (this.k1 + 1);
-    const denominator = tf + this.k1 * (1 - this.b + this.b * (docLength / this.#avgDocLength));
-    return idf * (numerator / denominator);
+  async init() {
   }
-};
-
-// src/workspace/search/search-engine.ts
-var SearchEngine = class {
-  /** BM25 index for keyword search */
-  #bm25Index;
-  /** Tokenization options (stored for lineRange computation) */
-  #tokenizeOptions;
-  /** Vector configuration */
-  #vectorConfig;
-  /** Whether to use lazy vector indexing */
-  #lazyVectorIndex;
-  /** Documents pending vector indexing (for lazy mode) */
-  #pendingVectorDocs = [];
-  /** Whether vector index has been built (for lazy mode) */
-  #vectorIndexBuilt = false;
-  constructor(config = {}) {
-    if (config.bm25 !== void 0) {
-      this.#tokenizeOptions = config.bm25.tokenize;
-      this.#bm25Index = new BM25Index(config.bm25.bm25, this.#tokenizeOptions);
+  /**
+   * Ensure the filesystem is ready.
+   *
+   * Calls `_init()` if status is not 'ready'. Useful for lazy initialization
+   * where operations should automatically initialize the filesystem if needed.
+   *
+   * @throws {FilesystemNotReadyError} if the filesystem fails to reach 'ready' status
+   *
+   * @example
+   * ```typescript
+   * async readFile(path: string): Promise<string | Buffer> {
+   *   await this.ensureReady();
+   *   // Now safe to use the filesystem
+   * }
+   * ```
+   */
+  async ensureReady() {
+    if (this.status !== "ready") {
+      await this._init();
     }
-    if (config.vector) {
-      this.#vectorConfig = config.vector;
+    if (this.status !== "ready") {
+      throw new FilesystemNotReadyError(this.id);
     }
-    this.#lazyVectorIndex = config.lazyVectorIndex ?? false;
   }
-  // ===========================================================================
-  // Public API
-  // ===========================================================================
   /**
-   * Index a document for search
+   * Destroy the filesystem and clean up all resources (wrapper with status management).
+   *
+   * This method is race-condition-safe - concurrent calls will return the same promise.
+   * Handles status management.
+   *
+   * Subclasses override `destroy()` to provide their destroy logic.
    */
-  async index(doc) {
-    const metadata = {
-      ...doc.metadata
-    };
-    if (doc.startLineOffset !== void 0) {
-      metadata._startLineOffset = doc.startLineOffset;
+  async _destroy() {
+    if (this.status === "destroyed") {
+      return;
     }
-    if (this.#bm25Index) {
-      this.#bm25Index.add(doc.id, doc.content, metadata);
+    if (this.status === "pending") {
+      this.status = "destroyed";
+      return;
     }
-    if (this.#vectorConfig) {
-      const docWithMergedMetadata = { ...doc, metadata };
-      if (this.#lazyVectorIndex) {
-        this.#pendingVectorDocs.push(docWithMergedMetadata);
-        this.#vectorIndexBuilt = false;
-      } else {
-        await this.#indexVector(docWithMergedMetadata);
-      }
+    if (this._destroyPromise) {
+      return this._destroyPromise;
     }
-  }
-  /**
-   * Index multiple documents
-   */
-  async indexMany(docs) {
-    for (const doc of docs) {
-      await this.index(doc);
+    this._destroyPromise = this._executeDestroy();
+    try {
+      await this._destroyPromise;
+    } finally {
+      this._destroyPromise = void 0;
     }
   }
   /**
-   * Remove a document from the index
+   * Internal destroy execution - handles status.
    */
-  async remove(id) {
-    if (this.#bm25Index) {
-      this.#bm25Index.remove(id);
-    }
-    if (this.#vectorConfig) {
+  async _executeDestroy() {
+    if (this._initPromise) {
       try {
-        await this.#vectorConfig.vectorStore.deleteVector({
-          indexName: this.#vectorConfig.indexName,
-          id
-        });
+        await this._initPromise;
       } catch {
       }
-      if (this.#lazyVectorIndex) {
-        this.#pendingVectorDocs = this.#pendingVectorDocs.filter((d) => d.id !== id);
-      }
+    }
+    this.status = "destroying";
+    try {
+      await this.destroy();
+      this.status = "destroyed";
+    } catch (error) {
+      this.status = "error";
+      this.logger.error("Failed to destroy filesystem", { error, id: this.id });
+      throw error;
     }
   }
   /**
-   * Clear all indexed documents
+   * Override this method to implement filesystem destroy logic.
+   *
+   * Called by `_destroy()` after status is set to 'destroying'.
+   * Status will be set to 'destroyed' on success, 'error' on failure.
    */
-  clear() {
-    if (this.#bm25Index) {
-      this.#bm25Index.clear();
-    }
-    this.#pendingVectorDocs = [];
-    this.#vectorIndexBuilt = false;
+  async destroy() {
   }
-  /**
-   * Search for documents
-   */
-  async search(query, options = {}) {
-    const { topK = 10, minScore, mode, vectorWeight = 0.5, filter } = options;
-    const effectiveMode = this.#determineSearchMode(mode);
-    if (effectiveMode === "bm25") {
-      return this.#searchBM25(query, topK, minScore);
-    }
-    if (effectiveMode === "vector") {
-      return this.#searchVector(query, topK, minScore, filter);
+};
+function isEnoentError(error) {
+  return error !== null && typeof error === "object" && "code" in error && error.code === "ENOENT";
+}
+function isEexistError(error) {
+  return error !== null && typeof error === "object" && "code" in error && error.code === "EEXIST";
+}
+var MIME_TYPES = {
+  // Text
+  txt: "text/plain",
+  html: "text/html",
+  htm: "text/html",
+  css: "text/css",
+  csv: "text/csv",
+  md: "text/markdown",
+  // Code
+  js: "application/javascript",
+  mjs: "application/javascript",
+  ts: "application/typescript",
+  tsx: "application/typescript",
+  jsx: "application/javascript",
+  json: "application/json",
+  xml: "application/xml",
+  yaml: "text/yaml",
+  yml: "text/yaml",
+  // Programming languages
+  py: "text/x-python",
+  rb: "text/x-ruby",
+  go: "text/x-go",
+  rs: "text/x-rust",
+  java: "text/x-java",
+  c: "text/x-c",
+  cpp: "text/x-c++",
+  h: "text/x-c",
+  hpp: "text/x-c++",
+  sh: "text/x-sh",
+  bash: "text/x-sh",
+  zsh: "text/x-sh",
+  // Config
+  toml: "text/toml",
+  ini: "text/plain",
+  env: "text/plain",
+  // Database/Query
+  sql: "text/x-sql",
+  graphql: "application/graphql",
+  gql: "application/graphql",
+  // Frameworks
+  vue: "text/x-vue",
+  // Images
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  svg: "image/svg+xml",
+  webp: "image/webp",
+  ico: "image/x-icon",
+  // Documents
+  pdf: "application/pdf"
+};
+function getMimeType(filename) {
+  const ext = nodePath.extname(filename).slice(1).toLowerCase();
+  return MIME_TYPES[ext] ?? "application/octet-stream";
+}
+var TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".md",
+  ".txt",
+  ".json",
+  ".yaml",
+  ".yml",
+  ".js",
+  ".mjs",
+  ".ts",
+  ".tsx",
+  ".jsx",
+  ".py",
+  ".rb",
+  ".go",
+  ".rs",
+  ".java",
+  ".c",
+  ".cpp",
+  ".h",
+  ".hpp",
+  ".sh",
+  ".bash",
+  ".zsh",
+  ".html",
+  ".htm",
+  ".css",
+  ".xml",
+  ".toml",
+  ".ini",
+  ".env",
+  ".csv",
+  ".sql",
+  ".graphql",
+  ".gql",
+  ".vue",
+  ".svg"
+]);
+function isTextFile(filename) {
+  const ext = nodePath.extname(filename).toLowerCase();
+  return TEXT_EXTENSIONS.has(ext);
+}
+async function fsExists(absolutePath) {
+  try {
+    await fs2.access(absolutePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function fsStat(absolutePath, userPath) {
+  try {
+    const stats = await fs2.stat(absolutePath);
+    return {
+      name: nodePath.basename(absolutePath),
+      type: stats.isDirectory() ? "directory" : "file",
+      size: stats.size,
+      createdAt: stats.birthtime,
+      modifiedAt: stats.mtime,
+      mimeType: stats.isFile() ? getMimeType(absolutePath) : void 0
+    };
+  } catch (error) {
+    if (isEnoentError(error)) {
+      throw new FileNotFoundError(userPath);
     }
-    return this.#searchHybrid(query, topK, minScore, vectorWeight, filter);
+    throw error;
   }
+}
+
+// src/workspace/filesystem/local-filesystem.ts
+var LocalFilesystem = class extends MastraFilesystem {
+  id;
+  name = "LocalFilesystem";
+  provider = "local";
+  readOnly;
+  status = "pending";
+  _basePath;
+  _contained;
   /**
-   * Check if BM25 search is available
+   * The absolute base path on disk where files are stored.
+   * Useful for understanding how workspace paths map to disk paths.
    */
-  get canBM25() {
-    return !!this.#bm25Index;
+  get basePath() {
+    return this._basePath;
   }
-  /**
-   * Check if vector search is available
-   */
-  get canVector() {
-    return !!this.#vectorConfig;
+  constructor(options) {
+    super({ name: "LocalFilesystem" });
+    this.id = options.id ?? this.generateId();
+    this._basePath = nodePath.resolve(options.basePath);
+    this._contained = options.contained ?? true;
+    this.readOnly = options.readOnly;
   }
-  /**
-   * Check if hybrid search is available
-   */
-  get canHybrid() {
-    return this.canBM25 && this.canVector;
+  generateId() {
+    return `local-fs-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
   }
-  /**
-   * Get the BM25 index (for serialization/debugging)
-   */
-  get bm25Index() {
-    return this.#bm25Index;
+  toBuffer(content) {
+    if (Buffer.isBuffer(content)) return content;
+    if (content instanceof Uint8Array) return Buffer.from(content);
+    return Buffer.from(content, "utf-8");
   }
-  // ===========================================================================
-  // Private Methods
-  // ===========================================================================
-  /**
-   * Determine the effective search mode
-   */
-  #determineSearchMode(requestedMode) {
-    if (requestedMode) {
-      if (requestedMode === "vector" && !this.canVector) {
-        throw new Error("Vector search requires vector configuration.");
-      }
-      if (requestedMode === "bm25" && !this.canBM25) {
-        throw new Error("BM25 search requires BM25 configuration.");
-      }
-      if (requestedMode === "hybrid" && !this.canHybrid) {
-        throw new Error("Hybrid search requires both vector and BM25 configuration.");
+  resolvePath(inputPath) {
+    const cleanedPath = inputPath.replace(/^\/+/, "");
+    const normalizedInput = nodePath.normalize(cleanedPath);
+    const absolutePath = nodePath.resolve(this._basePath, normalizedInput);
+    if (this._contained) {
+      const relative2 = nodePath.relative(this._basePath, absolutePath);
+      if (relative2.startsWith("..") || nodePath.isAbsolute(relative2)) {
+        throw new PermissionError(inputPath, "access");
       }
-      return requestedMode;
-    }
-    if (this.canHybrid) {
-      return "hybrid";
-    }
-    if (this.canVector) {
-      return "vector";
-    }
-    if (this.canBM25) {
-      return "bm25";
     }
-    throw new Error("No search configuration available. Provide bm25 or vector config.");
+    return absolutePath;
   }
-  /**
-   * Index a single document in the vector store
-   */
-  async #indexVector(doc) {
-    if (!this.#vectorConfig) return;
-    const { vectorStore, embedder, indexName } = this.#vectorConfig;
-    const embedding = await embedder(doc.content);
-    await vectorStore.upsert({
-      indexName,
-      vectors: [embedding],
-      metadata: [
-        {
-          id: doc.id,
-          text: doc.content,
-          ...doc.metadata
-        }
-      ],
-      ids: [doc.id]
-    });
+  toRelativePath(absolutePath) {
+    return "/" + nodePath.relative(this._basePath, absolutePath).replace(/\\/g, "/");
+  }
+  assertWritable(operation) {
+    if (this.readOnly) {
+      throw new WorkspaceReadOnlyError(operation);
+    }
   }
   /**
-   * Ensure vector index is built (for lazy mode)
+   * Verify that the resolved path doesn't escape basePath via symlinks.
+   * Uses realpath to resolve symlinks and check the actual target.
    */
-  async #ensureVectorIndex() {
-    if (!this.#lazyVectorIndex || this.#vectorIndexBuilt || this.#pendingVectorDocs.length === 0) {
-      return;
-    }
-    for (const doc of this.#pendingVectorDocs) {
-      await this.#indexVector(doc);
+  async assertPathContained(absolutePath) {
+    if (!this._contained) return;
+    let baseReal;
+    try {
+      baseReal = await fs2.realpath(this._basePath);
+    } catch (error) {
+      if (isEnoentError(error)) {
+        throw new DirectoryNotFoundError(this._basePath);
+      }
+      throw error;
     }
-    this.#pendingVectorDocs = [];
-    this.#vectorIndexBuilt = true;
-  }
-  /**
-   * BM25 keyword search
-   */
-  #searchBM25(query, topK, minScore) {
-    if (!this.#bm25Index) {
-      throw new Error("BM25 search requires BM25 configuration.");
+    let targetReal;
+    try {
+      targetReal = await fs2.realpath(absolutePath);
+    } catch (error) {
+      if (isEnoentError(error)) {
+        let parentPath = absolutePath;
+        while (true) {
+          const nextParent = nodePath.dirname(parentPath);
+          if (nextParent === parentPath) {
+            throw new DirectoryNotFoundError(absolutePath);
+          }
+          parentPath = nextParent;
+          try {
+            targetReal = await fs2.realpath(parentPath);
+            break;
+          } catch (parentError) {
+            if (!isEnoentError(parentError)) {
+              throw parentError;
+            }
+          }
+        }
+      } else {
+        throw error;
+      }
     }
-    const results = this.#bm25Index.search(query, topK, minScore);
-    const queryTokens = tokenize(query, this.#tokenizeOptions);
-    return results.map((result) => {
-      const rawLineRange = findLineRange(result.content, queryTokens, this.#tokenizeOptions);
-      const lineRange = this.#adjustLineRange(rawLineRange, result.metadata);
-      const { _startLineOffset, ...cleanMetadata } = result.metadata ?? {};
-      return {
-        id: result.id,
-        content: result.content,
-        score: result.score,
-        lineRange,
-        metadata: Object.keys(cleanMetadata).length > 0 ? cleanMetadata : void 0,
-        scoreDetails: { bm25: result.score }
-      };
-    });
-  }
-  /**
-   * Vector semantic search
-   */
-  async #searchVector(query, topK, minScore, filter) {
-    if (!this.#vectorConfig) {
-      throw new Error("Vector search requires vector configuration.");
+    if (targetReal !== baseReal && !targetReal.startsWith(baseReal + nodePath.sep)) {
+      throw new PermissionError(absolutePath, "access");
     }
-    await this.#ensureVectorIndex();
-    const { vectorStore, embedder, indexName } = this.#vectorConfig;
-    const queryEmbedding = await embedder(query);
-    const vectorResults = await vectorStore.query({
-      indexName,
-      queryVector: queryEmbedding,
-      topK,
-      filter
-    });
-    const queryTokens = tokenize(query, this.#tokenizeOptions);
-    const results = [];
-    for (const result of vectorResults) {
-      if (minScore !== void 0 && result.score < minScore) {
-        continue;
+  }
+  async readFile(inputPath, options) {
+    this.logger.debug("Reading file", { path: inputPath, encoding: options?.encoding });
+    await this.ensureReady();
+    const absolutePath = this.resolvePath(inputPath);
+    await this.assertPathContained(absolutePath);
+    try {
+      const stats = await fs2.stat(absolutePath);
+      if (stats.isDirectory()) {
+        throw new IsDirectoryError(inputPath);
       }
-      const id = result.metadata?.id ?? result.id;
-      const content = result.metadata?.text ?? "";
-      const { id: _id, text: _text, _startLineOffset, ...restMetadata } = result.metadata ?? {};
-      const rawLineRange = findLineRange(content, queryTokens, this.#tokenizeOptions);
-      const lineRange = this.#adjustLineRange(rawLineRange, result.metadata);
-      results.push({
-        id,
-        content,
-        score: result.score,
-        lineRange,
-        metadata: Object.keys(restMetadata).length > 0 ? restMetadata : void 0,
-        scoreDetails: { vector: result.score }
-      });
+      if (options?.encoding) {
+        return await fs2.readFile(absolutePath, { encoding: options.encoding });
+      }
+      return await fs2.readFile(absolutePath);
+    } catch (error) {
+      if (error instanceof IsDirectoryError) throw error;
+      if (isEnoentError(error)) {
+        throw new FileNotFoundError(inputPath);
+      }
+      throw error;
     }
-    return results;
   }
-  /**
-   * Hybrid search combining vector and BM25 scores
-   */
-  async #searchHybrid(query, topK, minScore, vectorWeight = 0.5, filter) {
-    const expandedTopK = Math.min(topK * 2, 50);
-    const [vectorResults, bm25Results] = await Promise.all([
-      this.#searchVector(query, expandedTopK, void 0, filter),
-      Promise.resolve(this.#searchBM25(query, expandedTopK, void 0))
-    ]);
-    const normalizedBM25 = this.#normalizeBM25Scores(bm25Results);
-    const bm25Map = /* @__PURE__ */ new Map();
-    for (const result of normalizedBM25) {
-      bm25Map.set(result.id, result);
-    }
-    const vectorMap = /* @__PURE__ */ new Map();
-    for (const result of vectorResults) {
-      vectorMap.set(result.id, result);
-    }
-    const combinedResults = /* @__PURE__ */ new Map();
-    const allIds = /* @__PURE__ */ new Set([...vectorMap.keys(), ...bm25Map.keys()]);
-    const bm25Weight = 1 - vectorWeight;
-    for (const id of allIds) {
-      const vectorResult = vectorMap.get(id);
-      const bm25Result = bm25Map.get(id);
-      const vectorScore = vectorResult?.scoreDetails?.vector ?? 0;
-      const bm25Score = bm25Result?.score ?? 0;
-      const combinedScore = vectorWeight * vectorScore + bm25Weight * bm25Score;
-      const baseResult = vectorResult ?? bm25Result;
-      combinedResults.set(id, {
-        id,
-        content: baseResult.content,
-        score: combinedScore,
-        lineRange: bm25Result?.lineRange ?? vectorResult?.lineRange,
-        metadata: baseResult.metadata,
-        scoreDetails: {
-          vector: vectorResult?.scoreDetails?.vector,
-          bm25: bm25Result?.scoreDetails?.bm25
+  async writeFile(inputPath, content, options) {
+    const contentSize = Buffer.isBuffer(content) ? content.length : content.length;
+    this.logger.debug("Writing file", { path: inputPath, size: contentSize, recursive: options?.recursive });
+    await this.ensureReady();
+    this.assertWritable("writeFile");
+    const absolutePath = this.resolvePath(inputPath);
+    await this.assertPathContained(absolutePath);
+    if (options?.recursive === false) {
+      const dir = nodePath.dirname(absolutePath);
+      const parentPath = nodePath.dirname(inputPath);
+      try {
+        const stat3 = await fs2.stat(dir);
+        if (!stat3.isDirectory()) {
+          throw new NotDirectoryError(parentPath);
         }
-      });
+      } catch (error) {
+        if (error instanceof NotDirectoryError) throw error;
+        if (isEnoentError(error)) {
+          throw new DirectoryNotFoundError(parentPath);
+        }
+        throw error;
+      }
     }
-    let results = Array.from(combinedResults.values());
-    results.sort((a, b) => b.score - a.score);
-    if (minScore !== void 0) {
-      results = results.filter((r) => r.score >= minScore);
+    if (options?.recursive !== false) {
+      const dir = nodePath.dirname(absolutePath);
+      await fs2.mkdir(dir, { recursive: true });
     }
-    return results.slice(0, topK);
-  }
-  /**
-   * Normalize BM25 scores to 0-1 range using min-max normalization
-   */
-  #normalizeBM25Scores(results) {
-    if (results.length === 0) return results;
-    const scores = results.map((r) => r.scoreDetails?.bm25 ?? r.score);
-    const maxScore = Math.max(...scores);
-    const minScore = Math.min(...scores);
-    const range = maxScore - minScore;
-    if (range === 0) {
-      return results.map((r) => ({ ...r, score: 1 }));
+    const writeFlag = options?.overwrite === false ? "wx" : "w";
+    try {
+      await fs2.writeFile(absolutePath, this.toBuffer(content), { flag: writeFlag });
+    } catch (error) {
+      if (options?.overwrite === false && isEexistError(error)) {
+        throw new FileExistsError(inputPath);
+      }
+      throw error;
     }
-    return results.map((r) => ({
-      ...r,
-      score: ((r.scoreDetails?.bm25 ?? r.score) - minScore) / range
-    }));
   }
-  /**
-   * Adjust line range for chunked documents.
-   * If the document has a _startLineOffset in metadata, adjust the line range
-   * to reflect the original document's line numbers.
-   */
-  #adjustLineRange(lineRange, metadata) {
-    if (!lineRange) return void 0;
-    const startLineOffset = metadata?._startLineOffset;
-    if (typeof startLineOffset !== "number") {
-      return lineRange;
+  async appendFile(inputPath, content) {
+    const contentSize = Buffer.isBuffer(content) ? content.length : content.length;
+    this.logger.debug("Appending to file", { path: inputPath, size: contentSize });
+    await this.ensureReady();
+    this.assertWritable("appendFile");
+    const absolutePath = this.resolvePath(inputPath);
+    await this.assertPathContained(absolutePath);
+    const dir = nodePath.dirname(absolutePath);
+    await fs2.mkdir(dir, { recursive: true });
+    await fs2.appendFile(absolutePath, this.toBuffer(content));
+  }
+  async deleteFile(inputPath, options) {
+    this.logger.debug("Deleting file", { path: inputPath, force: options?.force });
+    await this.ensureReady();
+    this.assertWritable("deleteFile");
+    const absolutePath = this.resolvePath(inputPath);
+    await this.assertPathContained(absolutePath);
+    try {
+      const stats = await fs2.stat(absolutePath);
+      if (stats.isDirectory()) {
+        throw new IsDirectoryError(inputPath);
+      }
+      await fs2.unlink(absolutePath);
+    } catch (error) {
+      if (error instanceof IsDirectoryError) throw error;
+      if (isEnoentError(error)) {
+        if (!options?.force) {
+          throw new FileNotFoundError(inputPath);
+        }
+      } else {
+        throw error;
+      }
     }
-    return {
-      start: lineRange.start + startLineOffset - 1,
-      end: lineRange.end + startLineOffset - 1
-    };
   }
-};
-
-// src/workspace/skills/schemas.ts
-var SKILL_LIMITS = {
-  /** Recommended max tokens for instructions */
-  MAX_INSTRUCTION_TOKENS: 5e3,
-  /** Recommended max lines for SKILL.md */
-  MAX_INSTRUCTION_LINES: 500,
-  /** Max characters for name field */
-  MAX_NAME_LENGTH: 64,
-  /** Max characters for description field */
-  MAX_DESCRIPTION_LENGTH: 1024};
-function validateSkillName(name) {
-  const errors = [];
-  const fieldPath = "name";
-  if (typeof name !== "string") {
-    errors.push(`${fieldPath}: Expected string, received ${typeof name}`);
-    return errors;
+  async copyFile(src, dest, options) {
+    this.logger.debug("Copying file", { src, dest, recursive: options?.recursive });
+    await this.ensureReady();
+    this.assertWritable("copyFile");
+    const srcPath = this.resolvePath(src);
+    const destPath = this.resolvePath(dest);
+    await this.assertPathContained(srcPath);
+    await this.assertPathContained(destPath);
+    try {
+      const stats = await fs2.stat(srcPath);
+      if (stats.isDirectory()) {
+        if (!options?.recursive) {
+          throw new IsDirectoryError(src);
+        }
+        await this.copyDirectory(srcPath, destPath, options);
+      } else {
+        await fs2.mkdir(nodePath.dirname(destPath), { recursive: true });
+        const copyFlags = options?.overwrite === false ? constants.COPYFILE_EXCL : 0;
+        try {
+          await fs2.copyFile(srcPath, destPath, copyFlags);
+        } catch (error) {
+          if (options?.overwrite === false && isEexistError(error)) {
+            throw new FileExistsError(dest);
+          }
+          throw error;
+        }
+      }
+    } catch (error) {
+      if (error instanceof IsDirectoryError || error instanceof FileExistsError) throw error;
+      if (isEnoentError(error)) {
+        throw new FileNotFoundError(src);
+      }
+      throw error;
+    }
+  }
+  async copyDirectory(src, dest, options) {
+    await this.ensureReady();
+    await fs2.mkdir(dest, { recursive: true });
+    const entries = await fs2.readdir(src, { withFileTypes: true });
+    for (const entry of entries) {
+      const srcEntry = nodePath.join(src, entry.name);
+      const destEntry = nodePath.join(dest, entry.name);
+      await this.assertPathContained(srcEntry);
+      await this.assertPathContained(destEntry);
+      if (entry.isDirectory()) {
+        await this.copyDirectory(srcEntry, destEntry, options);
+      } else {
+        const copyFlags = options?.overwrite === false ? constants.COPYFILE_EXCL : 0;
+        try {
+          await fs2.copyFile(srcEntry, destEntry, copyFlags);
+        } catch (error) {
+          if (options?.overwrite === false && isEexistError(error)) {
+            continue;
+          }
+          throw error;
+        }
+      }
+    }
+  }
+  async moveFile(src, dest, options) {
+    this.logger.debug("Moving file", { src, dest, overwrite: options?.overwrite });
+    await this.ensureReady();
+    this.assertWritable("moveFile");
+    const srcPath = this.resolvePath(src);
+    const destPath = this.resolvePath(dest);
+    await this.assertPathContained(srcPath);
+    await this.assertPathContained(destPath);
+    try {
+      await fs2.mkdir(nodePath.dirname(destPath), { recursive: true });
+      if (options?.overwrite === false) {
+        await this.copyFile(src, dest, { ...options, overwrite: false });
+        await fs2.rm(srcPath, { recursive: true, force: true });
+        return;
+      }
+      try {
+        await fs2.rename(srcPath, destPath);
+      } catch (error) {
+        const code = error.code;
+        if (code !== "EXDEV") {
+          throw error;
+        }
+        await this.copyFile(src, dest, options);
+        await fs2.rm(srcPath, { recursive: true, force: true });
+      }
+    } catch (error) {
+      if (error instanceof FileExistsError) throw error;
+      if (isEnoentError(error)) {
+        throw new FileNotFoundError(src);
+      }
+      throw error;
+    }
+  }
+  async mkdir(inputPath, options) {
+    this.logger.debug("Creating directory", { path: inputPath, recursive: options?.recursive });
+    await this.ensureReady();
+    this.assertWritable("mkdir");
+    const absolutePath = this.resolvePath(inputPath);
+    await this.assertPathContained(absolutePath);
+    try {
+      await fs2.mkdir(absolutePath, { recursive: options?.recursive ?? true });
+    } catch (error) {
+      if (isEexistError(error)) {
+        const stats = await fs2.stat(absolutePath);
+        if (!stats.isDirectory()) {
+          throw new FileExistsError(inputPath);
+        }
+      } else if (isEnoentError(error)) {
+        const parentPath = nodePath.dirname(inputPath);
+        throw new DirectoryNotFoundError(parentPath);
+      } else {
+        throw error;
+      }
+    }
+  }
+  async rmdir(inputPath, options) {
+    this.logger.debug("Removing directory", { path: inputPath, recursive: options?.recursive, force: options?.force });
+    await this.ensureReady();
+    this.assertWritable("rmdir");
+    const absolutePath = this.resolvePath(inputPath);
+    await this.assertPathContained(absolutePath);
+    try {
+      const stats = await fs2.stat(absolutePath);
+      if (!stats.isDirectory()) {
+        throw new NotDirectoryError(inputPath);
+      }
+      if (options?.recursive) {
+        await fs2.rm(absolutePath, { recursive: true, force: options?.force ?? false });
+      } else {
+        const entries = await fs2.readdir(absolutePath);
+        if (entries.length > 0) {
+          throw new DirectoryNotEmptyError(inputPath);
+        }
+        await fs2.rmdir(absolutePath);
+      }
+    } catch (error) {
+      if (error instanceof NotDirectoryError || error instanceof DirectoryNotEmptyError) {
+        throw error;
+      }
+      if (isEnoentError(error)) {
+        if (!options?.force) {
+          throw new DirectoryNotFoundError(inputPath);
+        }
+      } else {
+        throw error;
+      }
+    }
+  }
+  async readdir(inputPath, options) {
+    this.logger.debug("Reading directory", { path: inputPath, recursive: options?.recursive });
+    await this.ensureReady();
+    const absolutePath = this.resolvePath(inputPath);
+    await this.assertPathContained(absolutePath);
+    try {
+      const stats = await fs2.stat(absolutePath);
+      if (!stats.isDirectory()) {
+        throw new NotDirectoryError(inputPath);
+      }
+      const entries = await fs2.readdir(absolutePath, { withFileTypes: true });
+      const result = [];
+      for (const entry of entries) {
+        const entryPath = nodePath.join(absolutePath, entry.name);
+        if (options?.extension) {
+          const extensions = Array.isArray(options.extension) ? options.extension : [options.extension];
+          if (entry.isFile()) {
+            const ext = nodePath.extname(entry.name);
+            if (!extensions.some((e) => e === ext || e === ext.slice(1))) {
+              continue;
+            }
+          }
+        }
+        const isSymlink = entry.isSymbolicLink();
+        let symlinkTarget;
+        let resolvedType = "file";
+        if (isSymlink) {
+          try {
+            symlinkTarget = await fs2.readlink(entryPath);
+            const targetStat = await fs2.stat(entryPath);
+            resolvedType = targetStat.isDirectory() ? "directory" : "file";
+          } catch {
+            resolvedType = "file";
+          }
+        } else {
+          resolvedType = entry.isDirectory() ? "directory" : "file";
+        }
+        const fileEntry = {
+          name: entry.name,
+          type: resolvedType,
+          isSymlink: isSymlink || void 0,
+          symlinkTarget
+        };
+        if (resolvedType === "file" && !isSymlink) {
+          try {
+            const stat3 = await fs2.stat(entryPath);
+            fileEntry.size = stat3.size;
+          } catch {
+          }
+        }
+        result.push(fileEntry);
+        if (options?.recursive && resolvedType === "directory") {
+          const depth = options.maxDepth ?? 100;
+          if (depth > 0) {
+            const subEntries = await this.readdir(this.toRelativePath(entryPath), { ...options, maxDepth: depth - 1 });
+            result.push(
+              ...subEntries.map((e) => ({
+                ...e,
+                name: `${entry.name}/${e.name}`
+              }))
+            );
+          }
+        }
+      }
+      return result;
+    } catch (error) {
+      if (error instanceof NotDirectoryError) throw error;
+      if (isEnoentError(error)) {
+        throw new DirectoryNotFoundError(inputPath);
+      }
+      throw error;
+    }
+  }
+  async exists(inputPath) {
+    await this.ensureReady();
+    const absolutePath = this.resolvePath(inputPath);
+    await this.assertPathContained(absolutePath);
+    return fsExists(absolutePath);
+  }
+  async stat(inputPath) {
+    await this.ensureReady();
+    const absolutePath = this.resolvePath(inputPath);
+    await this.assertPathContained(absolutePath);
+    const result = await fsStat(absolutePath, inputPath);
+    return {
+      ...result,
+      path: this.toRelativePath(absolutePath)
+    };
+  }
+  /**
+   * Initialize the local filesystem by creating the base directory.
+   * Status management is handled by the base class.
+   */
+  async init() {
+    this.logger.debug("Initializing filesystem", { basePath: this._basePath });
+    await fs2.mkdir(this._basePath, { recursive: true });
+    this.logger.debug("Filesystem initialized", { basePath: this._basePath });
+  }
+  /**
+   * Clean up the local filesystem.
+   * LocalFilesystem doesn't delete files on destroy by default.
+   * Status management is handled by the base class.
+   */
+  async destroy() {
+  }
+  getInfo() {
+    return {
+      id: this.id,
+      name: this.name,
+      provider: this.provider,
+      readOnly: this.readOnly,
+      basePath: this.basePath,
+      status: this.status
+    };
+  }
+  getInstructions() {
+    return `Local filesystem at "${this.basePath}". Files at workspace path "/foo" are stored at "${this.basePath}/foo" on disk.`;
+  }
+};
+var InMemoryFileReadTracker = class {
+  records = /* @__PURE__ */ new Map();
+  recordRead(path4, modifiedAt) {
+    const normalizedPath = this.normalizePath(path4);
+    this.records.set(normalizedPath, {
+      path: normalizedPath,
+      readAt: /* @__PURE__ */ new Date(),
+      modifiedAtRead: modifiedAt
+    });
+  }
+  getReadRecord(path4) {
+    return this.records.get(this.normalizePath(path4));
+  }
+  needsReRead(path4, currentModifiedAt) {
+    const record = this.getReadRecord(path4);
+    if (!record) {
+      return {
+        needsReRead: true,
+        reason: `File "${path4}" has not been read. You must read a file before writing to it.`
+      };
+    }
+    if (currentModifiedAt.getTime() > record.modifiedAtRead.getTime()) {
+      return {
+        needsReRead: true,
+        reason: `File "${path4}" was modified since last read (read at: ${record.modifiedAtRead.toISOString()}, current: ${currentModifiedAt.toISOString()}). Please re-read the file to get the latest contents.`
+      };
+    }
+    return { needsReRead: false };
+  }
+  clearReadRecord(path4) {
+    this.records.delete(this.normalizePath(path4));
+  }
+  clear() {
+    this.records.clear();
+  }
+  normalizePath(pathStr) {
+    const normalized = nodePath.posix.normalize(pathStr.replace(/\\/g, "/"));
+    return normalized.replace(/\/$/, "") || "/";
+  }
+};
+
+// src/workspace/sandbox/errors.ts
+var SandboxError = class extends Error {
+  constructor(message, code, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "SandboxError";
+  }
+};
+var SandboxExecutionError = class extends SandboxError {
+  constructor(message, exitCode, stdout, stderr) {
+    super(message, "EXECUTION_FAILED", { exitCode, stdout, stderr });
+    this.exitCode = exitCode;
+    this.stdout = stdout;
+    this.stderr = stderr;
+    this.name = "SandboxExecutionError";
+  }
+};
+var SandboxTimeoutError = class extends SandboxError {
+  constructor(timeoutMs, operation) {
+    super(`Execution timed out after ${timeoutMs}ms`, "TIMEOUT", { timeoutMs, operation });
+    this.timeoutMs = timeoutMs;
+    this.operation = operation;
+    this.name = "SandboxTimeoutError";
+  }
+};
+var SandboxNotReadyError = class extends SandboxError {
+  constructor(idOrStatus) {
+    super(`Sandbox is not ready: ${idOrStatus}`, "NOT_READY", { id: idOrStatus });
+    this.name = "SandboxNotReadyError";
+  }
+};
+var IsolationUnavailableError = class extends SandboxError {
+  constructor(backend, reason) {
+    super(`Isolation backend '${backend}' is not available: ${reason}`, "ISOLATION_UNAVAILABLE", { backend, reason });
+    this.backend = backend;
+    this.reason = reason;
+    this.name = "IsolationUnavailableError";
+  }
+};
+var MountError = class extends SandboxError {
+  constructor(message, mountPath, details) {
+    super(message, "MOUNT_ERROR", { ...details, mountPath });
+    this.mountPath = mountPath;
+    this.name = "MountError";
+  }
+};
+var MountNotSupportedError = class extends SandboxError {
+  constructor(sandboxProvider) {
+    super(`Sandbox provider '${sandboxProvider}' does not support mounting`, "MOUNT_NOT_SUPPORTED", {
+      sandboxProvider
+    });
+    this.name = "MountNotSupportedError";
+  }
+};
+var FilesystemNotMountableError = class extends SandboxError {
+  constructor(filesystemProvider, reason) {
+    const message = reason ? `Filesystem '${filesystemProvider}' cannot be mounted: ${reason}` : `Filesystem '${filesystemProvider}' does not support mounting`;
+    super(message, "FILESYSTEM_NOT_MOUNTABLE", { filesystemProvider, reason });
+    this.name = "FilesystemNotMountableError";
+  }
+};
+var MountManager = class {
+  _entries = /* @__PURE__ */ new Map();
+  _mountFn;
+  _onMount;
+  _sandbox;
+  _workspace;
+  logger;
+  constructor(config) {
+    this._mountFn = config.mount;
+    this.logger = config.logger;
+  }
+  /**
+   * Set the sandbox and workspace references for onMount hook args.
+   * Called by Workspace during construction.
+   */
+  setContext(context) {
+    this._sandbox = context.sandbox;
+    this._workspace = context.workspace;
+  }
+  /**
+   * Set the onMount hook for custom mount handling.
+   * Called before each mount - can skip, handle, or defer to default.
+   */
+  setOnMount(hook) {
+    this._onMount = hook;
+  }
+  /**
+   * Update the logger instance.
+   * Called when the sandbox receives a logger from Mastra.
+   * @internal
+   */
+  __setLogger(logger) {
+    this.logger = logger;
+  }
+  // ---------------------------------------------------------------------------
+  // Entry Access
+  // ---------------------------------------------------------------------------
+  /**
+   * Get all mount entries.
+   */
+  get entries() {
+    return this._entries;
+  }
+  /**
+   * Get a mount entry by path.
+   */
+  get(path4) {
+    return this._entries.get(path4);
+  }
+  /**
+   * Check if a mount exists at the given path.
+   */
+  has(path4) {
+    return this._entries.has(path4);
+  }
+  // ---------------------------------------------------------------------------
+  // Entry Modification
+  // ---------------------------------------------------------------------------
+  /**
+   * Add pending mounts from workspace config.
+   * These will be processed when `processPending()` is called.
+   */
+  add(mounts) {
+    const paths = Object.keys(mounts);
+    this.logger.debug(`Adding ${paths.length} pending mount(s)`, { paths });
+    for (const [path4, filesystem] of Object.entries(mounts)) {
+      this._entries.set(path4, {
+        filesystem,
+        state: "pending"
+      });
+    }
+  }
+  /**
+   * Update a mount entry's state.
+   * Creates the entry if it doesn't exist.
+   */
+  set(path4, updates) {
+    const existing = this._entries.get(path4);
+    if (existing) {
+      existing.state = updates.state;
+      if (updates.config) {
+        existing.config = updates.config;
+        existing.configHash = this.hashConfig(updates.config);
+      }
+      if ("error" in updates) {
+        existing.error = updates.error;
+      }
+    } else if (updates.filesystem) {
+      this._entries.set(path4, {
+        filesystem: updates.filesystem,
+        state: updates.state,
+        config: updates.config,
+        configHash: updates.config ? this.hashConfig(updates.config) : void 0,
+        error: updates.error
+      });
+    } else {
+      this.logger.debug(`set() called for unknown path "${path4}" without filesystem \u2014 no entry created`);
+    }
+  }
+  /**
+   * Delete a mount entry.
+   */
+  delete(path4) {
+    return this._entries.delete(path4);
+  }
+  /**
+   * Clear all mount entries.
+   */
+  clear() {
+    this._entries.clear();
+  }
+  // ---------------------------------------------------------------------------
+  // Mount Processing
+  // ---------------------------------------------------------------------------
+  /**
+   * Process all pending mounts.
+   * Call this after sandbox is ready (in start()).
+   */
+  async processPending() {
+    const pendingCount = [...this._entries.values()].filter((e) => e.state === "pending").length;
+    if (pendingCount === 0) {
+      return;
+    }
+    this.logger.debug(`Processing ${pendingCount} pending mount(s)`);
+    for (const [path4, entry] of this._entries) {
+      if (entry.state !== "pending") {
+        continue;
+      }
+      const fsProvider = entry.filesystem.provider;
+      const config = entry.filesystem.getMountConfig?.();
+      if (this._onMount) {
+        try {
+          const hookResult = await this._onMount({
+            filesystem: entry.filesystem,
+            mountPath: path4,
+            config,
+            sandbox: this._sandbox,
+            workspace: this._workspace
+          });
+          if (hookResult === false) {
+            entry.state = "unsupported";
+            entry.error = "Skipped by onMount hook";
+            this.logger.debug(`Mount skipped by onMount hook`, { path: path4, provider: fsProvider });
+            continue;
+          }
+          if (hookResult && typeof hookResult === "object") {
+            if (hookResult.success) {
+              entry.state = "mounted";
+              entry.config = config;
+              entry.configHash = config ? this.hashConfig(config) : void 0;
+              this.logger.info(`Mount handled by onMount hook`, { path: path4, provider: fsProvider });
+            } else {
+              entry.state = "error";
+              entry.error = hookResult.error ?? "Mount hook failed";
+              this.logger.error(`Mount hook failed`, { path: path4, provider: fsProvider, error: entry.error });
+            }
+            continue;
+          }
+        } catch (err) {
+          entry.state = "error";
+          entry.error = `Mount hook error: ${String(err)}`;
+          this.logger.error(`Mount hook threw error`, { path: path4, provider: fsProvider, error: entry.error });
+          continue;
+        }
+      }
+      if (!config) {
+        entry.state = "unsupported";
+        entry.error = "Filesystem does not support mounting";
+        this.logger.debug(`Filesystem does not support mounting`, { path: path4, provider: fsProvider });
+        continue;
+      }
+      entry.config = config;
+      entry.configHash = this.hashConfig(config);
+      entry.state = "mounting";
+      this.logger.debug(`Mounting filesystem`, { path: path4, provider: fsProvider, type: config.type });
+      try {
+        const result = await this._mountFn(entry.filesystem, path4);
+        if (result.success) {
+          entry.state = "mounted";
+          this.logger.info(`Mount successful`, { path: path4, provider: fsProvider });
+        } else {
+          entry.state = "error";
+          entry.error = result.error ?? "Mount failed";
+          this.logger.error(`Mount failed`, { path: path4, provider: fsProvider, error: entry.error });
+        }
+      } catch (err) {
+        entry.state = "error";
+        entry.error = String(err);
+        this.logger.error(`Mount threw error`, { path: path4, provider: fsProvider, error: entry.error });
+      }
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Marker File Helpers
+  // ---------------------------------------------------------------------------
+  /**
+   * Generate a marker filename for a mount path.
+   * Used by sandboxes to store mount metadata for reconnection detection.
+   *
+   * @param mountPath - The mount path to generate a filename for
+   * @returns A safe filename like "mount-abc123"
+   */
+  markerFilename(mountPath) {
+    let hash = 0;
+    for (let i = 0; i < mountPath.length; i++) {
+      const char = mountPath.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash |= 0;
+    }
+    return `mount-${Math.abs(hash).toString(36)}`;
+  }
+  /**
+   * Generate marker file content for a mount path.
+   * Format: "path|configHash" - used for detecting config changes on reconnect.
+   *
+   * @param mountPath - The mount path
+   * @returns Marker content string, or null if no config hash available
+   */
+  getMarkerContent(mountPath) {
+    const entry = this._entries.get(mountPath);
+    if (!entry?.configHash) {
+      return null;
+    }
+    return `${mountPath}|${entry.configHash}`;
+  }
+  /**
+   * Parse marker file content.
+   *
+   * @param content - The marker file content (format: "path|configHash")
+   * @returns Parsed path and configHash, or null if invalid format
+   */
+  parseMarkerContent(content) {
+    const separatorIndex = content.lastIndexOf("|");
+    if (separatorIndex <= 0) {
+      return null;
+    }
+    const path4 = content.slice(0, separatorIndex);
+    const configHash = content.slice(separatorIndex + 1);
+    if (!path4 || !configHash) return null;
+    return { path: path4, configHash };
+  }
+  /**
+   * Check if a config hash matches the expected hash for a mount path.
+   *
+   * @param mountPath - The mount path to check
+   * @param storedHash - The hash from the marker file
+   * @returns true if the hashes match
+   */
+  isConfigMatching(mountPath, storedHash) {
+    const entry = this._entries.get(mountPath);
+    return entry?.configHash === storedHash;
+  }
+  /**
+   * Compute a hash for a mount config. Used for comparing configs across mounts.
+   *
+   * @param config - The config to hash
+   * @returns A hash string suitable for comparison
+   */
+  computeConfigHash(config) {
+    return this.hashConfig(config);
+  }
+  // ---------------------------------------------------------------------------
+  // Internal
+  // ---------------------------------------------------------------------------
+  /**
+   * Hash a mount config for comparison.
+   */
+  hashConfig(config) {
+    const normalized = JSON.stringify(this.sortKeysDeep(config));
+    return createHash("sha256").update(normalized).digest("hex").slice(0, 16);
+  }
+  sortKeysDeep(obj) {
+    if (obj === null || typeof obj !== "object") return obj;
+    if (Array.isArray(obj)) return obj.map((item) => this.sortKeysDeep(item));
+    return Object.keys(obj).sort().reduce(
+      (acc, key) => {
+        acc[key] = this.sortKeysDeep(obj[key]);
+        return acc;
+      },
+      {}
+    );
+  }
+};
+
+// src/workspace/sandbox/mastra-sandbox.ts
+var MastraSandbox = class extends MastraBase {
+  /** Mount manager - automatically created if subclass implements mount() */
+  mounts;
+  // ---------------------------------------------------------------------------
+  // Lifecycle Promise Tracking (prevents race conditions)
+  // ---------------------------------------------------------------------------
+  /** Promise for _start() to prevent race conditions from concurrent calls */
+  _startPromise;
+  /** Promise for _stop() to prevent race conditions from concurrent calls */
+  _stopPromise;
+  /** Promise for _destroy() to prevent race conditions from concurrent calls */
+  _destroyPromise;
+  /** Lifecycle callbacks */
+  _onStart;
+  _onStop;
+  _onDestroy;
+  constructor(options) {
+    super({ name: options.name, component: RegisteredLogger.WORKSPACE });
+    this._onStart = options.onStart;
+    this._onStop = options.onStop;
+    this._onDestroy = options.onDestroy;
+    if (this.mount) {
+      this.mounts = new MountManager({
+        mount: this.mount.bind(this),
+        logger: this.logger
+      });
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // Lifecycle Wrappers (race-condition-safe)
+  // ---------------------------------------------------------------------------
+  /**
+   * Start the sandbox (wrapper with status management and race-condition safety).
+   *
+   * This method is race-condition-safe - concurrent calls will return the same promise.
+   * Handles status management and automatically processes pending mounts after startup.
+   *
+   * Subclasses override `start()` to provide their startup logic.
+   */
+  async _start() {
+    if (this.status === "running") {
+      return;
+    }
+    if (this._stopPromise) await this._stopPromise;
+    if (this._destroyPromise) await this._destroyPromise;
+    if (this.status === "destroyed") {
+      throw new Error("Cannot start a destroyed sandbox");
+    }
+    if (this._startPromise) {
+      return this._startPromise;
+    }
+    this._startPromise = this._executeStart();
+    try {
+      await this._startPromise;
+    } finally {
+      this._startPromise = void 0;
+    }
+  }
+  /**
+   * Internal start execution - handles status and mount processing.
+   */
+  async _executeStart() {
+    this.status = "starting";
+    try {
+      await this.start();
+      this.status = "running";
+      try {
+        await this._onStart?.({ sandbox: this });
+      } catch (error) {
+        this.logger.warn("onStart callback failed", { error });
+      }
+    } catch (error) {
+      this.status = "error";
+      throw error;
+    }
+    try {
+      await this.mounts?.processPending();
+    } catch (error) {
+      this.logger.warn("Unexpected error processing pending mounts", { error });
+    }
+  }
+  /**
+   * Override this method to implement sandbox startup logic.
+   *
+   * Called by `_start()` after status is set to 'starting'.
+   * Status will be set to 'running' on success, 'error' on failure.
+   *
+   * @example
+   * ```typescript
+   * async start(): Promise<void> {
+   *   this._sandbox = await Sandbox.create({ ... });
+   * }
+   * ```
+   */
+  async start() {
   }
-  if (name.length === 0) {
-    errors.push(`${fieldPath}: Skill name cannot be empty`);
-    return errors;
+  /**
+   * Ensure the sandbox is running.
+   *
+   * Calls `_start()` if status is not 'running'. Useful for lazy initialization
+   * where operations should automatically start the sandbox if needed.
+   *
+   * @throws {SandboxNotReadyError} if the sandbox fails to reach 'running' status
+   *
+   * @example
+   * ```typescript
+   * async executeCommand(command: string): Promise<CommandResult> {
+   *   await this.ensureRunning();
+   *   // Now safe to use the sandbox
+   * }
+   * ```
+   */
+  async ensureRunning() {
+    if (this.status !== "running") {
+      await this._start();
+    }
+    if (this.status !== "running") {
+      throw new SandboxNotReadyError(this.id);
+    }
   }
-  if (name.length > SKILL_LIMITS.MAX_NAME_LENGTH) {
-    errors.push(`${fieldPath}: Skill name must be ${SKILL_LIMITS.MAX_NAME_LENGTH} characters or less`);
+  /**
+   * Stop the sandbox (wrapper with status management and race-condition safety).
+   *
+   * This method is race-condition-safe - concurrent calls will return the same promise.
+   * Handles status management.
+   *
+   * Subclasses override `stop()` to provide their stop logic.
+   */
+  async _stop() {
+    if (this.status === "stopped") {
+      return;
+    }
+    if (this._startPromise) await this._startPromise.catch(() => {
+    });
+    if (this._stopPromise) {
+      return this._stopPromise;
+    }
+    this._stopPromise = this._executeStop();
+    try {
+      await this._stopPromise;
+    } finally {
+      this._stopPromise = void 0;
+    }
   }
-  if (!/^[a-z0-9-]+$/.test(name)) {
-    errors.push(`${fieldPath}: Skill name must contain only lowercase letters, numbers, and hyphens`);
+  /**
+   * Internal stop execution - handles status.
+   */
+  async _executeStop() {
+    this.status = "stopping";
+    try {
+      await this._onStop?.({ sandbox: this });
+      await this.stop();
+      this.status = "stopped";
+    } catch (error) {
+      this.status = "error";
+      throw error;
+    }
   }
-  if (name.startsWith("-") || name.endsWith("-")) {
-    errors.push(`${fieldPath}: Skill name must not start or end with a hyphen`);
+  /**
+   * Override this method to implement sandbox stop logic.
+   *
+   * Called by `_stop()` after status is set to 'stopping'.
+   * Status will be set to 'stopped' on success, 'error' on failure.
+   */
+  async stop() {
   }
-  if (name.includes("--")) {
-    errors.push(`${fieldPath}: Skill name must not contain consecutive hyphens`);
+  /**
+   * Destroy the sandbox and clean up all resources (wrapper with status management).
+   *
+   * This method is race-condition-safe - concurrent calls will return the same promise.
+   * Handles status management.
+   *
+   * Subclasses override `destroy()` to provide their destroy logic.
+   */
+  async _destroy() {
+    if (this.status === "destroyed") {
+      return;
+    }
+    if (this._startPromise) await this._startPromise.catch(() => {
+    });
+    if (this._stopPromise) await this._stopPromise.catch(() => {
+    });
+    if (this._destroyPromise) {
+      return this._destroyPromise;
+    }
+    this._destroyPromise = this._executeDestroy();
+    try {
+      await this._destroyPromise;
+    } finally {
+      this._destroyPromise = void 0;
+    }
   }
-  return errors;
-}
-function validateSkillDescription(description) {
-  const errors = [];
-  const fieldPath = "description";
-  if (typeof description !== "string") {
-    errors.push(`${fieldPath}: Expected string, received ${typeof description}`);
-    return errors;
+  /**
+   * Internal destroy execution - handles status.
+   */
+  async _executeDestroy() {
+    this.status = "destroying";
+    try {
+      await this._onDestroy?.({ sandbox: this });
+      await this.destroy();
+      this.status = "destroyed";
+    } catch (error) {
+      this.status = "error";
+      throw error;
+    }
   }
-  if (description.length === 0) {
-    errors.push(`${fieldPath}: Skill description cannot be empty`);
-    return errors;
+  /**
+   * Override this method to implement sandbox destroy logic.
+   *
+   * Called by `_destroy()` after status is set to 'destroying'.
+   * Status will be set to 'destroyed' on success, 'error' on failure.
+   */
+  async destroy() {
   }
-  if (description.length > SKILL_LIMITS.MAX_DESCRIPTION_LENGTH) {
-    errors.push(`${fieldPath}: Skill description must be ${SKILL_LIMITS.MAX_DESCRIPTION_LENGTH} characters or less`);
+  // ---------------------------------------------------------------------------
+  // Logger Propagation
+  // ---------------------------------------------------------------------------
+  /**
+   * Override to propagate logger to MountManager.
+   * @internal
+   */
+  __setLogger(logger) {
+    super.__setLogger(logger);
+    this.mounts?.__setLogger(logger);
   }
-  if (description.trim().length === 0) {
-    errors.push(`${fieldPath}: Skill description cannot be only whitespace`);
+};
+
+// src/workspace/line-utils.ts
+function extractLines(content, startLine, endLine) {
+  const allLines = content.split("\n");
+  const totalLines = allLines.length;
+  const start = Math.max(1, startLine ?? 1);
+  const end = Math.min(totalLines, endLine ?? totalLines);
+  const extractedLines = allLines.slice(start - 1, end);
+  return {
+    content: extractedLines.join("\n"),
+    lines: { start, end },
+    totalLines
+  };
+}
+function extractLinesWithLimit(content, offset, limit) {
+  const startLine = offset ?? 1;
+  const endLine = limit ? startLine + limit - 1 : void 0;
+  return extractLines(content, startLine, endLine);
+}
+function formatWithLineNumbers(content, startLineNumber = 1) {
+  const lines = content.split("\n");
+  const maxLineNum = startLineNumber + lines.length - 1;
+  const padWidth = Math.max(6, String(maxLineNum).length + 1);
+  return lines.map((line, i) => {
+    const lineNum = startLineNumber + i;
+    return `${String(lineNum).padStart(padWidth)}\u2192${line}`;
+  }).join("\n");
+}
+function countOccurrences(content, searchString) {
+  if (!searchString) return 0;
+  let count = 0;
+  let position = 0;
+  while ((position = content.indexOf(searchString, position)) !== -1) {
+    count++;
+    position += searchString.length;
   }
-  return errors;
+  return count;
 }
-function validateSkillLicense(license) {
-  const errors = [];
-  const fieldPath = "license";
-  if (license === void 0 || license === null) {
-    return errors;
+function replaceString(content, oldString, newString, replaceAll = false) {
+  const count = countOccurrences(content, oldString);
+  if (count === 0) {
+    throw new StringNotFoundError(oldString);
   }
-  if (typeof license !== "string") {
-    errors.push(`${fieldPath}: Expected string, received ${typeof license}`);
+  if (!replaceAll && count > 1) {
+    throw new StringNotUniqueError(oldString, count);
+  }
+  if (replaceAll) {
+    const result = content.split(oldString).join(newString);
+    return { content: result, replacements: count };
+  } else {
+    const result = content.replace(oldString, newString);
+    return { content: result, replacements: 1 };
   }
-  return errors;
-}
-function validateSkillCompatibility(_compatibility) {
-  return [];
 }
-function validateSkillMetadataField(metadata) {
-  const errors = [];
-  const fieldPath = "metadata";
-  if (metadata === void 0 || metadata === null) {
-    return errors;
+var StringNotFoundError = class extends Error {
+  constructor(searchString) {
+    super(`The specified text was not found. Make sure you use the exact text from the file.`);
+    this.searchString = searchString;
+    this.name = "StringNotFoundError";
   }
-  if (typeof metadata !== "object" || Array.isArray(metadata)) {
-    errors.push(`${fieldPath}: Expected object, received ${Array.isArray(metadata) ? "array" : typeof metadata}`);
-    return errors;
+};
+var StringNotUniqueError = class extends Error {
+  constructor(searchString, occurrences) {
+    super(
+      `The specified text appears ${occurrences} times. Provide more surrounding context to make the match unique, or use replace_all to replace all occurrences.`
+    );
+    this.searchString = searchString;
+    this.occurrences = occurrences;
+    this.name = "StringNotUniqueError";
   }
-  return errors;
-}
-function estimateTokens(text) {
-  const words = text.split(/\s+/).filter(Boolean).length;
-  return Math.ceil(words * 1.3);
+};
+
+// src/workspace/search/bm25.ts
+var DEFAULT_STOPWORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "as",
+  "at",
+  "be",
+  "by",
+  "for",
+  "from",
+  "has",
+  "he",
+  "in",
+  "is",
+  "it",
+  "its",
+  "of",
+  "on",
+  "or",
+  "that",
+  "the",
+  "to",
+  "was",
+  "were",
+  "will",
+  "with"
+]);
+var DEFAULT_TOKENIZE_OPTIONS = {
+  lowercase: true,
+  removePunctuation: true,
+  minLength: 2,
+  stopwords: DEFAULT_STOPWORDS,
+  splitPattern: /\s+/
+};
+function tokenize(text, options = {}) {
+  const opts = { ...DEFAULT_TOKENIZE_OPTIONS, ...options };
+  let processed = text;
+  if (opts.lowercase) {
+    processed = processed.toLowerCase();
+  }
+  if (opts.removePunctuation) {
+    processed = processed.replace(/[^\w\s]/g, " ");
+  }
+  const tokens = processed.split(opts.splitPattern).filter((token) => {
+    if (token.length < opts.minLength) {
+      return false;
+    }
+    if (opts.stopwords?.has(token)) {
+      return false;
+    }
+    return true;
+  });
+  return tokens;
 }
-function countLines(text) {
-  return text.split("\n").length;
+function findLineRange(content, queryTerms, options = {}) {
+  if (queryTerms.length === 0) return void 0;
+  const lines = content.split("\n");
+  const defaultOpts = { lowercase: true, removePunctuation: true, minLength: 2 };
+  const opts = { ...defaultOpts, ...options };
+  const normalizedTerms = new Set(queryTerms.map((t) => opts.lowercase ? t.toLowerCase() : t));
+  let firstMatchLine;
+  let lastMatchLine;
+  for (let i = 0; i < lines.length; i++) {
+    const lineTokens = tokenize(lines[i], options);
+    for (const token of lineTokens) {
+      if (normalizedTerms.has(token)) {
+        const lineNum = i + 1;
+        if (firstMatchLine === void 0) {
+          firstMatchLine = lineNum;
+        }
+        lastMatchLine = lineNum;
+        break;
+      }
+    }
+  }
+  if (firstMatchLine !== void 0 && lastMatchLine !== void 0) {
+    return { start: firstMatchLine, end: lastMatchLine };
+  }
+  return void 0;
 }
-function validateSkillMetadata(metadata, dirName, instructions) {
-  const errors = [];
-  const warnings = [];
-  if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
-    errors.push(
-      `Expected object, received ${metadata === null ? "null" : Array.isArray(metadata) ? "array" : typeof metadata}`
-    );
-    return { valid: false, errors, warnings };
+function computeTermFrequencies(tokens) {
+  const frequencies = /* @__PURE__ */ new Map();
+  for (const token of tokens) {
+    frequencies.set(token, (frequencies.get(token) || 0) + 1);
   }
-  const data = metadata;
-  errors.push(...validateSkillName(data.name));
-  errors.push(...validateSkillDescription(data.description));
-  errors.push(...validateSkillLicense(data.license));
-  errors.push(...validateSkillCompatibility());
-  errors.push(...validateSkillMetadataField(data.metadata));
-  if (dirName && typeof data.name === "string" && data.name !== dirName) {
-    errors.push(`Skill name "${data.name}" must match directory name "${dirName}"`);
+  return frequencies;
+}
+var BM25Index = class _BM25Index {
+  /** BM25 k1 parameter */
+  k1;
+  /** BM25 b parameter */
+  b;
+  /** Documents in the index */
+  #documents = /* @__PURE__ */ new Map();
+  /** Inverted index: term -> document IDs containing the term */
+  #invertedIndex = /* @__PURE__ */ new Map();
+  /** Document frequency: term -> number of documents containing the term */
+  #documentFrequency = /* @__PURE__ */ new Map();
+  /** Average document length */
+  #avgDocLength = 0;
+  /** Total number of documents */
+  #docCount = 0;
+  /** Tokenization options */
+  #tokenizeOptions;
+  constructor(config = {}, tokenizeOptions = {}) {
+    this.k1 = config.k1 ?? 1.5;
+    this.b = config.b ?? 0.75;
+    this.#tokenizeOptions = tokenizeOptions;
   }
-  if (instructions) {
-    const lineCount = countLines(instructions);
-    const tokenEstimate = estimateTokens(instructions);
-    if (lineCount > SKILL_LIMITS.MAX_INSTRUCTION_LINES) {
-      warnings.push(
-        `Instructions have ${lineCount} lines (recommended: <${SKILL_LIMITS.MAX_INSTRUCTION_LINES}). Consider moving content to references/.`
-      );
+  /**
+   * Add a document to the index
+   */
+  add(id, content, metadata) {
+    if (this.#documents.has(id)) {
+      this.remove(id);
     }
-    if (tokenEstimate > SKILL_LIMITS.MAX_INSTRUCTION_TOKENS) {
-      warnings.push(
-        `Instructions have ~${tokenEstimate} estimated tokens (recommended: <${SKILL_LIMITS.MAX_INSTRUCTION_TOKENS}). Consider moving content to references/.`
-      );
+    const tokens = tokenize(content, this.#tokenizeOptions);
+    const termFrequencies = computeTermFrequencies(tokens);
+    const doc = {
+      id,
+      content,
+      tokens,
+      termFrequencies,
+      length: tokens.length,
+      metadata
+    };
+    this.#documents.set(id, doc);
+    this.#docCount++;
+    for (const term of termFrequencies.keys()) {
+      if (!this.#invertedIndex.has(term)) {
+        this.#invertedIndex.set(term, /* @__PURE__ */ new Set());
+      }
+      this.#invertedIndex.get(term).add(id);
+      this.#documentFrequency.set(term, (this.#documentFrequency.get(term) || 0) + 1);
     }
+    this.#updateAvgDocLength();
   }
-  return {
-    valid: errors.length === 0,
-    errors,
-    warnings
-  };
-}
-function isEnoentError(error) {
-  return error !== null && typeof error === "object" && "code" in error && error.code === "ENOENT";
-}
-function isEexistError(error) {
-  return error !== null && typeof error === "object" && "code" in error && error.code === "EEXIST";
-}
-var MIME_TYPES = {
-  // Text
-  txt: "text/plain",
-  html: "text/html",
-  htm: "text/html",
-  css: "text/css",
-  csv: "text/csv",
-  md: "text/markdown",
-  // Code
-  js: "application/javascript",
-  mjs: "application/javascript",
-  ts: "application/typescript",
-  tsx: "application/typescript",
-  jsx: "application/javascript",
-  json: "application/json",
-  xml: "application/xml",
-  yaml: "text/yaml",
-  yml: "text/yaml",
-  // Programming languages
-  py: "text/x-python",
-  rb: "text/x-ruby",
-  go: "text/x-go",
-  rs: "text/x-rust",
-  java: "text/x-java",
-  c: "text/x-c",
-  cpp: "text/x-c++",
-  h: "text/x-c",
-  hpp: "text/x-c++",
-  sh: "text/x-sh",
-  bash: "text/x-sh",
-  zsh: "text/x-sh",
-  // Config
-  toml: "text/toml",
-  ini: "text/plain",
-  env: "text/plain",
-  // Database/Query
-  sql: "text/x-sql",
-  graphql: "application/graphql",
-  gql: "application/graphql",
-  // Frameworks
-  vue: "text/x-vue",
-  // Images
-  png: "image/png",
-  jpg: "image/jpeg",
-  jpeg: "image/jpeg",
-  gif: "image/gif",
-  svg: "image/svg+xml",
-  webp: "image/webp",
-  ico: "image/x-icon",
-  // Documents
-  pdf: "application/pdf"
-};
-function getMimeType(filename) {
-  const ext = nodePath.extname(filename).slice(1).toLowerCase();
-  return MIME_TYPES[ext] ?? "application/octet-stream";
-}
-var TEXT_EXTENSIONS = /* @__PURE__ */ new Set([
-  ".md",
-  ".txt",
-  ".json",
-  ".yaml",
-  ".yml",
-  ".js",
-  ".mjs",
-  ".ts",
-  ".tsx",
-  ".jsx",
-  ".py",
-  ".rb",
-  ".go",
-  ".rs",
-  ".java",
-  ".c",
-  ".cpp",
-  ".h",
-  ".hpp",
-  ".sh",
-  ".bash",
-  ".zsh",
-  ".html",
-  ".htm",
-  ".css",
-  ".xml",
-  ".toml",
-  ".ini",
-  ".env",
-  ".csv",
-  ".sql",
-  ".graphql",
-  ".gql",
-  ".vue",
-  ".svg"
-]);
-function isTextFile(filename) {
-  const ext = nodePath.extname(filename).toLowerCase();
-  return TEXT_EXTENSIONS.has(ext);
-}
-async function fsExists(absolutePath) {
-  try {
-    await fs2.access(absolutePath);
+  /**
+   * Remove a document from the index
+   */
+  remove(id) {
+    const doc = this.#documents.get(id);
+    if (!doc) {
+      return false;
+    }
+    for (const term of doc.termFrequencies.keys()) {
+      const docIds = this.#invertedIndex.get(term);
+      if (docIds) {
+        docIds.delete(id);
+        if (docIds.size === 0) {
+          this.#invertedIndex.delete(term);
+          this.#documentFrequency.delete(term);
+        } else {
+          this.#documentFrequency.set(term, (this.#documentFrequency.get(term) || 1) - 1);
+        }
+      }
+    }
+    this.#documents.delete(id);
+    this.#docCount--;
+    this.#updateAvgDocLength();
     return true;
-  } catch {
-    return false;
   }
-}
-async function fsStat(absolutePath, userPath) {
-  try {
-    const stats = await fs2.stat(absolutePath);
-    return {
-      name: nodePath.basename(absolutePath),
-      type: stats.isDirectory() ? "directory" : "file",
-      size: stats.size,
-      createdAt: stats.birthtime,
-      modifiedAt: stats.mtime,
-      mimeType: stats.isFile() ? getMimeType(absolutePath) : void 0
-    };
-  } catch (error) {
-    if (isEnoentError(error)) {
-      throw new FileNotFoundError(userPath);
+  /**
+   * Clear all documents from the index
+   */
+  clear() {
+    this.#documents.clear();
+    this.#invertedIndex.clear();
+    this.#documentFrequency.clear();
+    this.#docCount = 0;
+    this.#avgDocLength = 0;
+  }
+  /**
+   * Search for documents matching the query
+   */
+  search(query, topK = 10, minScore = 0) {
+    const queryTokens = tokenize(query, this.#tokenizeOptions);
+    if (queryTokens.length === 0 || this.#docCount === 0) {
+      return [];
+    }
+    const scores = /* @__PURE__ */ new Map();
+    for (const queryTerm of queryTokens) {
+      const docIds = this.#invertedIndex.get(queryTerm);
+      if (!docIds) {
+        continue;
+      }
+      const df = this.#documentFrequency.get(queryTerm) || 0;
+      const idf = this.#computeIDF(df);
+      for (const docId of docIds) {
+        const doc = this.#documents.get(docId);
+        const tf = doc.termFrequencies.get(queryTerm) || 0;
+        const termScore = this.#computeTermScore(tf, doc.length, idf);
+        scores.set(docId, (scores.get(docId) || 0) + termScore);
+      }
     }
-    throw error;
+    const results = [];
+    for (const [docId, score] of scores.entries()) {
+      if (score >= minScore) {
+        const doc = this.#documents.get(docId);
+        results.push({
+          id: docId,
+          content: doc.content,
+          score,
+          metadata: doc.metadata
+        });
+      }
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, topK);
   }
-}
-
-// src/workspace/filesystem/local-filesystem.ts
-var LocalFilesystem = class extends MastraFilesystem {
-  id;
-  name = "LocalFilesystem";
-  provider = "local";
-  readOnly;
-  status = "stopped";
-  _basePath;
-  _contained;
   /**
-   * The absolute base path on disk where files are stored.
-   * Useful for understanding how workspace paths map to disk paths.
+   * Get a document by ID
    */
-  get basePath() {
-    return this._basePath;
-  }
-  constructor(options) {
-    super({ name: "LocalFilesystem" });
-    this.id = options.id ?? this.generateId();
-    this._basePath = nodePath.resolve(options.basePath);
-    this._contained = options.contained ?? true;
-    this.readOnly = options.readOnly;
-  }
-  generateId() {
-    return `local-fs-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+  get(id) {
+    return this.#documents.get(id);
   }
-  toBuffer(content) {
-    if (Buffer.isBuffer(content)) return content;
-    if (content instanceof Uint8Array) return Buffer.from(content);
-    return Buffer.from(content, "utf-8");
+  /**
+   * Check if a document exists in the index
+   */
+  has(id) {
+    return this.#documents.has(id);
   }
-  resolvePath(inputPath) {
-    const cleanedPath = inputPath.replace(/^\/+/, "");
-    const normalizedInput = nodePath.normalize(cleanedPath);
-    const absolutePath = nodePath.resolve(this._basePath, normalizedInput);
-    if (this._contained) {
-      const relative2 = nodePath.relative(this._basePath, absolutePath);
-      if (relative2.startsWith("..") || nodePath.isAbsolute(relative2)) {
-        throw new PermissionError(inputPath, "access");
-      }
-    }
-    return absolutePath;
+  /**
+   * Get the number of documents in the index
+   */
+  get size() {
+    return this.#docCount;
   }
-  toRelativePath(absolutePath) {
-    return "/" + nodePath.relative(this._basePath, absolutePath).replace(/\\/g, "/");
+  /**
+   * Get all document IDs
+   */
+  get documentIds() {
+    return Array.from(this.#documents.keys());
   }
-  assertWritable(operation) {
-    if (this.readOnly) {
-      throw new WorkspaceReadOnlyError(operation);
+  /**
+   * Serialize the index to a JSON-compatible object
+   */
+  serialize() {
+    const documents = [];
+    for (const [id, doc] of this.#documents.entries()) {
+      documents.push({
+        id,
+        content: doc.content,
+        tokens: doc.tokens,
+        termFrequencies: Object.fromEntries(doc.termFrequencies),
+        length: doc.length,
+        metadata: doc.metadata
+      });
     }
+    return {
+      k1: this.k1,
+      b: this.b,
+      documents,
+      avgDocLength: this.#avgDocLength
+    };
   }
   /**
-   * Verify that the resolved path doesn't escape basePath via symlinks.
-   * Uses realpath to resolve symlinks and check the actual target.
+   * Deserialize an index from a JSON object
    */
-  async assertPathContained(absolutePath) {
-    if (!this._contained) return;
-    let baseReal;
-    try {
-      baseReal = await fs2.realpath(this._basePath);
-    } catch (error) {
-      if (isEnoentError(error)) {
-        throw new DirectoryNotFoundError(this._basePath);
-      }
-      throw error;
-    }
-    let targetReal;
-    try {
-      targetReal = await fs2.realpath(absolutePath);
-    } catch (error) {
-      if (isEnoentError(error)) {
-        let parentPath = absolutePath;
-        while (true) {
-          const nextParent = nodePath.dirname(parentPath);
-          if (nextParent === parentPath) {
-            throw new DirectoryNotFoundError(absolutePath);
-          }
-          parentPath = nextParent;
-          try {
-            targetReal = await fs2.realpath(parentPath);
-            break;
-          } catch (parentError) {
-            if (!isEnoentError(parentError)) {
-              throw parentError;
-            }
-          }
+  static deserialize(data, tokenizeOptions = {}) {
+    const index = new _BM25Index({ k1: data.k1, b: data.b }, tokenizeOptions);
+    for (const doc of data.documents) {
+      const termFrequencies = new Map(Object.entries(doc.termFrequencies));
+      const document = {
+        id: doc.id,
+        content: doc.content,
+        tokens: doc.tokens,
+        termFrequencies,
+        length: doc.length,
+        metadata: doc.metadata
+      };
+      index.#documents.set(doc.id, document);
+      index.#docCount++;
+      for (const term of termFrequencies.keys()) {
+        if (!index.#invertedIndex.has(term)) {
+          index.#invertedIndex.set(term, /* @__PURE__ */ new Set());
         }
-      } else {
-        throw error;
+        index.#invertedIndex.get(term).add(doc.id);
+        index.#documentFrequency.set(term, (index.#documentFrequency.get(term) || 0) + 1);
       }
     }
-    if (targetReal !== baseReal && !targetReal.startsWith(baseReal + nodePath.sep)) {
-      throw new PermissionError(absolutePath, "access");
-    }
+    index.#avgDocLength = data.avgDocLength;
+    return index;
   }
-  async ensureInitialized() {
-    if (this.status !== "running") {
-      await this.init();
+  /**
+   * Update average document length after add/remove operations
+   */
+  #updateAvgDocLength() {
+    if (this.#docCount === 0) {
+      this.#avgDocLength = 0;
+      return;
     }
-  }
-  async readFile(inputPath, options) {
-    this.logger.debug("Reading file", { path: inputPath, encoding: options?.encoding });
-    await this.ensureInitialized();
-    const absolutePath = this.resolvePath(inputPath);
-    await this.assertPathContained(absolutePath);
-    try {
-      const stats = await fs2.stat(absolutePath);
-      if (stats.isDirectory()) {
-        throw new IsDirectoryError(inputPath);
-      }
-      if (options?.encoding) {
-        return await fs2.readFile(absolutePath, { encoding: options.encoding });
-      }
-      return await fs2.readFile(absolutePath);
-    } catch (error) {
-      if (error instanceof IsDirectoryError) throw error;
-      if (isEnoentError(error)) {
-        throw new FileNotFoundError(inputPath);
-      }
-      throw error;
+    let totalLength = 0;
+    for (const doc of this.#documents.values()) {
+      totalLength += doc.length;
     }
+    this.#avgDocLength = totalLength / this.#docCount;
   }
-  async writeFile(inputPath, content, options) {
-    const contentSize = Buffer.isBuffer(content) ? content.length : content.length;
-    this.logger.debug("Writing file", { path: inputPath, size: contentSize, recursive: options?.recursive });
-    await this.ensureInitialized();
-    this.assertWritable("writeFile");
-    const absolutePath = this.resolvePath(inputPath);
-    await this.assertPathContained(absolutePath);
-    if (options?.recursive === false) {
-      const dir = nodePath.dirname(absolutePath);
-      const parentPath = nodePath.dirname(inputPath);
-      try {
-        const stat3 = await fs2.stat(dir);
-        if (!stat3.isDirectory()) {
-          throw new NotDirectoryError(parentPath);
-        }
-      } catch (error) {
-        if (error instanceof NotDirectoryError) throw error;
-        if (isEnoentError(error)) {
-          throw new DirectoryNotFoundError(parentPath);
-        }
-        throw error;
-      }
+  /**
+   * Compute IDF (Inverse Document Frequency) for a term
+   */
+  #computeIDF(df) {
+    return Math.log((this.#docCount - df + 0.5) / (df + 0.5) + 1);
+  }
+  /**
+   * Compute the BM25 score component for a single term
+   */
+  #computeTermScore(tf, docLength, idf) {
+    const numerator = tf * (this.k1 + 1);
+    const denominator = tf + this.k1 * (1 - this.b + this.b * (docLength / this.#avgDocLength));
+    return idf * (numerator / denominator);
+  }
+};
+
+// src/workspace/search/search-engine.ts
+var SearchEngine = class {
+  /** BM25 index for keyword search */
+  #bm25Index;
+  /** Tokenization options (stored for lineRange computation) */
+  #tokenizeOptions;
+  /** Vector configuration */
+  #vectorConfig;
+  /** Whether to use lazy vector indexing */
+  #lazyVectorIndex;
+  /** Documents pending vector indexing (for lazy mode) */
+  #pendingVectorDocs = [];
+  /** Whether vector index has been built (for lazy mode) */
+  #vectorIndexBuilt = false;
+  constructor(config = {}) {
+    if (config.bm25 !== void 0) {
+      this.#tokenizeOptions = config.bm25.tokenize;
+      this.#bm25Index = new BM25Index(config.bm25.bm25, this.#tokenizeOptions);
     }
-    if (options?.recursive !== false) {
-      const dir = nodePath.dirname(absolutePath);
-      await fs2.mkdir(dir, { recursive: true });
+    if (config.vector) {
+      this.#vectorConfig = config.vector;
     }
-    const writeFlag = options?.overwrite === false ? "wx" : "w";
-    try {
-      await fs2.writeFile(absolutePath, this.toBuffer(content), { flag: writeFlag });
-    } catch (error) {
-      if (options?.overwrite === false && isEexistError(error)) {
-        throw new FileExistsError(inputPath);
+    this.#lazyVectorIndex = config.lazyVectorIndex ?? false;
+  }
+  // ===========================================================================
+  // Public API
+  // ===========================================================================
+  /**
+   * Index a document for search
+   */
+  async index(doc) {
+    const metadata = {
+      ...doc.metadata
+    };
+    if (doc.startLineOffset !== void 0) {
+      metadata._startLineOffset = doc.startLineOffset;
+    }
+    if (this.#bm25Index) {
+      this.#bm25Index.add(doc.id, doc.content, metadata);
+    }
+    if (this.#vectorConfig) {
+      const docWithMergedMetadata = { ...doc, metadata };
+      if (this.#lazyVectorIndex) {
+        this.#pendingVectorDocs.push(docWithMergedMetadata);
+        this.#vectorIndexBuilt = false;
+      } else {
+        await this.#indexVector(docWithMergedMetadata);
       }
-      throw error;
     }
   }
-  async appendFile(inputPath, content) {
-    const contentSize = Buffer.isBuffer(content) ? content.length : content.length;
-    this.logger.debug("Appending to file", { path: inputPath, size: contentSize });
-    await this.ensureInitialized();
-    this.assertWritable("appendFile");
-    const absolutePath = this.resolvePath(inputPath);
-    await this.assertPathContained(absolutePath);
-    const dir = nodePath.dirname(absolutePath);
-    await fs2.mkdir(dir, { recursive: true });
-    await fs2.appendFile(absolutePath, this.toBuffer(content));
+  /**
+   * Index multiple documents
+   */
+  async indexMany(docs) {
+    for (const doc of docs) {
+      await this.index(doc);
+    }
   }
-  async deleteFile(inputPath, options) {
-    this.logger.debug("Deleting file", { path: inputPath, force: options?.force });
-    await this.ensureInitialized();
-    this.assertWritable("deleteFile");
-    const absolutePath = this.resolvePath(inputPath);
-    await this.assertPathContained(absolutePath);
-    try {
-      const stats = await fs2.stat(absolutePath);
-      if (stats.isDirectory()) {
-        throw new IsDirectoryError(inputPath);
+  /**
+   * Remove a document from the index
+   */
+  async remove(id) {
+    if (this.#bm25Index) {
+      this.#bm25Index.remove(id);
+    }
+    if (this.#vectorConfig) {
+      try {
+        await this.#vectorConfig.vectorStore.deleteVector({
+          indexName: this.#vectorConfig.indexName,
+          id
+        });
+      } catch {
       }
-      await fs2.unlink(absolutePath);
-    } catch (error) {
-      if (error instanceof IsDirectoryError) throw error;
-      if (isEnoentError(error)) {
-        if (!options?.force) {
-          throw new FileNotFoundError(inputPath);
-        }
-      } else {
-        throw error;
+      if (this.#lazyVectorIndex) {
+        this.#pendingVectorDocs = this.#pendingVectorDocs.filter((d) => d.id !== id);
       }
     }
   }
-  async copyFile(src, dest, options) {
-    this.logger.debug("Copying file", { src, dest, recursive: options?.recursive });
-    await this.ensureInitialized();
-    this.assertWritable("copyFile");
-    const srcPath = this.resolvePath(src);
-    const destPath = this.resolvePath(dest);
-    await this.assertPathContained(srcPath);
-    await this.assertPathContained(destPath);
-    try {
-      const stats = await fs2.stat(srcPath);
-      if (stats.isDirectory()) {
-        if (!options?.recursive) {
-          throw new IsDirectoryError(src);
-        }
-        await this.copyDirectory(srcPath, destPath, options);
-      } else {
-        await fs2.mkdir(nodePath.dirname(destPath), { recursive: true });
-        const copyFlags = options?.overwrite === false ? constants.COPYFILE_EXCL : 0;
-        try {
-          await fs2.copyFile(srcPath, destPath, copyFlags);
-        } catch (error) {
-          if (options?.overwrite === false && isEexistError(error)) {
-            throw new FileExistsError(dest);
-          }
-          throw error;
-        }
-      }
-    } catch (error) {
-      if (error instanceof IsDirectoryError || error instanceof FileExistsError) throw error;
-      if (isEnoentError(error)) {
-        throw new FileNotFoundError(src);
-      }
-      throw error;
+  /**
+   * Clear all indexed documents
+   */
+  clear() {
+    if (this.#bm25Index) {
+      this.#bm25Index.clear();
     }
+    this.#pendingVectorDocs = [];
+    this.#vectorIndexBuilt = false;
   }
-  async copyDirectory(src, dest, options) {
-    await this.ensureInitialized();
-    await fs2.mkdir(dest, { recursive: true });
-    const entries = await fs2.readdir(src, { withFileTypes: true });
-    for (const entry of entries) {
-      const srcEntry = nodePath.join(src, entry.name);
-      const destEntry = nodePath.join(dest, entry.name);
-      await this.assertPathContained(srcEntry);
-      await this.assertPathContained(destEntry);
-      if (entry.isDirectory()) {
-        await this.copyDirectory(srcEntry, destEntry, options);
-      } else {
-        const copyFlags = options?.overwrite === false ? constants.COPYFILE_EXCL : 0;
-        try {
-          await fs2.copyFile(srcEntry, destEntry, copyFlags);
-        } catch (error) {
-          if (options?.overwrite === false && isEexistError(error)) {
-            continue;
-          }
-          throw error;
-        }
-      }
+  /**
+   * Search for documents
+   */
+  async search(query, options = {}) {
+    const { topK = 10, minScore, mode, vectorWeight = 0.5, filter } = options;
+    const effectiveMode = this.#determineSearchMode(mode);
+    if (effectiveMode === "bm25") {
+      return this.#searchBM25(query, topK, minScore);
     }
+    if (effectiveMode === "vector") {
+      return this.#searchVector(query, topK, minScore, filter);
+    }
+    return this.#searchHybrid(query, topK, minScore, vectorWeight, filter);
   }
-  async moveFile(src, dest, options) {
-    this.logger.debug("Moving file", { src, dest, overwrite: options?.overwrite });
-    await this.ensureInitialized();
-    this.assertWritable("moveFile");
-    const srcPath = this.resolvePath(src);
-    const destPath = this.resolvePath(dest);
-    await this.assertPathContained(srcPath);
-    await this.assertPathContained(destPath);
-    try {
-      await fs2.mkdir(nodePath.dirname(destPath), { recursive: true });
-      if (options?.overwrite === false) {
-        await this.copyFile(src, dest, { ...options, overwrite: false });
-        await fs2.rm(srcPath, { recursive: true, force: true });
-        return;
+  /**
+   * Check if BM25 search is available
+   */
+  get canBM25() {
+    return !!this.#bm25Index;
+  }
+  /**
+   * Check if vector search is available
+   */
+  get canVector() {
+    return !!this.#vectorConfig;
+  }
+  /**
+   * Check if hybrid search is available
+   */
+  get canHybrid() {
+    return this.canBM25 && this.canVector;
+  }
+  /**
+   * Get the BM25 index (for serialization/debugging)
+   */
+  get bm25Index() {
+    return this.#bm25Index;
+  }
+  // ===========================================================================
+  // Private Methods
+  // ===========================================================================
+  /**
+   * Determine the effective search mode
+   */
+  #determineSearchMode(requestedMode) {
+    if (requestedMode) {
+      if (requestedMode === "vector" && !this.canVector) {
+        throw new Error("Vector search requires vector configuration.");
       }
-      try {
-        await fs2.rename(srcPath, destPath);
-      } catch (error) {
-        const code = error.code;
-        if (code !== "EXDEV") {
-          throw error;
-        }
-        await this.copyFile(src, dest, options);
-        await fs2.rm(srcPath, { recursive: true, force: true });
+      if (requestedMode === "bm25" && !this.canBM25) {
+        throw new Error("BM25 search requires BM25 configuration.");
       }
-    } catch (error) {
-      if (error instanceof FileExistsError) throw error;
-      if (isEnoentError(error)) {
-        throw new FileNotFoundError(src);
+      if (requestedMode === "hybrid" && !this.canHybrid) {
+        throw new Error("Hybrid search requires both vector and BM25 configuration.");
       }
-      throw error;
+      return requestedMode;
+    }
+    if (this.canHybrid) {
+      return "hybrid";
+    }
+    if (this.canVector) {
+      return "vector";
+    }
+    if (this.canBM25) {
+      return "bm25";
+    }
+    throw new Error("No search configuration available. Provide bm25 or vector config.");
+  }
+  /**
+   * Index a single document in the vector store
+   */
+  async #indexVector(doc) {
+    if (!this.#vectorConfig) return;
+    const { vectorStore, embedder, indexName } = this.#vectorConfig;
+    const embedding = await embedder(doc.content);
+    await vectorStore.upsert({
+      indexName,
+      vectors: [embedding],
+      metadata: [
+        {
+          id: doc.id,
+          text: doc.content,
+          ...doc.metadata
+        }
+      ],
+      ids: [doc.id]
+    });
+  }
+  /**
+   * Ensure vector index is built (for lazy mode)
+   */
+  async #ensureVectorIndex() {
+    if (!this.#lazyVectorIndex || this.#vectorIndexBuilt || this.#pendingVectorDocs.length === 0) {
+      return;
     }
+    for (const doc of this.#pendingVectorDocs) {
+      await this.#indexVector(doc);
+    }
+    this.#pendingVectorDocs = [];
+    this.#vectorIndexBuilt = true;
   }
-  async mkdir(inputPath, options) {
-    this.logger.debug("Creating directory", { path: inputPath, recursive: options?.recursive });
-    await this.ensureInitialized();
-    this.assertWritable("mkdir");
-    const absolutePath = this.resolvePath(inputPath);
-    await this.assertPathContained(absolutePath);
-    try {
-      await fs2.mkdir(absolutePath, { recursive: options?.recursive ?? true });
-    } catch (error) {
-      if (isEexistError(error)) {
-        const stats = await fs2.stat(absolutePath);
-        if (!stats.isDirectory()) {
-          throw new FileExistsError(inputPath);
-        }
-      } else if (isEnoentError(error)) {
-        const parentPath = nodePath.dirname(inputPath);
-        throw new DirectoryNotFoundError(parentPath);
-      } else {
-        throw error;
-      }
+  /**
+   * BM25 keyword search
+   */
+  #searchBM25(query, topK, minScore) {
+    if (!this.#bm25Index) {
+      throw new Error("BM25 search requires BM25 configuration.");
     }
+    const results = this.#bm25Index.search(query, topK, minScore);
+    const queryTokens = tokenize(query, this.#tokenizeOptions);
+    return results.map((result) => {
+      const rawLineRange = findLineRange(result.content, queryTokens, this.#tokenizeOptions);
+      const lineRange = this.#adjustLineRange(rawLineRange, result.metadata);
+      const { _startLineOffset, ...cleanMetadata } = result.metadata ?? {};
+      return {
+        id: result.id,
+        content: result.content,
+        score: result.score,
+        lineRange,
+        metadata: Object.keys(cleanMetadata).length > 0 ? cleanMetadata : void 0,
+        scoreDetails: { bm25: result.score }
+      };
+    });
   }
-  async rmdir(inputPath, options) {
-    this.logger.debug("Removing directory", { path: inputPath, recursive: options?.recursive, force: options?.force });
-    await this.ensureInitialized();
-    this.assertWritable("rmdir");
-    const absolutePath = this.resolvePath(inputPath);
-    await this.assertPathContained(absolutePath);
-    try {
-      const stats = await fs2.stat(absolutePath);
-      if (!stats.isDirectory()) {
-        throw new NotDirectoryError(inputPath);
-      }
-      if (options?.recursive) {
-        await fs2.rm(absolutePath, { recursive: true, force: options?.force ?? false });
-      } else {
-        const entries = await fs2.readdir(absolutePath);
-        if (entries.length > 0) {
-          throw new DirectoryNotEmptyError(inputPath);
-        }
-        await fs2.rmdir(absolutePath);
-      }
-    } catch (error) {
-      if (error instanceof NotDirectoryError || error instanceof DirectoryNotEmptyError) {
-        throw error;
-      }
-      if (isEnoentError(error)) {
-        if (!options?.force) {
-          throw new DirectoryNotFoundError(inputPath);
-        }
-      } else {
-        throw error;
+  /**
+   * Vector semantic search
+   */
+  async #searchVector(query, topK, minScore, filter) {
+    if (!this.#vectorConfig) {
+      throw new Error("Vector search requires vector configuration.");
+    }
+    await this.#ensureVectorIndex();
+    const { vectorStore, embedder, indexName } = this.#vectorConfig;
+    const queryEmbedding = await embedder(query);
+    const vectorResults = await vectorStore.query({
+      indexName,
+      queryVector: queryEmbedding,
+      topK,
+      filter
+    });
+    const queryTokens = tokenize(query, this.#tokenizeOptions);
+    const results = [];
+    for (const result of vectorResults) {
+      if (minScore !== void 0 && result.score < minScore) {
+        continue;
       }
+      const id = result.metadata?.id ?? result.id;
+      const content = result.metadata?.text ?? "";
+      const { id: _id, text: _text, _startLineOffset, ...restMetadata } = result.metadata ?? {};
+      const rawLineRange = findLineRange(content, queryTokens, this.#tokenizeOptions);
+      const lineRange = this.#adjustLineRange(rawLineRange, result.metadata);
+      results.push({
+        id,
+        content,
+        score: result.score,
+        lineRange,
+        metadata: Object.keys(restMetadata).length > 0 ? restMetadata : void 0,
+        scoreDetails: { vector: result.score }
+      });
     }
+    return results;
   }
-  async readdir(inputPath, options) {
-    this.logger.debug("Reading directory", { path: inputPath, recursive: options?.recursive });
-    await this.ensureInitialized();
-    const absolutePath = this.resolvePath(inputPath);
-    await this.assertPathContained(absolutePath);
-    try {
-      const stats = await fs2.stat(absolutePath);
-      if (!stats.isDirectory()) {
-        throw new NotDirectoryError(inputPath);
-      }
-      const entries = await fs2.readdir(absolutePath, { withFileTypes: true });
-      const result = [];
-      for (const entry of entries) {
-        const entryPath = nodePath.join(absolutePath, entry.name);
-        if (options?.extension) {
-          const extensions = Array.isArray(options.extension) ? options.extension : [options.extension];
-          if (entry.isFile()) {
-            const ext = nodePath.extname(entry.name);
-            if (!extensions.some((e) => e === ext || e === ext.slice(1))) {
-              continue;
-            }
-          }
-        }
-        const isSymlink = entry.isSymbolicLink();
-        let symlinkTarget;
-        let resolvedType = "file";
-        if (isSymlink) {
-          try {
-            symlinkTarget = await fs2.readlink(entryPath);
-            const targetStat = await fs2.stat(entryPath);
-            resolvedType = targetStat.isDirectory() ? "directory" : "file";
-          } catch {
-            resolvedType = "file";
-          }
-        } else {
-          resolvedType = entry.isDirectory() ? "directory" : "file";
-        }
-        const fileEntry = {
-          name: entry.name,
-          type: resolvedType,
-          isSymlink: isSymlink || void 0,
-          symlinkTarget
-        };
-        if (resolvedType === "file" && !isSymlink) {
-          try {
-            const stat3 = await fs2.stat(entryPath);
-            fileEntry.size = stat3.size;
-          } catch {
-          }
-        }
-        result.push(fileEntry);
-        if (options?.recursive && resolvedType === "directory") {
-          const depth = options.maxDepth ?? 100;
-          if (depth > 0) {
-            const subEntries = await this.readdir(this.toRelativePath(entryPath), { ...options, maxDepth: depth - 1 });
-            result.push(
-              ...subEntries.map((e) => ({
-                ...e,
-                name: `${entry.name}/${e.name}`
-              }))
-            );
-          }
+  /**
+   * Hybrid search combining vector and BM25 scores
+   */
+  async #searchHybrid(query, topK, minScore, vectorWeight = 0.5, filter) {
+    const expandedTopK = Math.min(topK * 2, 50);
+    const [vectorResults, bm25Results] = await Promise.all([
+      this.#searchVector(query, expandedTopK, void 0, filter),
+      Promise.resolve(this.#searchBM25(query, expandedTopK, void 0))
+    ]);
+    const normalizedBM25 = this.#normalizeBM25Scores(bm25Results);
+    const bm25Map = /* @__PURE__ */ new Map();
+    for (const result of normalizedBM25) {
+      bm25Map.set(result.id, result);
+    }
+    const vectorMap = /* @__PURE__ */ new Map();
+    for (const result of vectorResults) {
+      vectorMap.set(result.id, result);
+    }
+    const combinedResults = /* @__PURE__ */ new Map();
+    const allIds = /* @__PURE__ */ new Set([...vectorMap.keys(), ...bm25Map.keys()]);
+    const bm25Weight = 1 - vectorWeight;
+    for (const id of allIds) {
+      const vectorResult = vectorMap.get(id);
+      const bm25Result = bm25Map.get(id);
+      const vectorScore = vectorResult?.scoreDetails?.vector ?? 0;
+      const bm25Score = bm25Result?.score ?? 0;
+      const combinedScore = vectorWeight * vectorScore + bm25Weight * bm25Score;
+      const baseResult = vectorResult ?? bm25Result;
+      combinedResults.set(id, {
+        id,
+        content: baseResult.content,
+        score: combinedScore,
+        lineRange: bm25Result?.lineRange ?? vectorResult?.lineRange,
+        metadata: baseResult.metadata,
+        scoreDetails: {
+          vector: vectorResult?.scoreDetails?.vector,
+          bm25: bm25Result?.scoreDetails?.bm25
         }
-      }
-      return result;
-    } catch (error) {
-      if (error instanceof NotDirectoryError) throw error;
-      if (isEnoentError(error)) {
-        throw new DirectoryNotFoundError(inputPath);
-      }
-      throw error;
+      });
     }
+    let results = Array.from(combinedResults.values());
+    results.sort((a, b) => b.score - a.score);
+    if (minScore !== void 0) {
+      results = results.filter((r) => r.score >= minScore);
+    }
+    return results.slice(0, topK);
   }
-  async exists(inputPath) {
-    await this.ensureInitialized();
-    const absolutePath = this.resolvePath(inputPath);
-    await this.assertPathContained(absolutePath);
-    return fsExists(absolutePath);
+  /**
+   * Normalize BM25 scores to 0-1 range using min-max normalization
+   */
+  #normalizeBM25Scores(results) {
+    if (results.length === 0) return results;
+    const scores = results.map((r) => r.scoreDetails?.bm25 ?? r.score);
+    const maxScore = Math.max(...scores);
+    const minScore = Math.min(...scores);
+    const range = maxScore - minScore;
+    if (range === 0) {
+      return results.map((r) => ({ ...r, score: 1 }));
+    }
+    return results.map((r) => ({
+      ...r,
+      score: ((r.scoreDetails?.bm25 ?? r.score) - minScore) / range
+    }));
   }
-  async stat(inputPath) {
-    await this.ensureInitialized();
-    const absolutePath = this.resolvePath(inputPath);
-    await this.assertPathContained(absolutePath);
-    const result = await fsStat(absolutePath, inputPath);
+  /**
+   * Adjust line range for chunked documents.
+   * If the document has a _startLineOffset in metadata, adjust the line range
+   * to reflect the original document's line numbers.
+   */
+  #adjustLineRange(lineRange, metadata) {
+    if (!lineRange) return void 0;
+    const startLineOffset = metadata?._startLineOffset;
+    if (typeof startLineOffset !== "number") {
+      return lineRange;
+    }
     return {
-      ...result,
-      path: this.toRelativePath(absolutePath)
+      start: lineRange.start + startLineOffset - 1,
+      end: lineRange.end + startLineOffset - 1
     };
   }
-  async init() {
-    this.logger.debug("Initializing filesystem", { basePath: this._basePath });
-    this.status = "starting";
-    try {
-      await fs2.mkdir(this._basePath, { recursive: true });
-      this.status = "running";
-      this.logger.debug("Filesystem initialized", { basePath: this._basePath, status: this.status });
-    } catch (error) {
-      this.status = "error";
-      this.logger.error("Failed to initialize filesystem", { basePath: this._basePath, error });
-      throw error;
-    }
+};
+
+// src/workspace/skills/schemas.ts
+var SKILL_LIMITS = {
+  /** Recommended max tokens for instructions */
+  MAX_INSTRUCTION_TOKENS: 5e3,
+  /** Recommended max lines for SKILL.md */
+  MAX_INSTRUCTION_LINES: 500,
+  /** Max characters for name field */
+  MAX_NAME_LENGTH: 64,
+  /** Max characters for description field */
+  MAX_DESCRIPTION_LENGTH: 1024};
+function validateSkillName(name) {
+  const errors = [];
+  const fieldPath = "name";
+  if (typeof name !== "string") {
+    errors.push(`${fieldPath}: Expected string, received ${typeof name}`);
+    return errors;
   }
-  async destroy() {
+  if (name.length === 0) {
+    errors.push(`${fieldPath}: Skill name cannot be empty`);
+    return errors;
   }
-  getInfo() {
-    return {
-      id: this.id,
-      name: this.name,
-      provider: this.provider,
-      readOnly: this.readOnly,
-      basePath: this.basePath,
-      status: this.status
-    };
+  if (name.length > SKILL_LIMITS.MAX_NAME_LENGTH) {
+    errors.push(`${fieldPath}: Skill name must be ${SKILL_LIMITS.MAX_NAME_LENGTH} characters or less`);
   }
-  getInstructions() {
-    return `Local filesystem at "${this.basePath}". Files at workspace path "/foo" are stored at "${this.basePath}/foo" on disk.`;
+  if (!/^[a-z0-9-]+$/.test(name)) {
+    errors.push(`${fieldPath}: Skill name must contain only lowercase letters, numbers, and hyphens`);
   }
-};
-var InMemoryFileReadTracker = class {
-  records = /* @__PURE__ */ new Map();
-  recordRead(path4, modifiedAt) {
-    const normalizedPath = this.normalizePath(path4);
-    this.records.set(normalizedPath, {
-      path: normalizedPath,
-      readAt: /* @__PURE__ */ new Date(),
-      modifiedAtRead: modifiedAt
-    });
+  if (name.startsWith("-") || name.endsWith("-")) {
+    errors.push(`${fieldPath}: Skill name must not start or end with a hyphen`);
   }
-  getReadRecord(path4) {
-    return this.records.get(this.normalizePath(path4));
+  if (name.includes("--")) {
+    errors.push(`${fieldPath}: Skill name must not contain consecutive hyphens`);
   }
-  needsReRead(path4, currentModifiedAt) {
-    const record = this.getReadRecord(path4);
-    if (!record) {
-      return {
-        needsReRead: true,
-        reason: `File "${path4}" has not been read. You must read a file before writing to it.`
-      };
-    }
-    if (currentModifiedAt.getTime() > record.modifiedAtRead.getTime()) {
-      return {
-        needsReRead: true,
-        reason: `File "${path4}" was modified since last read (read at: ${record.modifiedAtRead.toISOString()}, current: ${currentModifiedAt.toISOString()}). Please re-read the file to get the latest contents.`
-      };
-    }
-    return { needsReRead: false };
+  return errors;
+}
+function validateSkillDescription(description) {
+  const errors = [];
+  const fieldPath = "description";
+  if (typeof description !== "string") {
+    errors.push(`${fieldPath}: Expected string, received ${typeof description}`);
+    return errors;
   }
-  clearReadRecord(path4) {
-    this.records.delete(this.normalizePath(path4));
+  if (description.length === 0) {
+    errors.push(`${fieldPath}: Skill description cannot be empty`);
+    return errors;
   }
-  clear() {
-    this.records.clear();
+  if (description.length > SKILL_LIMITS.MAX_DESCRIPTION_LENGTH) {
+    errors.push(`${fieldPath}: Skill description must be ${SKILL_LIMITS.MAX_DESCRIPTION_LENGTH} characters or less`);
   }
-  normalizePath(pathStr) {
-    const normalized = nodePath.posix.normalize(pathStr.replace(/\\/g, "/"));
-    return normalized.replace(/\/$/, "") || "/";
+  if (description.trim().length === 0) {
+    errors.push(`${fieldPath}: Skill description cannot be only whitespace`);
   }
-};
-
-// src/workspace/skills/local-skill-source.ts
+  return errors;
+}
+function validateSkillLicense(license) {
+  const errors = [];
+  const fieldPath = "license";
+  if (license === void 0 || license === null) {
+    return errors;
+  }
+  if (typeof license !== "string") {
+    errors.push(`${fieldPath}: Expected string, received ${typeof license}`);
+  }
+  return errors;
+}
+function validateSkillCompatibility(_compatibility) {
+  return [];
+}
+function validateSkillMetadataField(metadata) {
+  const errors = [];
+  const fieldPath = "metadata";
+  if (metadata === void 0 || metadata === null) {
+    return errors;
+  }
+  if (typeof metadata !== "object" || Array.isArray(metadata)) {
+    errors.push(`${fieldPath}: Expected object, received ${Array.isArray(metadata) ? "array" : typeof metadata}`);
+    return errors;
+  }
+  return errors;
+}
+function estimateTokens(text) {
+  const words = text.split(/\s+/).filter(Boolean).length;
+  return Math.ceil(words * 1.3);
+}
+function countLines(text) {
+  return text.split("\n").length;
+}
+function validateSkillMetadata(metadata, dirName, instructions) {
+  const errors = [];
+  const warnings = [];
+  if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
+    errors.push(
+      `Expected object, received ${metadata === null ? "null" : Array.isArray(metadata) ? "array" : typeof metadata}`
+    );
+    return { valid: false, errors, warnings };
+  }
+  const data = metadata;
+  errors.push(...validateSkillName(data.name));
+  errors.push(...validateSkillDescription(data.description));
+  errors.push(...validateSkillLicense(data.license));
+  errors.push(...validateSkillCompatibility());
+  errors.push(...validateSkillMetadataField(data.metadata));
+  if (dirName && typeof data.name === "string" && data.name !== dirName) {
+    errors.push(`Skill name "${data.name}" must match directory name "${dirName}"`);
+  }
+  if (instructions) {
+    const lineCount = countLines(instructions);
+    const tokenEstimate = estimateTokens(instructions);
+    if (lineCount > SKILL_LIMITS.MAX_INSTRUCTION_LINES) {
+      warnings.push(
+        `Instructions have ${lineCount} lines (recommended: <${SKILL_LIMITS.MAX_INSTRUCTION_LINES}). Consider moving content to references/.`
+      );
+    }
+    if (tokenEstimate > SKILL_LIMITS.MAX_INSTRUCTION_TOKENS) {
+      warnings.push(
+        `Instructions have ~${tokenEstimate} estimated tokens (recommended: <${SKILL_LIMITS.MAX_INSTRUCTION_TOKENS}). Consider moving content to references/.`
+      );
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
 var LocalSkillSource = class {
   #basePath;
   constructor(options = {}) {
@@ -2167,8 +3194,22 @@ var Workspace = class {
     this.createdAt = /* @__PURE__ */ new Date();
     this.lastAccessedAt = /* @__PURE__ */ new Date();
     this._config = config;
-    this._fs = config.filesystem;
     this._sandbox = config.sandbox;
+    if (config.mounts && Object.keys(config.mounts).length > 0) {
+      if (config.filesystem) {
+        throw new WorkspaceError('Cannot use both "filesystem" and "mounts"', "INVALID_CONFIG");
+      }
+      this._fs = new CompositeFilesystem({ mounts: config.mounts });
+      if (this._sandbox?.mounts) {
+        this._sandbox.mounts.setContext({ sandbox: this._sandbox, workspace: this });
+        this._sandbox.mounts.add(config.mounts);
+        if (config.onMount) {
+          this._sandbox.mounts.setOnMount(config.onMount);
+        }
+      }
+    } else {
+      this._fs = config.filesystem;
+    }
     if (config.vectorStore && !config.embedder) {
       throw new WorkspaceError("vectorStore requires an embedder", "INVALID_SEARCH_CONFIG");
     }
@@ -2373,16 +3414,16 @@ var Workspace = class {
   // ---------------------------------------------------------------------------
   /**
    * Initialize the workspace.
-   * Starts the sandbox and initializes the filesystem.
+   * Starts the sandbox, initializes the filesystem, and auto-mounts filesystems.
    */
   async init() {
     this._status = "initializing";
     try {
-      if (this._fs?.init) {
-        await this._fs.init();
+      if (this._fs) {
+        await callLifecycle(this._fs, "init");
       }
-      if (this._sandbox?.start) {
-        await this._sandbox.start();
+      if (this._sandbox) {
+        await callLifecycle(this._sandbox, "start");
       }
       if (this._searchEngine && this._config.autoIndexPaths && this._config.autoIndexPaths.length > 0) {
         await this.rebuildSearchIndex(this._config.autoIndexPaths ?? []);
@@ -2399,11 +3440,11 @@ var Workspace = class {
   async destroy() {
     this._status = "destroying";
     try {
-      if (this._sandbox?.destroy) {
-        await this._sandbox.destroy();
+      if (this._sandbox) {
+        await callLifecycle(this._sandbox, "destroy");
       }
-      if (this._fs?.destroy) {
-        await this._fs.destroy();
+      if (this._fs) {
+        await callLifecycle(this._fs, "destroy");
       }
       this._status = "destroyed";
     } catch (error) {
@@ -2427,6 +3468,8 @@ var Workspace = class {
       const fsInfo = await this._fs.getInfo?.();
       info.filesystem = {
         provider: this._fs.provider,
+        name: fsInfo?.name ?? this._fs.name,
+        icon: fsInfo?.icon,
         basePath: fsInfo?.basePath ?? this._fs.basePath,
         readOnly: fsInfo?.readOnly ?? this._fs.readOnly,
         status: fsInfo?.status,
@@ -2489,47 +3532,6 @@ var Workspace = class {
     }
   }
 };
-
-// src/workspace/sandbox/sandbox.ts
-var SandboxError = class extends Error {
-  constructor(message, code, details) {
-    super(message);
-    this.code = code;
-    this.details = details;
-    this.name = "SandboxError";
-  }
-};
-var SandboxExecutionError = class extends SandboxError {
-  constructor(message, exitCode, stdout, stderr) {
-    super(message, "EXECUTION_FAILED", { exitCode, stdout, stderr });
-    this.exitCode = exitCode;
-    this.stdout = stdout;
-    this.stderr = stderr;
-    this.name = "SandboxExecutionError";
-  }
-};
-var SandboxTimeoutError = class extends SandboxError {
-  constructor(timeoutMs, operation) {
-    super(`Execution timed out after ${timeoutMs}ms`, "TIMEOUT", { timeoutMs, operation });
-    this.timeoutMs = timeoutMs;
-    this.operation = operation;
-    this.name = "SandboxTimeoutError";
-  }
-};
-var SandboxNotReadyError = class extends SandboxError {
-  constructor(idOrStatus) {
-    super(`Sandbox is not ready: ${idOrStatus}`, "NOT_READY", { id: idOrStatus });
-    this.name = "SandboxNotReadyError";
-  }
-};
-var IsolationUnavailableError = class extends SandboxError {
-  constructor(backend, reason) {
-    super(`Isolation backend '${backend}' is not available: ${reason}`, "ISOLATION_UNAVAILABLE", { backend, reason });
-    this.backend = backend;
-    this.reason = reason;
-    this.name = "IsolationUnavailableError";
-  }
-};
 function commandExists(command) {
   try {
     execFileSync("which", [command], { stdio: "ignore" });
@@ -2806,7 +3808,7 @@ var LocalSandbox = class extends MastraSandbox {
   id;
   name = "LocalSandbox";
   provider = "local";
-  status = "stopped";
+  status = "pending";
   _workingDirectory;
   env;
   timeout;
@@ -2845,7 +3847,7 @@ var LocalSandbox = class extends MastraSandbox {
     return detectIsolation();
   }
   constructor(options = {}) {
-    super({ name: "LocalSandbox" });
+    super({ name: "LocalSandbox", onStart: options.onStart, onStop: options.onStop, onDestroy: options.onDestroy });
     this.id = options.id ?? this.generateId();
     this._createdAt = /* @__PURE__ */ new Date();
     this._workingDirectory = options.workingDirectory ?? nodePath.join(process.cwd(), ".sandbox");
@@ -2875,44 +3877,52 @@ var LocalSandbox = class extends MastraSandbox {
       ...additionalEnv
     };
   }
+  /**
+   * Start the local sandbox.
+   * Creates working directory and sets up seatbelt profile if using macOS isolation.
+   * Status management is handled by the base class.
+   */
   async start() {
     this.logger.debug("Starting sandbox", { workingDirectory: this._workingDirectory, isolation: this._isolation });
-    this.status = "starting";
-    try {
-      await fs2.mkdir(this.workingDirectory, { recursive: true });
-      if (this._isolation === "seatbelt") {
-        const userProvidedPath = this._nativeSandboxConfig.seatbeltProfilePath;
-        if (userProvidedPath) {
-          this._seatbeltProfilePath = userProvidedPath;
-          this._userProvidedProfilePath = true;
-          try {
-            this._seatbeltProfile = await fs2.readFile(userProvidedPath, "utf-8");
-          } catch {
-            this._seatbeltProfile = generateSeatbeltProfile(this.workingDirectory, this._nativeSandboxConfig);
-            await fs2.mkdir(nodePath.dirname(userProvidedPath), { recursive: true });
-            await fs2.writeFile(userProvidedPath, this._seatbeltProfile, "utf-8");
+    await fs2.mkdir(this.workingDirectory, { recursive: true });
+    if (this._isolation === "seatbelt") {
+      const userProvidedPath = this._nativeSandboxConfig.seatbeltProfilePath;
+      if (userProvidedPath) {
+        this._seatbeltProfilePath = userProvidedPath;
+        this._userProvidedProfilePath = true;
+        try {
+          this._seatbeltProfile = await fs2.readFile(userProvidedPath, "utf-8");
+        } catch (err) {
+          if (err instanceof Error && "code" in err && err.code !== "ENOENT") {
+            throw err;
           }
-        } else {
           this._seatbeltProfile = generateSeatbeltProfile(this.workingDirectory, this._nativeSandboxConfig);
-          const configHash = crypto.createHash("sha256").update(this.workingDirectory).update(JSON.stringify(this._nativeSandboxConfig)).digest("hex").slice(0, 8);
-          this._sandboxFolderPath = nodePath.join(process.cwd(), ".sandbox-profiles");
-          await fs2.mkdir(this._sandboxFolderPath, { recursive: true });
-          this._seatbeltProfilePath = nodePath.join(this._sandboxFolderPath, `seatbelt-${configHash}.sb`);
-          await fs2.writeFile(this._seatbeltProfilePath, this._seatbeltProfile, "utf-8");
+          await fs2.mkdir(nodePath.dirname(userProvidedPath), { recursive: true });
+          await fs2.writeFile(userProvidedPath, this._seatbeltProfile, "utf-8");
         }
+      } else {
+        this._seatbeltProfile = generateSeatbeltProfile(this.workingDirectory, this._nativeSandboxConfig);
+        const configHash = crypto.createHash("sha256").update(this.workingDirectory).update(JSON.stringify(this._nativeSandboxConfig)).digest("hex").slice(0, 8);
+        this._sandboxFolderPath = nodePath.join(process.cwd(), ".sandbox-profiles");
+        await fs2.mkdir(this._sandboxFolderPath, { recursive: true });
+        this._seatbeltProfilePath = nodePath.join(this._sandboxFolderPath, `seatbelt-${configHash}.sb`);
+        await fs2.writeFile(this._seatbeltProfilePath, this._seatbeltProfile, "utf-8");
       }
-      this.status = "running";
-      this.logger.debug("Sandbox started", { workingDirectory: this._workingDirectory, status: this.status });
-    } catch (error) {
-      this.status = "error";
-      this.logger.error("Failed to start sandbox", { workingDirectory: this._workingDirectory, error });
-      throw error;
     }
+    this.logger.debug("Sandbox started", { workingDirectory: this._workingDirectory });
   }
+  /**
+   * Stop the local sandbox.
+   * Status management is handled by the base class.
+   */
   async stop() {
     this.logger.debug("Stopping sandbox", { workingDirectory: this._workingDirectory });
-    this.status = "stopped";
   }
+  /**
+   * Destroy the local sandbox and clean up resources.
+   * Cleans up seatbelt profile if auto-generated.
+   * Status management is handled by the base class.
+   */
   async destroy() {
     this.logger.debug("Destroying sandbox", { workingDirectory: this._workingDirectory });
     if (this._seatbeltProfilePath && !this._userProvidedProfilePath) {
@@ -2931,7 +3941,6 @@ var LocalSandbox = class extends MastraSandbox {
       }
       this._sandboxFolderPath = void 0;
     }
-    await this.stop();
   }
   async isReady() {
     return this.status === "running";
@@ -2982,15 +3991,13 @@ var LocalSandbox = class extends MastraSandbox {
   }
   async executeCommand(command, args = [], options = {}) {
     this.logger.debug("Executing command", { command, args, cwd: options.cwd ?? this.workingDirectory });
-    if (this.status !== "running") {
-      await this.start();
-    }
+    await this.ensureRunning();
     const startTime = Date.now();
     const wrapped = this.wrapCommandForIsolation(command, args);
     try {
       const result = await execWithStreaming(wrapped.command, wrapped.args, {
         cwd: options.cwd ?? this.workingDirectory,
-        timeout: this.timeout ?? options.timeout ?? 3e4,
+        timeout: options.timeout ?? this.timeout ?? 3e4,
         env: this.buildEnv(options.env),
         onStdout: options.onStdout,
         onStderr: options.onStderr
@@ -3066,7 +4073,10 @@ async function formatAsTree(fs5, path4, options) {
     let entries;
     try {
       entries = await fs5.readdir(currentPath);
-    } catch {
+    } catch (error) {
+      if (depth === 0) {
+        throw error;
+      }
       return;
     }
     let filtered = entries;
@@ -3583,15 +4593,13 @@ Examples:
 Usage:
 - Verify parent directories exist before running commands that create files or directories.
 - Always quote file paths that contain spaces (e.g., cd "/path/with spaces").
-- Commands timeout after 30 seconds by default. Use the timeout parameter for longer operations.
+- Use the timeout parameter to limit execution time. Behavior when omitted depends on the sandbox provider.
 - Use cwd to set the working directory, or commands run from the sandbox default.`,
         requireApproval: executeCommandConfig.requireApproval,
         inputSchema: z.object({
           command: z.string().describe('The command to execute (e.g., "ls", "npm", "python")'),
           args: z.array(z.string()).nullish().default([]).describe("Arguments to pass to the command"),
-          timeout: z.number().nullish().default(3e4).describe(
-            "Maximum execution time in milliseconds. Default is 30000 (30 seconds). Example: 60000 for 1 minute."
-          ),
+          timeout: z.number().nullish().describe("Maximum execution time in milliseconds. Example: 60000 for 1 minute."),
           cwd: z.string().nullish().describe("Working directory for the command")
         }),
         outputSchema: z.object({
@@ -3617,7 +4625,7 @@ Usage:
           const startedAt = Date.now();
           try {
             const result = await workspace.sandbox.executeCommand(command, args ?? [], {
-              timeout: timeout ?? 3e4,
+              timeout: timeout ?? void 0,
               cwd: cwd ?? void 0,
               // Stream stdout/stderr as tool-output chunks for proper UI integration
               onStdout: async (data) => {
@@ -3668,6 +4676,6 @@ Usage:
   return tools;
 }
 
-export { BM25Index, DirectoryNotEmptyError, DirectoryNotFoundError, FileExistsError, FileNotFoundError, FileReadRequiredError, FilesystemError, FilesystemNotAvailableError, IsDirectoryError, IsolationUnavailableError, LocalFilesystem, LocalSandbox, MastraFilesystem, MastraSandbox, NotDirectoryError, PermissionError, SandboxError, SandboxExecutionError, SandboxFeatureNotSupportedError, SandboxNotAvailableError, SandboxNotReadyError, SandboxTimeoutError, SearchNotAvailableError, WORKSPACE_TOOLS, WORKSPACE_TOOLS_PREFIX, Workspace, WorkspaceError, WorkspaceNotReadyError, WorkspaceReadOnlyError, createWorkspaceTools, detectIsolation, extractLines, getRecommendedIsolation, isIsolationAvailable, resolveToolConfig };
-//# sourceMappingURL=chunk-ENCTSDWC.js.map
-//# sourceMappingURL=chunk-ENCTSDWC.js.map
+export { BM25Index, CompositeFilesystem, DirectoryNotEmptyError, DirectoryNotFoundError, FileExistsError, FileNotFoundError, FileReadRequiredError, FilesystemError, FilesystemNotAvailableError, FilesystemNotMountableError, FilesystemNotReadyError, IsDirectoryError, IsolationUnavailableError, LocalFilesystem, LocalSandbox, MastraFilesystem, MastraSandbox, MountError, MountManager, MountNotSupportedError, NotDirectoryError, PermissionError, SandboxError, SandboxExecutionError, SandboxFeatureNotSupportedError, SandboxNotAvailableError, SandboxNotReadyError, SandboxTimeoutError, SearchNotAvailableError, WORKSPACE_TOOLS, WORKSPACE_TOOLS_PREFIX, Workspace, WorkspaceError, WorkspaceNotReadyError, WorkspaceReadOnlyError, callLifecycle, createWorkspaceTools, detectIsolation, extractLines, getRecommendedIsolation, isIsolationAvailable, resolveToolConfig };
+//# sourceMappingURL=chunk-2GWTJFVM.js.map
+//# sourceMappingURL=chunk-2GWTJFVM.js.map