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

package/src/content/contentAnalyzer.ts

@@ -0,0 +1,105 @@
+/**
+ * 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

@@ -0,0 +1,51 @@
+/**
+ * @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

@@ -0,0 +1,185 @@
+/**
+ * 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

@@ -0,0 +1,82 @@
+/**
+ * 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/index.ts

@@ -33,6 +33,25 @@ export * from './tools/proxyTool';
 /* Capability Providers */
 export * from './providers';
 
+/* Content / artifact stores.
+ * Prefer the subpath import `@illuma-ai/agents/content` — this barrel
+ * only re-exports the store classes to avoid symbol collisions with
+ * existing top-level exports (e.g., Logger from tools/search,
+ * ContentType from elsewhere). */
+export { ContentStore, CONTENT_TTL_MS } from './content/ContentStore';
+export { ArtifactStore, sanitizeName } from './content/ArtifactStore';
+export type {
+  S3Strategy,
+  FileModel,
+  Logger as ContentLogger,
+} from './content/ArtifactStore';
+export {
+  interceptMcpResult,
+  extractUiMarkers,
+  buildCachedResponse,
+} from './content/mcpAutoCache';
+export type { AutoCacheContext, AutoCacheResult } from './content/mcpAutoCache';
+
 /* Memory (storage + factory) */
 export * from './memory';
 

package/src/providers/__tests__/ToolsServerCapabilityProvider.test.ts

@@ -203,4 +203,69 @@ describe('ToolsServerCapabilityProvider.createRunnables', () => {
       /missing API key/
     );
   });
+
+  it('getExecuteAuthHeaders is invoked per call and forwarded as HTTP headers', async () => {
+    const client = {
+      get: jest.fn().mockResolvedValue({ status: 200, data: manifestFixture }),
+      post: jest.fn().mockResolvedValue({
+        status: 200,
+        data: {
+          success: true,
+          result: 'ok',
+          timing: { durationMs: 1 },
+        },
+      }),
+      defaults: { baseURL: 'http://stub', headers: {} },
+    };
+
+    let mintCount = 0;
+    const p = new ToolsServerCapabilityProvider({
+      baseUrl: 'http://x',
+      apiKey: 'k',
+      client: client as unknown as ReturnType<typeof axios.create>,
+      getExecuteAuthHeaders: async () => {
+        mintCount += 1;
+        return { Authorization: `Bearer TOKEN-${mintCount}` };
+      },
+    });
+    const caps = await p.fetchManifest();
+    const [wikipedia] = await p.createRunnables(
+      caps.filter((c) => c.name === 'wikipedia'),
+      {}
+    );
+
+    await wikipedia.invoke({ query: 'a' });
+    await wikipedia.invoke({ query: 'b' });
+
+    // Two invocations → two mints (fresh token each call)
+    expect(mintCount).toBe(2);
+
+    // Each POST includes the Authorization header from the mint
+    const firstCall = (client.post as jest.Mock).mock.calls[0];
+    const secondCall = (client.post as jest.Mock).mock.calls[1];
+    expect(firstCall[2]?.headers).toEqual({ Authorization: 'Bearer TOKEN-1' });
+    expect(secondCall[2]?.headers).toEqual({ Authorization: 'Bearer TOKEN-2' });
+  });
+
+  it('getExecuteAuthHeaders is NOT called during manifest fetch (service-to-service)', async () => {
+    const client = {
+      get: jest.fn().mockResolvedValue({ status: 200, data: manifestFixture }),
+      post: jest.fn(),
+      defaults: { baseURL: 'http://stub', headers: {} },
+    };
+
+    const authBuilder = jest
+      .fn()
+      .mockReturnValue({ Authorization: 'Bearer X' });
+    const p = new ToolsServerCapabilityProvider({
+      baseUrl: 'http://x',
+      apiKey: 'k',
+      client: client as unknown as ReturnType<typeof axios.create>,
+      getExecuteAuthHeaders: authBuilder,
+    });
+
+    await p.fetchManifest();
+    // Manifest fetch is service-to-service — no per-user auth headers
+    expect(authBuilder).not.toHaveBeenCalled();
+  });
 });

