@animus-labs/cortex 0.2.0

package/src/skill-tool.ts

@@ -0,0 +1,130 @@
+/**
+ * load_skill tool: loads a skill's full instructions into the agent's
+ * active context.
+ *
+ * The skill body is read from the SkillRegistry, preprocessed (variable
+ * substitution, shell commands, scripts), and pushed to the skill buffer.
+ * The skill buffer is injected into ephemeral context via transformContext
+ * on every subsequent LLM call within the current agentic loop.
+ *
+ * References:
+ *   - docs/cortex/skill-system.md
+ *   - docs/cortex/plans/phase-4-sub-agents-and-skills.md
+ */
+
+import { Type, type Static } from 'typebox';
+import type { SkillRegistry } from './skill-registry.js';
+import type { LoadedSkill } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+export const LoadSkillParams = Type.Object({
+  name: Type.String({
+    description: 'The skill name to load.',
+  }),
+  arguments: Type.Optional(Type.String({
+    description: 'Optional arguments to pass to the skill.',
+  })),
+});
+
+export type LoadSkillParamsType = Static<typeof LoadSkillParams>;
+
+// ---------------------------------------------------------------------------
+// Tool name constant
+// ---------------------------------------------------------------------------
+
+export const LOAD_SKILL_TOOL_NAME = 'load_skill';
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export interface LoadSkillToolConfig {
+  /** The skill registry to load skills from. */
+  registry: SkillRegistry;
+  /** Build the visible skills summary for the tool description. */
+  getAvailableSkillsSummary?: () => string;
+  /** The skill buffer to push loaded skills into. */
+  getSkillBuffer: () => LoadedSkill[];
+  /** Push a loaded skill to the buffer (handles deduplication). */
+  pushToSkillBuffer: (skill: LoadedSkill) => void;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create the load_skill tool.
+ *
+ * Returns a Cortex-native tool. CortexAgent adapts it to pi-agent-core's
+ * execute signature when synchronizing the tool inventory.
+ * The tool description includes the available skills summary, which
+ * updates when skills are added or removed from the registry.
+ */
+export function createLoadSkillTool(config: LoadSkillToolConfig): {
+  name: string;
+  description: string;
+  parameters: typeof LoadSkillParams;
+  execute: (args: unknown) => Promise<unknown>;
+} {
+  return {
+    name: LOAD_SKILL_TOOL_NAME,
+
+    description: `Load a skill's full instructions into your active context. Call this tool when you need detailed guidance for a specific task. The skill's instructions will be available in your context for the remainder of this loop.
+
+${config.getAvailableSkillsSummary ? config.getAvailableSkillsSummary() : config.registry.getAvailableSkillsSummary()}`,
+
+    parameters: LoadSkillParams,
+
+    execute: async (args: unknown): Promise<unknown> => {
+      const params = args as LoadSkillParamsType;
+
+      // Check if skill exists
+      const entry = config.registry.getEntry(params.name);
+      if (!entry) {
+        return `Unknown skill: "${params.name}". Check available skills in the tool description.`;
+      }
+
+      // Check if the skill is model-invocable
+      if (!entry.modelInvocable) {
+        return `Skill "${params.name}" is not available for direct loading.`;
+      }
+
+      // Load and preprocess the skill body
+      try {
+        const callArgs = {
+          args: params.arguments ? params.arguments.split(/\s+/) : [],
+          rawArgs: params.arguments ?? '',
+        };
+
+        const body = await config.registry.getSkillBody(params.name, callArgs);
+
+        // Push to skill buffer (deduplication handled by pushToSkillBuffer)
+        config.pushToSkillBuffer({ name: params.name, content: body });
+
+        return `Skill "${params.name}" loaded. Full instructions are now active in your context (see the skill instructions section below the conversation history). Review them before proceeding.`;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return `Failed to load skill "${params.name}": ${message}`;
+      }
+    },
+  };
+}
+
+/**
+ * Rebuild the load_skill tool's description with the current available
+ * skills summary. Called when skills are added or removed.
+ *
+ * Returns a function that produces the updated description string.
+ */
+export function buildLoadSkillDescription(
+  registry: SkillRegistry,
+  availableSkillsSummary?: string,
+): string {
+  return `Load a skill's full instructions into your active context. Call this tool when you need detailed guidance for a specific task. The skill's instructions will be available in your context for the remainder of this loop.
+
+${availableSkillsSummary ?? registry.getAvailableSkillsSummary()}`;
+}

package/src/sub-agent-manager.ts

@@ -0,0 +1,236 @@
+/**
+ * SubAgentManager: tracks active sub-agents, enforces concurrency limits,
+ * manages lifecycle, and delivers background completion notifications.
+ *
+ * Each sub-agent is an independent CortexAgent instance tracked by task ID.
+ * The manager does not own the CortexAgent; it tracks references and
+ * coordinates lifecycle events for the consumer.
+ *
+ * References:
+ *   - docs/cortex/tools/sub-agent.md
+ *   - docs/cortex/plans/phase-4-sub-agents-and-skills.md
+ */
+
+import type { SubAgentResult, TrackedSubAgent } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface SubAgentManagerConfig {
+  /** Maximum concurrent sub-agents. Default: 4. */
+  maxConcurrent: number;
+}
+
+export interface SubAgentLifecycleHooks {
+  onSpawned?: (taskId: string, instructions: string, background: boolean) => void;
+  onCompleted?: (taskId: string, result: string, status: string, usage: unknown) => void;
+  onFailed?: (taskId: string, error: string) => void;
+}
+
+// ---------------------------------------------------------------------------
+// SubAgentManager
+// ---------------------------------------------------------------------------
+
+export class SubAgentManager {
+  private readonly agents = new Map<string, TrackedSubAgent>();
+  private readonly maxConcurrent: number;
+  private hooks: SubAgentLifecycleHooks = {};
+
+  constructor(config?: Partial<SubAgentManagerConfig>) {
+    this.maxConcurrent = config?.maxConcurrent ?? 4;
+  }
+
+  /**
+   * Set lifecycle hooks. Called by CortexAgent to wire consumer event handlers.
+   */
+  setHooks(hooks: SubAgentLifecycleHooks): void {
+    this.hooks = hooks;
+  }
+
+  /**
+   * Check if another sub-agent can be spawned within the concurrency limit.
+   */
+  canSpawn(): boolean {
+    return this.agents.size < this.maxConcurrent;
+  }
+
+  /**
+   * Get the number of currently active sub-agents.
+   */
+  get activeCount(): number {
+    return this.agents.size;
+  }
+
+  /**
+   * Get the concurrency limit.
+   */
+  get limit(): number {
+    return this.maxConcurrent;
+  }
+
+  /**
+   * Register a newly spawned sub-agent.
+   * Returns false if the concurrency limit would be exceeded.
+   */
+  track(entry: TrackedSubAgent): boolean {
+    if (this.agents.size >= this.maxConcurrent) {
+      return false;
+    }
+
+    this.agents.set(entry.taskId, entry);
+
+    // Fire lifecycle hook
+    try {
+      this.hooks.onSpawned?.(entry.taskId, entry.instructions, entry.background);
+    } catch {
+      // Swallow hook errors
+    }
+
+    return true;
+  }
+
+  /**
+   * Mark a sub-agent as completed and remove it from tracking.
+   */
+  complete(taskId: string, result: SubAgentResult): void {
+    const entry = this.agents.get(taskId);
+    if (!entry) return;
+
+    this.agents.delete(taskId);
+
+    // Resolve the completion promise
+    entry.resolve(result);
+
+    // Fire lifecycle hook (pass full result metadata including toolCalls)
+    try {
+      const usageWithToolCalls: Record<string, unknown> = { ...result.usage };
+      if (result.toolCalls) {
+        usageWithToolCalls['toolCalls'] = result.toolCalls;
+      }
+      this.hooks.onCompleted?.(
+        taskId,
+        result.output,
+        result.status,
+        usageWithToolCalls,
+      );
+    } catch {
+      // Swallow hook errors
+    }
+  }
+
+  /**
+   * Mark a sub-agent as failed and remove it from tracking.
+   */
+  fail(taskId: string, error: string): void {
+    const entry = this.agents.get(taskId);
+    if (!entry) return;
+
+    this.agents.delete(taskId);
+
+    // Resolve the completion promise with a failed result
+    entry.resolve({
+      output: '',
+      status: 'failed',
+      usage: { turns: 0, cost: 0, durationMs: Date.now() - entry.spawnedAt, contextTokens: 0 },
+    });
+
+    // Fire lifecycle hook
+    try {
+      this.hooks.onFailed?.(taskId, error);
+    } catch {
+      // Swallow hook errors
+    }
+  }
+
+  /**
+   * Get a tracked sub-agent by task ID.
+   */
+  get(taskId: string): TrackedSubAgent | undefined {
+    return this.agents.get(taskId);
+  }
+
+  /**
+   * Update tool activity for a running sub-agent.
+   * Called when child tool_call_start events are forwarded via EventBridge.
+   */
+  updateToolActivity(taskId: string, toolName: string, summary: string): void {
+    const entry = this.agents.get(taskId);
+    if (!entry) return;
+    entry.toolCount++;
+    entry.lastToolName = toolName;
+    entry.lastToolSummary = summary;
+    entry.lastToolStartedAt = Date.now();
+  }
+
+  /**
+   * Get all active sub-agent task IDs.
+   */
+  getActiveTaskIds(): string[] {
+    return [...this.agents.keys()];
+  }
+
+  /**
+   * Get completion promises for all background sub-agents.
+   * Used to build follow-up messages when background agents complete.
+   */
+  getBackgroundCompletions(): Array<{ taskId: string; completion: Promise<SubAgentResult> }> {
+    const results: Array<{ taskId: string; completion: Promise<SubAgentResult> }> = [];
+    for (const [taskId, entry] of this.agents) {
+      if (entry.background) {
+        results.push({ taskId, completion: entry.completion });
+      }
+    }
+    return results;
+  }
+
+  /**
+   * Cancel all active sub-agents. Called during parent destroy().
+   * Aborts each sub-agent and removes it from tracking.
+   *
+   * @param abortFn - Function to abort a CortexAgent (passed to avoid circular dep)
+   */
+  async cancelAll(abortFn: (agent: unknown) => Promise<void>): Promise<void> {
+    const entries = [...this.agents.values()];
+    this.agents.clear();
+
+    const settled = await Promise.allSettled(
+      entries.map(async (entry) => {
+        try {
+          await abortFn(entry.agent);
+        } catch {
+          // Best-effort abort
+        }
+
+        // Resolve the completion promise as cancelled
+        entry.resolve({
+          output: '',
+          status: 'cancelled',
+          usage: { turns: 0, cost: 0, durationMs: Date.now() - entry.spawnedAt, contextTokens: 0 },
+        });
+
+        // Fire failure hook
+        try {
+          this.hooks.onFailed?.(entry.taskId, 'Parent agent destroyed');
+        } catch {
+          // Swallow hook errors
+        }
+      }),
+    );
+
+    // Log any unexpected errors (consumer should provide logging)
+    for (const result of settled) {
+      if (result.status === 'rejected') {
+        // Swallowed: best-effort cleanup
+      }
+    }
+  }
+
+  /**
+   * Clean up all state. Called during parent destroy().
+   */
+  destroy(): void {
+    this.agents.clear();
+    this.hooks = {};
+  }
+}

package/src/token-estimator.ts

@@ -0,0 +1,26 @@
+/**
+ * Heuristic token estimation.
+ *
+ * Uses character-based heuristic (chars / 4), the community standard and
+ * closest to Anthropic's official recommendation (chars / 3.5).
+ * Character-based is more stable than word-based across content types
+ * (prose, code, JSON, markdown).
+ *
+ * This is a duplicate of the same utility in @animus-labs/shared,
+ * kept inline to avoid a dependency from cortex to shared.
+ */
+
+/**
+ * Estimate the number of tokens in a text string.
+ *
+ * Uses chars / 4 heuristic (community standard, ~15% underestimate for Claude).
+ * Not a tokenizer; a fast estimation for budget decisions and compaction triggers.
+ * For exact counts, use the Anthropic count_tokens API.
+ *
+ * @param text - The text to estimate tokens for
+ * @returns Estimated token count (always at least 0, rounded up)
+ */
+export function estimateTokens(text: string): number {
+  if (!text) return 0;
+  return Math.ceil(text.length / 4);
+}

package/src/tool-contract.ts

@@ -0,0 +1,113 @@
+import type { ToolExecuteContext } from './types.js';
+
+/**
+ * Cortex's canonical in-process tool contract.
+ *
+ * All tools registered with CortexAgent are normalized to this signature.
+ * Cortex adapts this shape to pi-agent-core's execute signature at the
+ * registration boundary.
+ */
+export interface CortexTool<TParams = unknown, TResult = unknown> {
+  name: string;
+  description: string;
+  parameters: unknown;
+  execute: (params: TParams, context?: ToolExecuteContext) => Promise<TResult>;
+
+  /**
+   * Marks this tool as eligible for deferred loading. When the agent has
+   * `deferredTools.enabled = true`, deferred tools are NOT included in the
+   * `tools` array sent to the model on every turn. Instead, only their names
+   * appear in the `_available_tools` slot, and the model uses ToolSearch to
+   * load full schemas on demand.
+   *
+   * MCP tools get `isMcp: true` set automatically by the MCP client and are
+   * deferred when `deferredTools.deferMcp` is true (default). Built-in or
+   * consumer-supplied tools can opt in via `shouldDefer: true`.
+   */
+  shouldDefer?: boolean;
+
+  /**
+   * Forces this tool to always be sent in the `tools` array, even if it
+   * matches deferral criteria (e.g., an MCP tool the consumer wants always
+   * available). Overrides `shouldDefer` and the `deferMcp` config.
+   */
+  alwaysLoad?: boolean;
+
+  /**
+   * Marker indicating this tool was wrapped from an MCP server. Set
+   * automatically by the MCP client. Consumers should not set this manually.
+   */
+  isMcp?: boolean;
+
+  /**
+   * Optional pi-agent-core execution hint. Use "sequential" for tools that
+   * must update shared agent state before later tool calls in the same batch.
+   */
+  executionMode?: 'sequential' | 'parallel';
+}
+
+/**
+ * Raw pi-agent-core tool contract.
+ *
+ * Use fromPiAgentTool() to explicitly adapt a tool with this signature into
+ * Cortex's canonical CortexTool shape.
+ */
+export interface PiAgentTool<TParams = unknown, TResult = unknown> {
+  name: string;
+  description: string;
+  parameters: unknown;
+  executionMode?: 'sequential' | 'parallel';
+  execute: (
+    toolCallId: string,
+    params: TParams,
+    signal?: AbortSignal,
+    onUpdate?: (partialResult: unknown) => void,
+  ) => Promise<TResult>;
+}
+
+/**
+ * Explicitly adapt a pi-agent-core-style tool into Cortex's canonical tool contract.
+ */
+export function fromPiAgentTool<TParams = unknown, TResult = unknown>(
+  tool: PiAgentTool<TParams, TResult>,
+): CortexTool<TParams, TResult> {
+  const cortexTool: CortexTool<TParams, TResult> = {
+    name: tool.name,
+    description: tool.description,
+    parameters: tool.parameters,
+    execute: (params: TParams, context?: ToolExecuteContext) => {
+      return tool.execute(
+        context?.toolCallId ?? `${tool.name}-direct`,
+        params,
+        context?.signal,
+        context?.onUpdate as ((partialResult: unknown) => void) | undefined,
+      );
+    },
+  };
+  if (tool.executionMode) {
+    cortexTool.executionMode = tool.executionMode;
+  }
+  return cortexTool;
+}
+
+/**
+ * Validate that a tool matches Cortex's canonical execute signature.
+ *
+ * Cortex does not infer tool execution contracts from function arity. Tools
+ * that already use pi-agent-core's raw execute signature must be adapted
+ * explicitly with fromPiAgentTool().
+ */
+export function assertValidCortexTool(tool: CortexTool): CortexTool {
+  if (typeof tool.execute !== 'function') {
+    throw new Error(`Tool "${tool.name}" is missing an execute() function.`);
+  }
+
+  if (tool.execute.length > 2) {
+    throw new Error(
+      `Tool "${tool.name}" does not use Cortex's execute(params, context?) contract. ` +
+      'Wrap raw pi-agent-core tools with fromPiAgentTool() before passing them to CortexAgent.create().',
+    );
+  }
+
+  return tool;
+}

package/src/tool-result-persistence.ts

@@ -0,0 +1,197 @@
+/**
+ * Tool result persistence: bookend-and-persist for oversized tool results.
+ *
+ * Sits at the tool execution boundary (refreshTools wrapper). After a tool
+ * returns its result, this module checks whether the text content exceeds
+ * the per-result threshold and either:
+ *   - passes through unchanged (under threshold or skipped tool)
+ *   - persists to disk (when `persistResult` is configured) and returns
+ *     a bookend preview (head + tail) plus a file reference
+ *   - returns a bookend preview only (when no `persistResult` is configured)
+ *
+ * This replaces ad-hoc per-tool truncation (Grep, Bash, WebFetch) with a
+ * single, uniform mechanism. Reuses `applyBookend` and `getToolCategory`
+ * from the existing compaction infrastructure.
+ *
+ * Reference: docs/cortex/tool-result-persistence.md
+ */
+
+import type { PersistResultFn, ToolCategory } from './types.js';
+import { applyBookend, getToolCategory } from './compaction/microcompaction.js';
+import { estimateTokens } from './token-estimator.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Default per-tool token threshold. Results larger than this trigger persistence/bookend. */
+export const MAX_RESULT_TOKENS = 25_000;
+
+/** Bookend size for the preview (head and tail each). 1,500 chars ≈ 375 tokens. */
+export const BOOKEND_CHARS = 1_500;
+
+/**
+ * Tools whose results bypass the interceptor entirely.
+ *
+ * Either inherently bounded (Edit, Write, Glob) or content already on disk
+ * where the model can use offset/limit on the original file (Read).
+ */
+export const SKIP_RESULT_PERSISTENCE = new Set<string>([
+  'Read',
+  'Edit',
+  'UndoEdit',
+  'Write',
+  'Glob',
+]);
+
+/**
+ * Built-in per-tool threshold overrides. Tools listed here use a different
+ * token limit than `MAX_RESULT_TOKENS` (25K).
+ *
+ * Rationale per tool:
+ * - Bash: command output is verbose with low signal density (logs, stack
+ *   traces, build spam). A tighter cap reduces noise in context while still
+ *   preserving full output via persistence.
+ *
+ * Consumers can extend or override this map via `CortexAgentConfig.toolResultThresholds`.
+ */
+export const DEFAULT_TOOL_THRESHOLDS: Record<string, number> = {
+  Bash: 7_500,
+};
+
+/**
+ * Resolve the effective threshold for a tool.
+ * Order of precedence: consumer overrides > built-in defaults > MAX_RESULT_TOKENS.
+ */
+export function resolveThreshold(
+  toolName: string,
+  consumerOverrides?: Record<string, number>,
+): number {
+  if (consumerOverrides && toolName in consumerOverrides) return consumerOverrides[toolName]!;
+  if (toolName in DEFAULT_TOOL_THRESHOLDS) return DEFAULT_TOOL_THRESHOLDS[toolName]!;
+  return MAX_RESULT_TOKENS;
+}
+
+// ---------------------------------------------------------------------------
+// API
+// ---------------------------------------------------------------------------
+
+export interface ApplyPersistenceOptions {
+  toolName: string;
+  toolCallId: string;
+  persistResult?: PersistResultFn | undefined;
+  toolCategories?: Record<string, ToolCategory> | undefined;
+  /** Consumer-provided per-tool threshold overrides (in tokens). */
+  thresholds?: Record<string, number> | undefined;
+}
+
+/**
+ * Options for processing a full tool result (with potentially multiple parts).
+ * Same shape as ApplyPersistenceOptions minus the per-call identifiers.
+ */
+export interface ProcessResultOptions {
+  toolName: string;
+  toolCallId: string;
+  persistResult?: PersistResultFn | undefined;
+  toolCategories?: Record<string, ToolCategory> | undefined;
+  thresholds?: Record<string, number> | undefined;
+}
+
+/**
+ * Process a tool result text part for size limiting.
+ *
+ * - Under threshold or skipped tool: returns content unchanged
+ * - Over threshold + `persistResult` configured: persists, returns bookend + file ref
+ * - Over threshold + no `persistResult`: returns bookend only (lossy, but bounded)
+ *
+ * Pure async helper; never throws. Persist failures fall back to bookend-only.
+ */
+export async function applyResultPersistence(
+  content: string,
+  options: ApplyPersistenceOptions,
+): Promise<string> {
+  if (SKIP_RESULT_PERSISTENCE.has(options.toolName)) return content;
+
+  const threshold = resolveThreshold(options.toolName, options.thresholds);
+  const tokens = estimateTokens(content);
+  if (tokens <= threshold) return content;
+
+  const bookended = applyBookend(content, BOOKEND_CHARS, BOOKEND_CHARS, tokens);
+
+  if (options.persistResult) {
+    const category = getToolCategory(options.toolName, options.toolCategories) ?? 'ephemeral';
+    try {
+      const path = await options.persistResult(content, {
+        toolName: options.toolName,
+        toolCallId: options.toolCallId,
+        category,
+      });
+      return [
+        `[Result persisted: ${path} (${content.length.toLocaleString()} chars, ~${tokens.toLocaleString()} tokens)]`,
+        '',
+        bookended,
+        '',
+        'Use the Read tool with offset/limit to examine specific sections.',
+      ].join('\n');
+    } catch {
+      // Persist failed; fall through to bookend-only path below.
+    }
+  }
+
+  return [
+    `[Result truncated: ~${tokens.toLocaleString()} tokens exceeded ${threshold.toLocaleString()} token limit]`,
+    '',
+    bookended,
+  ].join('\n');
+}
+
+/**
+ * Process a full tool result (potentially multi-part) through the
+ * persistence interceptor.
+ *
+ * - Iterates the `content` array
+ * - For each `text` part, runs `applyResultPersistence`
+ * - Other part types (e.g., `image`) pass through unchanged
+ * - Returns the same object reference if nothing changed (no allocation)
+ *
+ * Used by `CortexAgent.refreshTools()` at the tool execution boundary.
+ * Exported so the wrapper logic is unit-testable.
+ */
+export async function processToolResult(
+  result: unknown,
+  options: ProcessResultOptions,
+): Promise<unknown> {
+  if (!result || typeof result !== 'object') return result;
+  const asObj = result as Record<string, unknown>;
+  const content = asObj['content'];
+  if (!Array.isArray(content) || content.length === 0) return result;
+
+  let modified = false;
+  const newContent = await Promise.all(
+    content.map(async (part: unknown) => {
+      if (
+        part &&
+        typeof part === 'object' &&
+        (part as Record<string, unknown>)['type'] === 'text' &&
+        typeof (part as Record<string, unknown>)['text'] === 'string'
+      ) {
+        const text = (part as { text: string }).text;
+        const processed = await applyResultPersistence(text, {
+          toolName: options.toolName,
+          toolCallId: options.toolCallId,
+          persistResult: options.persistResult,
+          toolCategories: options.toolCategories,
+          thresholds: options.thresholds,
+        });
+        if (processed !== text) {
+          modified = true;
+          return { ...(part as Record<string, unknown>), text: processed };
+        }
+      }
+      return part;
+    }),
+  );
+
+  if (!modified) return result;
+  return { ...asObj, content: newContent };
+}