@animus-labs/cortex 0.2.0

package/src/tools/task-output.ts

@@ -0,0 +1,236 @@
+/**
+ * TaskOutput tool: companion tool for polling backgrounded processes.
+ *
+ * Auto-registered alongside the Bash tool. Provides three actions:
+ * - poll: get latest output and status
+ * - send: send input to process stdin
+ * - kill: send a signal to the process
+ *
+ * Reference: docs/cortex/tools/bash.md (Background Execution)
+ */
+
+import { Type, type Static } from 'typebox';
+import type { ToolContentDetails } from '../types.js';
+import type { CortexToolRuntime } from './runtime.js';
+import {
+  attachRuntimeAwareTool,
+  globalBackgroundTaskStore,
+} from './runtime.js';
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+export const TaskOutputParams = Type.Object({
+  task_id: Type.String({ description: 'The task ID returned by a backgrounded Bash command' }),
+  action: Type.Union([
+    Type.Literal('poll'),
+    Type.Literal('send'),
+    Type.Literal('kill'),
+  ], { description: 'Action to perform: poll (get output), send (send input), or kill (terminate)' }),
+  input: Type.Optional(
+    Type.String({ description: 'Input to send to the process stdin (only for "send" action)' }),
+  ),
+  signal: Type.Optional(
+    Type.String({ description: 'Signal to send (only for "kill" action). Default: SIGTERM. Options: SIGINT, SIGTERM, SIGKILL' }),
+  ),
+});
+
+export type TaskOutputParamsType = Static<typeof TaskOutputParams>;
+
+// ---------------------------------------------------------------------------
+// Details type
+// ---------------------------------------------------------------------------
+
+export interface TaskOutputDetails {
+  taskId: string;
+  action: string;
+  status: 'running' | 'completed' | 'failed' | 'not_found';
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+}
+
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+
+export interface TaskOutputToolConfig {
+  runtime?: CortexToolRuntime | undefined;
+}
+
+export function createTaskOutputTool(config?: TaskOutputToolConfig): {
+  name: string;
+  description: string;
+  parameters: typeof TaskOutputParams;
+  execute: (params: TaskOutputParamsType) => Promise<ToolContentDetails<TaskOutputDetails>>;
+} {
+  const backgroundTasks = config?.runtime?.backgroundTasks ?? globalBackgroundTaskStore;
+
+  const tool = {
+    name: 'TaskOutput',
+    description: 'Poll, send input to, or kill a backgrounded process.',
+    parameters: TaskOutputParams,
+
+    async execute(params: TaskOutputParamsType): Promise<ToolContentDetails<TaskOutputDetails>> {
+      const { task_id: taskId, action } = params;
+
+      const task = backgroundTasks.get(taskId);
+      if (!task) {
+        return {
+          content: [{ type: 'text', text: `Task not found: ${taskId}` }],
+          details: {
+            taskId,
+            action,
+            status: 'not_found',
+            exitCode: null,
+            stdout: '',
+            stderr: '',
+          },
+        };
+      }
+
+      switch (action) {
+        case 'poll': {
+          const status = task.completed
+            ? (task.exitCode === 0 ? 'completed' : 'failed')
+            : 'running';
+
+          let text = `Status: ${status}`;
+          if (task.completed && task.exitCode !== null) {
+            text += ` (exit code: ${task.exitCode})`;
+          }
+          if (task.stdout) {
+            const output = task.stdout.length > 30000
+              ? task.stdout.slice(-30000)
+              : task.stdout;
+            text += `\n\nOutput:\n${output}`;
+          }
+          if (task.stderr) {
+            text += `\n\nStderr:\n${task.stderr}`;
+          }
+
+          return {
+            content: [{ type: 'text', text }],
+            details: {
+              taskId,
+              action,
+              status: status as 'running' | 'completed' | 'failed',
+              exitCode: task.exitCode,
+              stdout: task.stdout,
+              stderr: task.stderr,
+            },
+          };
+        }
+
+        case 'send': {
+          if (task.completed) {
+            return {
+              content: [{ type: 'text', text: `Task ${taskId} has already completed. Cannot send input.` }],
+              details: {
+                taskId,
+                action,
+                status: task.exitCode === 0 ? 'completed' : 'failed',
+                exitCode: task.exitCode,
+                stdout: task.stdout,
+                stderr: task.stderr,
+              },
+            };
+          }
+
+          const input = params.input ?? '';
+          try {
+            task.process.stdin?.write(input + '\n');
+            return {
+              content: [{ type: 'text', text: `Sent input to task ${taskId}.` }],
+              details: {
+                taskId,
+                action,
+                status: 'running',
+                exitCode: null,
+                stdout: task.stdout,
+                stderr: task.stderr,
+              },
+            };
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+              content: [{ type: 'text', text: `Failed to send input to task ${taskId}: ${msg}` }],
+              details: {
+                taskId,
+                action,
+                status: 'running',
+                exitCode: null,
+                stdout: task.stdout,
+                stderr: task.stderr,
+              },
+            };
+          }
+        }
+
+        case 'kill': {
+          if (task.completed) {
+            return {
+              content: [{ type: 'text', text: `Task ${taskId} has already completed.` }],
+              details: {
+                taskId,
+                action,
+                status: task.exitCode === 0 ? 'completed' : 'failed',
+                exitCode: task.exitCode,
+                stdout: task.stdout,
+                stderr: task.stderr,
+              },
+            };
+          }
+
+          const signal = (params.signal ?? 'SIGTERM') as NodeJS.Signals;
+          try {
+            task.process.kill(signal);
+            return {
+              content: [{ type: 'text', text: `Sent ${signal} to task ${taskId}.` }],
+              details: {
+                taskId,
+                action,
+                status: 'running',
+                exitCode: null,
+                stdout: task.stdout,
+                stderr: task.stderr,
+              },
+            };
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return {
+              content: [{ type: 'text', text: `Failed to kill task ${taskId}: ${msg}` }],
+              details: {
+                taskId,
+                action,
+                status: 'running',
+                exitCode: null,
+                stdout: task.stdout,
+                stderr: task.stderr,
+              },
+            };
+          }
+        }
+
+        default:
+          return {
+            content: [{ type: 'text', text: `Unknown action: ${action}` }],
+            details: {
+              taskId,
+              action,
+              status: 'not_found',
+              exitCode: null,
+              stdout: '',
+              stderr: '',
+            },
+          };
+      }
+    },
+  };
+
+  return attachRuntimeAwareTool(tool, {
+    toolKind: 'TaskOutput',
+    cloneForRuntime: (runtime) => createTaskOutputTool({ runtime }),
+  });
+}

