@animus-labs/cortex 0.2.0

package/src/tools/shared/pdf-extractor.ts

@@ -0,0 +1,290 @@
+/**
+ * PDF text extraction.
+ *
+ * Wraps `unpdf` (pure-ESM, zero native deps) behind a narrow, well-typed
+ * boundary so the Read tool never touches pdfjs directly. Swapping the
+ * backend later is a one-file change.
+ *
+ * Responsibilities:
+ *   - Parse the caller's `pages` spec and clamp it to the document and
+ *     the per-call page cap.
+ *   - Extract per-page text.
+ *   - Detect "no extractable text" (scanned / image-only PDFs) and
+ *     return a structured signal rather than silently-empty output.
+ *   - Render the extracted text with `[Page N]` markers so the caller
+ *     can line-number it exactly like any other file content.
+ *
+ * Pure-ish: does no filesystem I/O. Callers are expected to have
+ * already loaded the PDF bytes.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface PdfExtractionRequest {
+  /** PDF bytes. Accepts a Node Buffer or any Uint8Array. */
+  data: Buffer | Uint8Array;
+  /**
+   * Page spec: `"N"`, `"N-M"`, or undefined. When undefined, extracts
+   * the first `maxPages` pages starting at page 1.
+   */
+  pagesSpec?: string | undefined;
+  /** Upper bound on how many pages may be extracted in one call. */
+  maxPages?: number;
+}
+
+export interface PdfExtractionOk {
+  kind: 'ok';
+  totalPages: number;
+  /** First page extracted (1-based, inclusive). */
+  firstPage: number;
+  /** Last page extracted (1-based, inclusive). */
+  lastPage: number;
+  /** Per-page text. `pages[i].pageNumber` is 1-based. */
+  pages: Array<{ pageNumber: number; text: string }>;
+  /**
+   * Full rendered text with `[Page N]` markers separating pages, ready
+   * to be handed to the same line-numbering pipeline Read uses for
+   * plain text files.
+   */
+  rendered: string;
+}
+
+export interface PdfExtractionEmpty {
+  kind: 'empty';
+  totalPages: number;
+  firstPage: number;
+  lastPage: number;
+  message: string;
+}
+
+export interface PdfExtractionInvalidRange {
+  kind: 'invalid-range';
+  totalPages: number;
+  message: string;
+}
+
+export interface PdfExtractionError {
+  kind: 'error';
+  message: string;
+}
+
+export type PdfExtractionResult =
+  | PdfExtractionOk
+  | PdfExtractionEmpty
+  | PdfExtractionInvalidRange
+  | PdfExtractionError;
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Default cap on pages extracted per call. Matches the advertised
+ * schema default for Read's `pages` param ("max 20 pages per request").
+ */
+export const DEFAULT_MAX_PAGES = 20;
+
+/**
+ * Total-text length below which we treat the document as image-based.
+ * 20 characters allows for a stray page number or watermark without
+ * pretending we extracted meaningful content.
+ */
+const EMPTY_TEXT_THRESHOLD = 20;
+
+// ---------------------------------------------------------------------------
+// Pages-spec parsing (pure, unit-testable)
+// ---------------------------------------------------------------------------
+
+export type PagesSpecResult =
+  | { ok: true; first: number; last: number }
+  | { ok: false; message: string };
+
+/**
+ * Parse a pages-spec string against a document's page count and the
+ * per-call cap. Enforces:
+ *   - Format: `"N"` or `"N-M"` (base 10, whitespace tolerant)
+ *   - 1 <= first <= last <= totalPages
+ *   - (last - first + 1) <= maxPages
+ *
+ * Returns `{ ok: false }` with an actionable message on any failure.
+ */
+export function parsePagesSpec(
+  spec: string,
+  totalPages: number,
+  maxPages: number,
+): PagesSpecResult {
+  const trimmed = spec.trim();
+  const rangeMatch = /^(\d+)-(\d+)$/u.exec(trimmed);
+  const singleMatch = /^(\d+)$/u.exec(trimmed);
+
+  let first: number;
+  let last: number;
+  if (rangeMatch) {
+    first = Number.parseInt(rangeMatch[1]!, 10);
+    last = Number.parseInt(rangeMatch[2]!, 10);
+  } else if (singleMatch) {
+    first = Number.parseInt(singleMatch[1]!, 10);
+    last = first;
+  } else {
+    return {
+      ok: false,
+      message: `Invalid pages spec "${spec}". Use "N" or "N-M" (e.g. "1-5", "3").`,
+    };
+  }
+
+  if (first < 1) {
+    return { ok: false, message: `Page numbers are 1-based; got first page ${first}.` };
+  }
+  if (last < first) {
+    return {
+      ok: false,
+      message: `Invalid pages spec "${spec}": last page (${last}) is before first page (${first}).`,
+    };
+  }
+  if (last > totalPages) {
+    return {
+      ok: false,
+      message: `Pages spec "${spec}" exceeds document (has ${totalPages} page${totalPages === 1 ? '' : 's'}).`,
+    };
+  }
+  const count = last - first + 1;
+  if (count > maxPages) {
+    return {
+      ok: false,
+      message: `Pages spec "${spec}" requests ${count} pages; the per-call limit is ${maxPages}. Narrow the range.`,
+    };
+  }
+
+  return { ok: true, first, last };
+}
+
+// ---------------------------------------------------------------------------
+// Buffer normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert input bytes to a fresh, owned `Uint8Array`.
+ *
+ * `unpdf` rejects `Buffer` inputs outright ("Please provide binary data
+ * as `Uint8Array`, rather than `Buffer`"), and its PDF.js worker path
+ * may transfer the backing buffer during postMessage — leaving a shared
+ * view detached for subsequent calls. Making a full copy here keeps
+ * the caller's buffer usable and makes repeat extractions on the same
+ * bytes safe across tests and sessions.
+ */
+function toUint8Array(data: Buffer | Uint8Array): Uint8Array {
+  return new Uint8Array(data);
+}
+
+// ---------------------------------------------------------------------------
+// Extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract text from a PDF buffer. Never throws — all failure modes are
+ * returned as structured results so the caller can render them as
+ * tool-content messages.
+ */
+export async function extractPdfText(
+  req: PdfExtractionRequest,
+): Promise<PdfExtractionResult> {
+  const maxPages = req.maxPages ?? DEFAULT_MAX_PAGES;
+  const bytes = toUint8Array(req.data);
+
+  let extractResult: { totalPages: number; text: string[] };
+  try {
+    const { extractText } = await import('unpdf');
+    const raw = await extractText(bytes, { mergePages: false });
+    extractResult = {
+      totalPages: raw.totalPages,
+      text: Array.isArray(raw.text) ? raw.text : [raw.text],
+    };
+  } catch (err: unknown) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      kind: 'error',
+      message: `Failed to parse PDF: ${msg}`,
+    };
+  }
+
+  const { totalPages, text: allPages } = extractResult;
+
+  if (totalPages === 0) {
+    return {
+      kind: 'empty',
+      totalPages: 0,
+      firstPage: 0,
+      lastPage: 0,
+      message: 'PDF contains no pages.',
+    };
+  }
+
+  // Resolve the page range.
+  let first: number;
+  let last: number;
+  if (req.pagesSpec !== undefined) {
+    const parsed = parsePagesSpec(req.pagesSpec, totalPages, maxPages);
+    if (!parsed.ok) {
+      return { kind: 'invalid-range', totalPages, message: parsed.message };
+    }
+    first = parsed.first;
+    last = parsed.last;
+  } else {
+    first = 1;
+    last = Math.min(maxPages, totalPages);
+  }
+
+  const pages: Array<{ pageNumber: number; text: string }> = [];
+  for (let pageNumber = first; pageNumber <= last; pageNumber++) {
+    const raw = allPages[pageNumber - 1] ?? '';
+    pages.push({ pageNumber, text: raw });
+  }
+
+  const totalLen = pages.reduce((n, p) => n + p.text.trim().length, 0);
+  if (totalLen < EMPTY_TEXT_THRESHOLD) {
+    return {
+      kind: 'empty',
+      totalPages,
+      firstPage: first,
+      lastPage: last,
+      message:
+        totalPages > 0 && totalLen === 0
+          ? 'PDF has no extractable text (likely scanned or image-only). Use an OCR tool to process it.'
+          : 'PDF yielded almost no extractable text (likely scanned or image-heavy). Use an OCR tool for full content.',
+    };
+  }
+
+  const rendered = renderPages(pages, first, last, totalPages);
+
+  return {
+    kind: 'ok',
+    totalPages,
+    firstPage: first,
+    lastPage: last,
+    pages,
+    rendered,
+  };
+}
+
+/**
+ * Render the per-page text into a single string with `[Page N]`
+ * markers. A leading summary line is included so the model knows how
+ * many pages the document has and which subset it's seeing.
+ */
+function renderPages(
+  pages: Array<{ pageNumber: number; text: string }>,
+  firstPage: number,
+  lastPage: number,
+  totalPages: number,
+): string {
+  const header =
+    firstPage === 1 && lastPage === totalPages
+      ? `[PDF: ${totalPages} page${totalPages === 1 ? '' : 's'}]`
+      : `[PDF: showing pages ${firstPage}-${lastPage} of ${totalPages}]`;
+  const body = pages
+    .map((p) => `[Page ${p.pageNumber}]\n${p.text.trim()}`)
+    .join('\n\n');
+  return `${header}\n\n${body}\n`;
+}

