@illuma-ai/agents 1.4.0-alpha.6 → 1.5.0

package/src/content/contentAnalyzer.ts

@@ -1,105 +0,0 @@
-/**
- * Utilities for measuring, classifying, and previewing content.
- * Used by the content_tool and MCP auto-caching (Phase 2) to decide
- * when content is "large" and how to summarize it for the LLM.
- */
-
-/**
- * Threshold in characters above which content is considered "large"
- * and should be stored in ContentStore rather than inlined.
- * 50K chars ~ 12.5K tokens ~ 6% of 200K context window.
- */
-const LARGE_CONTENT_THRESHOLD = 50_000;
-
-/** Content size measurements. */
-export interface ContentMeasurement {
-  totalChars: number;
-  totalLines: number;
-  /** True if content exceeds the large-content threshold. */
-  isLarge: boolean;
-}
-
-/** Detected content type. */
-export type ContentType = 'json_array' | 'json_object' | 'text' | 'mixed';
-
-/**
- * Measure content size and determine if it exceeds the large-content threshold.
- * @param text - The content to measure.
- * @returns Measurement with char count, line count, and large flag.
- */
-export function measureContent(text: string): ContentMeasurement {
-  return {
-    totalChars: text.length,
-    totalLines: text.split('\n').length,
-    isLarge: text.length > LARGE_CONTENT_THRESHOLD,
-  };
-}
-
-/**
- * Detect the structural type of content.
- * @param text - The content to classify.
- * @returns The detected type: 'json_array', 'json_object', 'text', or 'mixed'.
- */
-export function detectContentType(text: string): ContentType {
-  const trimmed = text.trim();
-  if (!trimmed) {
-    return 'text';
-  }
-
-  // Fast check: does it look like JSON?
-  if (trimmed[0] === '[' || trimmed[0] === '{') {
-    try {
-      const parsed = JSON.parse(trimmed);
-      if (Array.isArray(parsed)) {
-        return 'json_array';
-      }
-      if (typeof parsed === 'object' && parsed !== null) {
-        return 'json_object';
-      }
-    } catch {
-      // Not valid JSON — might be mixed content
-      if (trimmed[0] === '[' || trimmed[0] === '{') {
-        return 'mixed';
-      }
-    }
-  }
-
-  return 'text';
-}
-
-/**
- * Generate a preview/summary of content for the LLM context.
- * For JSON arrays, shows the first N items. For text, truncates with an ellipsis.
- *
- * @param text - The full content to preview.
- * @param opts - Options controlling preview size.
- * @returns A truncated preview string.
- */
-export function generatePreview(
-  text: string,
-  opts?: { maxItems?: number; maxChars?: number }
-): string {
-  const maxItems = opts?.maxItems ?? 5;
-  const maxChars = opts?.maxChars ?? 2048;
-  const contentType = detectContentType(text);
-
-  if (contentType === 'json_array') {
-    try {
-      const arr = JSON.parse(text.trim()) as unknown[];
-      if (arr.length <= maxItems) {
-        return text.trim();
-      }
-      const preview = arr.slice(0, maxItems);
-      const result = JSON.stringify(preview, null, 2);
-      return `${result}\n... (${arr.length - maxItems} more items, ${arr.length} total)`;
-    } catch {
-      // Fall through to text truncation
-    }
-  }
-
-  if (text.length <= maxChars) {
-    return text;
-  }
-
-  return `${text.substring(0, maxChars)}\n... (truncated, ${text.length} chars total)`;
-}

package/src/content/index.ts