package/src/providers/tools-server/ToolsServerCapabilityProvider.ts

@@ -48,6 +48,21 @@ export interface ToolsServerConfig {
   client?: AxiosInstance;
   /** Optional proxy override (defaults to process.env.PROXY). */
   proxy?: string | null;
+  /**
+   * Optional per-request auth header builder — invoked on every tool
+   * invocation (NOT on the manifest fetch, which is service-to-service).
+   * When provided, the returned headers are merged into the `/execute`
+   * request so the host can pass user-scoped identity (e.g.,
+   * `Authorization: Bearer <jwt>`) that tools-server verifies for
+   * admin-gated tools.
+   *
+   * Typical host wiring: mint a short-lived JWT per call carrying the
+   * authenticated user's `{ userId, role }` claims; tools-server's
+   * `TOOLS_SERVER_JWT_SECRET` validates.
+   */
+  getExecuteAuthHeaders?: () =>
+    | Record<string, string>
+    | Promise<Record<string, string>>;
 }
 
 /**
@@ -91,6 +106,9 @@ export class ToolsServerCapabilityProvider implements CapabilityProvider {
   private readonly manifestPath: string;
   private readonly executePath: string;
   private readonly cache: ManifestCache;
+  private readonly getExecuteAuthHeaders?: () =>
+    | Record<string, string>
+    | Promise<Record<string, string>>;
 
   constructor(private readonly config: ToolsServerConfig) {
     const {
@@ -102,6 +120,7 @@ export class ToolsServerCapabilityProvider implements CapabilityProvider {
       manifestTtlMs = 60_000,
       client,
       proxy,
+      getExecuteAuthHeaders,
     } = config;
 
     if (!baseUrl) {
@@ -115,6 +134,7 @@ export class ToolsServerCapabilityProvider implements CapabilityProvider {
     this.manifestPath = manifestPath;
     this.executePath = executePath;
     this.cache = new ManifestCache({ ttlMs: manifestTtlMs });
+    this.getExecuteAuthHeaders = getExecuteAuthHeaders;
 
     if (client) {
       this.client = client;
@@ -184,6 +204,7 @@ export class ToolsServerCapabilityProvider implements CapabilityProvider {
       buildProxyTool(cap, credentials, {
         client: this.client,
         executePath: this.executePath,
+        getAuthHeaders: this.getExecuteAuthHeaders,
       })
     );
   }

package/src/tools/proxyTool.ts

@@ -40,6 +40,15 @@ export interface ProxyToolOptions {
    * telemetry, debug logging. Errors in the hook are swallowed.
    */
   onExecute?: (ctx: ExecuteCallbackContext) => void;
+  /**
+   * Optional per-invocation auth header builder. Called on every tool
+   * invocation before POSTing; returned headers are merged into the
+   * request alongside the base client's headers. Typical use: pass a
+   * freshly minted per-user JWT for admin-gated tools.
+   */
+  getAuthHeaders?: () =>
+    | Record<string, string>
+    | Promise<Record<string, string>>;
 }
 
 export interface ExecuteCallbackContext {
@@ -61,7 +70,12 @@ export function buildProxyTool(
   credentials: CredentialMap,
   options: ProxyToolOptions
 ): StructuredToolInterface {
-  const { client, executePath = '/execute/:name', onExecute } = options;
+  const {
+    client,
+    executePath = '/execute/:name',
+    onExecute,
+    getAuthHeaders,
+  } = options;
   const url = executePath.replace(':name', encodeURIComponent(capability.name));
 
   return tool(
@@ -76,10 +90,16 @@ export function buildProxyTool(
           `${debugPrefix} invoking — inputKeys=${input && typeof input === 'object' ? Object.keys(input as object).length : 0}`
         );
 
-        const res = await client.post<ExecuteResponse>(url, {
-          input,
-          credentials,
-        });
+        const extraHeaders = getAuthHeaders
+          ? await getAuthHeaders()
+          : undefined;
+        const res = await client.post<ExecuteResponse>(
+          url,
+          { input, credentials },
+          extraHeaders && Object.keys(extraHeaders).length > 0
+            ? { headers: extraHeaders }
+            : undefined
+        );
 
         const durationMs = Date.now() - startMs;