package/src/tools/shared/read-registry.ts

@@ -0,0 +1,93 @@
+/**
+ * Loop-scoped file read tracking.
+ *
+ * Shared by the Read, Write, and Edit tools to enforce
+ * the read-before-write/edit contract. Tracks which files
+ * have been read during the current agentic loop, along with
+ * metadata (mtime, offset, limit) for file-unchanged dedup.
+ *
+ * Created once per CortexAgent and cleared at the start
+ * of each agentic loop via clear().
+ */
+
+import * as path from 'node:path';
+
+export interface ReadState {
+  /** File mtime at time of read (ms since epoch). */
+  timestamp: number;
+  /** 1-based offset used for the read (undefined = full read). */
+  offset?: number;
+  /** Line limit used for the read (undefined = default/full). */
+  limit?: number;
+  /**
+   * SHA-256 hex digest of the raw file bytes at the time of read.
+   * Populated only for non-truncated, full reads; used as a fallback
+   * on mtime mismatch to allow writes when the on-disk bytes are
+   * actually unchanged (e.g. a formatter or cloud-sync tool touched
+   * the mtime without modifying content).
+   */
+  contentHash?: string;
+}
+
+export class ReadRegistry {
+  private readonly entries = new Map<string, ReadState>();
+
+  /**
+   * Mark a file as read with metadata for dedup.
+   * The path is normalized to an absolute, platform-canonical form.
+   */
+  markRead(filePath: string, state?: ReadState): void {
+    this.entries.set(
+      this.normalize(filePath),
+      state ?? { timestamp: Date.now() },
+    );
+  }
+
+  /**
+   * Check whether a file has been read in the current agentic loop.
+   */
+  hasBeenRead(filePath: string): boolean {
+    return this.entries.has(this.normalize(filePath));
+  }
+
+  /**
+   * Get the read state for a file, or undefined if not read.
+   */
+  getState(filePath: string): ReadState | undefined {
+    return this.entries.get(this.normalize(filePath));
+  }
+
+  /**
+   * Invalidate a single file's read state.
+   * Called when the on-disk mtime diverges from the recorded read
+   * state (external modification), forcing a fresh Read before
+   * the next mutation. Successful Edit/Write calls instead call
+   * markRead() with the new mtime, since the agent's own mutation
+   * is authoritative knowledge of current file contents.
+   */
+  invalidate(filePath: string): void {
+    this.entries.delete(this.normalize(filePath));
+  }
+
+  /**
+   * Clear all read tracking. Called at the start of each agentic loop.
+   */
+  clear(): void {
+    this.entries.clear();
+  }
+
+  /**
+   * Get the number of tracked files (for diagnostics).
+   */
+  get size(): number {
+    return this.entries.size;
+  }
+
+  /**
+   * Normalize a file path for consistent comparison.
+   * Resolves to absolute and normalizes separators.
+   */
+  private normalize(filePath: string): string {
+    return path.resolve(filePath);
+  }
+}

