@animus-labs/cortex 0.2.0

package/src/tools/undo-edit.ts

@@ -0,0 +1,314 @@
+/**
+ * UndoEdit tool: revert the most recent Edit or Write on a single file.
+ *
+ * Uses the per-runtime `EditHistory` stack: every successful Edit /
+ * Write push a pre-mutation snapshot, and `UndoEdit` pops the top
+ * snapshot to restore the prior state.
+ *
+ * The undo is guarded: we verify the current on-disk state still
+ * matches what we recorded at the moment the mutation completed (via
+ * mtime + SHA-256 hash). If anything has diverged since — another
+ * Edit/Write that wasn't history-tracked, a formatter, cloud sync —
+ * we refuse rather than overwrite unrelated changes.
+ *
+ * Reference: docs/cortex/tools/undo-edit.md
+ */
+
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { Type, type Static } from 'typebox';
+import type { EditHistory, EditHistoryEntry } from './shared/edit-history.js';
+import type { FileMutationLock } from './shared/file-mutation-lock.js';
+import type { ReadRegistry } from './shared/read-registry.js';
+import type { ToolContentDetails } from '../types.js';
+import type { CortexToolRuntime } from './runtime.js';
+import { attachRuntimeAwareTool } from './runtime.js';
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+export const UndoEditParams = Type.Object({
+  file_path: Type.String({
+    description: 'Absolute path to the file whose most recent Edit or Write should be reverted.',
+  }),
+});
+
+export type UndoEditParamsType = Static<typeof UndoEditParams>;
+
+// ---------------------------------------------------------------------------
+// Details
+// ---------------------------------------------------------------------------
+
+export interface UndoEditDetails {
+  filePath: string;
+  /** The tool whose mutation was reverted (when the undo succeeds). */
+  revertedSource?: 'Edit' | 'Write';
+  /** True when the undo removed a file that Write had created. */
+  deleted?: boolean;
+  /** True when the undo restored prior content to an existing file. */
+  restored?: boolean;
+  /** True when the undo was rejected (no history, stale state, etc.). */
+  rejected?: boolean;
+  /** Remaining history depth for this file after the operation. */
+  remainingDepth?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export interface UndoEditToolConfig {
+  runtime?: CortexToolRuntime | undefined;
+  editHistory?: EditHistory | undefined;
+  readRegistry?: ReadRegistry | undefined;
+  fileMutationLock?: FileMutationLock | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function hashBytes(data: Buffer | string): string {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+function rejection(
+  filePath: string,
+  text: string,
+  remainingDepth: number,
+): ToolContentDetails<UndoEditDetails> {
+  return {
+    content: [{ type: 'text', text }],
+    details: { filePath, rejected: true, remainingDepth },
+  };
+}
+
+/**
+ * Atomically write the restored content to disk. Mirrors the pattern
+ * used by Edit and Write so concurrent consumers observe a coherent
+ * file at all times.
+ */
+async function atomicWrite(filePath: string, content: string): Promise<void> {
+  const tempPath = path.join(
+    path.dirname(filePath),
+    `.undo-${crypto.randomUUID()}.tmp`,
+  );
+  try {
+    await fs.promises.writeFile(tempPath, content, 'utf8');
+    try {
+      await fs.promises.rename(tempPath, filePath);
+    } catch {
+      // Rename may fail on Windows if the target is open. Fall back to a
+      // direct write and clean up the temp file.
+      await fs.promises.writeFile(filePath, content, 'utf8');
+      try { await fs.promises.unlink(tempPath); } catch { /* ignore */ }
+    }
+  } catch (err) {
+    try { await fs.promises.unlink(tempPath); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+
+export function createUndoEditTool(config: UndoEditToolConfig): {
+  name: string;
+  description: string;
+  parameters: typeof UndoEditParams;
+  execute: (params: UndoEditParamsType) => Promise<ToolContentDetails<UndoEditDetails>>;
+} {
+  const editHistory = config.runtime?.editHistory ?? config.editHistory;
+  if (!editHistory) {
+    throw new Error('createUndoEditTool requires either runtime or editHistory');
+  }
+  const readRegistry = config.runtime?.readRegistry ?? config.readRegistry;
+  const fileMutationLock = config.runtime?.fileMutationLock ?? config.fileMutationLock;
+
+  const tool = {
+    name: 'UndoEdit',
+    description:
+      'Revert the most recent Edit or Write on a single file, returning it to the state it had before the last mutation. ' +
+      'Only reverts the most recent mutation; call repeatedly to roll back multiple steps (bounded history). ' +
+      'Refuses if the file has been modified externally since the mutation was recorded.',
+    parameters: UndoEditParams,
+
+    async execute(
+      params: UndoEditParamsType,
+    ): Promise<ToolContentDetails<UndoEditDetails>> {
+      const filePath = path.resolve(params.file_path);
+
+      const release = fileMutationLock ? await fileMutationLock.acquire(filePath) : undefined;
+      try {
+        // Peek-then-pop pattern isn't expressible directly since `pop`
+        // returns the entry. We pop immediately and, on abort, push it
+        // back so the stack isn't silently truncated by a rejected
+        // undo.
+        const entry = editHistory.pop(filePath);
+        if (!entry) {
+          return rejection(
+            filePath,
+            `No recorded Edit or Write to undo for ${filePath}.`,
+            0,
+          );
+        }
+
+        const restoreEntry = (): void => editHistory.record(filePath, entry);
+        const remainingAfter = editHistory.depth(filePath);
+
+        // Verify current on-disk state matches what we recorded when
+        // the mutation completed. Any mismatch means the file drifted
+        // and undoing would stomp unrelated changes.
+        const verification = await verifyPostMutationState(filePath, entry);
+        if (verification.kind === 'drift') {
+          restoreEntry();
+          return rejection(
+            filePath,
+            `Cannot undo: ${verification.reason} Read the file to resync, then issue an explicit Edit or Write.`,
+            remainingAfter + 1,
+          );
+        }
+
+        // Apply the revert.
+        if (entry.originalContent === null) {
+          // Write created the file; undo = delete.
+          try {
+            await fs.promises.unlink(filePath);
+          } catch (err) {
+            restoreEntry();
+            const msg = err instanceof Error ? err.message : String(err);
+            return rejection(
+              filePath,
+              `Cannot undo: failed to delete ${filePath}: ${msg}`,
+              remainingAfter + 1,
+            );
+          }
+          readRegistry?.invalidate(filePath);
+          return {
+            content: [{
+              type: 'text',
+              text: `Undid ${entry.source} of ${filePath} (file deleted; was created by the prior ${entry.source}).`,
+            }],
+            details: {
+              filePath,
+              revertedSource: entry.source,
+              deleted: true,
+              rejected: false,
+              remainingDepth: remainingAfter,
+            },
+          };
+        }
+
+        // Existing file — restore prior content.
+        try {
+          await atomicWrite(filePath, entry.originalContent);
+        } catch (err) {
+          restoreEntry();
+          const msg = err instanceof Error ? err.message : String(err);
+          return rejection(
+            filePath,
+            `Cannot undo: failed to restore ${filePath}: ${msg}`,
+            remainingAfter + 1,
+          );
+        }
+
+        // Refresh read state: after a successful undo, the agent's
+        // knowledge of the file is the restored content.
+        try {
+          const postStat = await fs.promises.stat(filePath);
+          const postHash = hashBytes(entry.originalContent);
+          readRegistry?.markRead(filePath, {
+            timestamp: postStat.mtimeMs,
+            contentHash: postHash,
+          });
+        } catch {
+          readRegistry?.invalidate(filePath);
+        }
+
+        return {
+          content: [{
+            type: 'text',
+            text: `Undid ${entry.source} of ${filePath} (restored ${entry.originalContent.length} character${entry.originalContent.length === 1 ? '' : 's'} of prior content).`,
+          }],
+          details: {
+            filePath,
+            revertedSource: entry.source,
+            restored: true,
+            rejected: false,
+            remainingDepth: remainingAfter,
+          },
+        };
+      } finally {
+        release?.();
+      }
+    },
+  };
+
+  return attachRuntimeAwareTool(tool, {
+    toolKind: 'UndoEdit',
+    cloneForRuntime: (runtime) => createUndoEditTool({
+      ...config,
+      runtime,
+      editHistory: runtime.editHistory,
+      readRegistry: runtime.readRegistry,
+      fileMutationLock: runtime.fileMutationLock,
+    }),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Drift detection
+// ---------------------------------------------------------------------------
+
+type VerificationResult = { kind: 'ok' } | { kind: 'drift'; reason: string };
+
+/**
+ * Confirm that the file on disk still carries the exact post-mutation
+ * fingerprint we recorded. Two axes:
+ *   - existence:   the file must be present iff we expected it to be
+ *   - identity:    bytes must hash to the recorded value
+ * mtime is checked first as a cheap short-circuit; on mtime mismatch
+ * the hash check is authoritative (formatters / cloud sync can touch
+ * mtime without changing bytes).
+ */
+async function verifyPostMutationState(
+  filePath: string,
+  entry: EditHistoryEntry,
+): Promise<VerificationResult> {
+  let stat: fs.Stats | undefined;
+  try {
+    stat = await fs.promises.stat(filePath);
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') {
+      return {
+        kind: 'drift',
+        reason: 'the file has been deleted since the recorded mutation.',
+      };
+    }
+    return {
+      kind: 'drift',
+      reason: `the file is inaccessible (${code ?? 'unknown error'}).`,
+    };
+  }
+
+  // Fast path: mtime matches exactly. (We use equality here because
+  // we're comparing against our OWN previously-recorded mtime, not a
+  // user-provided read state — quirks around mtime going backwards
+  // aren't relevant when both values came from our writes.)
+  if (stat.mtimeMs === entry.postMutationMtimeMs) return { kind: 'ok' };
+
+  // mtime drifted — confirm via hash before rejecting, since formatters
+  // and cloud-sync can touch mtime without changing bytes.
+  const bytes = await fs.promises.readFile(filePath);
+  const currentHash = hashBytes(bytes);
+  if (currentHash === entry.postMutationContentHash) return { kind: 'ok' };
+
+  return {
+    kind: 'drift',
+    reason: 'the file has been modified since the recorded mutation.',
+  };
+}

package/src/tools/web-fetch/cache.ts

@@ -0,0 +1,112 @@
+/**
+ * In-memory URL cache with 15-minute TTL for WebFetch tool.
+ *
+ * Keyed by URL. Cached entries include the converted markdown content
+ * so repeated fetches skip both the HTTP request and HTML conversion.
+ *
+ * Self-cleaning: expired entries are removed on access and periodically.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CacheEntry {
+  content: string;
+  fetchedAt: number;
+  statusCode: number;
+  finalUrl: string;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const DEFAULT_TTL_MS = 15 * 60 * 1000; // 15 minutes
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+
+// ---------------------------------------------------------------------------
+// Cache
+// ---------------------------------------------------------------------------
+
+export class WebFetchCache {
+  private readonly cache = new Map<string, CacheEntry>();
+  private readonly ttlMs: number;
+  private cleanupTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(ttlMs: number = DEFAULT_TTL_MS) {
+    this.ttlMs = ttlMs;
+    // Start periodic cleanup
+    this.cleanupTimer = setInterval(() => this.cleanup(), CLEANUP_INTERVAL_MS);
+    // Unref the timer so it doesn't prevent process exit
+    if (this.cleanupTimer && typeof this.cleanupTimer === 'object' && 'unref' in this.cleanupTimer) {
+      this.cleanupTimer.unref();
+    }
+  }
+
+  /**
+   * Get a cached entry for a URL, or undefined if not cached or expired.
+   */
+  get(url: string): CacheEntry | undefined {
+    const entry = this.cache.get(url);
+    if (!entry) return undefined;
+
+    if (Date.now() - entry.fetchedAt > this.ttlMs) {
+      this.cache.delete(url);
+      return undefined;
+    }
+
+    return entry;
+  }
+
+  /**
+   * Store a cache entry for a URL.
+   */
+  set(url: string, entry: CacheEntry): void {
+    this.cache.set(url, entry);
+  }
+
+  /**
+   * Check if a URL has a valid (non-expired) cache entry.
+   */
+  has(url: string): boolean {
+    return this.get(url) !== undefined;
+  }
+
+  /**
+   * Remove expired entries.
+   */
+  cleanup(): void {
+    const now = Date.now();
+    for (const [url, entry] of this.cache) {
+      if (now - entry.fetchedAt > this.ttlMs) {
+        this.cache.delete(url);
+      }
+    }
+  }
+
+  /**
+   * Clear all cached entries.
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Stop the cleanup timer. Call on shutdown.
+   */
+  destroy(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    this.cache.clear();
+  }
+
+  /**
+   * Get the number of cached entries (for diagnostics).
+   */
+  get size(): number {
+    return this.cache.size;
+  }
+}