@@ -1,51 +0,0 @@
-/**
- * @illuma-ai/agents/content — per-conversation content + artifact stores.
- *
- * Host-agnostic primitives for keeping large tool / agent output out of
- * the LLM context window:
- *
- *   - {@link ContentStore} — ephemeral per-conversation cache (backed by
- *     any caller-provided {@link Keyv} instance; recommended with
- *     @keyv/redis for multi-instance deployments).
- *   - {@link ArtifactStore} — extends {@link ContentStore} with
- *     durable persistence via caller-provided {@link S3Strategy} and
- *     {@link FileModel} adapters.
- *   - {@link interceptMcpResult} — MCP tool-result auto-caching with
- *     gate semantics (no-op when the agent can't dereference
- *     `content_id`s).
- *   - {@link measureContent} / {@link detectContentType} /
- *     {@link generatePreview} — content classifiers shared by
- *     consumers that need to decide when to store vs inline.
- */
-
-export { ContentStore, CONTENT_TTL_MS } from './ContentStore';
-export {
-  ArtifactStore,
-  sanitizeName,
-  type S3Strategy,
-  type FileModel,
-  type Logger,
-} from './ArtifactStore';
-export {
-  measureContent,
-  detectContentType,
-  generatePreview,
-  type ContentMeasurement,
-  type ContentType,
-} from './contentAnalyzer';
-export type {
-  StoreEntry,
-  StoredEntry,
-  ContentMetadata,
-  ReadResult,
-  ReadAllResult,
-  SearchMatch,
-  EditResult,
-} from './types';
-export {
-  interceptMcpResult,
-  extractUiMarkers,
-  buildCachedResponse,
-  type AutoCacheContext,
-  type AutoCacheResult,
-} from './mcpAutoCache';

package/src/content/mcpAutoCache.ts