package/src/tools/shared/safe-env.ts

@@ -0,0 +1,82 @@
+/**
+ * Shared environment sanitization for child processes.
+ *
+ * Used by both the Bash tool (safety.ts) and MCP client (mcp-client.ts)
+ * to strip dangerous environment variables before spawning subprocesses.
+ */
+
+// ---------------------------------------------------------------------------
+// Blocked variables
+// ---------------------------------------------------------------------------
+
+const BLOCKED_ENV_PREFIXES = ['LD_', 'DYLD_', 'BASH_FUNC_'];
+
+const BLOCKED_ENV_VARS = new Set([
+  // Runtime loaders
+  'NODE_OPTIONS', 'NODE_PATH',
+  'PYTHONPATH', 'PYTHONHOME',
+  'PERL5LIB', 'PERL5OPT',
+  'RUBYLIB', 'RUBYOPT',
+  // Shell startup injection
+  'BASH_ENV', 'ENV', 'SHELLOPTS', 'PS4', 'IFS', 'PROMPT_COMMAND', 'ZDOTDIR',
+  // Git execution
+  'GIT_EXTERNAL_DIFF', 'GIT_EXEC_PATH', 'GIT_SSH_COMMAND',
+  // Security-sensitive
+  'SSLKEYLOGFILE', 'GCONV_PATH', 'OPENSSL_CONF', 'CURL_HOME', 'WGETRC',
+]);
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a safe environment for child processes by stripping dangerous variables.
+ *
+ * @param parentEnv - The source environment (typically process.env or a consumer-supplied map)
+ * @param marker - Optional context marker added as CORTEX_SHELL. Pass undefined to skip.
+ * @param overrides - Optional key-value pairs merged ON TOP of the sanitized env, bypassing
+ *   the blocklist. Used for consumer-set variables that must propagate (e.g., macOS dock
+ *   icon suppression vars like DYLD_INSERT_LIBRARIES).
+ * @returns A new object with dangerous variables removed and overrides applied
+ */
+export function buildSafeEnv(
+  parentEnv: NodeJS.ProcessEnv | Record<string, string>,
+  marker?: string | undefined,
+  overrides?: Record<string, string> | undefined,
+): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  for (const [key, value] of Object.entries(parentEnv)) {
+    if (value === undefined) continue;
+
+    // Check exact match
+    if (BLOCKED_ENV_VARS.has(key)) continue;
+
+    // Check prefix match
+    let blocked = false;
+    for (const prefix of BLOCKED_ENV_PREFIXES) {
+      if (key.startsWith(prefix)) {
+        blocked = true;
+        break;
+      }
+    }
+    if (blocked) continue;
+
+    env[key] = value;
+  }
+
+  if (marker !== undefined) {
+    env['CORTEX_SHELL'] = marker;
+  }
+
+  // Merge overrides ON TOP of the sanitized env, bypassing the blocklist.
+  // This allows consumers to restore specific blocked variables (e.g.,
+  // DYLD_INSERT_LIBRARIES for macOS dock icon suppression).
+  if (overrides) {
+    for (const [key, value] of Object.entries(overrides)) {
+      env[key] = value;
+    }
+  }
+
+  return env;
+}

