@cydm/pie 1.0.18 → 1.0.20

package/dist/chunks/{chunk-G4GV2CRT.js → chunk-NHR6EBM2.js}

@@ -1,7 +1,7 @@
 import { createRequire as __createRequire } from "node:module"; const require = __createRequire(import.meta.url);
 import {
   Agent
-} from "./chunk-VE2HDCNB.js";
+} from "./chunk-L5BJNCNG.js";
 import {
   FileSystemGateway,
   Type,
@@ -9,8 +9,9 @@ import {
   detectPlatform,
   getFileSystem,
   getPlatformConfig,
+  hashText,
   streamSimple
-} from "./chunk-5DA2D3K2.js";
+} from "./chunk-VESPMEDG.js";
 import {
   __require
 } from "./chunk-TG2EQLX2.js";
@@ -1995,7 +1996,7 @@ function isTransientFileError(error) {
   return /^(EPERM|EACCES|EBUSY|ENOTEMPTY)$/.test(code) || /\b(EPERM|EACCES|EBUSY|locked|busy)\b/i.test(message);
 }
 function sleep(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 async function retryFileOperation(operation, retryDelaysMs) {
   let lastError;
@@ -2070,6 +2071,15 @@ function candidatePriority(role) {
   return 1;
 }
 function chooseBestCandidate(candidates) {
+  const main = candidates.find((candidate) => candidate.role === "main");
+  if (main) {
+    const backup = candidates.find((candidate) => candidate.role === "backup");
+    const previous = candidates.find((candidate) => candidate.role === "previous");
+    if (backup && previous && backup.content !== main.content && previous.content === main.content && backup.updatedAt >= main.updatedAt) {
+      return backup;
+    }
+    return main;
+  }
   return [...candidates].sort((a, b) => {
     const updatedAtDiff = b.updatedAt - a.updatedAt;
     if (updatedAtDiff !== 0) return updatedAtDiff;
@@ -2158,6 +2168,8 @@ function deleteDurableFile(gateway, filePath) {
 
 // ../../packages/agent-framework/src/session/store.ts
 var SESSION_VERSION = 2;
+var METADATA_INDEX_VERSION = 3;
+var METADATA_FAST_READ_BYTES = 64 * 1024;
 function isSessionEntry(value) {
   return !!value && typeof value === "object" && "id" in value && "type" in value;
 }
@@ -2180,6 +2192,60 @@ function normalizeEntriesInput(entriesOrMessages) {
   }
   return entries;
 }
+function extractJsonObjectProperty(content, propertyName) {
+  const propertyIndex = content.indexOf(`"${propertyName}"`);
+  if (propertyIndex < 0) return null;
+  const colonIndex = content.indexOf(":", propertyIndex + propertyName.length + 2);
+  if (colonIndex < 0) return null;
+  let index = colonIndex + 1;
+  while (index < content.length && /\s/.test(content[index])) index += 1;
+  if (content[index] !== "{") return null;
+  let depth = 0;
+  let inString = false;
+  let escaping = false;
+  for (let cursor = index; cursor < content.length; cursor += 1) {
+    const char = content[cursor];
+    if (inString) {
+      if (escaping) {
+        escaping = false;
+      } else if (char === "\\") {
+        escaping = true;
+      } else if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+    if (char === "{") {
+      depth += 1;
+    } else if (char === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return content.slice(index, cursor + 1);
+      }
+    }
+  }
+  return null;
+}
+function parseMetadataOnly(content) {
+  const metadataText = extractJsonObjectProperty(content, "metadata");
+  if (!metadataText) return null;
+  const parsed = JSON.parse(metadataText);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const metadata = parsed;
+  if (typeof metadata.id !== "string" || typeof metadata.name !== "string" || typeof metadata.createdAt !== "number" || typeof metadata.updatedAt !== "number" || typeof metadata.entryCount !== "number" || typeof metadata.messageCount !== "number") {
+    return null;
+  }
+  return metadata;
+}
+function durableRolePriority(role) {
+  if (role === "main") return 3;
+  if (role === "backup") return 2;
+  return 1;
+}
 var LEGACY_VERSION = 1;
 function getDefaultSessionsDir() {
   return getPlatformConfig().sessionsPath;
@@ -2245,6 +2311,9 @@ var FileSessionStore = class {
     const safeId = sessionId.replace(/[^a-zA-Z0-9_-]/g, "_");
     return this.gateway.join(this.sessionsDir, `${safeId}.json`);
   }
+  getMetadataIndexPath() {
+    return this.gateway.join(this.sessionsDir, ".metadata-index.json");
+  }
   normalizeLoadedData(data) {
     if (data.version === LEGACY_VERSION || !data.version) {
       return { data: migrateV1ToV2(data), shouldPersist: true };
@@ -2279,6 +2348,8 @@ var FileSessionStore = class {
     const normalizedEntries = normalizeEntriesInput(entries);
     const now = Date.now();
     const existing = await this.load(sessionId);
+    const requestedUpdatedAt = metadata?.updatedAt ?? now;
+    const updatedAt = Math.max(requestedUpdatedAt, existing?.metadata.updatedAt ?? 0);
     const messageCount = normalizedEntries.filter((e) => e.type === "message" && e.message).length;
     const rootEntry = normalizedEntries.find((e) => e.parentId === null);
     const activeEntryId = metadata?.activeEntryId ?? existing?.metadata.activeEntryId ?? normalizedEntries[normalizedEntries.length - 1]?.id ?? null;
@@ -2288,13 +2359,13 @@ var FileSessionStore = class {
         id: sessionId,
         name: metadata?.name ?? existing?.metadata.name ?? `Session ${sessionId.slice(0, 8)}`,
         createdAt: existing?.metadata.createdAt ?? now,
-        updatedAt: now,
         entryCount: normalizedEntries.length,
         messageCount,
         activeEntryId: activeEntryId ?? rootEntry?.id ?? null,
         rootEntryId: rootEntry?.id ?? null,
         tags: metadata?.tags ?? existing?.metadata.tags,
-        ...metadata
+        ...metadata,
+        updatedAt
       },
       entries: normalizedEntries,
       messages: flattenTreeToMessages(normalizedEntries, activeEntryId ?? null)
@@ -2306,6 +2377,7 @@ var FileSessionStore = class {
       filePath,
       parse: (content, path3) => this.parseSessionContent(content, path3)
     }, json);
+    this.upsertMetadataIndexBestEffort(sessionData.metadata);
   }
   /**
    * Legacy save method for backward compatibility
@@ -2361,7 +2433,9 @@ var FileSessionStore = class {
   async delete(sessionId) {
     const filePath = this.getSessionPath(sessionId);
     try {
-      return deleteDurableFile(this.gateway, filePath);
+      const deleted = deleteDurableFile(this.gateway, filePath);
+      if (deleted) this.removeMetadataIndexEntryBestEffort(sessionId);
+      return deleted;
     } catch (e) {
       console.error(`[SessionStore] Failed to delete session: ${sessionId}`, e);
       return false;
@@ -2378,13 +2452,16 @@ var FileSessionStore = class {
    * List all session IDs
    */
   async list() {
+    return this.listSessionIdsSync();
+  }
+  listSessionIdsSync() {
     if (!this.gateway.exists(this.sessionsDir)) {
       return [];
     }
     const files = this.gateway.readdir(this.sessionsDir);
     const sessionIds = /* @__PURE__ */ new Set();
     for (const file of files) {
-      if (file.endsWith("-files.json") || file.endsWith("-files.json.bak") || file.endsWith("-files.json.prev")) {
+      if (isSessionSidecarFile(file)) {
         continue;
       }
       if (file.endsWith(".json")) {
@@ -2401,24 +2478,235 @@ var FileSessionStore = class {
    * List all session metadata
    */
   async listMetadata() {
-    const sessionIds = await this.list();
-    const metadata = [];
-    for (const id of sessionIds) {
-      const meta = await this.getMetadata(id);
-      if (meta) {
-        metadata.push(meta);
-      }
+    return await this.listMetadataIndexed();
+  }
+  async listMetadataPage(input) {
+    const limit = Math.max(0, input.limit);
+    if (limit === 0) return { metadata: [], hasMore: false };
+    const result = [];
+    for (const metadata of await this.listMetadataIndexed()) {
+      if (input.after && compareMetadataListPosition(metadata, input.after) <= 0) continue;
+      if (input.filter && !input.filter(metadata)) continue;
+      result.push(metadata);
+      if (result.length > limit) break;
     }
-    return metadata.sort((a, b) => b.updatedAt - a.updatedAt);
+    return {
+      metadata: result.slice(0, limit),
+      hasMore: result.length > limit
+    };
   }
   /**
    * Get session metadata without loading full entries
    */
   async getMetadata(sessionId) {
+    const fastMetadata = this.getMetadataFast(sessionId);
+    if (fastMetadata) return fastMetadata;
     const data = await this.load(sessionId);
     return data?.metadata ?? null;
   }
+  getMetadataFast(sessionId) {
+    const paths = durableFilePaths(this.getSessionPath(sessionId));
+    const candidates = [];
+    for (const [role, path3] of [
+      ["main", paths.main],
+      ["backup", paths.backup],
+      ["previous", paths.previous]
+    ]) {
+      try {
+        if (!this.gateway.exists(path3)) continue;
+        const metadata = this.readMetadataOnlyFast(path3);
+        if (metadata) candidates.push({ metadata, role });
+      } catch {
+      }
+    }
+    if (candidates.length === 0) return null;
+    return chooseBestMetadataCandidate(candidates).metadata;
+  }
+  readMetadataOnlyFast(path3) {
+    const fileSize = this.gateway.getFileSize(path3);
+    if (fileSize <= METADATA_FAST_READ_BYTES) {
+      return parseMetadataOnly(this.gateway.readFile(path3, "utf-8"));
+    }
+    const head = this.gateway.readFileHead(path3, METADATA_FAST_READ_BYTES, "utf-8");
+    const metadata = parseMetadataOnly(head);
+    if (metadata) return metadata;
+    return parseMetadataOnly(this.gateway.readFile(path3, "utf-8"));
+  }
+  async listMetadataIndexed() {
+    const sessionIds = await this.list();
+    const sessionIdSet = new Set(sessionIds);
+    const index = this.readMetadataIndexBestEffort();
+    if (index && this.metadataIndexMatchesSessionFiles(index, sessionIdSet)) {
+      return sortMetadata(index.sessions.map((entry) => entry.metadata).filter((metadata2) => sessionIdSet.has(metadata2.id)));
+    }
+    const metadata = [];
+    for (const id of sessionIds) {
+      const meta = await this.getMetadata(id);
+      if (meta) metadata.push(meta);
+    }
+    const sorted = sortMetadata(metadata);
+    this.writeMetadataIndexBestEffort(sorted);
+    return sorted;
+  }
+  readMetadataIndexBestEffort() {
+    try {
+      if (!this.gateway.exists(this.getMetadataIndexPath())) return null;
+      const parsed = JSON.parse(this.gateway.readFile(this.getMetadataIndexPath(), "utf-8"));
+      if (!isRecord(parsed) || parsed.v !== METADATA_INDEX_VERSION || !Array.isArray(parsed.sessions)) return null;
+      const sessions = parsed.sessions.filter(isMetadataIndexEntry);
+      if (sessions.length !== parsed.sessions.length) return null;
+      return {
+        v: METADATA_INDEX_VERSION,
+        sessions,
+        updatedAt: typeof parsed.updatedAt === "number" ? parsed.updatedAt : 0
+      };
+    } catch {
+      return null;
+    }
+  }
+  writeMetadataIndexBestEffort(sessions) {
+    try {
+      this.gateway.writeFile(this.getMetadataIndexPath(), JSON.stringify({
+        v: METADATA_INDEX_VERSION,
+        updatedAt: Date.now(),
+        sessions: sortMetadata(sessions).map((metadata) => ({
+          metadata,
+          files: this.sessionFileSignature(metadata.id)
+        }))
+      }, null, 2));
+    } catch {
+    }
+  }
+  upsertMetadataIndexBestEffort(metadata) {
+    const current = this.readMetadataIndexBestEffort();
+    if (current && !this.metadataIndexCanAcceptUpsert(current, metadata.id)) {
+      this.removeMetadataIndexFileBestEffort();
+      return;
+    }
+    const next = (current?.sessions.map((entry) => entry.metadata) ?? []).filter((item) => item.id !== metadata.id);
+    next.push(metadata);
+    this.writeMetadataIndexBestEffort(next);
+  }
+  removeMetadataIndexEntryBestEffort(sessionId) {
+    const current = this.readMetadataIndexBestEffort();
+    if (!current) return;
+    if (!this.metadataIndexCanRemoveSession(current, sessionId)) {
+      this.removeMetadataIndexFileBestEffort();
+      return;
+    }
+    this.writeMetadataIndexBestEffort(current.sessions.map((entry) => entry.metadata).filter((item) => item.id !== sessionId));
+  }
+  removeMetadataIndexFileBestEffort() {
+    try {
+      if (this.gateway.exists(this.getMetadataIndexPath())) this.gateway.deleteFile(this.getMetadataIndexPath());
+    } catch {
+    }
+  }
+  metadataIndexCanAcceptUpsert(index, upsertedSessionId) {
+    const sessionIds = new Set(this.listSessionIdsSync());
+    const indexedIds = new Set(index.sessions.map((entry) => entry.metadata.id));
+    if (indexedIds.size !== index.sessions.length) return false;
+    for (const id of sessionIds) {
+      if (id !== upsertedSessionId && !indexedIds.has(id)) return false;
+    }
+    for (const entry of index.sessions) {
+      const id = entry.metadata.id;
+      if (id !== upsertedSessionId && !sessionIds.has(id)) return false;
+      if (id !== upsertedSessionId && !sessionFileSignaturesEqual(entry.files, this.sessionFileSignature(id))) return false;
+    }
+    return true;
+  }
+  metadataIndexCanRemoveSession(index, removedSessionId) {
+    const sessionIds = new Set(this.listSessionIdsSync());
+    return index.sessions.every(
+      (entry) => entry.metadata.id === removedSessionId || sessionIds.has(entry.metadata.id) && sessionFileSignaturesEqual(entry.files, this.sessionFileSignature(entry.metadata.id))
+    );
+  }
+  metadataIndexMatchesSessionFiles(index, sessionIds) {
+    if (index.sessions.length !== sessionIds.size) return false;
+    const indexedIds = new Set(index.sessions.map((entry) => entry.metadata.id));
+    if (indexedIds.size !== index.sessions.length) return false;
+    for (const id of sessionIds) {
+      if (!indexedIds.has(id)) return false;
+    }
+    return index.sessions.every((entry) => sessionFileSignaturesEqual(entry.files, this.sessionFileSignature(entry.metadata.id)));
+  }
+  sessionFileSignature(sessionId) {
+    const paths = durableFilePaths(this.getSessionPath(sessionId));
+    return {
+      ...this.gateway.exists(paths.main) ? { main: this.fileSignature(paths.main) } : {},
+      ...this.gateway.exists(paths.backup) ? { backup: this.fileSignature(paths.backup) } : {},
+      ...this.gateway.exists(paths.previous) ? { previous: this.fileSignature(paths.previous) } : {}
+    };
+  }
+  fileSignature(path3) {
+    return {
+      size: this.gateway.getFileSize(path3),
+      modifiedAt: this.gateway.getModifiedTime(path3)
+    };
+  }
 };
+function isSessionSidecarFile(file) {
+  return file === ".metadata-index.json" || file.endsWith(".trace.json") || file.endsWith(".trace.json.bak") || file.endsWith(".trace.json.prev") || file.endsWith("-files.json") || file.endsWith("-files.json.bak") || file.endsWith("-files.json.prev");
+}
+function sortMetadata(metadata) {
+  return [...metadata].sort((a, b) => b.updatedAt - a.updatedAt || a.id.localeCompare(b.id));
+}
+function chooseBestMetadataCandidate(candidates) {
+  const main = candidates.find((candidate) => candidate.role === "main");
+  if (main) {
+    const backup = candidates.find((candidate) => candidate.role === "backup");
+    const previous = candidates.find((candidate) => candidate.role === "previous");
+    if (backup && previous && !metadataObjectsEqual(backup.metadata, main.metadata) && metadataObjectsEqual(previous.metadata, main.metadata) && backup.metadata.updatedAt >= main.metadata.updatedAt) {
+      return backup;
+    }
+    return main;
+  }
+  return [...candidates].sort((left, right) => {
+    const updatedAtDiff = right.metadata.updatedAt - left.metadata.updatedAt;
+    if (updatedAtDiff !== 0) return updatedAtDiff;
+    return durableRolePriority(right.role) - durableRolePriority(left.role);
+  })[0];
+}
+function metadataObjectsEqual(left, right) {
+  return stableJson(left) === stableJson(right);
+}
+function stableJson(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableJson(item)).join(",")}]`;
+  }
+  if (isRecord(value)) {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function compareMetadataListPosition(metadata, boundary) {
+  const updatedAtDiff = boundary.updatedAt - metadata.updatedAt;
+  if (updatedAtDiff !== 0) return updatedAtDiff;
+  return metadata.id.localeCompare(boundary.id);
+}
+function isSessionMetadata(value) {
+  if (!isRecord(value)) return false;
+  return typeof value.id === "string" && typeof value.name === "string" && typeof value.createdAt === "number" && typeof value.updatedAt === "number" && typeof value.entryCount === "number" && typeof value.messageCount === "number";
+}
+function isMetadataIndexEntry(value) {
+  if (!isRecord(value) || !isSessionMetadata(value.metadata) || !isRecord(value.files)) return false;
+  return optionalFileSignature(value.files.main) && optionalFileSignature(value.files.backup) && optionalFileSignature(value.files.previous);
+}
+function optionalFileSignature(value) {
+  if (value === void 0) return true;
+  return isRecord(value) && typeof value.size === "number" && Number.isFinite(value.size) && typeof value.modifiedAt === "number" && Number.isFinite(value.modifiedAt);
+}
+function sessionFileSignaturesEqual(left, right) {
+  return fileSignaturesEqual(left.main, right.main) && fileSignaturesEqual(left.backup, right.backup) && fileSignaturesEqual(left.previous, right.previous);
+}
+function fileSignaturesEqual(left, right) {
+  if (!left || !right) return left === right;
+  return left.size === right.size && left.modifiedAt === right.modifiedAt;
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
 
 // ../../packages/agent-framework/src/session/manager.ts
 function generateSessionId() {
@@ -2507,10 +2795,12 @@ var SessionManager = class {
   /**
    * Load an existing session
    */
-  async loadSession(sessionId) {
+  async loadSession(sessionId, options) {
     const data = await this.store.load(sessionId);
     if (!data) {
-      console.warn(`[SessionManager] Session not found: ${sessionId}`);
+      if (options?.warnIfMissing !== false) {
+        console.warn(`[SessionManager] Session not found: ${sessionId}`);
+      }
       return false;
     }
     if (!data.entries) {
@@ -3038,15 +3328,15 @@ var AgentSessionAutoCompactScheduler = class {
   }
   ensurePendingWait() {
     if (this.pendingWait) return;
-    this.pendingWait = new Promise((resolve2) => {
-      this.resolvePendingWait = resolve2;
+    this.pendingWait = new Promise((resolve3) => {
+      this.resolvePendingWait = resolve3;
     });
   }
   resolvePending() {
-    const resolve2 = this.resolvePendingWait;
+    const resolve3 = this.resolvePendingWait;
     this.pendingWait = void 0;
     this.resolvePendingWait = void 0;
-    resolve2?.();
+    resolve3?.();
   }
 };
 
@@ -3124,29 +3414,29 @@ var AgentSessionAutoContinueController = class {
     this.options.emit({ type: "auto_continue_scheduled", reason });
     this.options.agent.followUp(message);
     const setTimer = this.options.retry?.setTimeout ?? defaultSetTimeout2;
-    await new Promise((resolve2) => {
+    await new Promise((resolve3) => {
       this.autoContinueTimer = setTimer(() => {
         this.autoContinueTimer = void 0;
         if (this.options.getDisposed()) {
-          resolve2();
+          resolve3();
           return;
         }
         void this.options.continueTurn().catch(() => {
-        }).finally(resolve2);
+        }).finally(resolve3);
       }, 0);
     });
   }
   ensurePending() {
     if (this.pendingAutoContinue) return;
-    this.pendingAutoContinue = new Promise((resolve2) => {
-      this.resolvePendingAutoContinue = resolve2;
+    this.pendingAutoContinue = new Promise((resolve3) => {
+      this.resolvePendingAutoContinue = resolve3;
     });
   }
   resolvePending() {
-    const resolve2 = this.resolvePendingAutoContinue;
+    const resolve3 = this.resolvePendingAutoContinue;
     this.pendingAutoContinue = void 0;
     this.resolvePendingAutoContinue = void 0;
-    resolve2?.();
+    resolve3?.();
   }
 };
 
@@ -3555,15 +3845,15 @@ var AgentSessionQueueDispatcher = class {
   }
   ensurePending() {
     if (this.pendingDispatch) return;
-    this.pendingDispatch = new Promise((resolve2) => {
-      this.resolvePendingDispatch = resolve2;
+    this.pendingDispatch = new Promise((resolve3) => {
+      this.resolvePendingDispatch = resolve3;
     });
   }
   resolvePending() {
-    const resolve2 = this.resolvePendingDispatch;
+    const resolve3 = this.resolvePendingDispatch;
     this.pendingDispatch = void 0;
     this.resolvePendingDispatch = void 0;
-    resolve2?.();
+    resolve3?.();
   }
 };
 
@@ -3717,15 +4007,15 @@ var AgentSessionRetryController = class {
     if (this.pendingRetry) {
       return;
     }
-    this.pendingRetry = new Promise((resolve2) => {
-      this.resolvePendingRetry = resolve2;
+    this.pendingRetry = new Promise((resolve3) => {
+      this.resolvePendingRetry = resolve3;
     });
   }
   resolvePending() {
-    const resolve2 = this.resolvePendingRetry;
+    const resolve3 = this.resolvePendingRetry;
     this.pendingRetry = void 0;
     this.resolvePendingRetry = void 0;
-    resolve2?.();
+    resolve3?.();
   }
 };
 
@@ -5443,9 +5733,98 @@ function truncateLine(line, maxChars = GREP_MAX_LINE_LENGTH) {
   return { text: `${line.slice(0, maxChars)}... [truncated]`, wasTruncated: true };
 }
 
+// ../../packages/shared-headless-capabilities/src/builtin/fs/file-observation-state.ts
+function snapshotsEqual(left, right) {
+  return left.mtimeMs === right.mtimeMs && left.size === right.size && left.contentHash === right.contentHash;
+}
+function snapshotsHaveSameContent(left, right) {
+  return left.size === right.size && left.contentHash === right.contentHash;
+}
+function snapshotFromStatAndContent(stat, content) {
+  return {
+    mtimeMs: stat.mtime.getTime(),
+    size: stat.size,
+    contentHash: hashText(content)
+  };
+}
+function createFileObservationState(options = {}) {
+  const files = /* @__PURE__ */ new Map();
+  const maxFiles = Math.max(1, Math.floor(options.maxFiles ?? 100));
+  const maxRangesPerFile = Math.max(0, Math.floor(options.maxRangesPerFile ?? 8));
+  function touchFile(absolutePath, observed) {
+    files.delete(absolutePath);
+    files.set(absolutePath, observed);
+    while (files.size > maxFiles) {
+      const oldest = files.keys().next().value;
+      if (oldest === void 0) break;
+      files.delete(oldest);
+    }
+  }
+  function touchRange(readRanges, rangeKey, range) {
+    if (maxRangesPerFile === 0) {
+      readRanges.clear();
+      return;
+    }
+    readRanges.delete(rangeKey);
+    readRanges.set(rangeKey, range);
+    while (readRanges.size > maxRangesPerFile) {
+      const oldest = readRanges.keys().next().value;
+      if (oldest === void 0) break;
+      readRanges.delete(oldest);
+    }
+  }
+  return {
+    isUnchangedReadRange(absolutePath, rangeKey, snapshot, selectedContentHash) {
+      const observed = files.get(absolutePath);
+      const range = observed?.readRanges.get(rangeKey);
+      if (!observed || !range) {
+        return false;
+      }
+      const unchanged = snapshotsEqual(range.snapshot, snapshot) && range.selectedContentHash === selectedContentHash;
+      touchRange(observed.readRanges, rangeKey, range);
+      touchFile(absolutePath, observed);
+      return unchanged;
+    },
+    recordTextRead(absolutePath, rangeKey, snapshot, selectedContentHash, completeTextKnown) {
+      const observed = files.get(absolutePath) ?? {
+        snapshot,
+        completeTextKnown: false,
+        readRanges: /* @__PURE__ */ new Map()
+      };
+      const preservesFreshCompleteRead = observed.completeTextKnown && snapshotsHaveSameContent(observed.snapshot, snapshot);
+      observed.snapshot = snapshot;
+      observed.completeTextKnown = completeTextKnown || preservesFreshCompleteRead;
+      touchRange(observed.readRanges, rangeKey, { snapshot, selectedContentHash });
+      touchFile(absolutePath, observed);
+    },
+    getCompleteTextSnapshot(absolutePath) {
+      const observed = files.get(absolutePath);
+      if (!observed?.completeTextKnown) {
+        return void 0;
+      }
+      touchFile(absolutePath, observed);
+      return observed.snapshot;
+    },
+    recordCompleteTextWrite(absolutePath, snapshot) {
+      touchFile(absolutePath, {
+        snapshot,
+        completeTextKnown: true,
+        readRanges: /* @__PURE__ */ new Map()
+      });
+    },
+    invalidate(absolutePath) {
+      files.delete(absolutePath);
+    },
+    clear() {
+      files.clear();
+    }
+  };
+}
+
 // ../../packages/shared-headless-capabilities/src/builtin/fs/read.ts
 function createReadTool(cwd, options) {
   const fs2 = getFileSystem();
+  const fileObservationState = options?.fileObservationState ?? createFileObservationState();
   const rootSchema = buildRootParameterSchema(cwd, options);
   const readSchema = Type.Object({
     path: Type.String({ description: "Path to the file to read. Example: 'Scripts/PlayerController.cs' or 'Assets/Gen/config.json'." }),
@@ -5464,7 +5843,7 @@ function createReadTool(cwd, options) {
       const { path: path3, root, offset, limit, question } = params;
       const absolutePath = resolveReadPath(path3, cwd, options, root);
       return new Promise(
-        (resolve2, reject) => {
+        (resolve3, reject) => {
           if (signal?.aborted) {
             reject(new Error("Operation aborted"));
             return;
@@ -5480,11 +5859,18 @@ function createReadTool(cwd, options) {
           (async () => {
             try {
               await fs2.access(absolutePath);
+              if (isSpecialDevicePath(absolutePath)) {
+                throw new Error(`Refusing to read special device path: ${absolutePath}`);
+              }
+              const stat = await fs2.stat(absolutePath);
+              if (!stat.isFile) {
+                throw new Error(`Refusing to read non-regular file: ${absolutePath}`);
+              }
               if (aborted) return;
               const imageInfo = await readImageInfo(absolutePath, fs2);
               if (imageInfo) {
                 if (question && options?.understandFile) {
-                  resolve2(await options.understandFile({
+                  resolve3(await options.understandFile({
                     absolutePath,
                     displayPath: path3,
                     mimeType: imageInfo.mimeType,
@@ -5496,7 +5882,7 @@ function createReadTool(cwd, options) {
                   return;
                 }
                 const dimensionText = imageInfo.width && imageInfo.height ? `, ${imageInfo.width}x${imageInfo.height}` : "";
-                resolve2({
+                resolve3({
                   content: [
                     { type: "text", text: `Read image file [${imageInfo.mimeType}${dimensionText}]. Original image attached as an image block; for very large images, prefer a smaller crop or resized copy before rereading.` },
                     { type: "image", data: imageInfo.base64, mimeType: imageInfo.mimeType }
@@ -5513,7 +5899,7 @@ function createReadTool(cwd, options) {
               }
               const mediaInfo = detectUnderstandingKind(absolutePath);
               if (mediaInfo && options?.understandFile) {
-                resolve2(await options.understandFile({
+                resolve3(await options.understandFile({
                   absolutePath,
                   displayPath: path3,
                   mimeType: mediaInfo.mimeType,
@@ -5524,7 +5910,7 @@ function createReadTool(cwd, options) {
                 return;
               }
               if (mediaInfo) {
-                resolve2({
+                resolve3({
                   content: [{
                     type: "text",
                     text: `Cannot read ${mediaInfo.kind} file ${path3} semantically: no media understanding handler is configured for ${mediaInfo.mimeType}.`
@@ -5540,24 +5926,62 @@ function createReadTool(cwd, options) {
                 });
                 return;
               }
-              const content = String(await fs2.readFile(absolutePath, "utf-8"));
-              const allLines = content.split("\n");
-              const totalFileLines = allLines.length;
               const startLine = offset ? Math.max(0, offset - 1) : 0;
               const startLineDisplay = startLine + 1;
-              if (startLine >= allLines.length) {
-                throw new Error(`Offset ${offset} is beyond end of file (${allLines.length} lines total)`);
+              const range = await fs2.readTextRange(absolutePath, {
+                offsetLine: startLine,
+                limitLines: limit,
+                maxOutputLines: DEFAULT_MAX_LINES,
+                maxOutputBytes: DEFAULT_MAX_BYTES
+              }, signal);
+              const snapshot = {
+                mtimeMs: range.mtimeMs,
+                size: range.size,
+                contentHash: range.contentHash
+              };
+              const totalFileLines = range.totalLines;
+              if (startLine >= range.totalLines) {
+                throw new Error(`Offset ${offset} is beyond end of file (${range.totalLines} lines total)`);
               }
-              let selectedContent;
               let userLimitedLines;
               if (limit !== void 0) {
-                const endLine = Math.min(startLine + limit, allLines.length);
-                selectedContent = allLines.slice(startLine, endLine).join("\n");
-                userLimitedLines = endLine - startLine;
-              } else {
-                selectedContent = allLines.slice(startLine).join("\n");
+                userLimitedLines = range.selectedLines;
+              }
+              const rangeKey = `${startLineDisplay}:${limit === void 0 ? "all" : limit}`;
+              const truncation = {
+                content: range.content,
+                truncated: range.truncated,
+                truncatedBy: range.truncatedBy,
+                totalLines: range.selectedLines,
+                totalBytes: range.selectedBytes,
+                outputLines: range.outputLines,
+                outputBytes: range.outputBytes,
+                lastLinePartial: false,
+                firstLineExceedsLimit: range.firstLineExceedsLimit,
+                maxLines: DEFAULT_MAX_LINES,
+                maxBytes: DEFAULT_MAX_BYTES
+              };
+              const readStartsAtBeginning = offset === void 0 || offset === 1;
+              const readReachedEndOfFile = startLine + range.selectedLines >= range.totalLines;
+              const isCompleteTextKnown = readStartsAtBeginning && readReachedEndOfFile && !truncation.truncated && !truncation.firstLineExceedsLimit;
+              if (fileObservationState.isUnchangedReadRange(absolutePath, rangeKey, snapshot, range.selectedContentHash)) {
+                if (signal) {
+                  signal.removeEventListener("abort", onAbort);
+                }
+                resolve3({
+                  content: [{
+                    type: "text",
+                    text: "File unchanged since previous read of this range. Use a different offset/limit if you need another section."
+                  }],
+                  details: {
+                    unchangedSincePreviousRead: true,
+                    path: absolutePath,
+                    offset: startLineDisplay,
+                    limit
+                  }
+                });
+                return;
               }
-              const truncation = truncateHead(selectedContent);
               let outputText;
               let details;
               const sourceHeader = `File: ${absolutePath}
@@ -5565,7 +5989,7 @@ Base directory: ${nodePath.dirname(absolutePath)}
 
 `;
               if (truncation.firstLineExceedsLimit) {
-                const firstLineSize = formatSize(Buffer.byteLength(allLines[startLine], "utf-8"));
+                const firstLineSize = formatSize(range.firstLineBytes);
                 outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit.]`;
                 details = { truncation };
               } else if (truncation.truncated) {
@@ -5582,8 +6006,8 @@ Base directory: ${nodePath.dirname(absolutePath)}
 [Showing lines ${startLineDisplay}-${endLineDisplay} of ${totalFileLines} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue.]`;
                 }
                 details = { truncation };
-              } else if (userLimitedLines !== void 0 && startLine + userLimitedLines < allLines.length) {
-                const remaining = allLines.length - (startLine + userLimitedLines);
+              } else if (userLimitedLines !== void 0 && startLine + userLimitedLines < range.totalLines) {
+                const remaining = range.totalLines - (startLine + userLimitedLines);
                 const nextOffset = startLine + userLimitedLines + 1;
                 outputText = truncation.content;
                 outputText += `
@@ -5592,13 +6016,20 @@ Base directory: ${nodePath.dirname(absolutePath)}
               } else {
                 outputText = truncation.content;
               }
+              fileObservationState.recordTextRead(
+                absolutePath,
+                rangeKey,
+                snapshot,
+                range.selectedContentHash,
+                isCompleteTextKnown
+              );
               outputText = sourceHeader + outputText;
               const textContent = [{ type: "text", text: outputText }];
               if (aborted) return;
               if (signal) {
                 signal.removeEventListener("abort", onAbort);
               }
-              resolve2({ content: textContent, details });
+              resolve3({ content: textContent, details });
             } catch (error) {
               if (signal) {
                 signal.removeEventListener("abort", onAbort);
@@ -5613,6 +6044,10 @@ Base directory: ${nodePath.dirname(absolutePath)}
     }
   };
 }
+function isSpecialDevicePath(path3) {
+  const normalized = nodePath.resolve(path3).replace(/\\/g, "/");
+  return /^\/dev\/(?:zero|random|urandom|full|stdin|stdout|stderr|tty|console)$/.test(normalized) || /^\/dev\/fd\/[0-2]$/.test(normalized) || /^\/proc\/(?:self|\d+)\/fd\/[0-2]$/.test(normalized);
+}
 function detectUnderstandingKind(filePath) {
   const lower = filePath.toLowerCase();
   if (/\.(mp4|mov|m4v|webm|avi|mkv)$/.test(lower)) {
@@ -5734,6 +6169,8 @@ function parseWebpDimensions(bytes) {
 // ../../packages/shared-headless-capabilities/src/builtin/fs/write.ts
 function createWriteTool(cwd, options) {
   const fs2 = getFileSystem();
+  const usesExternalFileObservationState = !!options?.fileObservationState;
+  const fileObservationState = options?.fileObservationState ?? createFileObservationState();
   const rootSchema = buildRootParameterSchema(cwd, options);
   const writeSchema = Type.Object({
     path: Type.String({ description: "Path to the file to write." }),
@@ -5744,14 +6181,14 @@ function createWriteTool(cwd, options) {
   return {
     name: "write",
     label: "write",
-    description: `Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories. ${pathResolutionDescription}`,
+    description: `Write complete file contents. Use this to create a new file, or to intentionally replace an entire existing file after reading the latest full file with read_file. Do not use for targeted edits to existing files; use edit_file instead. For existing files, omitted content will be deleted. Automatically creates parent directories. ${pathResolutionDescription}`,
     parameters: writeSchema,
     execute: async (_toolCallId, params, signal) => {
       const { path: filePath, root, content } = params;
       const absolutePath = resolveToCwd(filePath, cwd, options, root);
       const dir = fs2.dirname(absolutePath);
       return new Promise(
-        (resolve2, reject) => {
+        (resolve3, reject) => {
           if (signal?.aborted) {
             reject(new Error("Operation aborted"));
             return;
@@ -5768,12 +6205,38 @@ function createWriteTool(cwd, options) {
             try {
               await fs2.mkdir(dir, { recursive: true });
               if (aborted) return;
+              let fileExists = false;
+              try {
+                const stat = await fs2.stat(absolutePath);
+                fileExists = stat.isFile;
+              } catch {
+                fileExists = false;
+              }
+              if (fileExists) {
+                const currentContent = String(await fs2.readFile(absolutePath, "utf-8"));
+                const currentStat = await fs2.stat(absolutePath);
+                const currentSnapshot = snapshotFromStatAndContent(currentStat, currentContent);
+                const observedSnapshot = fileObservationState.getCompleteTextSnapshot(absolutePath);
+                if (!observedSnapshot) {
+                  throw new Error(
+                    usesExternalFileObservationState ? "Read the current full file with read_file before overwriting it, or use edit_file for targeted changes." : "Existing-file overwrite requires write_file to share a fileObservationState with read_file; use createSharedFileSystemTools or pass the same fileObservationState to both tools."
+                  );
+                }
+                if (!snapshotsHaveSameContent(observedSnapshot, currentSnapshot)) {
+                  throw new Error("File changed since it was read. Read the latest file contents before overwriting it.");
+                }
+              }
               await fs2.writeFile(absolutePath, content, "utf-8");
+              const writtenStat = await fs2.stat(absolutePath);
+              fileObservationState.recordCompleteTextWrite(
+                absolutePath,
+                snapshotFromStatAndContent(writtenStat, content)
+              );
               if (aborted) return;
               if (signal) {
                 signal.removeEventListener("abort", onAbort);
               }
-              resolve2({
+              resolve3({
                 content: [{ type: "text", text: `Successfully wrote ${content.length} bytes to ${filePath}` }],
                 details: void 0
               });
@@ -5839,28 +6302,30 @@ function buildFuzzyIndexMap(text) {
   }
   return { normalized, originalStartByNormalizedIndex, originalEndByNormalizedIndex };
 }
-function countOccurrences(content, needle) {
-  if (needle.length === 0) return 0;
-  let count = 0;
+function collectMatches(content, needle) {
+  if (needle.length === 0) return [];
+  const matches = [];
   let index = 0;
   while (true) {
     const nextIndex = content.indexOf(needle, index);
     if (nextIndex === -1) break;
-    count++;
+    matches.push({ index: nextIndex, matchLength: needle.length });
     index = nextIndex + needle.length;
   }
-  return count;
+  return matches;
 }
 function fuzzyFindText(content, oldText) {
   const exactIndex = content.indexOf(oldText);
   if (exactIndex !== -1) {
+    const matches2 = collectMatches(content, oldText);
     return {
       found: true,
       index: exactIndex,
       matchLength: oldText.length,
       usedFuzzyMatch: false,
       contentForReplacement: content,
-      occurrences: countOccurrences(content, oldText),
+      occurrences: matches2.length,
+      matches: matches2,
       matchKind: "exact"
     };
   }
@@ -5875,6 +6340,7 @@ function fuzzyFindText(content, oldText) {
       usedFuzzyMatch: false,
       contentForReplacement: content,
       occurrences: 0,
+      matches: [],
       matchKind: "none"
     };
   }
@@ -5887,19 +6353,26 @@ function fuzzyFindText(content, oldText) {
       usedFuzzyMatch: false,
       contentForReplacement: content,
       occurrences: 0,
+      matches: [],
       matchKind: "none"
     };
   }
-  const endFuzzyIndex = fuzzyIndex + fuzzyOldText.length - 1;
-  const originalStart = fuzzyMap.originalStartByNormalizedIndex[fuzzyIndex];
-  const originalEnd = fuzzyMap.originalEndByNormalizedIndex[endFuzzyIndex];
+  const fuzzyMatches = collectMatches(fuzzyContent, fuzzyOldText);
+  const matches = fuzzyMatches.map((match) => {
+    const endFuzzyIndex = match.index + match.matchLength - 1;
+    const originalStart = fuzzyMap.originalStartByNormalizedIndex[match.index] ?? match.index;
+    const originalEnd = fuzzyMap.originalEndByNormalizedIndex[endFuzzyIndex] ?? originalStart + match.matchLength;
+    return { index: originalStart, matchLength: originalEnd - originalStart };
+  });
+  const firstMatch = matches[0] ?? { index: -1, matchLength: 0 };
   return {
     found: true,
-    index: originalStart,
-    matchLength: originalEnd - originalStart,
+    index: firstMatch.index,
+    matchLength: firstMatch.matchLength,
     usedFuzzyMatch: true,
     contentForReplacement: content,
-    occurrences: countOccurrences(fuzzyContent, fuzzyOldText),
+    occurrences: matches.length,
+    matches,
     matchKind: "fuzzy"
   };
 }
@@ -5947,7 +6420,7 @@ function generateDiffString(oldContent, newContent, contextLines = 4) {
 }
 
 // ../../packages/shared-headless-capabilities/src/builtin/fs/edit.ts
-function validateEditArgs(path3, oldText, newText) {
+function validateEditArgs(path3, oldText, newText, replaceAll) {
   const filePath = typeof path3 === "string" ? path3.trim() : "";
   if (!filePath) {
     throw new Error("Invalid edit_file arguments: path cannot be empty. Pass the file path in path and the exact text to replace in oldText.");
@@ -5961,11 +6434,14 @@ function validateEditArgs(path3, oldText, newText) {
   if (oldText === newText) {
     throw new Error("Invalid edit_file arguments: oldText and newText are identical, so the edit would make no change.");
   }
+  if (replaceAll !== void 0 && typeof replaceAll !== "boolean") {
+    throw new Error("Invalid edit_file arguments: replaceAll must be a boolean when provided.");
+  }
   if (filePath.includes("<|tool") || oldText.includes("<|tool") || newText.includes("<|tool")) {
     throw new Error("Invalid edit_file arguments: path, oldText, and newText must be real edit values, not tool-call markup.");
   }
 }
-function countOccurrences2(content, needle) {
+function countOccurrences(content, needle) {
   if (needle.length === 0) return 0;
   let count = 0;
   let index = 0;
@@ -5992,6 +6468,8 @@ function createEditErrorResult(params) {
       diff: "",
       oldTextOccurrences: params.oldTextOccurrences,
       newTextOccurrences: params.newTextOccurrences,
+      replaceAll: params.replaceAll,
+      replacedOccurrences: 0,
       errorReason: params.errorReason,
       recoveryHint: params.recoveryHint,
       staleBaseLikely: params.staleBaseLikely,
@@ -6002,12 +6480,14 @@ function createEditErrorResult(params) {
 }
 function createEditTool(cwd, options) {
   const fs2 = getFileSystem();
+  const fileObservationState = options?.fileObservationState ?? createFileObservationState();
   const rootSchema = buildRootParameterSchema(cwd, options);
   const editSchema = Type.Object({
     path: Type.String({ description: "Path to the file to edit." }),
     ...rootSchema ? { root: rootSchema } : {},
     oldText: Type.String({ description: "Exact text to find and replace (must match exactly)" }),
-    newText: Type.String({ description: "New text to replace the old text with" })
+    newText: Type.String({ description: "New text to replace the old text with" }),
+    replaceAll: Type.Optional(Type.Boolean({ description: "Replace every occurrence of oldText. Only set this to true when every matching occurrence should be replaced." }))
   });
   const pathResolutionDescription = buildPathResolutionDescription(cwd, options);
   return {
@@ -6016,10 +6496,11 @@ function createEditTool(cwd, options) {
     description: `Edit a file by replacing exact text. The oldText must match exactly (including whitespace). Use this for precise, surgical edits. ${pathResolutionDescription}`,
     parameters: editSchema,
     execute: async (_toolCallId, params, signal) => {
-      const { path: path3, root, oldText, newText } = params;
-      validateEditArgs(path3, oldText, newText);
+      const { path: path3, root, oldText, newText, replaceAll } = params;
+      validateEditArgs(path3, oldText, newText, replaceAll);
+      const shouldReplaceAll = replaceAll === true;
       const absolutePath = resolveToCwd(path3, cwd, options, root);
-      return new Promise((resolve2, reject) => {
+      return new Promise((resolve3, reject) => {
         if (signal?.aborted) {
           reject(new Error("Operation aborted"));
           return;
@@ -6049,50 +6530,57 @@ function createEditTool(cwd, options) {
             const normalizedContent = normalizeToLF(content);
             const normalizedOldText = normalizeToLF(oldText);
             const normalizedNewText = normalizeToLF(newText);
-            const newTextOccurrences = countOccurrences2(normalizedContent, normalizedNewText);
+            const newTextOccurrences = countOccurrences(normalizedContent, normalizedNewText);
             const matchResult = fuzzyFindText(normalizedContent, normalizedOldText);
             if (!matchResult.found) {
               if (signal) signal.removeEventListener("abort", onAbort);
-              resolve2(
+              resolve3(
                 createEditErrorResult({
                   message: `Could not find oldText in ${path3}.`,
                   matchKind: "none",
                   errorReason: "old_text_not_found",
                   oldTextOccurrences: 0,
                   newTextOccurrences,
+                  replaceAll: shouldReplaceAll,
                   staleBaseLikely: newTextOccurrences > 0,
                   alreadyAppliedCandidate: newTextOccurrences > 0,
-                  recoveryHint: newTextOccurrences > 0 ? "The replacement text already appears in the current file. Read the current file before retrying; this may be a stale oldText from an earlier edit in the same turn." : "Read the current file and retry with a larger exact block copied from the latest file contents."
+                  recoveryHint: newTextOccurrences > 0 ? "The replacement text already appears in the current file. Read the current file before retrying; this may be a stale oldText from an earlier edit in the same turn." : "Read the current file and retry with exact text copied from the latest file contents."
                 })
               );
               return;
             }
-            if (matchResult.occurrences > 1) {
+            if (matchResult.occurrences > 1 && !shouldReplaceAll) {
               if (signal) signal.removeEventListener("abort", onAbort);
-              resolve2(
+              resolve3(
                 createEditErrorResult({
                   message: `Found ${matchResult.occurrences} occurrences of oldText in ${path3}. The text must be unique.`,
                   matchKind: matchResult.matchKind,
                   errorReason: "old_text_not_unique",
                   oldTextOccurrences: matchResult.occurrences,
                   newTextOccurrences,
-                  recoveryHint: "Read the current file and retry with a larger exact block that uniquely identifies the intended location."
+                  replaceAll: shouldReplaceAll,
+                  recoveryHint: "Read the current file and retry with a larger exact block copied from the latest file contents, or set replaceAll to true if every occurrence should be replaced."
                 })
               );
               return;
             }
             if (aborted) return;
-            const baseContent = normalizedContent;
-            const newContent = baseContent.substring(0, matchResult.index) + normalizedNewText + baseContent.substring(matchResult.index + matchResult.matchLength);
+            const baseContent = matchResult.contentForReplacement;
+            const matchesToReplace = shouldReplaceAll ? matchResult.matches : matchResult.matches.slice(0, 1);
+            let newContent = baseContent;
+            for (const match of [...matchesToReplace].sort((left, right) => right.index - left.index)) {
+              newContent = newContent.substring(0, match.index) + normalizedNewText + newContent.substring(match.index + match.matchLength);
+            }
             if (baseContent === newContent) {
               if (signal) signal.removeEventListener("abort", onAbort);
-              resolve2(
+              resolve3(
                 createEditErrorResult({
                   message: `No changes made to ${path3}. The replacement produced identical content.`,
                   matchKind: matchResult.matchKind,
                   errorReason: "replacement_no_change",
                   oldTextOccurrences: matchResult.occurrences,
                   newTextOccurrences,
+                  replaceAll: shouldReplaceAll,
                   recoveryHint: "Read the current file and verify whether the intended edit is already present or whether oldText/newText need a larger exact block.",
                   alreadyAppliedCandidate: newTextOccurrences > 0
                 })
@@ -6101,16 +6589,17 @@ function createEditTool(cwd, options) {
             }
             const finalContent = bom + restoreLineEndings(newContent, originalEnding);
             await fs2.writeFile(absolutePath, finalContent, "utf-8");
+            fileObservationState.invalidate(absolutePath);
             if (aborted) return;
             if (signal) {
               signal.removeEventListener("abort", onAbort);
             }
             const diffResult = generateDiffString(content, restoreLineEndings(newContent, originalEnding));
-            resolve2({
+            resolve3({
               content: [
                 {
                   type: "text",
-                  text: `Successfully replaced text in ${path3} using ${matchResult.matchKind} match.`
+                  text: `Successfully replaced text in ${path3} using ${matchResult.matchKind} match (${matchesToReplace.length} occurrence${matchesToReplace.length === 1 ? "" : "s"}).`
                 },
                 { type: "text", text: diffResult.diff }
               ],
@@ -6121,7 +6610,9 @@ function createEditTool(cwd, options) {
                 diff: diffResult.diff,
                 firstChangedLine: diffResult.firstChangedLine,
                 oldTextOccurrences: matchResult.occurrences,
-                newTextOccurrences
+                newTextOccurrences,
+                replaceAll: shouldReplaceAll,
+                replacedOccurrences: matchesToReplace.length
               }
             });
           } catch (error) {
@@ -6155,7 +6646,7 @@ function createLsTool(cwd, options) {
     description: `List directory contents. Use this to inspect folders before reading or writing files. Example: list_dir path='Scripts' or list_dir path='Data'. ${pathResolutionDescription} Returns entries sorted alphabetically, with '/' suffix for directories. Includes dotfiles. Output is truncated to ${DEFAULT_LIMIT} entries or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first).`,
     parameters: lsSchema,
     execute: async (_toolCallId, params, signal) => {
-      return new Promise((resolve2, reject) => {
+      return new Promise((resolve3, reject) => {
         if (signal?.aborted) {
           reject(new Error("Operation aborted"));
           return;
@@ -6205,7 +6696,7 @@ function createLsTool(cwd, options) {
             }
             signal?.removeEventListener("abort", onAbort);
             if (results.length === 0) {
-              resolve2({ content: [{ type: "text", text: "(empty directory)" }], details: void 0 });
+              resolve3({ content: [{ type: "text", text: "(empty directory)" }], details: void 0 });
               return;
             }
             const rawOutput = results.join("\n");
@@ -6226,7 +6717,7 @@ function createLsTool(cwd, options) {
 
 [${notices.join(". ")}]`;
             }
-            resolve2({
+            resolve3({
               content: [{ type: "text", text: output }],
               details: Object.keys(details).length > 0 ? details : void 0
             });
@@ -6402,11 +6893,11 @@ function waitForFileCompletion(requestId) {
   if (existing) {
     return Promise.resolve(existing);
   }
-  return new Promise((resolve2) => {
-    store.waiters.set(requestId, resolve2);
+  return new Promise((resolve3) => {
+    store.waiters.set(requestId, resolve3);
   });
 }
-async function runNativeGrep(searchPath, pattern, globPattern, ignoreCase, literal, contextLines, limit, signal) {
+async function runNativeGrep(searchPath, pattern, globPattern, ignoreCase, literal, contextLines, limit, outputMode, offset, signal) {
   const bridge = getNativeFileBridge();
   if (!bridge) {
     throw new Error("CS.Pie.PieFileBridge not available");
@@ -6418,7 +6909,9 @@ async function runNativeGrep(searchPath, pattern, globPattern, ignoreCase, liter
     !!ignoreCase,
     !!literal,
     contextLines,
-    limit
+    limit,
+    outputMode,
+    offset
   );
   const onAbort = () => bridge.CancelRequest(requestId);
   signal?.addEventListener("abort", onAbort, { once: true });
@@ -6443,6 +6936,45 @@ async function runNativeGrep(searchPath, pattern, globPattern, ignoreCase, liter
     bridge.ReleaseRequest(requestId);
   }
 }
+function normalizeOutputMode(value) {
+  if (value === void 0 || value === null || value === "content") return "content";
+  if (value === "files_with_matches" || value === "count") return value;
+  throw new Error("Invalid grep_text arguments: outputMode must be one of content, files_with_matches, or count.");
+}
+function normalizeNonNegativeInteger(value, fallback, name) {
+  if (value === void 0 || value === null) return fallback;
+  const numberValue = Number(value);
+  if (!Number.isInteger(numberValue) || numberValue < 0) {
+    throw new Error(`Invalid grep_text arguments: ${name} must be a non-negative integer.`);
+  }
+  return numberValue;
+}
+function formatContentMatches(matches, contextLines) {
+  const outputLines = [];
+  let linesTruncated = false;
+  for (const match of matches) {
+    const start = contextLines > 0 ? Math.max(0, match.lineIndex - contextLines) : match.lineIndex;
+    const end = contextLines > 0 ? Math.min(match.lines.length - 1, match.lineIndex + contextLines) : match.lineIndex;
+    for (let c = start; c <= end; c++) {
+      const lineText = match.lines[c];
+      const { text: truncatedText, wasTruncated } = truncateLine(lineText);
+      if (wasTruncated) linesTruncated = true;
+      const currentLineNum = c + 1;
+      if (c === match.lineIndex) {
+        outputLines.push(`${match.relativePath}:${currentLineNum}: ${truncatedText}`);
+      } else {
+        outputLines.push(`${match.relativePath}-${currentLineNum}- ${truncatedText}`);
+      }
+    }
+  }
+  return { lines: outputLines, linesTruncated };
+}
+function sortFileSummariesByMtime(files) {
+  return files.sort((left, right) => {
+    if (right.mtimeMs !== left.mtimeMs) return right.mtimeMs - left.mtimeMs;
+    return left.relativePath.localeCompare(right.relativePath);
+  });
+}
 async function collectFiles(dirPath, globPattern, fs2, isGitignored = () => false) {
   const files = [];
   const queue = [{ dir: dirPath, relPrefix: "" }];
@@ -6502,13 +7034,19 @@ function createGrepTextTool(cwd, options) {
     context: Type.Optional(
       Type.Number({ description: "Number of lines to show before and after each match (default: 0)" })
     ),
+    outputMode: Type.Optional(Type.Union([
+      Type.Literal("content"),
+      Type.Literal("files_with_matches"),
+      Type.Literal("count")
+    ], { description: "Result mode: content returns matching lines, files_with_matches returns matching file paths, count returns per-file match counts." })),
+    offset: Type.Optional(Type.Number({ description: "Number of results to skip before returning output (default: 0)." })),
     limit: Type.Optional(Type.Number({ description: "Maximum number of matches to return (default: 100)" }))
   });
   const pathResolutionDescription = buildPathResolutionDescription(cwd, options);
   return {
     name: "grep_text",
     label: "grep_text",
-    description: `Search file contents for a pattern. ${pathResolutionDescription} Returns matching lines with file paths and line numbers. Output is truncated to ${DEFAULT_LIMIT2} matches or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Long lines are truncated to ${GREP_MAX_LINE_LENGTH} chars.`,
+    description: `Search file contents for a pattern. ${pathResolutionDescription} outputMode='content' returns matching lines with file paths and line numbers, outputMode='files_with_matches' returns matching file paths, and outputMode='count' returns per-file match counts. Output is truncated to ${DEFAULT_LIMIT2} results or ${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first). Long lines are truncated to ${GREP_MAX_LINE_LENGTH} chars.`,
     parameters: grepSchema,
     execute: async (_toolCallId, params, signal) => {
       const {
@@ -6519,9 +7057,11 @@ function createGrepTextTool(cwd, options) {
         ignoreCase,
         literal,
         context: contextLines,
+        outputMode: rawOutputMode,
+        offset: rawOffset,
         limit
       } = params;
-      return new Promise((resolve2, reject) => {
+      return new Promise((resolve3, reject) => {
         if (signal?.aborted) {
           reject(new Error("Operation aborted"));
           return;
@@ -6531,6 +7071,8 @@ function createGrepTextTool(cwd, options) {
         (async () => {
           try {
             const searchPath = resolveToCwd(searchDir || ".", cwd, options, root);
+            const outputMode = normalizeOutputMode(rawOutputMode);
+            const offset = normalizeNonNegativeInteger(rawOffset, 0, "offset");
             const effectiveLimit = Math.max(1, limit ?? DEFAULT_LIMIT2);
             const ctx = contextLines && contextLines > 0 ? contextLines : 0;
             let isDir;
@@ -6558,6 +7100,8 @@ function createGrepTextTool(cwd, options) {
             let matchCount = 0;
             let matchLimitReached = false;
             let linesTruncated = false;
+            let filesScanned = 0;
+            let totalFilesWithMatches = 0;
             const isGitignored = await loadGitignoreMatcher(searchPath, fs2);
             if (platform === "puerts" && getNativeFileBridge()) {
               const nativeResult = await runNativeGrep(
@@ -6568,12 +7112,16 @@ function createGrepTextTool(cwd, options) {
                 !!literal,
                 ctx,
                 effectiveLimit,
+                outputMode,
+                offset,
                 signal
               );
               outputLines = nativeResult.Lines ?? [];
-              matchCount = nativeResult.MatchCount ?? 0;
+              matchCount = nativeResult.TotalMatches ?? nativeResult.MatchCount ?? 0;
               matchLimitReached = !!nativeResult.MatchLimitReached;
               linesTruncated = !!nativeResult.LinesTruncated;
+              filesScanned = nativeResult.FilesScanned ?? 0;
+              totalFilesWithMatches = nativeResult.TotalFilesWithMatches ?? 0;
               globalThis.pieBridge?.log?.(
                 "info",
                 `[grep_text] path=${searchPath} pattern=${pattern} matches=${matchCount} files=${nativeResult.FilesScanned ?? 0}`
@@ -6586,11 +7134,9 @@ function createGrepTextTool(cwd, options) {
               } else {
                 filePaths = [searchPath];
               }
+              const contentMatches = [];
+              const fileSummaries = /* @__PURE__ */ new Map();
               for (const filePath of filePaths) {
-                if (matchCount >= effectiveLimit) {
-                  matchLimitReached = true;
-                  break;
-                }
                 if (signal?.aborted) {
                   reject(new Error("Operation aborted"));
                   return;
@@ -6603,36 +7149,65 @@ function createGrepTextTool(cwd, options) {
                 }
                 const lines = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
                 const relativePath = isDir ? fs2.relative(searchPath, filePath) : fs2.basename(filePath);
+                filesScanned++;
+                let fileMatchCount = 0;
                 for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
-                  if (matchCount >= effectiveLimit) {
-                    matchLimitReached = true;
-                    break;
-                  }
                   regex.lastIndex = 0;
                   if (regex.test(lines[lineIdx])) {
                     matchCount++;
-                    const start = ctx > 0 ? Math.max(0, lineIdx - ctx) : lineIdx;
-                    const end = ctx > 0 ? Math.min(lines.length - 1, lineIdx + ctx) : lineIdx;
-                    for (let c = start; c <= end; c++) {
-                      const lineText = lines[c];
-                      const { text: truncatedText, wasTruncated } = truncateLine(lineText);
-                      if (wasTruncated) linesTruncated = true;
-                      const currentLineNum = c + 1;
-                      if (c === lineIdx) {
-                        outputLines.push(`${relativePath}:${currentLineNum}: ${truncatedText}`);
-                      } else {
-                        outputLines.push(`${relativePath}-${currentLineNum}- ${truncatedText}`);
-                      }
+                    fileMatchCount++;
+                    if (outputMode === "content" && matchCount > offset && matchCount <= offset + effectiveLimit) {
+                      contentMatches.push({ filePath, relativePath, lineIndex: lineIdx, lines });
                     }
                   }
                 }
+                if (fileMatchCount > 0) {
+                  const fileStat = await fs2.stat(filePath);
+                  fileSummaries.set(filePath, {
+                    filePath,
+                    relativePath,
+                    mtimeMs: fileStat.mtime.getTime(),
+                    matchCount: fileMatchCount
+                  });
+                }
+              }
+              totalFilesWithMatches = fileSummaries.size;
+              if (outputMode === "content") {
+                matchLimitReached = matchCount > offset + effectiveLimit;
+                const formatted = formatContentMatches(contentMatches.slice(0, effectiveLimit), ctx);
+                outputLines = formatted.lines;
+                linesTruncated = formatted.linesTruncated;
+              } else {
+                const sortedFiles = sortFileSummariesByMtime([...fileSummaries.values()]);
+                const page = sortedFiles.slice(offset, offset + effectiveLimit);
+                if (offset + effectiveLimit < sortedFiles.length) {
+                  matchLimitReached = true;
+                }
+                if (outputMode === "files_with_matches") {
+                  outputLines = page.map((file) => file.relativePath);
+                } else {
+                  outputLines = [
+                    `Total matches: ${matchCount}`,
+                    `Files with matches: ${sortedFiles.length}`,
+                    ...page.map((file) => `${file.relativePath}: ${file.matchCount}`)
+                  ];
+                }
               }
             }
             signal?.removeEventListener("abort", onAbort);
             if (matchCount === 0) {
-              resolve2({
+              resolve3({
                 content: [{ type: "text", text: "No matches found" }],
-                details: { noMatches: true }
+                details: {
+                  noMatches: true,
+                  outputMode,
+                  totalMatches: 0,
+                  totalFilesWithMatches: 0,
+                  filesScanned,
+                  offset,
+                  limit: effectiveLimit,
+                  resultLimitReached: false
+                }
               });
               return;
             }
@@ -6640,10 +7215,17 @@ function createGrepTextTool(cwd, options) {
             const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
             let output = truncation.content;
             const details = {};
+            details.outputMode = outputMode;
+            details.totalMatches = matchCount;
+            details.totalFilesWithMatches = totalFilesWithMatches;
+            details.filesScanned = filesScanned;
+            details.offset = offset;
+            details.limit = effectiveLimit;
+            details.resultLimitReached = matchLimitReached;
             const notices = [];
             if (matchLimitReached) {
               notices.push(
-                `${effectiveLimit} matches limit reached. Use limit=${effectiveLimit * 2} for more, or refine pattern`
+                outputMode === "content" ? `${effectiveLimit} matches limit reached. Use offset=${offset + effectiveLimit} for more, increase limit, or refine pattern` : `${effectiveLimit} results limit reached. Use offset=${offset + effectiveLimit} for more, increase limit, or refine pattern`
               );
               details.matchLimitReached = effectiveLimit;
             }
@@ -6662,7 +7244,7 @@ function createGrepTextTool(cwd, options) {
 
 [${notices.join(". ")}]`;
             }
-            resolve2({
+            resolve3({
               content: [{ type: "text", text: output }],
               details: Object.keys(details).length > 0 ? details : void 0
             });
@@ -6745,8 +7327,8 @@ function waitForFileCompletion2(requestId) {
   if (existing) {
     return Promise.resolve(existing);
   }
-  return new Promise((resolve2) => {
-    store.waiters.set(requestId, resolve2);
+  return new Promise((resolve3) => {
+    store.waiters.set(requestId, resolve3);
   });
 }
 async function runNativeFind(searchPath, pattern, limit, signal) {
@@ -6836,7 +7418,7 @@ function createFindFilesTool(cwd, options) {
     parameters: findSchema,
     execute: async (_toolCallId, params, signal) => {
       const { pattern, path: searchDir, root, limit } = params;
-      return new Promise((resolve2, reject) => {
+      return new Promise((resolve3, reject) => {
         if (signal?.aborted) {
           reject(new Error("Operation aborted"));
           return;
@@ -6852,10 +7434,12 @@ function createFindFilesTool(cwd, options) {
               return;
             }
             let results;
+            let resultLimitReached = false;
             const isGitignored = await loadGitignoreMatcher(searchPath, fs2);
             if (platform === "puerts" && getNativeFileBridge2()) {
               const nativeResult = await runNativeFind(searchPath, pattern, effectiveLimit, signal);
               results = (nativeResult.Results ?? []).filter((filePath) => !isGitignored(filePath, false));
+              resultLimitReached = !!nativeResult.LimitReached && results.length >= effectiveLimit;
               globalThis.pieBridge?.log?.(
                 "info",
                 `[find_files] path=${searchPath} pattern=${pattern} matches=${results.length} dirs=${nativeResult.ScannedDirectories ?? 0} files=${nativeResult.ScannedFiles ?? 0}`
@@ -6864,28 +7448,33 @@ function createFindFilesTool(cwd, options) {
               try {
                 const _require = globalThis.require || __require;
                 const { globSync } = _require("glob");
-                results = globSync(pattern, {
+                const allResults = globSync(pattern, {
                   cwd: searchPath,
                   ignore: ["**/node_modules/**", "**/.git/**"],
                   nodir: false,
                   absolute: false,
                   dot: true
-                }).filter((filePath) => !isGitignored(filePath, false)).slice(0, effectiveLimit);
+                }).filter((filePath) => !isGitignored(filePath, false));
+                resultLimitReached = allResults.length > effectiveLimit;
+                results = allResults.slice(0, effectiveLimit);
               } catch {
-                results = await globFiles(searchPath, pattern, fs2, effectiveLimit, signal, isGitignored);
+                const allResults = await globFiles(searchPath, pattern, fs2, effectiveLimit + 1, signal, isGitignored);
+                resultLimitReached = allResults.length > effectiveLimit;
+                results = allResults.slice(0, effectiveLimit);
               }
             } else {
-              results = await globFiles(searchPath, pattern, fs2, effectiveLimit, signal, isGitignored);
+              const allResults = await globFiles(searchPath, pattern, fs2, effectiveLimit + 1, signal, isGitignored);
+              resultLimitReached = allResults.length > effectiveLimit;
+              results = allResults.slice(0, effectiveLimit);
             }
             signal?.removeEventListener("abort", onAbort);
             if (results.length === 0) {
-              resolve2({
+              resolve3({
                 content: [{ type: "text", text: "No files found matching pattern" }],
                 details: { noMatches: true }
               });
               return;
             }
-            const resultLimitReached = results.length >= effectiveLimit;
             const rawOutput = results.join("\n");
             const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
             let resultOutput = truncation.content;
@@ -6902,7 +7491,7 @@ function createFindFilesTool(cwd, options) {
             if (notices.length > 0) {
               resultOutput += "\n\n[" + notices.join(". ") + "]";
             }
-            resolve2({
+            resolve3({
               content: [{ type: "text", text: resultOutput }],
               details: Object.keys(details).length > 0 ? details : void 0
             });
@@ -6918,10 +7507,12 @@ function createFindFilesTool(cwd, options) {
 
 // ../../packages/shared-headless-capabilities/src/builtin/fs/index.ts
 function createSharedFileSystemTools(sandboxRoot, options) {
+  const fileObservationState = options?.fileObservationState ?? createFileObservationState();
+  const sharedOptions = { ...options, fileObservationState };
   return [
-    createReadTool(sandboxRoot, options),
-    createWriteTool(sandboxRoot, options),
-    createEditTool(sandboxRoot, options),
+    createReadTool(sandboxRoot, sharedOptions),
+    createWriteTool(sandboxRoot, sharedOptions),
+    createEditTool(sandboxRoot, sharedOptions),
     createLsTool(sandboxRoot, options),
     createGrepTextTool(sandboxRoot, options),
     createFindFilesTool(sandboxRoot, options)
@@ -7048,23 +7639,23 @@ async function understandFileWithModel(deps, request) {
 }
 
 // ../../packages/shared-headless-capabilities/src/session-trace.ts
-function isRecord(value) {
+function isRecord2(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 function getTextFromMessageContent(content) {
   if (typeof content === "string") return content;
   if (!Array.isArray(content)) return "";
-  return content.filter((block) => isRecord(block) && block.type === "text").map((block) => String(block.text || "")).join("");
+  return content.filter((block) => isRecord2(block) && block.type === "text").map((block) => String(block.text || "")).join("");
 }
 function summarizeToolResult(result) {
-  if (!isRecord(result)) return void 0;
+  if (!isRecord2(result)) return void 0;
   const content = Array.isArray(result.content) ? result.content : [];
-  const text = content.filter((item) => isRecord(item) && item.type === "text").map((item) => String(item.text || "")).join("\n").trim();
+  const text = content.filter((item) => isRecord2(item) && item.type === "text").map((item) => String(item.text || "")).join("\n").trim();
   if (!text) return void 0;
   return text.length > 500 ? `${text.slice(0, 500)}...` : text;
 }
 function summarizeToolResultDetails(result) {
-  if (!isRecord(result) || !isRecord(result.details)) return void 0;
+  if (!isRecord2(result) || !isRecord2(result.details)) return void 0;
   const details = result.details;
   const keys = [
     "providerMode",
@@ -7099,7 +7690,7 @@ function summarizeToolResultDetails(result) {
     const value = details[key];
     if (key === "attempts" && Array.isArray(value)) {
       summary[key] = value.slice(-5).map((attempt) => {
-        if (!isRecord(attempt)) return attempt;
+        if (!isRecord2(attempt)) return attempt;
         return {
           provider: attempt.provider,
           modelId: attempt.modelId,
@@ -7117,7 +7708,7 @@ function summarizeToolResultDetails(result) {
       summary[key] = {
         count: value.length,
         items: value.slice(0, 5).map((entry) => {
-          if (!isRecord(entry)) return entry;
+          if (!isRecord2(entry)) return entry;
           return {
             url: entry.finalUrl || entry.url,
             title: entry.title,
@@ -7133,7 +7724,7 @@ function summarizeToolResultDetails(result) {
     }
     if (key === "providerHealth" && Array.isArray(value)) {
       summary[key] = value.slice(0, 5).map((entry) => {
-        if (!isRecord(entry)) return entry;
+        if (!isRecord2(entry)) return entry;
         return {
           routeKey: entry.routeKey,
           attempts: entry.attempts,
@@ -7148,7 +7739,7 @@ function summarizeToolResultDetails(result) {
     }
     if (key === "providerAttempts" && Array.isArray(value)) {
       summary[key] = value.slice(-5).map((attempt) => {
-        if (!isRecord(attempt)) return attempt;
+        if (!isRecord2(attempt)) return attempt;
         return {
           provider: attempt.provider,
           modelId: attempt.modelId,
@@ -7180,10 +7771,10 @@ function summarizeString(value, maxLength = 300) {
   return value.length > maxLength ? `${value.slice(0, maxLength)}...` : value;
 }
 function summarizeMessage(message) {
-  if (!isRecord(message)) return typeof message;
+  if (!isRecord2(message)) return typeof message;
   if ("contentBlocks" in message && !("content" in message)) return message;
   const content = Array.isArray(message.content) ? message.content : [];
-  const blockTypes = content.filter(isRecord).map((block) => String(block.type || "unknown")).slice(0, 10);
+  const blockTypes = content.filter(isRecord2).map((block) => String(block.type || "unknown")).slice(0, 10);
   const text = getTextFromMessageContent(content);
   return {
     role: message.role,
@@ -7195,12 +7786,12 @@ function summarizeMessage(message) {
   };
 }
 function summarizeToolResults(value) {
-  if (isRecord(value) && typeof value.count === "number" && !Array.isArray(value)) return value;
+  if (isRecord2(value) && typeof value.count === "number" && !Array.isArray(value)) return value;
   if (!Array.isArray(value)) return typeof value;
   let errors = 0;
   const toolNames = [];
   for (const result of value) {
-    if (!isRecord(result)) continue;
+    if (!isRecord2(result)) continue;
     if (result.isError === true) errors++;
     const toolName = typeof result.toolName === "string" ? result.toolName : typeof result.name === "string" ? result.name : void 0;
     if (toolName && toolNames.length < 10) toolNames.push(toolName);
@@ -7212,7 +7803,7 @@ function collectTextLength(content) {
   if (!Array.isArray(content)) return 0;
   let length = 0;
   for (const block of content) {
-    if (!isRecord(block)) continue;
+    if (!isRecord2(block)) continue;
     if (typeof block.text === "string") length += block.text.length;
   }
   return length;
@@ -7221,7 +7812,7 @@ function collectArgumentLength(content) {
   if (!Array.isArray(content)) return 0;
   let length = 0;
   for (const block of content) {
-    if (!isRecord(block) || !("arguments" in block)) continue;
+    if (!isRecord2(block) || !("arguments" in block)) continue;
     if (typeof block.arguments === "string") {
       length += block.arguments.length;
       continue;
@@ -7244,7 +7835,7 @@ function summarizeMessages(value) {
   let textLength = 0;
   let argumentLength = 0;
   for (const message of value) {
-    if (!isRecord(message)) continue;
+    if (!isRecord2(message)) continue;
     const role = typeof message.role === "string" ? message.role : void 0;
     if (role && roles.length < 20) roles.push(role);
     if (typeof message.stopReason === "string" && stopReasons.length < 20) stopReasons.push(message.stopReason);
@@ -7255,7 +7846,7 @@ function summarizeMessages(value) {
     textLength += collectTextLength(message.content);
     argumentLength += collectArgumentLength(message.content);
     for (const block of content) {
-      if (isRecord(block) && typeof block.name === "string" && toolNames.length < 20) {
+      if (isRecord2(block) && typeof block.name === "string" && toolNames.length < 20) {
         toolNames.push(block.name);
       }
     }
@@ -7272,7 +7863,7 @@ function summarizeMessages(value) {
   };
 }
 function summarizeFailure(value) {
-  if (!isRecord(value)) return typeof value;
+  if (!isRecord2(value)) return typeof value;
   return {
     kind: value.kind,
     retryable: value.retryable,
@@ -7283,7 +7874,7 @@ function summarizeFailure(value) {
   };
 }
 function summarizeRuntimeEvent(value) {
-  if (!isRecord(value)) return typeof value;
+  if (!isRecord2(value)) return typeof value;
   const summary = {
     type: value.type
   };
@@ -7316,7 +7907,7 @@ function recomputeRuntimeSummaryFromTimeline(events) {
   return summary;
 }
 function summarizeMeta(meta) {
-  if (!isRecord(meta)) return meta;
+  if (!isRecord2(meta)) return meta;
   const summary = {};
   for (const [key, value] of Object.entries(meta)) {
     if (key === "messages" || key === "queuedInputs" || key === "result") {
@@ -7343,7 +7934,7 @@ function summarizeMeta(meta) {
       summary[key] = summarizeRuntimeEvent(value);
       continue;
     }
-    if (key === "queuedInput" && isRecord(value)) {
+    if (key === "queuedInput" && isRecord2(value)) {
       summary[key] = {
         mode: value.mode,
         source: value.source,
@@ -7363,18 +7954,18 @@ function toStringArray(value) {
 }
 function summarizeExcludedTools(value) {
   if (!Array.isArray(value)) return void 0;
-  const entries = value.filter(isRecord).map((entry) => ({
+  const entries = value.filter(isRecord2).map((entry) => ({
     name: String(entry.name || ""),
     reason: String(entry.reason || "")
   })).filter((entry) => entry.name);
   return entries.length > 0 ? entries : void 0;
 }
 function extractSubagentSummaries(toolCallId, toolName, result) {
-  if (toolName !== "spawn_subagents_parallel" || !isRecord(result)) return [];
-  const details = isRecord(result.details) ? result.details : void 0;
+  if (toolName !== "spawn_subagents_parallel" || !isRecord2(result)) return [];
+  const details = isRecord2(result.details) ? result.details : void 0;
   const tasks = Array.isArray(details?.tasks) ? details.tasks : [];
-  return tasks.filter(isRecord).map((task) => {
-    const plan = isRecord(task.plan) ? task.plan : void 0;
+  return tasks.filter(isRecord2).map((task) => {
+    const plan = isRecord2(task.plan) ? task.plan : void 0;
     const evidence = Array.isArray(task.evidence) ? task.evidence : [];
     const confidenceSignals = Array.isArray(task.confidenceSignals) ? task.confidenceSignals : [];
     const runtimeEvidence = Array.isArray(task.runtimeEvidence) ? task.runtimeEvidence : [];
@@ -7401,7 +7992,7 @@ function extractSubagentSummaries(toolCallId, toolName, result) {
 }
 function timelineEventFromTraceEvent(type, meta) {
   const normalizedType = type.startsWith("runtime:") ? type.slice("runtime:".length) : type;
-  const data = isRecord(meta) ? meta : {};
+  const data = isRecord2(meta) ? meta : {};
   const detail = summarizeMeta(meta);
   if (normalizedType === "assistant_update" || normalizedType === "dispatch_settled" || normalizedType === "wait_for_idle_settled") {
     return null;
@@ -8197,14 +8788,14 @@ function extractAnthropicContent(content, originalQuery) {
       results.push(makeTextSegment(block.text));
     }
     if (block?.type === "server_tool_use") {
-      const input = isRecord2(block.input) ? block.input : void 0;
+      const input = isRecord3(block.input) ? block.input : void 0;
       if (typeof input?.query === "string" && input.query.trim()) {
         actualQueries.push(input.query.trim());
       }
     }
     if (block?.type === "web_search_tool_result") {
       if (!Array.isArray(block.content)) {
-        const errorCode = isRecord2(block.content) && typeof block.content.error_code === "string" ? block.content.error_code : "unknown";
+        const errorCode = isRecord3(block.content) && typeof block.content.error_code === "string" ? block.content.error_code : "unknown";
         results.push({
           type: "error",
           toolUseId: typeof block.tool_use_id === "string" ? block.tool_use_id : void 0,
@@ -8248,7 +8839,7 @@ function collectUrlStrings(text, sources) {
 function resolveResponsesEndpoint(baseUrl) {
   return `${baseUrl.replace(/\/+$/, "")}/responses`;
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null;
 }
 function collectUrlCitations(value, sources) {
@@ -8256,7 +8847,7 @@ function collectUrlCitations(value, sources) {
     for (const item of value) collectUrlCitations(item, sources);
     return;
   }
-  if (!isRecord2(value)) return;
+  if (!isRecord3(value)) return;
   if (value.type === "url_citation" && typeof value.url === "string") {
     sources.push(sourceFromUrl(value.url, typeof value.title === "string" ? value.title : void 0));
   }
@@ -8275,7 +8866,7 @@ function collectOutputText(value, chunks) {
     for (const item of value) collectOutputText(item, chunks);
     return;
   }
-  if (!isRecord2(value)) return;
+  if (!isRecord3(value)) return;
   if (value.type === "output_text" && typeof value.text === "string") {
     chunks.push(value.text);
     return;
@@ -8289,7 +8880,7 @@ function collectOutputText(value, chunks) {
   }
 }
 function extractOpenAIResponsesContent(response, originalQuery) {
-  const body = isRecord2(response) ? response : {};
+  const body = isRecord3(response) ? response : {};
   const sources = [];
   collectUrlCitations(body.output, sources);
   if (typeof body.output_text === "string" && body.output_text.trim()) {
@@ -8306,12 +8897,12 @@ function extractOpenAIResponsesContent(response, originalQuery) {
   return { text, sources: uniqueSources(sources), results: text ? [makeTextSegment(text)] : [], actualQueries: [originalQuery] };
 }
 function extractChatCompletionsContent(response, originalQuery) {
-  const body = isRecord2(response) ? response : {};
+  const body = isRecord3(response) ? response : {};
   const sources = [];
   collectUrlCitations(body, sources);
   const choices = Array.isArray(body.choices) ? body.choices : [];
-  const firstChoice = isRecord2(choices[0]) ? choices[0] : {};
-  const message = isRecord2(firstChoice.message) ? firstChoice.message : {};
+  const firstChoice = isRecord3(choices[0]) ? choices[0] : {};
+  const message = isRecord3(firstChoice.message) ? firstChoice.message : {};
   const content = typeof message.content === "string" ? message.content : "";
   if (content) {
     collectUrlStrings(content, sources);
@@ -8526,8 +9117,8 @@ async function runQueuedSearch(model, fn) {
   const key = `${model.provider}/${model.id}`;
   const previous = SEARCH_PROVIDER_QUEUE.get(key) ?? Promise.resolve();
   let release;
-  const next = new Promise((resolve2) => {
-    release = resolve2;
+  const next = new Promise((resolve3) => {
+    release = resolve3;
   });
   const queued = previous.catch(() => void 0).then(() => next);
   SEARCH_PROVIDER_QUEUE.set(key, queued);
@@ -8898,10 +9489,10 @@ function assistantText(message) {
 async function withAbort(promise, signal) {
   if (!signal) return promise;
   if (signal.aborted) throw signal.reason ?? new Error("operation aborted");
-  return await new Promise((resolve2, reject) => {
+  return await new Promise((resolve3, reject) => {
     const onAbort = () => reject(signal.reason ?? new Error("operation aborted"));
     signal.addEventListener("abort", onAbort, { once: true });
-    promise.then(resolve2, reject).finally(() => signal.removeEventListener("abort", onAbort));
+    promise.then(resolve3, reject).finally(() => signal.removeEventListener("abort", onAbort));
   });
 }
 async function applyPromptWithModel(deps, prompt, url, content, signal) {
@@ -9123,7 +9714,7 @@ var webResearchSchema = Type.Object({
 var DEFAULT_WEB_RESEARCH_SEARCH_ATTEMPT_TIMEOUT_MS = 45e3;
 var DEFAULT_WEB_RESEARCH_FETCH_ATTEMPT_TIMEOUT_MS = 3e4;
 var DEFAULT_WEB_RESEARCH_BROWSER_ATTEMPT_TIMEOUT_MS = 45e3;
-function isRecord3(value) {
+function isRecord4(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
 function textFromResult(result) {
@@ -9337,7 +9928,7 @@ function updateProviderHealth(current, attempts) {
   return [...byKey.values()].sort((a, b) => b.updatedAt - a.updatedAt).slice(0, 20);
 }
 function contentDetails(result) {
-  return isRecord3(result.details) ? result.details : {};
+  return isRecord4(result.details) ? result.details : {};
 }
 function excerpt(text, max = 1400) {
   const clean = text.replace(/\s+/g, " ").trim();
@@ -9402,13 +9993,13 @@ async function runWithDeadline(operation, timeoutMs, message, parentSignal) {
   const child = createChildSignal(parentSignal);
   let timer;
   try {
-    return await new Promise((resolve2, reject) => {
+    return await new Promise((resolve3, reject) => {
       timer = setTimeout(() => {
         const error = new Error(message);
         child.abort(error);
         reject(error);
       }, timeoutMs);
-      operation(child.signal).then(resolve2, reject);
+      operation(child.signal).then(resolve3, reject);
     });
   } finally {
     if (timer) clearTimeout(timer);
@@ -9963,6 +10554,8 @@ export {
   getAutoCompactTokenLimit,
   findFirstKeptEntryId,
   createCompactionSummary,
+  generateEntryId,
+  FileSessionStore,
   createSessionManager,
   AgentSessionController,
   registerInteractionHandler,
@@ -9972,6 +10565,7 @@ export {
   buildProjectContextSection,
   createAskUserCapability,
   createPolicyEnforcedTools,
+  createFileObservationState,
   createSharedFileSystemTools,
   buildToolsPromptSection,
   createSharedWebSearchTool,