@@ -1,185 +0,0 @@
-/**
- * MCP Auto-Caching Interceptor
- *
- * When an MCP tool returns a large text result (>50K chars / ~12.5K tokens),
- * stores it in the caller-provided {@link ContentStore} and returns a
- * compact metadata reference. The LLM then uses a `content_reader` tool
- * (read/search/list/info) to pull relevant pieces of the stored result
- * without burning tokens on the full payload.
- *
- * Gate: callers MUST pass `contentReaderEnabled: true` on the context —
- * otherwise the interceptor returns the original text unchanged, because
- * caching without a reader tool leaves the agent with a content_id it
- * cannot dereference.
- *
- * Design:
- * - Only text content is cached. Images and UI resources pass through.
- * - UI resource markers (\ui{...}) are preserved in the returned text.
- * - Artifacts (second element of the tuple) are never modified.
- * - Cached response is a compact one-liner (~30 tokens) — no preview blob.
- * - If the store write fails, degrades gracefully — returns original text.
- */
-
-import { ContentStore } from './ContentStore';
-import { measureContent, detectContentType } from './contentAnalyzer';
-import type { Logger } from './ArtifactStore';
-import type { ContentMeasurement } from './contentAnalyzer';
-
-/** Context for the auto-cache interceptor. */
-export interface AutoCacheContext {
-  /**
-   * Pre-constructed {@link ContentStore} instance scoped to the current
-   * conversation. Caller owns the underlying cache lifecycle.
-   */
-  store: ContentStore;
-  /** MCP server name (e.g. "sharepoint", "github"). */
-  serverName: string;
-  /** MCP tool name (e.g. "read_file", "search_code"). */
-  toolName: string;
-  /**
-   * Whether the current agent has `content_reader` available. When false,
-   * the interceptor passes the large text through unchanged — caching
-   * without a reader tool leaves the agent with a content_id it cannot
-   * dereference, which is worse than returning the raw text.
-   */
-  contentReaderEnabled: boolean;
-  /**
-   * Optional diagnostic echo. Typically the conversation ID so operators
-   * can correlate the log line with upstream traces.
-   */
-  conversationId?: string;
-  /** Optional logger; defaults to silence. */
-  logger?: Logger;
-}
-
-/** Result of the auto-cache interception. */
-export interface AutoCacheResult {
-  /** The (possibly modified) text content to return to the LLM. */
-  text: string;
-  /** Whether the content was cached. */
-  cached: boolean;
-  /** The content_id if cached. */
-  contentId?: string;
-  /** Content measurement data. */
-  measurement?: ContentMeasurement;
-}
-
-/**
- * Regex to detect UI resource markers: \ui{...}
- * These MUST be preserved in the returned text even after caching.
- */
-const UI_MARKER_REGEX = /\\ui\{[^}]+\}/g;
-
-/**
- * Extract all UI resource markers from text.
- * @param text - The text to scan.
- * @returns Array of marker strings (e.g. ['\\ui{abc123}', '\\ui{def456}'])
- */
-export function extractUiMarkers(text: string): string[] {
-  return text.match(UI_MARKER_REGEX) ?? [];
-}
-
-/**
- * Build a compact metadata reference for the cached content.
- * Keeps token usage minimal (~30 tokens) while giving the LLM all it needs
- * to access the data via content_tool.
- *
- * @param contentId - ContentStore entry ID.
- * @param measurement - Size data.
- * @param toolName - The MCP tool that produced the result.
- * @param uiMarkers - UI markers extracted from the original text.
- */
-export function buildCachedResponse(
-  contentId: string,
-  measurement: ContentMeasurement,
-  toolName: string,
-  uiMarkers: string[]
-): string {
-  const sizeKB = (measurement.totalChars / 1024).toFixed(0);
-  let response = `[Stored: ${toolName} result | ${sizeKB}KB | ${measurement.totalLines} lines | content_id: ${contentId}]\nUse content_reader (action: read or search) with this content_id to access the full result — do NOT re-run the MCP tool.`;
-
-  if (uiMarkers.length > 0) {
-    response += '\n\n' + uiMarkers.join('\n');
-  }
-
-  return response;
-}
-
-/**
- * Core auto-cache interceptor for MCP tool results.
- *
- * If the text exceeds the large-content threshold (50K chars), stores it
- * in ContentStore and returns a preview + content_id. Otherwise passes through.
- *
- * @param text - The text content from the MCP tool result.
- * @param context - MCP tool and conversation context.
- * @returns AutoCacheResult with possibly-modified text and caching metadata.
- */
-export async function interceptMcpResult(
-  text: string,
-  context: AutoCacheContext
-): Promise<AutoCacheResult> {
-  const measurement = measureContent(text);
-  const log = context.logger;
-
-  if (!measurement.isLarge) {
-    return { text, cached: false, measurement };
-  }
-
-  // Gate: caching only makes sense when the agent can read back the stub.
-  // If content_reader is disabled, returning a content_id the agent can't
-  // dereference is strictly worse than returning the full text — the model
-  // would either hallucinate tool calls or flag the result as inaccessible.
-  if (!context.contentReaderEnabled) {
-    log?.debug(
-      `[MCP Auto-Cache] Skipped caching for ${context.serverName}:${context.toolName} — content_reader disabled on this agent`,
-      {
-        totalChars: measurement.totalChars,
-        totalLines: measurement.totalLines,
-        conversationId: context.conversationId,
-      }
-    );
-    return { text, cached: false, measurement };
-  }
-
-  try {
-    const contentType = detectContentType(text);
-
-    const contentId = await context.store.store({
-      name: `${context.toolName} result`,
-      type: contentType === 'text' ? 'text/plain' : 'application/json',
-      content: text,
-      source: `mcp:${context.serverName}`,
-    });
-
-    const uiMarkers = extractUiMarkers(text);
-
-    const replacementText = buildCachedResponse(
-      contentId,
-      measurement,
-      context.toolName,
-      uiMarkers
-    );
-
-    log?.debug(
-      `[MCP Auto-Cache] Cached large result from ${context.serverName}:${context.toolName}`,
-      {
-        contentId,
-        totalChars: measurement.totalChars,
-        totalLines: measurement.totalLines,
-        conversationId: context.conversationId,
-        contentType,
-        uiMarkersPreserved: uiMarkers.length,
-      }
-    );
-
-    return { text: replacementText, cached: true, contentId, measurement };
-  } catch (error) {
-    // PERF: If caching fails, fall through silently — full content goes to LLM
-    log?.warn(
-      `[MCP Auto-Cache] Failed to cache result from ${context.serverName}:${context.toolName}, passing through`,
-      { error: (error as Error).message }
-    );
-    return { text, cached: false, measurement };
-  }
-}

package/src/content/types.ts

