@animus-labs/cortex 0.2.0

package/dist/tools/tool-search/index.js

@@ -0,0 +1,110 @@
+/**
+ * ToolSearch tool: load full tool schemas on demand.
+ *
+ * Auto-registered when `deferredTools.enabled` is true. The model uses this
+ * tool to discover and load tools that appear by name in the
+ * `_available_tools` slot but whose schemas are not yet in the agent's
+ * tools array.
+ *
+ * Once a tool is loaded, it persists in the agent's tools array for the
+ * rest of the session and can be called normally.
+ */
+import { Type } from 'typebox';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const TOOL_SEARCH_TOOL_NAME = 'ToolSearch';
+const DEFAULT_MAX_RESULTS = 5;
+const QUERY_DESCRIPTION = [
+    'Query for the tool(s) you want to load. Supported formats:',
+    '- "select:NameA,NameB" to load specific tools by exact name (preferred when you already know the names from the available-tools list)',
+    '- "exact_tool_name" to load a single tool by its exact name',
+    '- "prefix" to load all tools starting with the given prefix (e.g., "mcp__obsidian")',
+    '- "keyword another keyword" for keyword search across tool names and descriptions',
+    '- prefix any keyword with "+" to require it (e.g., "+slack send")',
+].join('\n');
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+export const ToolSearchParams = Type.Object({
+    query: Type.String({ description: QUERY_DESCRIPTION }),
+    max_results: Type.Optional(Type.Number({
+        description: `Maximum number of tools to load when using keyword/prefix search. Default ${DEFAULT_MAX_RESULTS}. Ignored for select: queries (which always load every requested tool).`,
+        default: DEFAULT_MAX_RESULTS,
+    })),
+});
+export function createToolSearchTool(config) {
+    return {
+        name: TOOL_SEARCH_TOOL_NAME,
+        description: [
+            'Load tool schemas on demand. Some tools are not loaded by default to save context tokens; their names appear in the "Available Tools" section but their parameters are not visible to you yet.',
+            '',
+            'Call this tool to load specific tools before using them. Once loaded, tools become callable on the next turn.',
+            '',
+            'Use a "select:Name1,Name2" query when you already know the tool names you need (most common). Use keyword queries when you need to discover tools by capability.',
+        ].join('\n'),
+        parameters: ToolSearchParams,
+        alwaysLoad: true, // ToolSearch itself must never be deferred
+        executionMode: 'sequential',
+        async execute(params) {
+            const max = params.max_results ?? DEFAULT_MAX_RESULTS;
+            const result = config.registry.resolveQuery(params.query, max);
+            const alreadyAvailable = result.resolved
+                .map((t) => t.name)
+                .filter((n) => !result.newlyDiscovered.includes(n));
+            const totalDeferred = config.registry.getUndiscoveredNames().length;
+            // Only trigger downstream refresh when something actually changed.
+            if (result.newlyDiscovered.length > 0) {
+                config.onAfterDiscovery();
+            }
+            const text = formatResultText(params.query, result, alreadyAvailable, totalDeferred);
+            return {
+                content: [{ type: 'text', text }],
+                details: {
+                    query: params.query,
+                    loaded: result.newlyDiscovered,
+                    alreadyAvailable,
+                    notFound: result.notFound,
+                    totalDeferred,
+                },
+            };
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Result formatting
+// ---------------------------------------------------------------------------
+function formatResultText(query, result, alreadyAvailable, totalDeferredAfter) {
+    const lines = [];
+    if (result.newlyDiscovered.length > 0) {
+        lines.push('Loaded the following tools (callable on the next turn):');
+        for (const name of result.newlyDiscovered) {
+            lines.push(`- ${name}`);
+        }
+    }
+    if (alreadyAvailable.length > 0) {
+        if (lines.length > 0)
+            lines.push('');
+        lines.push('Already loaded (no action needed):');
+        for (const name of alreadyAvailable) {
+            lines.push(`- ${name}`);
+        }
+    }
+    if (result.notFound.length > 0) {
+        if (lines.length > 0)
+            lines.push('');
+        lines.push('Not found in the deferred tool list:');
+        for (const name of result.notFound) {
+            lines.push(`- ${name}`);
+        }
+    }
+    if (result.resolved.length === 0 && result.notFound.length === 0) {
+        lines.push(`No tools matched the query: "${query}"`);
+        if (totalDeferredAfter > 0) {
+            lines.push('');
+            lines.push(`There are ${totalDeferredAfter} tools still available. Refer to the "Available Tools" section for the full list.`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/tool-search/index.js.map

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

package/dist/tools/tool-search/registry.d.ts

@@ -0,0 +1,82 @@
+/**
+ * DeferredToolRegistry: tracks the deferred tool pool and which tools the
+ * agent has discovered (loaded) during this session.
+ *
+ * Lives on the CortexAgent instance. `refreshTools()` populates the deferred
+ * pool from the union of registered + MCP tools (filtered by deferral
+ * criteria), and `ToolSearch` updates the discovered set when the agent
+ * resolves a query.
+ *
+ * The slot content (`formatSlotContent`) is the canonical text that goes
+ * into the `_available_tools` slot. It is byte-stable for any given pool +
+ * discovered set so the prompt cache hits cleanly.
+ */
+import type { CortexTool } from '../../tool-contract.js';
+/**
+ * Result of resolving a ToolSearch query.
+ */
+export interface ToolSearchResult {
+    /** Tools that were resolved by the query (newly loaded + already loaded). */
+    resolved: CortexTool[];
+    /** Names of tools newly added to the discovered set by this query. */
+    newlyDiscovered: string[];
+    /** Names of tools the query referenced that were not found in the pool. */
+    notFound: string[];
+}
+export declare class DeferredToolRegistry {
+    /** Tools currently eligible for deferral, keyed by name. */
+    private deferredPool;
+    /** Names the model has loaded via ToolSearch. Persists for the session. */
+    private discovered;
+    /**
+     * Replace the deferred pool. Called by `refreshTools()` whenever the
+     * underlying tool set changes (MCP server connect/disconnect, etc).
+     *
+     * Tools that were previously discovered remain in the discovered set even
+     * if they're temporarily missing from the pool (e.g., MCP server briefly
+     * disconnected). The next `refreshTools()` call will see them again.
+     */
+    setDeferredPool(tools: readonly CortexTool[]): void;
+    /**
+     * Mark tool names as discovered. Subsequent `refreshTools()` calls will
+     * include their full schemas in the agent's tools array.
+     *
+     * Returns the subset that were newly added (i.e., were not already
+     * discovered). Used by ToolSearch to report what changed.
+     */
+    markDiscovered(names: readonly string[]): string[];
+    /**
+     * The set of tool names the agent has loaded so far.
+     */
+    getDiscovered(): ReadonlySet<string>;
+    /**
+     * Names currently in the deferred pool that have NOT yet been discovered.
+     * These are the names that should appear in the `_available_tools` slot.
+     * Returned sorted alphabetically for deterministic, cache-stable output.
+     */
+    getUndiscoveredNames(): string[];
+    /**
+     * Format the `_available_tools` slot content. Names only (no descriptions),
+     * sorted, in a fixed format. Returns an empty string when there are no
+     * undiscovered tools (the slot will be set to empty content, which still
+     * occupies a slot index but contributes no tokens).
+     */
+    formatSlotContent(): string;
+    /**
+     * Resolve a ToolSearch query against the deferred pool.
+     *
+     * Query formats:
+     *   - "select:NameA,NameB"      Direct load by name. Bypasses scoring.
+     *   - "ExactToolName"           Exact name match if it exists in the pool.
+     *   - "prefix__"                Returns all tools starting with the prefix.
+     *   - "keyword another"         Keyword search; scored by name + description.
+     *
+     * Discovered tools that are referenced by the query are still returned
+     * (harmless no-op so the model gets confirmation), but they don't count
+     * as "newly discovered".
+     */
+    resolveQuery(query: string, maxResults: number): ToolSearchResult;
+    private resolveByNames;
+    private scoreKeywordQuery;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/tools/tool-search/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/tools/tool-search/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAMzD;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6EAA6E;IAC7E,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,sEAAsE;IACtE,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAMD,qBAAa,oBAAoB;IAC/B,4DAA4D;IAC5D,OAAO,CAAC,YAAY,CAAiC;IACrD,2EAA2E;IAC3E,OAAO,CAAC,UAAU,CAAqB;IAEvC;;;;;;;OAOG;IACH,eAAe,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,IAAI;IAOnD;;;;;;OAMG;IACH,cAAc,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE;IAWlD;;OAEG;IACH,aAAa,IAAI,WAAW,CAAC,MAAM,CAAC;IAIpC;;;;OAIG;IACH,oBAAoB,IAAI,MAAM,EAAE;IAUhC;;;;;OAKG;IACH,iBAAiB,IAAI,MAAM;IAkB3B;;;;;;;;;;;;OAYG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,gBAAgB;IAuDjE,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,iBAAiB;CAqE1B"}

package/dist/tools/tool-search/registry.js

@@ -0,0 +1,238 @@
+/**
+ * DeferredToolRegistry: tracks the deferred tool pool and which tools the
+ * agent has discovered (loaded) during this session.
+ *
+ * Lives on the CortexAgent instance. `refreshTools()` populates the deferred
+ * pool from the union of registered + MCP tools (filtered by deferral
+ * criteria), and `ToolSearch` updates the discovered set when the agent
+ * resolves a query.
+ *
+ * The slot content (`formatSlotContent`) is the canonical text that goes
+ * into the `_available_tools` slot. It is byte-stable for any given pool +
+ * discovered set so the prompt cache hits cleanly.
+ */
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+export class DeferredToolRegistry {
+    /** Tools currently eligible for deferral, keyed by name. */
+    deferredPool = new Map();
+    /** Names the model has loaded via ToolSearch. Persists for the session. */
+    discovered = new Set();
+    /**
+     * Replace the deferred pool. Called by `refreshTools()` whenever the
+     * underlying tool set changes (MCP server connect/disconnect, etc).
+     *
+     * Tools that were previously discovered remain in the discovered set even
+     * if they're temporarily missing from the pool (e.g., MCP server briefly
+     * disconnected). The next `refreshTools()` call will see them again.
+     */
+    setDeferredPool(tools) {
+        this.deferredPool.clear();
+        for (const tool of tools) {
+            this.deferredPool.set(tool.name, tool);
+        }
+    }
+    /**
+     * Mark tool names as discovered. Subsequent `refreshTools()` calls will
+     * include their full schemas in the agent's tools array.
+     *
+     * Returns the subset that were newly added (i.e., were not already
+     * discovered). Used by ToolSearch to report what changed.
+     */
+    markDiscovered(names) {
+        const added = [];
+        for (const name of names) {
+            if (!this.discovered.has(name)) {
+                this.discovered.add(name);
+                added.push(name);
+            }
+        }
+        return added;
+    }
+    /**
+     * The set of tool names the agent has loaded so far.
+     */
+    getDiscovered() {
+        return this.discovered;
+    }
+    /**
+     * Names currently in the deferred pool that have NOT yet been discovered.
+     * These are the names that should appear in the `_available_tools` slot.
+     * Returned sorted alphabetically for deterministic, cache-stable output.
+     */
+    getUndiscoveredNames() {
+        const names = [];
+        for (const name of this.deferredPool.keys()) {
+            if (!this.discovered.has(name)) {
+                names.push(name);
+            }
+        }
+        return names.sort();
+    }
+    /**
+     * Format the `_available_tools` slot content. Names only (no descriptions),
+     * sorted, in a fixed format. Returns an empty string when there are no
+     * undiscovered tools (the slot will be set to empty content, which still
+     * occupies a slot index but contributes no tokens).
+     */
+    formatSlotContent() {
+        const names = this.getUndiscoveredNames();
+        if (names.length === 0) {
+            return '';
+        }
+        const list = names.map((n) => `- ${n}`).join('\n');
+        return [
+            '# Available Tools',
+            '',
+            'The following tools are available but their schemas have not been loaded.',
+            'Use the ToolSearch tool to load a tool before calling it.',
+            '',
+            'Calling any of these tools directly (without loading first) will fail.',
+            '',
+            list,
+        ].join('\n');
+    }
+    /**
+     * Resolve a ToolSearch query against the deferred pool.
+     *
+     * Query formats:
+     *   - "select:NameA,NameB"      Direct load by name. Bypasses scoring.
+     *   - "ExactToolName"           Exact name match if it exists in the pool.
+     *   - "prefix__"                Returns all tools starting with the prefix.
+     *   - "keyword another"         Keyword search; scored by name + description.
+     *
+     * Discovered tools that are referenced by the query are still returned
+     * (harmless no-op so the model gets confirmation), but they don't count
+     * as "newly discovered".
+     */
+    resolveQuery(query, maxResults) {
+        const trimmed = query.trim();
+        // Direct select format
+        if (trimmed.startsWith('select:')) {
+            const requested = trimmed
+                .slice('select:'.length)
+                .split(',')
+                .map((s) => s.trim())
+                .filter((s) => s.length > 0);
+            return this.resolveByNames(requested);
+        }
+        // Empty or whitespace-only query: return nothing useful
+        if (trimmed.length === 0) {
+            return { resolved: [], newlyDiscovered: [], notFound: [] };
+        }
+        // Exact name match (single token, exists in pool)
+        if (!/\s/.test(trimmed) && this.deferredPool.has(trimmed)) {
+            return this.resolveByNames([trimmed]);
+        }
+        // Prefix match (single token, no spaces, ends with __ or matches a prefix)
+        if (!/\s/.test(trimmed)) {
+            const prefixMatches = [];
+            for (const name of this.deferredPool.keys()) {
+                if (name.startsWith(trimmed)) {
+                    prefixMatches.push(name);
+                }
+            }
+            if (prefixMatches.length > 0) {
+                prefixMatches.sort();
+                return this.resolveByNames(prefixMatches.slice(0, maxResults));
+            }
+        }
+        // Keyword search with scoring
+        const scored = this.scoreKeywordQuery(trimmed);
+        const top = scored
+            .sort((a, b) => b.score - a.score)
+            .slice(0, maxResults)
+            .filter((entry) => entry.score > 0)
+            .map((entry) => entry.name);
+        if (top.length === 0) {
+            return { resolved: [], newlyDiscovered: [], notFound: [] };
+        }
+        return this.resolveByNames(top);
+    }
+    // -----------------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------------
+    resolveByNames(names) {
+        const resolved = [];
+        const notFound = [];
+        const toMarkDiscovered = [];
+        for (const name of names) {
+            const tool = this.deferredPool.get(name);
+            if (tool) {
+                resolved.push(tool);
+                toMarkDiscovered.push(name);
+            }
+            else {
+                notFound.push(name);
+            }
+        }
+        const newlyDiscovered = this.markDiscovered(toMarkDiscovered);
+        return { resolved, newlyDiscovered, notFound };
+    }
+    scoreKeywordQuery(query) {
+        // Split into terms; "+term" means required.
+        const tokens = query
+            .toLowerCase()
+            .split(/\s+/)
+            .filter((t) => t.length > 0);
+        const required = new Set();
+        const optional = [];
+        for (const token of tokens) {
+            if (token.startsWith('+') && token.length > 1) {
+                required.add(token.slice(1));
+            }
+            else {
+                optional.push(token);
+            }
+        }
+        const allTerms = [...required, ...optional];
+        if (allTerms.length === 0)
+            return [];
+        const results = [];
+        for (const [name, tool] of this.deferredPool.entries()) {
+            const lowerName = name.toLowerCase();
+            const lowerDesc = (tool.description ?? '').toLowerCase();
+            // Tool name parts: split by __ (MCP namespacing) and underscore for general matching
+            const nameParts = lowerName.split(/__|_/).filter((p) => p.length > 0);
+            // Required terms must all match somewhere
+            let satisfiesRequired = true;
+            for (const req of required) {
+                if (!lowerName.includes(req) && !lowerDesc.includes(req)) {
+                    satisfiesRequired = false;
+                    break;
+                }
+            }
+            if (!satisfiesRequired)
+                continue;
+            const isMcp = tool.isMcp === true;
+            let score = 0;
+            for (const term of allTerms) {
+                // Exact part match in name (highest weight)
+                if (nameParts.includes(term)) {
+                    score += isMcp ? 12 : 10;
+                    continue;
+                }
+                // Partial part match
+                if (nameParts.some((p) => p.includes(term))) {
+                    score += isMcp ? 6 : 5;
+                    continue;
+                }
+                // Full-name substring fallback
+                if (lowerName.includes(term)) {
+                    score += 3;
+                    continue;
+                }
+                // Description substring
+                if (lowerDesc.includes(term)) {
+                    score += 2;
+                }
+            }
+            if (score > 0) {
+                results.push({ name, score });
+            }
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/tools/tool-search/registry.js.map

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

package/dist/tools/undo-edit.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 { Type, type Static } from 'typebox';
+import type { EditHistory } 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';
+export declare const UndoEditParams: Type.TObject<{
+    file_path: Type.TString;
+}>;
+export type UndoEditParamsType = Static<typeof UndoEditParams>;
+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;
+}
+export interface UndoEditToolConfig {
+    runtime?: CortexToolRuntime | undefined;
+    editHistory?: EditHistory | undefined;
+    readRegistry?: ReadRegistry | undefined;
+    fileMutationLock?: FileMutationLock | undefined;
+}
+export declare function createUndoEditTool(config: UndoEditToolConfig): {
+    name: string;
+    description: string;
+    parameters: typeof UndoEditParams;
+    execute: (params: UndoEditParamsType) => Promise<ToolContentDetails<UndoEditDetails>>;
+};
+//# sourceMappingURL=undo-edit.d.ts.map

package/dist/tools/undo-edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"undo-edit.d.ts","sourceRoot":"","sources":["../../src/tools/undo-edit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,OAAO,EAAE,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAoB,MAAM,0BAA0B,CAAC;AAC9E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAOtD,eAAO,MAAM,cAAc;;EAIzB,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAM/D,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,cAAc,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAClC,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAMD,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACxC,WAAW,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IACtC,YAAY,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IACxC,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CACjD;AAmDD,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;CACvF,CAyIA"}