@tanstack/ai-sandbox 0.2.2 → 0.2.3

package/src/watch.ts

@@ -19,6 +19,7 @@
 import { DEFAULT_WORKSPACE_ROOT } from './bootstrap'
 import type { SandboxHandle } from './contracts'
 import type { SandboxFileEvent } from '@tanstack/ai'
+import type { InternalLogger } from '@tanstack/ai/adapter-internals'
 
 export type { SandboxFileEvent } from '@tanstack/ai'
 /** @deprecated alias retained for the low-level watch API. */
@@ -39,6 +40,12 @@ export interface WatchOptions {
   ignore?: Array<string>
   /** Stop watching when this signal aborts. */
   signal?: AbortSignal
+  /**
+   * Optional logger. When present, a failed `find` poll (non-zero exit or a
+   * thrown exec) is logged instead of silently degrading the snapshot — the
+   * failure mode a plain exec-poll watcher hides.
+   */
+  logger?: InternalLogger
 }
 
 export interface SandboxWatchHandle {
@@ -144,17 +151,49 @@ async function startNativeWatch(
   handle: SandboxHandle,
   options: WatchOptions & { root: string; ignore: Array<string> },
 ): Promise<SandboxWatchHandle> {
-  const { onEvent, root, ignore } = options
+  const { onEvent, root, ignore, logger } = options
   const watch = handle.fs.watch
   if (!watch) throw new Error('native watch is unavailable on this provider')
   // Seed the set of existing files so the first event per path is classified
   // correctly (create vs change).
-  const known = await collectPaths(handle, root, ignore)
+  const seed = await collectPaths(handle, root, ignore, logger)
+  const known = seed.files
+  // If the ROOT list failed, `known` is untrustworthy — every pre-existing
+  // file would misclassify as `create` on its first edit. Re-seed lazily on
+  // the next event(s): by the time real activity arrives the fs has usually
+  // recovered, and re-listing then establishes the baseline. Dedupe concurrent
+  // re-seeds behind a single in-flight promise.
+  // ponytail: a file genuinely CREATED in the narrow window between the failed
+  // seed and the first event gets picked up by the re-seed and so mislabels as
+  // `change` once. That's strictly better than the whole-run mislabel a
+  // never-recovered empty seed causes, and `diff()` is correct regardless.
+  let seeded = seed.rootOk
+  let reseeding: Promise<void> | null = null
+  const ensureSeeded = (): Promise<void> => {
+    if (seeded) return Promise.resolve()
+    if (!reseeding) {
+      reseeding = collectPaths(handle, root, ignore, logger).then((r) => {
+        if (r.rootOk) {
+          for (const p of r.files) known.add(p)
+          seeded = true
+          logger?.sandbox(
+            'sandbox watch: re-seeded after failed initial seed',
+            {
+              root,
+            },
+          )
+        }
+        reseeding = null
+      })
+    }
+    return reseeding
+  }
 
   const subscription = await watch(root, (raw) => {
     const path = raw.path
     if (isIgnored(path, ignore)) return
     void (async () => {
+      await ensureSeeded()
       const exists = await handle.fs.exists(path)
       const timestamp = Date.now()
       if (!exists) {
@@ -166,14 +205,28 @@ async function startNativeWatch(
         known.add(path)
         onEvent({ type: 'create', path, timestamp })
       }
-    })().catch(() => undefined)
+    })().catch((error: unknown) => {
+      // A failed classify (e.g. `fs.exists` threw) drops this file's event —
+      // log it so a missing diff isn't silent (the whole point of the watcher).
+      logger?.warn('sandbox watch: native event classify failed', {
+        path,
+        error,
+      })
+    })
   })
 
-  const onAbort = (): void => void subscription.stop().catch(() => undefined)
+  // A failed `subscription.stop()` can leak an OS-level watch — log rather
+  // than swallow it silently.
+  const logStopFailure = (error: unknown): void =>
+    logger?.warn('sandbox watch: native subscription.stop() failed', {
+      root,
+      error,
+    })
+  const onAbort = (): void => void subscription.stop().catch(logStopFailure)
   options.signal?.addEventListener('abort', onAbort, { once: true })
   // The signal may have aborted during the awaits above (the once-listener
   // would have missed it) — tear down now if so.
-  if (options.signal?.aborted) void subscription.stop().catch(() => undefined)
+  if (options.signal?.aborted) void subscription.stop().catch(logStopFailure)
 
   return {
     stop: async () => {
@@ -192,33 +245,154 @@ async function startPollWatch(
     intervalMs: number
   },
 ): Promise<SandboxWatchHandle> {
-  const { onEvent, root, ignore, intervalMs } = options
+  const { onEvent, root, ignore, intervalMs, logger } = options
   const command = buildFindCommand(ignore)
   const controller = new AbortController()
 
-  const snapshot = async (): Promise<Map<string, string>> => {
-    const result = await handle.process.exec(command, {
-      cwd: root,
-      signal: controller.signal,
+  // A poll result: the parsed snapshot plus whether `find` completed cleanly.
+  // `null` means the poll produced no usable output at all (thrown exec, or a
+  // non-zero exit with empty stdout) — callers preserve the previous snapshot.
+  // Collapsing a failed poll to `{}` would make the next diff fabricate a
+  // `delete` for every tracked file (and a `create` for each on recovery) —
+  // one transient `find` blip would fan a phantom storm out to hooks/stream.
+  interface Poll {
+    map: Map<string, string>
+    /** `false` when `find` exited non-zero but still printed rows (partial). */
+    complete: boolean
+  }
+  // Escalate a steady-state poll throw to `warn` after this many in a row.
+  const STEADY_STATE_THROW_WARN_AFTER = 3
+  let consecutiveThrows = 0
+  const snapshot = async (isInitial = false): Promise<Poll | null> => {
+    let result
+    try {
+      result = await handle.process.exec(command, {
+        cwd: root,
+        signal: controller.signal,
+      })
+      consecutiveThrows = 0 // exec returned (any exit code) — the seam is alive
+    } catch (error) {
+      // Thrown exec — container not ready, `find` seam rejects, or a
+      // mid-teardown abort. Treat as a failed poll so BOTH the initial seed
+      // and every tick preserve `previous` instead of rejecting setup (which
+      // would crash the run and leak the sandbox) or the interval.
+      if (isInitial) {
+        // The INITIAL poll can't be a teardown (a pre-aborted signal is guarded
+        // in `watchWorkspace`), so a throw here is an unambiguous anomaly (`find`
+        // missing, container never ready) that leaves the watcher dead for the
+        // whole run — surface it at `warn`.
+        logger?.warn('sandbox watch: initial `find` poll threw', {
+          root,
+          error,
+        })
+      } else if (controller.signal.aborted) {
+        // Mid-teardown abort — expected, stay quiet.
+        logger?.sandbox('sandbox watch: `find` poll threw during teardown', {
+          root,
+          error,
+        })
+      } else {
+        // Steady-state throw while NOT tearing down. One is usually a transient
+        // blip (→ `sandbox`), but a run of them means the exec seam is wedged:
+        // every poll returns null and the watcher emits nothing for the rest of
+        // the run. That silent-death case escalates to `warn` (on by default).
+        consecutiveThrows += 1
+        if (consecutiveThrows >= STEADY_STATE_THROW_WARN_AFTER) {
+          logger?.warn('sandbox watch: `find` poll threw repeatedly', {
+            root,
+            error,
+            consecutiveThrows,
+          })
+        } else {
+          logger?.sandbox('sandbox watch: `find` poll threw', { root, error })
+        }
+      }
+      return null
+    }
+    if (result.exitCode === 0) {
+      return { map: parseFindOutput(result.stdout, root), complete: true }
+    }
+    // Non-zero exit doesn't mean "no data": GNU `find` exits >0 on the first
+    // permission-denied entry it hits mid-traversal (common in containers, and
+    // the ignore list is a `-not -path` filter, not `-prune`, so `find` still
+    // descends into unreadable dirs) yet still prints every readable file. Use
+    // that partial output — marked `complete: false` so the tick merges rather
+    // than diffs it — instead of blinding the watcher for the whole run. Only a
+    // non-zero exit with NO output is a truly failed poll.
+    if (result.stdout !== '') {
+      logger?.sandbox(
+        'sandbox watch: `find` non-zero exit with partial output',
+        { root, exitCode: result.exitCode, stderr: result.stderr },
+      )
+      return { map: parseFindOutput(result.stdout, root), complete: false }
+    }
+    logger?.warn('sandbox watch: `find` poll exited non-zero with no output', {
+      root,
+      exitCode: result.exitCode,
+      stderr: result.stderr,
     })
-    return result.exitCode === 0
-      ? parseFindOutput(result.stdout, root)
-      : new Map<string, string>()
+    return null
   }
 
-  let previous = await snapshot()
+  // `null` until the first poll that yields usable output. A failed INITIAL
+  // poll must NOT seed an empty baseline — the first successful poll would then
+  // diff against `{}` and fabricate a `create` for every pre-existing file. So
+  // the first non-null snapshot is adopted as the baseline WITHOUT diffing.
+  let previous: Map<string, string> | null = null
+  // Whether `previous` was established from a COMPLETE poll. A baseline seeded
+  // from a PARTIAL poll is provisional — files unreadable during that poll are
+  // absent from it and would later fabricate `create`s when they recover — so
+  // the first complete poll re-baselines without diffing.
+  let seededFromComplete = false
+  {
+    const poll = await snapshot(true)
+    if (poll) {
+      previous = poll.map
+      seededFromComplete = poll.complete
+    }
+  }
   const state = { running: true }
 
   const tick = async (): Promise<void> => {
     if (!state.running) return
     try {
-      const next = await snapshot()
+      const poll = await snapshot()
+      // Failed poll — keep `previous` and retry next tick (see `snapshot`).
+      if (poll === null) return
+      if (previous === null) {
+        // First usable snapshot after a failed initial poll — seed, don't diff.
+        previous = poll.map
+        seededFromComplete = poll.complete
+        return
+      }
+      if (!seededFromComplete && poll.complete) {
+        // First complete poll after a provisional (partial) seed — re-baseline
+        // WITHOUT diffing, so files merely unreadable at seed time don't
+        // fabricate `create`s. (Real creates during this degraded-startup
+        // window are missed — an acceptable trade for not fabricating events.)
+        logger?.sandbox(
+          'sandbox watch: re-baselined after provisional partial seed',
+          { root },
+        )
+        previous = poll.map
+        seededFromComplete = true
+        return
+      }
+      // A partial (non-`complete`) poll can't distinguish "deleted" from
+      // "transiently unreadable this poll", so MERGE it over `previous`: pick
+      // up new/changed files without fabricating a `delete` for a path this
+      // poll simply couldn't see. A real deletion still surfaces on the next
+      // complete poll.
+      const next = poll.complete
+        ? poll.map
+        : new Map([...previous, ...poll.map])
       for (const event of diffSnapshots(previous, next, Date.now())) {
         onEvent(event)
       }
       previous = next
-    } catch {
-      // transient exec failure (e.g. mid-teardown) — try again next tick
+    } catch (error) {
+      // Defensive: a throw from diff dispatch — preserve `previous`, retry.
+      logger?.sandbox('sandbox watch: tick failed', { root, error })
     }
   }
 
@@ -244,26 +418,41 @@ async function startPollWatch(
   return { stop }
 }
 
-/** Recursively collect file paths under `root`, honoring `ignore`. */
+/**
+ * Recursively collect file paths under `root`, honoring `ignore`. `rootOk` is
+ * `false` when the ROOT `list` itself failed — the seed is then untrustworthy
+ * (empty/partial), which the native watcher uses to trigger a lazy re-seed. A
+ * failed *subdirectory* list is logged but doesn't flip `rootOk` (its files are
+ * simply absent, a smaller misclassification surface).
+ */
 async function collectPaths(
   handle: SandboxHandle,
   root: string,
   ignore: Array<string>,
-): Promise<Set<string>> {
+  logger?: InternalLogger,
+): Promise<{ files: Set<string>; rootOk: boolean }> {
   const files = new Set<string>()
-  const walk = async (dir: string): Promise<void> => {
+  let rootOk = true
+  const walk = async (dir: string, isRoot: boolean): Promise<void> => {
     let entries: Awaited<ReturnType<SandboxHandle['fs']['list']>>
     try {
       entries = await handle.fs.list(dir)
-    } catch {
+    } catch (error) {
+      // A dir we can't list is seeded as empty, so its existing files would
+      // later misclassify as `create` on first edit — log rather than hide it.
+      if (isRoot) rootOk = false
+      logger?.warn('sandbox watch: failed to list directory while seeding', {
+        dir,
+        error,
+      })
       return
     }
     for (const entry of entries) {
       if (ignore.includes(entry.name)) continue
-      if (entry.type === 'dir') await walk(entry.path)
+      if (entry.type === 'dir') await walk(entry.path, false)
       else files.add(entry.path)
     }
   }
-  await walk(root)
-  return files
+  await walk(root, true)
+  return { files, rootOk }
 }