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

package/dist/types/content/ArtifactStore.d.ts

@@ -0,0 +1,223 @@
+import type Keyv from 'keyv';
+import { ContentStore } from './ContentStore';
+import type { StoreEntry, StoredEntry, ContentMetadata, EditResult, ReadResult, ReadAllResult, SearchMatch } from './types';
+/**
+ * Minimal logger surface. Callers inject any winston/pino/console-like
+ * logger that honors the four level methods; defaults to a no-op so the
+ * library runs without a configured logger.
+ */
+export interface Logger {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/**
+ * Callback interface for S3 operations.
+ * Injected at construction so ArtifactStore stays host-agnostic — the
+ * consumer wires this to its own S3 strategy / presigner.
+ */
+export interface S3Strategy {
+    /** Upload a buffer to S3, return the stored filepath (signed URL or key). */
+    saveBuffer(params: {
+        userId: string;
+        buffer: Buffer;
+        fileName: string;
+        basePath: string;
+    }): Promise<string>;
+    /** Download file content from S3 as a readable stream. */
+    getFileStream(filePath: string): Promise<NodeJS.ReadableStream>;
+    /** Delete a file from S3. Requires userId for ownership validation. */
+    deleteFile(userId: string, filePath: string): Promise<void>;
+}
+/**
+ * Callback interface for MongoDB File model operations.
+ * Injected to keep ArtifactStore decoupled from Mongoose models.
+ */
+export interface FileModel {
+    /** Create or upsert a File document. */
+    createFile(data: Record<string, unknown>, disableTTL: boolean): Promise<Record<string, unknown>>;
+    /** Find a single File by filter. */
+    findFile(filter: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    /** Find multiple Files by filter. */
+    findFiles(filter: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    /** Update a File document (must include file_id). */
+    updateFile(data: Record<string, unknown>): Promise<Record<string, unknown> | null>;
+    /** Delete a File by file_id. */
+    deleteFile(fileId: string): Promise<Record<string, unknown> | null>;
+    /**
+     * Get the file_ids linked to a conversation via the Conversation.files array.
+     * Returns an empty array if the conversation is not found or has no files.
+     * This is the primary source of truth for "which files belong to this conversation".
+     */
+    getConversationFileIds(conversationId: string): Promise<string[]>;
+    /**
+     * Link file_ids to a conversation via $addToSet on Conversation.files.
+     * Idempotent — calling with already-linked file_ids is a no-op.
+     * Used after creating a File record to ensure it appears in "Files in Context".
+     */
+    addFilesToConversation(conversationId: string, fileIds: string[]): Promise<void>;
+}
+/**
+ * Sanitize a filename for safe S3 key usage.
+ * Replaces non-alphanumeric characters (except . _ - /) with underscores.
+ */
+export declare function sanitizeName(name: string): string;
+/**
+ * File-backed artifact store extending ContentStore with S3 persistence.
+ *
+ * Every write immediately persists to Redis (fast cache) AND S3 (permanent store).
+ * S3 writes are fire-and-forget async — the agent gets an instant response from Redis.
+ * On Redis cache miss, content is transparently restored from S3 via MongoDB lookup.
+ *
+ * Key structure (consistent across all layers):
+ * - Redis:   `CONTENT_STORE::{conversationId}::{contentId}`
+ * - S3:      `artifacts/{conversationId}/{userId}/{contentId}__{name}`
+ * - MongoDB: `file_id: "artifact-{contentId}"`, `metadata.contentId: "{contentId}"`
+ *
+ * @example
+ * ```ts
+ * import Keyv from 'keyv';
+ * import { ArtifactStore, CONTENT_TTL_MS } from '@illuma-ai/agents/content';
+ *
+ * const cache = new Keyv({ namespace: `content-store::${conversationId}`, ttl: CONTENT_TTL_MS });
+ * const store = new ArtifactStore(cache, conversationId, userId, s3Strategy, fileModel, logger);
+ * const id = await store.store({ name: 'App.tsx', type: 'text/x-typescript', content: code, source: 'agent' });
+ * // Content is in the cache immediately; S3 + the injected FileModel persist in background.
+ * const result = await store.readLines(id, 1, 50);
+ * ```
+ */
+export declare class ArtifactStore extends ContentStore {
+    protected conversationId: string;
+    protected userId: string;
+    protected s3: S3Strategy;
+    protected fileModel: FileModel;
+    protected logger: Logger;
+    constructor(cache: Keyv, conversationId: string, userId: string, s3: S3Strategy, fileModel: FileModel, logger?: Logger);
+    /** File ID prefix for MongoDB file_id. Override in subclasses. */
+    protected getFileIdPrefix(): string;
+    /** Context label stored on MongoDB File records. Override in subclasses. */
+    protected getContextLabel(): string;
+    /** S3 base path prefix. Override in subclasses. */
+    protected getS3BasePath(): string;
+    /** Build S3 file name. Override in subclasses. */
+    protected getS3FileName(contentId: string, name: string): string;
+    /** Build the canonical file_id for a content entry. */
+    protected buildFileId(contentId: string): string;
+    /**
+     * Store new content in Redis and persist to S3 + MongoDB in background.
+     * Returns immediately after Redis write — agent doesn't wait for S3.
+     *
+     * @param entry - The content to store.
+     * @returns The generated content ID.
+     */
+    store(entry: StoreEntry): Promise<string>;
+    /**
+     * Overwrite content for an existing entry. Updates Redis + syncs to S3.
+     *
+     * @param contentId - The content entry ID.
+     * @param content - New content to write.
+     * @throws If content ID is not found in Redis or S3.
+     */
+    write(contentId: string, content: string): Promise<void>;
+    /**
+     * Surgical string replacement. Updates Redis + syncs to S3.
+     *
+     * @param contentId - The content entry ID.
+     * @param oldStr - Exact string to find.
+     * @param newStr - Replacement string.
+     * @returns Edit result with diff and affected line info.
+     */
+    strReplace(contentId: string, oldStr: string, newStr: string): Promise<EditResult>;
+    /**
+     * Read lines with S3 fallback. If Redis has expired, loads from S3 first.
+     *
+     * @param contentId - The content entry ID.
+     * @param startLine - First line to read (1-based).
+     * @param endLine - Last line to read (inclusive).
+     * @returns Read result or null if not found in any layer.
+     */
+    readLines(contentId: string, startLine?: number, endLine?: number): Promise<ReadResult | null>;
+    /**
+     * Read full content with S3 fallback. If Redis has expired, loads from S3 first.
+     * No line cap — returns raw content for frontend display (e.g., CodeViz).
+     *
+     * @param contentId - The content entry ID.
+     * @returns Raw content with total line/char counts, or null if not found in any layer.
+     */
+    readAll(contentId: string): Promise<ReadAllResult | null>;
+    /**
+     * Search with S3 fallback. If Redis has expired, loads from S3 first.
+     *
+     * @param contentId - The content entry ID.
+     * @param pattern - Text or regex pattern to match.
+     * @param maxResults - Maximum matches to return.
+     * @returns Array of matches or null if not found.
+     */
+    search(contentId: string, pattern: string, maxResults?: number): Promise<SearchMatch[] | null>;
+    /**
+     * Get metadata with S3 fallback.
+     *
+     * @param contentId - The content entry ID.
+     * @returns Metadata or null if not found in any layer.
+     */
+    info(contentId: string): Promise<ContentMetadata | null>;
+    /**
+     * Delete an artifact from all layers: Redis + S3 + MongoDB.
+     *
+     * @param contentId - The content entry ID.
+     */
+    deleteFile(contentId: string): Promise<void>;
+    /**
+     * List all files in this conversation. Merges Redis index with MongoDB File
+     * records found via `Conversation.files` (the single source of truth).
+     *
+     * Query flow:
+     * 1. Redis index — fast cache of recently-accessed content entries (in-memory, no DB hit)
+     * 2. Conversation.files — canonical file_id list via `getConversationFileIds()`
+     *    SCALE: Single indexed `findOne` on `{ conversationId }` — O(1)
+     * 3. Backward compat fallback — `File.find({ conversationId, user })` for pre-migration
+     *    data not yet in `Conversation.files`. Uses index `{ user, conversationId, updatedAt }`.
+     *    Can be removed once all File records are migrated.
+     * 4. Batch fetch — `File.find({ file_id: { $in: mergedIds }, user })` to hydrate full
+     *    File documents. Uses index `{ file_id, user }`.
+     *
+     * Deduplication: Redis entries win — if a contentId is already in Redis, the MongoDB
+     * record is skipped. Non-artifact files are keyed by `file:{file_id}` to avoid dupes.
+     *
+     * @returns Array of metadata for all files in this conversation.
+     */
+    listFiles(): Promise<ContentMetadata[]>;
+    /**
+     * Persist a new content entry to S3 and create a MongoDB File record.
+     * Called in background after Redis store — agent doesn't wait for this.
+     *
+     * @param contentId - The content entry ID.
+     * @param entry - The original store entry with content and metadata.
+     */
+    protected persistToS3(contentId: string, entry: StoreEntry): Promise<void>;
+    /**
+     * Sync updated Redis content to S3 (overwrite same key).
+     * Called in background after write/edit operations.
+     *
+     * @param contentId - The content entry ID to sync.
+     */
+    protected syncToS3(contentId: string): Promise<void>;
+    /**
+     * Restore content from S3 into Redis on cache miss.
+     * Looks up the MongoDB File record to find the S3 path, downloads content,
+     * and re-populates the Redis cache with the same key structure.
+     *
+     * @param contentId - The content entry ID to restore.
+     * @returns The restored StoredEntry, or null if not found in S3/MongoDB.
+     */
+    protected restoreFromS3(contentId: string): Promise<StoredEntry | null>;
+    /**
+     * Ensure content is loaded into Redis. If not in Redis, attempt S3 restore.
+     * Used before write/edit operations that need content to be present.
+     *
+     * @param contentId - The content entry ID.
+     * @throws If content is not found in Redis or S3.
+     */
+    protected ensureLoaded(contentId: string): Promise<void>;
+}

package/dist/types/content/ContentStore.d.ts

@@ -0,0 +1,140 @@
+import type Keyv from 'keyv';
+import type { StoreEntry, StoredEntry, ContentMetadata, ReadResult, ReadAllResult, SearchMatch, EditResult } from './types';
+/**
+ * Default 3-minute TTL for ephemeral content entries. Resets on every
+ * access. Kept short to reduce cache-backing memory pressure — callers
+ * that persist to durable storage (see {@link ArtifactStore}) rely on
+ * lazy restore from the durable backend on cache miss.
+ *
+ * Exported so consumers can construct their injected {@link Keyv}
+ * instance with a matching TTL without hard-coding the number.
+ */
+export declare const CONTENT_TTL_MS = 180000;
+/**
+ * Per-conversation content store backed by a caller-provided {@link Keyv}
+ * cache (typically Keyv + @keyv/redis, with in-memory fallback).
+ *
+ * Stores large content (MCP results, artifacts, agent-generated text)
+ * outside the LLM context window. Entries inherit the TTL configured on
+ * the injected {@link Keyv} instance — {@link CONTENT_TTL_MS} is the
+ * recommended default.
+ *
+ * The caller is responsible for namespacing the Keyv instance per
+ * conversation so content_ids don't collide across threads.
+ *
+ * @example
+ * ```ts
+ * import Keyv from 'keyv';
+ * const cache = new Keyv({ namespace: `content-store::${conversationId}`, ttl: CONTENT_TTL_MS });
+ * const store = new ContentStore(cache);
+ * const id = await store.store({ name: 'report.csv', type: 'text/plain', content: csv, source: 'mcp:sharepoint' });
+ * const result = await store.readLines(id, 1, 50);
+ * ```
+ */
+export declare class ContentStore {
+    protected cache: Keyv;
+    protected indexKey: string;
+    /**
+     * @param cache - A pre-namespaced {@link Keyv} instance. The store
+     *   writes both content entries and a per-store `_index` key, so
+     *   callers MUST namespace the Keyv per conversation to avoid
+     *   cross-thread collisions.
+     */
+    constructor(cache: Keyv);
+    /**
+     * Store new content and return a content ID.
+     * @param entry - The content to store with metadata.
+     * @returns The generated content ID.
+     */
+    store(entry: StoreEntry): Promise<string>;
+    /**
+     * Get metadata for a content entry without loading the full content.
+     * @param contentId - The content entry ID.
+     * @returns Metadata or null if not found.
+     */
+    info(contentId: string): Promise<ContentMetadata | null>;
+    /**
+     * Read lines from a content entry with optional range.
+     * Lines are 1-based and inclusive. Returns formatted content with line numbers.
+     *
+     * @param contentId - The content entry ID.
+     * @param startLine - First line to read (1-based, default 1).
+     * @param endLine - Last line to read (inclusive, default startLine + DEFAULT_READ_LINES - 1).
+     * @returns Read result with formatted content and range info, or null if not found.
+     */
+    readLines(contentId: string, startLine?: number, endLine?: number): Promise<ReadResult | null>;
+    /**
+     * Read the full content of an entry without line-number formatting or line caps.
+     * Used by API endpoints that serve complete content to the frontend (e.g., CodeViz).
+     * Unlike readLines(), this has no MAX_READ_LINES cap and returns raw content.
+     *
+     * @param contentId - The content entry ID.
+     * @returns Raw content with total line/char counts, or null if not found.
+     */
+    readAll(contentId: string): Promise<ReadAllResult | null>;
+    /**
+     * Search for a pattern within a content entry.
+     * Supports plain text matching and regex patterns.
+     *
+     * @param contentId - The content entry ID.
+     * @param pattern - Text or regex pattern to match.
+     * @param maxResults - Maximum matches to return (default MAX_SEARCH_RESULTS).
+     * @returns Array of matches with line numbers, or null if content not found.
+     */
+    search(contentId: string, pattern: string, maxResults?: number): Promise<SearchMatch[] | null>;
+    /**
+     * Surgical string replacement within a content entry.
+     * Fails if old_str is not found or appears more than once (ambiguous).
+     *
+     * Uses layered matching: exact → line-number-stripped → CRLF-normalized → trailing-whitespace-trimmed.
+     * On failure, returns diagnostic context showing nearby content to help the agent self-correct.
+     *
+     * @param contentId - The content entry ID.
+     * @param oldStr - Exact string to find.
+     * @param newStr - Replacement string.
+     * @returns Edit result with diff and affected line info.
+     */
+    strReplace(contentId: string, oldStr: string, newStr: string): Promise<EditResult>;
+    /**
+     * Overwrite content for an existing entry, preserving its name/source/type.
+     * @param contentId - The content entry ID.
+     * @param content - New content to write.
+     * @throws If content ID is not found.
+     */
+    write(contentId: string, content: string): Promise<void>;
+    /**
+     * List all content entries in this conversation's store.
+     * @returns Array of metadata for all entries.
+     */
+    list(): Promise<ContentMetadata[]>;
+    /**
+     * Get the raw content string for a content entry, without line-number formatting.
+     * Resets TTL on access. Used by code edit wrapper to retrieve stored code for execution.
+     *
+     * @param contentId - The content entry ID.
+     * @returns Raw content string, or null if not found/expired.
+     */
+    getRawContent(contentId: string): Promise<string | null>;
+    /**
+     * Delete a content entry.
+     * @param contentId - The content entry ID.
+     */
+    delete(contentId: string): Promise<void>;
+    /**
+     * Reset TTL on both a content entry and the index.
+     * Called on every access to keep active content alive.
+     * @param contentId - The content entry ID.
+     * @param stored - The stored entry to re-set (resets TTL via Keyv).
+     */
+    protected touchEntry(contentId: string, stored: StoredEntry): Promise<void>;
+    /**
+     * Retrieve the full stored entry (content + metadata) from Redis.
+     * Returns null if the entry has expired or doesn't exist.
+     */
+    protected getStored(contentId: string): Promise<StoredEntry | null>;
+    /**
+     * Retrieve the conversation's content index from Redis.
+     * The index maps content IDs to their metadata.
+     */
+    protected getIndex(): Promise<Record<string, ContentMetadata>>;
+}

package/dist/types/content/contentAnalyzer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+/** 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 declare function measureContent(text: string): ContentMeasurement;
+/**
+ * Detect the structural type of content.
+ * @param text - The content to classify.
+ * @returns The detected type: 'json_array', 'json_object', 'text', or 'mixed'.
+ */
+export declare function detectContentType(text: string): ContentType;
+/**
+ * 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 declare function generatePreview(text: string, opts?: {
+    maxItems?: number;
+    maxChars?: number;
+}): string;

package/dist/types/content/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @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/dist/types/content/mcpAutoCache.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 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 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;
+}
+/**
+ * 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 declare function extractUiMarkers(text: string): string[];
+/**
+ * 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 declare function buildCachedResponse(contentId: string, measurement: ContentMeasurement, toolName: string, uiMarkers: string[]): string;
+/**
+ * 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 declare function interceptMcpResult(text: string, context: AutoCacheContext): Promise<AutoCacheResult>;

package/dist/types/content/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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/dist/types/index.d.ts

@@ -20,6 +20,11 @@ export * from './tools/fileSearch';
 export * from './tools/artifacts';
 export * from './tools/proxyTool';
 export * from './providers';
+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';
 export * from './memory';
 export { MEMORY_FLUSH_SYSTEM_PROMPT } from './prompts/memoryFlushPrompt';
 export { shouldFlushMemory, runMemoryFlush, } from './graphs/phases/memoryFlushPhase';

package/dist/types/providers/tools-server/ToolsServerCapabilityProvider.d.ts

@@ -29,6 +29,19 @@ 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>>;
 }
 export declare class ToolsServerCapabilityProvider implements CapabilityProvider {
     private readonly config;
@@ -37,6 +50,7 @@ export declare class ToolsServerCapabilityProvider implements CapabilityProvider
     private readonly manifestPath;
     private readonly executePath;
     private readonly cache;
+    private readonly getExecuteAuthHeaders?;
     constructor(config: ToolsServerConfig);
     fetchManifest(filter?: CapabilityFilter): Promise<Capability[]>;
     createRunnables(capabilities: Capability[], credentials: CredentialMap): Promise<StructuredToolInterface[]>;

package/dist/types/tools/proxyTool.d.ts

@@ -38,6 +38,13 @@ 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 {
     capabilityName: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/agents",
-  "version": "1.4.0-alpha.4",
+  "version": "1.4.0-alpha.6",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -24,6 +24,11 @@
       "import": "./dist/esm/providers/a2a/A2ACapabilityProvider.mjs",
       "require": "./dist/cjs/providers/a2a/A2ACapabilityProvider.cjs",
       "types": "./dist/types/providers/a2a/A2ACapabilityProvider.d.ts"
+    },
+    "./content": {
+      "import": "./dist/esm/content/index.mjs",
+      "require": "./dist/cjs/content/index.cjs",
+      "types": "./dist/types/content/index.d.ts"
     }
   },
   "type": "module",