package/src/tools/sub-agent.ts

@@ -0,0 +1,171 @@
+/**
+ * SubAgent tool: spawn independent cortex-based sub-agents for delegated work.
+ *
+ * Supports foreground (blocking) and background (async) execution modes.
+ * Each sub-agent is an independent CortexAgent with its own message array
+ * and empty context slots.
+ *
+ * The SubAgent tool is ALWAYS excluded from child agents to prevent
+ * recursive spawning.
+ *
+ * References:
+ *   - docs/cortex/tools/sub-agent.md
+ *   - docs/cortex/plans/phase-4-sub-agents-and-skills.md
+ */
+
+import { Type, type Static } from 'typebox';
+
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+
+export const SubAgentParams = Type.Object({
+  instructions: Type.String({
+    description: 'What the sub-agent should do. This becomes the sub-agent\'s initial prompt.',
+  }),
+  tools: Type.Optional(Type.Array(Type.String(), {
+    description: 'Tool names to make available. Default: inherits parent\'s registered tools.',
+  })),
+  systemPrompt: Type.Optional(Type.String({
+    description: 'Custom system prompt. Default: inherits parent\'s full system prompt.',
+  })),
+  maxTurns: Type.Optional(Type.Number({
+    description: 'Maximum LLM turns. Default: inherits parent\'s budget guard config.',
+  })),
+  maxCost: Type.Optional(Type.Number({
+    description: 'Maximum cost in USD. Default: inherits parent\'s budget guard config.',
+  })),
+  background: Type.Optional(Type.Boolean({
+    description: 'Run asynchronously. Default: false (blocks until complete).',
+  })),
+});
+
+export type SubAgentParamsType = Static<typeof SubAgentParams>;
+
+// ---------------------------------------------------------------------------
+// Details type (for UI/logs)
+// ---------------------------------------------------------------------------
+
+export interface SubAgentDetails {
+  taskId: string;
+  background: boolean;
+  status: string;
+  durationMs: number | null;
+  turns: number | null;
+  cost: number | null;
+  /** Model ID used by the sub-agent (inherited from parent). */
+  modelId?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+/**
+ * Configuration passed to the SubAgent tool factory.
+ * The CortexAgent provides all of these at tool registration time.
+ */
+export interface SubAgentToolConfig {
+  /**
+   * Spawn a sub-agent and run it. Returns the result when complete.
+   * The factory function handles CortexAgent creation, budget guard
+   * inheritance, tool filtering, and lifecycle management.
+   */
+  spawnSubAgent: (params: SubAgentParamsType) => Promise<{
+    taskId: string;
+    output: string;
+    status: string;
+    usage: { turns: number; cost: number; durationMs: number };
+  }>;
+
+  /**
+   * Spawn a background sub-agent. Returns the task ID immediately.
+   */
+  spawnBackgroundSubAgent: (params: SubAgentParamsType) => Promise<{
+    taskId: string;
+  }>;
+
+  /**
+   * Check if another sub-agent can be spawned.
+   */
+  canSpawn: () => boolean;
+
+  /**
+   * Get concurrency info for error messages.
+   */
+  getConcurrencyInfo: () => { active: number; limit: number };
+
+  /**
+   * Get the model ID for the child agent.
+   * Child agents inherit the parent's primary model.
+   */
+  getModelId: () => string;
+}
+
+// ---------------------------------------------------------------------------
+// Tool name constant
+// ---------------------------------------------------------------------------
+
+export const SUB_AGENT_TOOL_NAME = 'SubAgent';
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Create the SubAgent tool.
+ *
+ * Returns a Cortex-native tool. CortexAgent adapts it to pi-agent-core's
+ * execute signature when synchronizing the tool inventory.
+ */
+export function createSubAgentTool(config: SubAgentToolConfig): {
+  name: string;
+  description: string;
+  parameters: typeof SubAgentParams;
+  execute: (args: unknown) => Promise<unknown>;
+} {
+  return {
+    name: SUB_AGENT_TOOL_NAME,
+    description: `Spawn a sub-agent to handle a delegated task independently. Use for tasks that are complex, long-running, or can proceed in parallel with your main work.
+
+Foreground mode (default): Blocks until the sub-agent completes and returns its result directly. Use for quick, focused tasks where you need the result to continue.
+
+Background mode (background: true): Returns a task ID immediately. The sub-agent runs independently. You will be notified when it completes. Use for long-running research, analysis, or multi-step work.
+
+Sub-agents are independent: they have their own conversation, do not share your context, and cannot spawn further sub-agents. Give them clear, self-contained instructions.`,
+
+    parameters: SubAgentParams,
+
+    execute: async (args: unknown): Promise<unknown> => {
+      const params = args as SubAgentParamsType;
+
+      // Check concurrency limit
+      if (!config.canSpawn()) {
+        const info = config.getConcurrencyInfo();
+        return `Cannot spawn sub-agent: concurrency limit reached (${info.active}/${info.limit} active). Wait for a running sub-agent to complete or cancel one to free a slot.`;
+      }
+
+      // Background mode: spawn and return immediately
+      if (params.background) {
+        const { taskId } = await config.spawnBackgroundSubAgent(params);
+        return `Sub-agent spawned in background. Task ID: ${taskId}\nYou will be notified when it completes. Continue with other work.`;
+      }
+
+      // Foreground mode: block until complete
+      const result = await config.spawnSubAgent(params);
+
+      // Format result for the parent agent
+      const statusLine = result.status === 'completed'
+        ? 'Sub-agent completed successfully.'
+        : `Sub-agent finished with status: ${result.status}`;
+
+      const usageLine = `(${result.usage.turns} turns, $${result.usage.cost.toFixed(4)}, ${(result.usage.durationMs / 1000).toFixed(1)}s)`;
+
+      if (result.output) {
+        return `${statusLine} ${usageLine}\n\n${result.output}`;
+      }
+
+      return `${statusLine} ${usageLine}\n\nNo output was produced.`;
+    },
+  };
+}