@animus-labs/cortex 0.2.0

package/dist/tools/undo-edit.js

@@ -0,0 +1,231 @@
+/**
+ * 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 } from 'typebox';
+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.',
+    }),
+});
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function hashBytes(data) {
+    return crypto.createHash('sha256').update(data).digest('hex');
+}
+function rejection(filePath, text, remainingDepth) {
+    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, content) {
+    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) {
+    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) {
+            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 = () => 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,
+        }),
+    });
+}
+/**
+ * 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, entry) {
+    let stat;
+    try {
+        stat = await fs.promises.stat(filePath);
+    }
+    catch (err) {
+        const code = err.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.',
+    };
+}
+//# sourceMappingURL=undo-edit.js.map

package/dist/tools/undo-edit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"undo-edit.js","sourceRoot":"","sources":["../../src/tools/undo-edit.ts"],"names":[],"mappings":"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"}

package/dist/tools/web-fetch/cache.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+export interface CacheEntry {
+    content: string;
+    fetchedAt: number;
+    statusCode: number;
+    finalUrl: string;
+}
+export declare class WebFetchCache {
+    private readonly cache;
+    private readonly ttlMs;
+    private cleanupTimer;
+    constructor(ttlMs?: number);
+    /**
+     * Get a cached entry for a URL, or undefined if not cached or expired.
+     */
+    get(url: string): CacheEntry | undefined;
+    /**
+     * Store a cache entry for a URL.
+     */
+    set(url: string, entry: CacheEntry): void;
+    /**
+     * Check if a URL has a valid (non-expired) cache entry.
+     */
+    has(url: string): boolean;
+    /**
+     * Remove expired entries.
+     */
+    cleanup(): void;
+    /**
+     * Clear all cached entries.
+     */
+    clear(): void;
+    /**
+     * Stop the cleanup timer. Call on shutdown.
+     */
+    destroy(): void;
+    /**
+     * Get the number of cached entries (for diagnostics).
+     */
+    get size(): number;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/tools/web-fetch/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/tools/web-fetch/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAaD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;IACvD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,YAAY,CAA+C;gBAEvD,KAAK,GAAE,MAAuB;IAU1C;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAYxC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI;IAIzC;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB;;OAEG;IACH,OAAO,IAAI,IAAI;IASf;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,OAAO,IAAI,IAAI;IAQf;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/tools/web-fetch/cache.js

@@ -0,0 +1,89 @@
+/**
+ * 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.
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+const DEFAULT_TTL_MS = 15 * 60 * 1000; // 15 minutes
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+// ---------------------------------------------------------------------------
+// Cache
+// ---------------------------------------------------------------------------
+export class WebFetchCache {
+    cache = new Map();
+    ttlMs;
+    cleanupTimer = null;
+    constructor(ttlMs = 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) {
+        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, entry) {
+        this.cache.set(url, entry);
+    }
+    /**
+     * Check if a URL has a valid (non-expired) cache entry.
+     */
+    has(url) {
+        return this.get(url) !== undefined;
+    }
+    /**
+     * Remove expired entries.
+     */
+    cleanup() {
+        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() {
+        this.cache.clear();
+    }
+    /**
+     * Stop the cleanup timer. Call on shutdown.
+     */
+    destroy() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+        this.cache.clear();
+    }
+    /**
+     * Get the number of cached entries (for diagnostics).
+     */
+    get size() {
+        return this.cache.size;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/tools/web-fetch/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../../src/tools/web-fetch/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,MAAM,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,aAAa;AACpD,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,YAAY;AAEvD,8EAA8E;AAC9E,QAAQ;AACR,8EAA8E;AAE9E,MAAM,OAAO,aAAa;IACP,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IACtC,KAAK,CAAS;IACvB,YAAY,GAA0C,IAAI,CAAC;IAEnE,YAAY,QAAgB,cAAc;QACxC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,yBAAyB;QACzB,IAAI,CAAC,YAAY,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,mBAAmB,CAAC,CAAC;QAC3E,qDAAqD;QACrD,IAAI,IAAI,CAAC,YAAY,IAAI,OAAO,IAAI,CAAC,YAAY,KAAK,QAAQ,IAAI,OAAO,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YAC/F,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;QAC5B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,GAAW;QACb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAE7B,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9C,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,GAAW,EAAE,KAAiB;QAChC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC7B,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;IACrC,CAAC;IAED;;OAEG;IACH,OAAO;QACL,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,IAAI,GAAG,GAAG,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;gBACvC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,OAAO;QACL,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC;YACtB,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YACjC,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF"}

package/dist/tools/web-fetch/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * WebFetch tool: fetch a web page and return its content as processed text.
+ *
+ * Two-model architecture:
+ * 1. Fetch: HTTP request via Node built-in fetch
+ * 2. Convert: HTML to markdown via Turndown
+ * 3. Summarize: utility model answers the prompt using the page content
+ *
+ * The main agent never sees raw page content.
+ *
+ * Reference: docs/cortex/tools/web-fetch.md
+ */
+import { Type, type Static } from 'typebox';
+import type { ToolContentDetails } from '../../types.js';
+import { WebFetchCache } from './cache.js';
+import type { CortexToolRuntime } from '../runtime.js';
+export declare const WebFetchParams: Type.TObject<{
+    url: Type.TString;
+    prompt: Type.TString;
+}>;
+export type WebFetchParamsType = Static<typeof WebFetchParams>;
+export interface WebFetchDetails {
+    finalUrl: string;
+    statusCode: number;
+    cacheHit: boolean;
+    rawSize: number;
+    markdownSize: number;
+}
+/**
+ * Check whether an IP address (v4 or v6) belongs to a private, loopback,
+ * link-local, or otherwise non-routable range. Handles IPv4-mapped IPv6
+ * addresses (::ffff:x.x.x.x) and parses octets numerically to catch
+ * alternate encodings (decimal IPs, zero-padded, etc.).
+ */
+export declare function isPrivateIp(ip: string): boolean;
+export interface WebFetchToolConfig {
+    runtime?: CortexToolRuntime | undefined;
+    /** Utility model completion function for summarization. */
+    utilityComplete?: ((context: unknown) => Promise<unknown>) | undefined;
+    /** Max fetches per agentic loop. */
+    maxPerLoop?: number | undefined;
+}
+export declare function createWebFetchTool(config: WebFetchToolConfig): {
+    name: string;
+    description: string;
+    parameters: typeof WebFetchParams;
+    execute: (params: WebFetchParamsType) => Promise<ToolContentDetails<WebFetchDetails>>;
+    /** Reset the per-loop rate counter. Called at the start of each loop. */
+    resetRateLimit: () => void;
+    /** Get the underlying cache (for testing/diagnostics). */
+    getCache: () => WebFetchCache;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/web-fetch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/tools/web-fetch/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAAE,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAOvD,eAAO,MAAM,cAAc;;;EAGzB,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAM/D,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;CACtB;AAsCD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CA8C/C;AAyBD,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACxC,2DAA2D;IAC3D,eAAe,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IACvE,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAwFD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,OAAO,cAAc,CAAC;IAClC,OAAO,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,OAAO,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAC,CAAC;IACtF,yEAAyE;IACzE,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,aAAa,CAAC;CAC/B,CA8RA"}