package/src/tools/tool-search/index.ts

@@ -0,0 +1,167 @@
+/**
+ * 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, type Static } from 'typebox';
+import type { CortexTool } from '../../tool-contract.js';
+import type { ToolContentDetails } from '../../types.js';
+import type { DeferredToolRegistry, ToolSearchResult } from './registry.js';
+
+// ---------------------------------------------------------------------------
+// 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 type ToolSearchParamsType = Static<typeof ToolSearchParams>;
+
+// ---------------------------------------------------------------------------
+// Details
+// ---------------------------------------------------------------------------
+
+export interface ToolSearchDetails {
+  query: string;
+  loaded: string[];
+  alreadyAvailable: string[];
+  notFound: string[];
+  totalDeferred: number;
+}
+
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+
+export interface ToolSearchToolConfig {
+  /** The deferred tool registry shared with CortexAgent. */
+  registry: DeferredToolRegistry;
+  /**
+   * Called after the registry is updated. The agent uses this to refresh
+   * its tools array (so the newly discovered tools appear in the next API
+   * call) and update the `_available_tools` slot.
+   */
+  onAfterDiscovery: () => void;
+}
+
+export function createToolSearchTool(
+  config: ToolSearchToolConfig,
+): CortexTool<ToolSearchParamsType, ToolContentDetails<ToolSearchDetails>> {
+  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): Promise<ToolContentDetails<ToolSearchDetails>> {
+      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: string,
+  result: ToolSearchResult,
+  alreadyAvailable: string[],
+  totalDeferredAfter: number,
+): string {
+  const lines: string[] = [];
+
+  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');
+}

package/src/tools/tool-search/registry.ts

@@ -0,0 +1,278 @@
+/**
+ * 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';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * 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[];
+}
+
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+
+export class DeferredToolRegistry {
+  /** Tools currently eligible for deferral, keyed by name. */
+  private deferredPool = new Map<string, CortexTool>();
+  /** Names the model has loaded via ToolSearch. Persists for the session. */
+  private discovered = new Set<string>();
+
+  /**
+   * 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 {
+    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: readonly string[]): string[] {
+    const added: string[] = [];
+    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(): ReadonlySet<string> {
+    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(): string[] {
+    const names: string[] = [];
+    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(): string {
+    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: string, maxResults: number): ToolSearchResult {
+    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: string[] = [];
+      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
+  // -----------------------------------------------------------------------
+
+  private resolveByNames(names: readonly string[]): ToolSearchResult {
+    const resolved: CortexTool[] = [];
+    const notFound: string[] = [];
+    const toMarkDiscovered: string[] = [];
+
+    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 };
+  }
+
+  private scoreKeywordQuery(query: string): Array<{ name: string; score: number }> {
+    // Split into terms; "+term" means required.
+    const tokens = query
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((t) => t.length > 0);
+
+    const required = new Set<string>();
+    const optional: string[] = [];
+    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: Array<{ name: string; score: number }> = [];
+
+    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;
+  }
+}