@@ -1,82 +0,0 @@
-/**
- * Types for the per-conversation content store.
- * Content entries are ephemeral (Redis-backed, 5 min TTL) and used to keep
- * large tool results out of the LLM context window.
- */
-
-/** Input when storing new content. */
-export interface StoreEntry {
-  /** Human-readable name (e.g. "Q1 Sales Report.xlsx") */
-  name: string;
-  /** MIME-like type: "text/plain", "application/json", "mcp_response", "artifact" */
-  type: string;
-  /** The raw content string */
-  content: string;
-  /** Origin identifier: "mcp:sharepoint", "artifact:msg123", "agent", etc. */
-  source: string;
-  /** Arbitrary extra data attached to the entry */
-  metadata?: Record<string, unknown>;
-}
-
-/** Metadata returned by info() and list() — content is NOT included. */
-export interface ContentMetadata {
-  id: string;
-  name: string;
-  type: string;
-  source: string;
-  totalLines: number;
-  totalChars: number;
-  createdAt: number;
-  /** MongoDB File.file_id after persistence to S3 (set by ArtifactStore) */
-  fileId?: string;
-  /** Owner user ID (set by ArtifactStore for S3 path construction) */
-  userId?: string;
-  /** Conversation scope (set by ArtifactStore for S3 path construction) */
-  conversationId?: string;
-  /** True when the file exists in MongoDB but hasn't been ingested into ContentStore yet */
-  needsIngestion?: boolean;
-}
-
-/** Result of a readLines() call. */
-export interface ReadResult {
-  /** Formatted content with line numbers */
-  content: string;
-  startLine: number;
-  endLine: number;
-  totalLines: number;
-  totalChars: number;
-  /** True if there are more lines beyond endLine */
-  truncated: boolean;
-}
-
-/** Result of a readAll() call — raw content without line-number formatting. */
-export interface ReadAllResult {
-  /** Raw content string (no line-number prefixes) */
-  content: string;
-  totalLines: number;
-  totalChars: number;
-}
-
-/** A single search match within content. */
-export interface SearchMatch {
-  lineNumber: number;
-  content: string;
-}
-
-/** Result of a strReplace() edit. */
-export interface EditResult {
-  success: boolean;
-  /** Human-readable diff snippet */
-  diff: string;
-  /** Line number where the replacement occurred */
-  lineNumber: number;
-  /** Number of lines affected by the edit */
-  linesAffected: number;
-  error?: string;
-}
-
-/** Internal shape stored in Redis for each content entry. */
-export interface StoredEntry {
-  content: string;
-  metadata: ContentMetadata;
-}

package/src/graphs/HandoffRegistry.ts

