@animus-labs/cortex 0.2.0

package/src/tools/runtime.ts

@@ -0,0 +1,173 @@
+/**
+ * Per-agent runtime state for mutable built-in tool behavior.
+ *
+ * Cortex clones runtime-aware built-in tools into a fresh runtime for each
+ * agent so parent and child agents do not share mutable closures.
+ */
+
+import type * as child_process from 'node:child_process';
+import { CwdTracker } from './shared/cwd-tracker.js';
+import { EditHistory } from './shared/edit-history.js';
+import { FileMutationLock } from './shared/file-mutation-lock.js';
+import { ReadRegistry } from './shared/read-registry.js';
+import { WebFetchCache } from './web-fetch/cache.js';
+
+// ---------------------------------------------------------------------------
+// Background task state
+// ---------------------------------------------------------------------------
+
+export interface BackgroundTask {
+  id: string;
+  /** The command that was executed (for status display). */
+  command: string;
+  process: child_process.ChildProcess;
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  completed: boolean;
+  startTime: number;
+}
+
+export class BackgroundTaskStore {
+  private readonly tasks = new Map<string, BackgroundTask>();
+  private taskIdCounter = 0;
+
+  nextTaskId(): string {
+    this.taskIdCounter += 1;
+    return `task_${this.taskIdCounter}`;
+  }
+
+  set(task: BackgroundTask): void {
+    this.tasks.set(task.id, task);
+  }
+
+  get(taskId: string): BackgroundTask | undefined {
+    return this.tasks.get(taskId);
+  }
+
+  getAll(): Map<string, BackgroundTask> {
+    return this.tasks;
+  }
+
+  cleanupCompletedTasks(maxAgeMs = 30 * 60 * 1000): void {
+    const now = Date.now();
+    for (const [id, task] of this.tasks) {
+      if (task.completed && now - task.startTime > maxAgeMs) {
+        this.tasks.delete(id);
+      }
+    }
+  }
+
+  clear(): void {
+    this.tasks.clear();
+  }
+}
+
+export const globalBackgroundTaskStore = new BackgroundTaskStore();
+
+// ---------------------------------------------------------------------------
+// WebFetch runtime state
+// ---------------------------------------------------------------------------
+
+export class WebFetchRuntimeState {
+  private readonly cache = new WebFetchCache();
+  private fetchesThisLoop = 0;
+
+  getCache(): WebFetchCache {
+    return this.cache;
+  }
+
+  get fetchCount(): number {
+    return this.fetchesThisLoop;
+  }
+
+  incrementFetchCount(): void {
+    this.fetchesThisLoop += 1;
+  }
+
+  resetLoop(): void {
+    this.fetchesThisLoop = 0;
+  }
+
+  destroy(): void {
+    this.cache.destroy();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Per-agent runtime container
+// ---------------------------------------------------------------------------
+
+export class CortexToolRuntime {
+  readonly cwdTracker: CwdTracker;
+  readonly readRegistry: ReadRegistry;
+  readonly fileMutationLock: FileMutationLock;
+  readonly editHistory: EditHistory;
+  readonly backgroundTasks: BackgroundTaskStore;
+  readonly webFetch: WebFetchRuntimeState;
+
+  constructor(workingDirectory: string) {
+    this.cwdTracker = new CwdTracker(workingDirectory);
+    this.readRegistry = new ReadRegistry();
+    this.fileMutationLock = new FileMutationLock();
+    this.editHistory = new EditHistory();
+    this.backgroundTasks = new BackgroundTaskStore();
+    this.webFetch = new WebFetchRuntimeState();
+  }
+
+  resetForLoop(): void {
+    this.cwdTracker.reset();
+    this.readRegistry.clear();
+    this.fileMutationLock.clear();
+    this.editHistory.clear();
+    this.webFetch.resetLoop();
+  }
+
+  destroy(): void {
+    this.readRegistry.clear();
+    this.fileMutationLock.clear();
+    this.editHistory.clear();
+    this.backgroundTasks.clear();
+    this.webFetch.destroy();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Runtime-aware tool metadata
+// ---------------------------------------------------------------------------
+
+export interface RuntimeAwareToolMetadata<TTool> {
+  readonly toolKind: string;
+  cloneForRuntime: (runtime: CortexToolRuntime) => TTool;
+}
+
+const RUNTIME_AWARE_TOOL = Symbol.for('cortex.runtimeAwareTool');
+
+export function attachRuntimeAwareTool<TTool extends object>(
+  tool: TTool,
+  metadata: RuntimeAwareToolMetadata<TTool>,
+): TTool {
+  Object.defineProperty(tool, RUNTIME_AWARE_TOOL, {
+    value: metadata,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
+  return tool;
+}
+
+export function getRuntimeAwareToolMetadata<TTool>(
+  tool: TTool,
+): RuntimeAwareToolMetadata<TTool> | undefined {
+  if (!tool || typeof tool !== 'object') return undefined;
+  const record = tool as Record<string | symbol, unknown>;
+  return record[RUNTIME_AWARE_TOOL] as RuntimeAwareToolMetadata<TTool> | undefined;
+}
+
+export function cloneRuntimeAwareTool<TTool>(
+  tool: TTool,
+  runtime: CortexToolRuntime,
+): TTool | null {
+  const metadata = getRuntimeAwareToolMetadata(tool);
+  return metadata ? metadata.cloneForRuntime(runtime) : null;
+}

package/src/tools/shared/cwd-tracker.ts

@@ -0,0 +1,50 @@
+/**
+ * Working directory tracking across Bash calls.
+ *
+ * Each Bash tool call spawns a new shell process. Shell state
+ * (env vars, aliases) does NOT persist between calls. Only the
+ * working directory persists via this tracker.
+ *
+ * The tracker is reset to the default directory at the start
+ * of each agentic loop.
+ */
+
+import * as path from 'node:path';
+
+export class CwdTracker {
+  private readonly defaultDir: string;
+  private currentDir: string;
+
+  constructor(defaultDir: string) {
+    this.defaultDir = path.resolve(defaultDir);
+    this.currentDir = this.defaultDir;
+  }
+
+  /**
+   * Get the current working directory.
+   */
+  getCwd(): string {
+    return this.currentDir;
+  }
+
+  /**
+   * Update the working directory. The path is resolved to absolute.
+   */
+  updateCwd(newDir: string): void {
+    this.currentDir = path.resolve(newDir);
+  }
+
+  /**
+   * Reset to the default directory. Called at the start of each agentic loop.
+   */
+  reset(): void {
+    this.currentDir = this.defaultDir;
+  }
+
+  /**
+   * Get the default (initial) directory.
+   */
+  getDefaultDir(): string {
+    return this.defaultDir;
+  }
+}

package/src/tools/shared/edit-history.ts

@@ -0,0 +1,96 @@
+/**
+ * Per-file pre-mutation snapshot stack.
+ *
+ * Both Edit and Write push a snapshot immediately AFTER each successful
+ * mutation. The UndoEdit tool pops the most recent snapshot to revert
+ * a file to its prior state, as long as the on-disk state still matches
+ * what we recorded when the mutation completed (so we never undo on top
+ * of unrelated external changes).
+ *
+ * Scoped per-agent via `CortexToolRuntime`, cleared on each loop reset
+ * — history does not persist across agentic loops or across agents.
+ *
+ * The stack is intentionally bounded (`MAX_STACK_DEPTH`). An unbounded
+ * stack would accumulate full file contents during long refactors and
+ * bloat memory. A deep stack is also rarely useful for the agentic
+ * loop: if the model wants to roll back more than a few edits, it's
+ * more reliable to Read the file and write the intended content
+ * directly.
+ */
+
+import * as path from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface EditHistoryEntry {
+  /**
+   * File contents BEFORE the mutation, or `null` when the file did not
+   * exist before the mutation (created by Write). Undoing a `null`
+   * entry deletes the file.
+   */
+  originalContent: string | null;
+  /** mtime (ms since epoch) of the file immediately AFTER the mutation. */
+  postMutationMtimeMs: number;
+  /** SHA-256 hex digest of the file bytes immediately AFTER the mutation. */
+  postMutationContentHash: string;
+  /** Which tool created the entry (for diagnostics / undo messaging). */
+  source: 'Edit' | 'Write';
+}
+
+/** Upper bound on snapshots retained per file. */
+export const MAX_STACK_DEPTH = 5;
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+export class EditHistory {
+  private readonly stacks = new Map<string, EditHistoryEntry[]>();
+
+  /**
+   * Push a snapshot for `filePath`. When the per-file stack is at its
+   * depth cap, the oldest entry is dropped so newer edits remain
+   * undoable.
+   */
+  record(filePath: string, entry: EditHistoryEntry): void {
+    const key = this.normalize(filePath);
+    const stack = this.stacks.get(key);
+    if (stack === undefined) {
+      this.stacks.set(key, [entry]);
+      return;
+    }
+    stack.push(entry);
+    while (stack.length > MAX_STACK_DEPTH) stack.shift();
+  }
+
+  /**
+   * Pop and return the most recent entry for `filePath`, or `undefined`
+   * when the file has no recorded history.
+   */
+  pop(filePath: string): EditHistoryEntry | undefined {
+    const key = this.normalize(filePath);
+    const stack = this.stacks.get(key);
+    if (!stack || stack.length === 0) return undefined;
+    const entry = stack.pop()!;
+    if (stack.length === 0) this.stacks.delete(key);
+    return entry;
+  }
+
+  /** Current stack depth for `filePath` (0 when absent). Diagnostic use. */
+  depth(filePath: string): number {
+    return this.stacks.get(this.normalize(filePath))?.length ?? 0;
+  }
+
+  /** Drop all history. Called from `CortexToolRuntime.resetForLoop`. */
+  clear(): void {
+    this.stacks.clear();
+  }
+
+  private normalize(filePath: string): string {
+    // Matches the normalization used by FileMutationLock and
+    // ReadRegistry so keys stay consistent across the three.
+    return path.resolve(filePath);
+  }
+}