@@ -1,199 +0,0 @@
-import type { BaseMessage } from '@langchain/core/messages';
-import type * as t from '@/types';
-
-/**
- * Tracks the lifecycle of a spawned handoff child agent.
- */
-export type HandoffRecord = {
-  /** Agent identity (destination agentId) — stable across multiple spawns of the same agent */
-  id: string;
-  /** Unique internal key for this specific spawn (agentId + monotonic counter) */
-  spawnKey: string;
-  /** Display name of the child agent */
-  name: string;
-  /** Task description / instructions passed to child */
-  task: string;
-  /** When the handoff was spawned */
-  spawnedAt: number;
-  /** Current status */
-  status: 'pending' | 'running' | 'completed' | 'failed';
-  /** The background promise executing the child subgraph */
-  promise: Promise<t.BaseGraphState>;
-  /** Resolved result text (populated on completion) */
-  resultText?: string;
-  /** Error message (populated on failure) */
-  error?: string;
-  /** Duration in ms (populated on completion/failure) */
-  durationMs?: number;
-  /** Number of messages in child's output */
-  resultMessageCount?: number;
-};
-
-/**
- * Registry for async handoff execution.
- *
- * Enables the autonomous orchestration pattern:
- * 1. Orchestrator spawns children (non-blocking)
- * 2. Orchestrator stays alive to reason, spawn more, or check status
- * 3. Orchestrator collects results when ready
- *
- * Scoped per MultiAgentGraph instance — each orchestrator graph gets its own registry.
- */
-export class HandoffRegistry {
-  private records: Map<string, HandoffRecord> = new Map();
-  /** Monotonically increasing counter for unique spawn IDs */
-  private spawnCounter = 0;
-
-  /**
-   * Register a spawned handoff child.
-   * The promise runs in the background — not awaited here.
-   * Uses a unique key per spawn so the same agent can be spawned multiple times
-   * across rounds without overwriting prior records.
-   */
-  spawn(params: {
-    id: string;
-    name: string;
-    task: string;
-    promise: Promise<t.BaseGraphState>;
-    extractResult: (messages: BaseMessage[], agentId: string) => string;
-    truncateResult: (text: string, maxChars: number) => string;
-    maxResultChars: number;
-    /** Callback when child completes (for SSE events) */
-    onComplete?: (record: HandoffRecord) => void;
-  }): void {
-    // Unique internal key: agentId + counter to support multiple spawns of same agent.
-    // record.id stays as the agent identity so callers/observability can attribute
-    // results to the agent regardless of which spawn round they came from.
-    const spawnKey = `${params.id}__${this.spawnCounter++}`;
-    const record: HandoffRecord = {
-      id: params.id,
-      spawnKey,
-      name: params.name,
-      task: params.task,
-      spawnedAt: Date.now(),
-      status: 'running',
-      promise: params.promise,
-    };
-
-    // Wire up the promise to update the record on completion
-    params.promise
-      .then((result) => {
-        const resultText = params.extractResult(result.messages, params.id);
-        const truncated = params.truncateResult(
-          resultText,
-          params.maxResultChars
-        );
-        record.status = 'completed';
-        record.resultText = truncated;
-        record.durationMs = Date.now() - record.spawnedAt;
-        record.resultMessageCount = result.messages.length;
-        params.onComplete?.(record);
-      })
-      .catch((err) => {
-        record.status = 'failed';
-        record.error = err instanceof Error ? err.message : String(err);
-        record.durationMs = Date.now() - record.spawnedAt;
-        params.onComplete?.(record);
-      });
-
-    this.records.set(spawnKey, record);
-  }
-
-  /** List all pending (running) handoffs */
-  listPending(): HandoffRecord[] {
-    return Array.from(this.records.values()).filter(
-      (r) => r.status === 'running'
-    );
-  }
-
-  /** List all completed handoffs (not yet collected) */
-  listCompleted(): HandoffRecord[] {
-    return Array.from(this.records.values()).filter(
-      (r) => r.status === 'completed' || r.status === 'failed'
-    );
-  }
-
-  /** List all handoffs regardless of status */
-  listAll(): HandoffRecord[] {
-    return Array.from(this.records.values());
-  }
-
-  /**
-   * Get a handoff record by either its unique spawnKey or by agentId.
-   * - Exact spawnKey match wins (O(1)).
-   * - Falls back to the most recently spawned record for that agentId — matching
-   *   lookups by callers that only know the agent identity, not the spawn round.
-   */
-  get(idOrSpawnKey: string): HandoffRecord | undefined {
-    const direct = this.records.get(idOrSpawnKey);
-    if (direct) return direct;
-    let latest: HandoffRecord | undefined;
-    for (const record of this.records.values()) {
-      if (record.id !== idOrSpawnKey) continue;
-      if (!latest || record.spawnedAt >= latest.spawnedAt) latest = record;
-    }
-    return latest;
-  }
-
-  /** Check if any handoffs are still running */
-  hasPending(): boolean {
-    return this.listPending().length > 0;
-  }
-
-  /**
-   * Wait for ALL pending handoffs to complete and return all records.
-   * Records are NOT auto-cleared — caller removes collected records via remove().
-   */
-  async waitForAll(): Promise<HandoffRecord[]> {
-    const pending = this.listPending();
-    if (pending.length > 0) {
-      await Promise.allSettled(pending.map((r) => r.promise));
-    }
-    const results = this.listAll();
-    return results;
-  }
-
-  /**
-   * Wait for ANY pending handoff to complete.
-   * Returns the newly completed record(s).
-   */
-  async waitForAny(): Promise<HandoffRecord[]> {
-    const pending = this.listPending();
-    if (pending.length === 0) {
-      return this.listCompleted();
-    }
-
-    // Race all pending promises — at least one will resolve
-    await Promise.race(
-      pending.map((r) => r.promise.then(() => r).catch(() => r))
-    );
-
-    // Small yield to let promise handlers update records
-    await new Promise((resolve) => setTimeout(resolve, 0));
-
-    return this.listCompleted();
-  }
-
-  /**
-   * Remove record(s) by spawnKey or agentId.
-   * - Exact spawnKey match removes only that record.
-   * - agentId match removes ALL records for that agent (covers callers that
-   *   want to forget everything tied to a given agent).
-   */
-  remove(idOrSpawnKey: string): void {
-    if (this.records.delete(idOrSpawnKey)) return;
-    for (const [key, record] of this.records) {
-      if (record.id === idOrSpawnKey) this.records.delete(key);
-    }
-  }
-
-  /** Clear all records (for cleanup between graph invocations) */
-  clear(): void {
-    this.records.clear();
-  }
-
-  /** Number of total tracked handoffs */
-  get size(): number {
-    return this.records.size;
-  }
-}