@illuma-ai/agents 1.1.4 → 1.1.5

package/dist/esm/main.mjs

@@ -40,6 +40,7 @@ export { extractFinishReason, isMaxTokensFinish } from './utils/toolCallContinua
 export { buildMultiDocHintContent, buildPostPruneNote, detectDocuments, hasTaskTool, shouldInjectMultiDocHint } from './utils/contextPressure.mjs';
 export { ToolDiscoveryCache } from './utils/toolDiscoveryCache.mjs';
 export { applyCalibration, createPruneCalibration, updatePruneCalibration } from './utils/pruneCalibration.mjs';
+export { FILE_MANIFEST_PREFIX, buildFileManifestBlock } from './utils/fileManifest.mjs';
 export { CustomOpenAIClient } from './llm/openai/index.mjs';
 export { ChatOpenRouter } from './llm/openrouter/index.mjs';
 export { getChatModelClass, llmProviders } from './llm/providers.mjs';

package/dist/esm/main.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"main.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"main.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/types/graph.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"graph.mjs","sources":["../../../src/types/graph.ts"],"sourcesContent":["// src/types/graph.ts\nimport type {\n  START,\n  StateType,\n  UpdateType,\n  StateGraph,\n  StateGraphArgs,\n  StateDefinition,\n  CompiledStateGraph,\n  BinaryOperatorAggregate,\n} from '@langchain/langgraph';\nimport type { BindToolsInput } from '@langchain/core/language_models/chat_models';\nimport type {\n  BaseMessage,\n  AIMessageChunk,\n  SystemMessage,\n} from '@langchain/core/messages';\nimport type { RunnableConfig, Runnable } from '@langchain/core/runnables';\nimport type { ChatGenerationChunk } from '@langchain/core/outputs';\nimport type { GoogleAIToolType } from '@langchain/google-common';\nimport type {\n  ToolMap,\n  ToolEndEvent,\n  GenericTool,\n  LCTool,\n  ToolApprovalConfig,\n} from '@/types/tools';\nimport type { Providers, Callback, GraphNodeKeys } from '@/common';\nimport type { StandardGraph, MultiAgentGraph } from '@/graphs';\nimport type { ClientOptions } from '@/types/llm';\nimport type {\n  RunStep,\n  RunStepDeltaEvent,\n  MessageDeltaEvent,\n  ReasoningDeltaEvent,\n} from '@/types/stream';\nimport type { TokenCounter } from '@/types/run';\n\n/** Interface for bound model with stream and invoke methods */\nexport interface ChatModel {\n  stream?: (\n    messages: BaseMessage[],\n    config?: RunnableConfig\n  ) => Promise<AsyncIterable<AIMessageChunk>>;\n  invoke: (\n    messages: BaseMessage[],\n    config?: RunnableConfig\n  ) => Promise<AIMessageChunk>;\n}\n\nexport type GraphNode = GraphNodeKeys | typeof START;\nexport type ClientCallback<T extends unknown[]> = (\n  graph: StandardGraph,\n  ...args: T\n) => void;\n\nexport type ClientCallbacks = {\n  [Callback.TOOL_ERROR]?: ClientCallback<[Error, string]>;\n  [Callback.TOOL_START]?: ClientCallback<unknown[]>;\n  [Callback.TOOL_END]?: ClientCallback<unknown[]>;\n};\n\nexport type SystemCallbacks = {\n  [K in keyof ClientCallbacks]: ClientCallbacks[K] extends ClientCallback<\n    infer Args\n  >\n    ? (...args: Args) => void\n    : never;\n};\n\nexport type BaseGraphState = {\n  messages: BaseMessage[];\n  /**\n   * Structured response when using structured output mode.\n   * Contains the validated JSON response conforming to the configured schema.\n   */\n  structuredResponse?: Record<string, unknown>;\n};\n\nexport type MultiAgentGraphState = BaseGraphState & {\n  agentMessages?: BaseMessage[];\n};\n\nexport type IState = BaseGraphState;\n\nexport interface EventHandler {\n  handle(\n    event: string,\n    data:\n      | StreamEventData\n      | ModelEndData\n      | RunStep\n      | RunStepDeltaEvent\n      | MessageDeltaEvent\n      | ReasoningDeltaEvent\n      | { result: ToolEndEvent },\n    metadata?: Record<string, unknown>,\n    graph?: StandardGraph | MultiAgentGraph\n  ): void | Promise<void>;\n}\n\nexport type GraphStateChannels<T extends BaseGraphState> =\n  StateGraphArgs<T>['channels'];\n\nexport type Workflow<\n  T extends BaseGraphState = BaseGraphState,\n  U extends Partial<T> = Partial<T>,\n  N extends string = string,\n> = StateGraph<T, U, N>;\n\nexport type CompiledWorkflow<\n  T extends BaseGraphState = BaseGraphState,\n  U extends Partial<T> = Partial<T>,\n  N extends string = string,\n> = CompiledStateGraph<T, U, N>;\n\nexport type CompiledStateWorkflow = CompiledStateGraph<\n  StateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  UpdateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  string,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition\n>;\n\nexport type CompiledMultiAgentWorkflow = CompiledStateGraph<\n  StateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  UpdateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  string,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition\n>;\n\nexport type CompiledAgentWorfklow = CompiledStateGraph<\n  {\n    messages: BaseMessage[];\n  },\n  {\n    messages?: BaseMessage[] | undefined;\n  },\n  '__start__' | `agent=${string}` | `tools=${string}`,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition,\n  {\n    [x: `agent=${string}`]: Partial<BaseGraphState>;\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    [x: `tools=${string}`]: any;\n  }\n>;\n\nexport type SystemRunnable =\n  | Runnable<\n      BaseMessage[],\n      (BaseMessage | SystemMessage)[],\n      RunnableConfig<Record<string, unknown>>\n    >\n  | undefined;\n\n/**\n * Optional compile options passed to workflow.compile().\n * These are intentionally untyped to avoid coupling to library internals.\n */\nexport type CompileOptions = {\n  // A checkpointer instance (e.g., MemorySaver, SQL saver)\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  checkpointer?: any;\n  interruptBefore?: string[];\n  interruptAfter?: string[];\n  /**\n   * Human-in-the-loop tool approval configuration.\n   * When set, tools matching the policy will trigger an interrupt()\n   * before execution, pausing the graph for human approval.\n   * Requires a checkpointer to be set for interrupt/resume to work.\n   */\n  toolApprovalConfig?: ToolApprovalConfig;\n};\n\nexport type EventStreamCallbackHandlerInput =\n  Parameters<CompiledWorkflow['streamEvents']>[2] extends Omit<\n    infer T,\n    'autoClose'\n  >\n    ? T\n    : never;\n\nexport type StreamChunk =\n  | (ChatGenerationChunk & {\n      message: AIMessageChunk;\n    })\n  | AIMessageChunk;\n\n/**\n * Data associated with a StreamEvent.\n */\nexport type StreamEventData = {\n  /**\n   * The input passed to the runnable that generated the event.\n   * Inputs will sometimes be available at the *START* of the runnable, and\n   * sometimes at the *END* of the runnable.\n   * If a runnable is able to stream its inputs, then its input by definition\n   * won't be known until the *END* of the runnable when it has finished streaming\n   * its inputs.\n   */\n  input?: unknown;\n  /**\n   * The output of the runnable that generated the event.\n   * Outputs will only be available at the *END* of the runnable.\n   * For most runnables, this field can be inferred from the `chunk` field,\n   * though there might be some exceptions for special cased runnables (e.g., like\n   * chat models), which may return more information.\n   */\n  output?: unknown;\n  /**\n   * A streaming chunk from the output that generated the event.\n   * chunks support addition in general, and adding them up should result\n   * in the output of the runnable that generated the event.\n   */\n  chunk?: StreamChunk;\n  /**\n   * Runnable config for invoking other runnables within handlers.\n   */\n  config?: RunnableConfig;\n  /**\n   * Custom result from the runnable that generated the event.\n   */\n  result?: unknown;\n  /**\n   * Custom field to indicate the event was manually emitted, and may have been handled already\n   */\n  emitted?: boolean;\n};\n\n/**\n * A streaming event.\n *\n * Schema of a streaming event which is produced from the streamEvents method.\n */\nexport type StreamEvent = {\n  /**\n   * Event names are of the format: on_[runnable_type]_(start|stream|end).\n   *\n   * Runnable types are one of:\n   * - llm - used by non chat models\n   * - chat_model - used by chat models\n   * - prompt --  e.g., ChatPromptTemplate\n   * - tool -- LangChain tools\n   * - chain - most Runnables are of this type\n   *\n   * Further, the events are categorized as one of:\n   * - start - when the runnable starts\n   * - stream - when the runnable is streaming\n   * - end - when the runnable ends\n   *\n   * start, stream and end are associated with slightly different `data` payload.\n   *\n   * Please see the documentation for `EventData` for more details.\n   */\n  event: string;\n  /** The name of the runnable that generated the event. */\n  name: string;\n  /**\n   * An randomly generated ID to keep track of the execution of the given runnable.\n   *\n   * Each child runnable that gets invoked as part of the execution of a parent runnable\n   * is assigned its own unique ID.\n   */\n  run_id: string;\n  /**\n   * Tags associated with the runnable that generated this event.\n   * Tags are always inherited from parent runnables.\n   */\n  tags?: string[];\n  /** Metadata associated with the runnable that generated this event. */\n  metadata: Record<string, unknown>;\n  /**\n   * Event data.\n   *\n   * The contents of the event data depend on the event type.\n   */\n  data: StreamEventData;\n};\n\nexport type GraphConfig = {\n  provider: string;\n  thread_id?: string;\n  run_id?: string;\n};\n\nexport type PartMetadata = {\n  progress?: number;\n  asset_pointer?: string;\n  status?: string;\n  action?: boolean;\n  output?: string;\n};\n\nexport type ModelEndData =\n  | (StreamEventData & { output: AIMessageChunk | undefined })\n  | undefined;\nexport type GraphTools = GenericTool[] | BindToolsInput[] | GoogleAIToolType[];\nexport type StandardGraphInput = {\n  runId?: string;\n  signal?: AbortSignal;\n  agents: AgentInputs[];\n  tokenCounter?: TokenCounter;\n  indexTokenCountMap?: Record<string, number>;\n};\n\nexport type GraphEdge = {\n  /** Agent ID, use a list for multiple sources */\n  from: string | string[];\n  /** Agent ID, use a list for multiple destinations */\n  to: string | string[];\n  description?: string;\n  /** Can return boolean or specific destination(s) */\n  condition?: (state: BaseGraphState) => boolean | string | string[];\n  /** EdgeType.HANDOFF creates tools for dynamic routing, EdgeType.DIRECT creates direct edges with parallel execution */\n  edgeType?: import('@/common').EdgeType;\n  /**\n   * For direct edges: Optional prompt to add when transitioning through this edge.\n   * String prompts can include variables like {results} which will be replaced with\n   * messages from startIndex onwards. When {results} is used, excludeResults defaults to true.\n   *\n   * For handoff edges: Description for the input parameter that the handoff tool accepts,\n   * allowing the supervisor to pass specific instructions/context to the transferred agent.\n   */\n  prompt?:\n    | string\n    | ((\n        messages: BaseMessage[],\n        runStartIndex: number\n      ) => string | Promise<string> | undefined);\n  /**\n   * When true, excludes messages from startIndex when adding prompt.\n   * Automatically set to true when {results} variable is used in prompt.\n   */\n  excludeResults?: boolean;\n  /**\n   * For handoff edges: Customizes the parameter name for the handoff input.\n   * Defaults to \"instructions\" if not specified.\n   * Only applies when prompt is provided for handoff edges.\n   */\n  promptKey?: string;\n};\n\nexport type MultiAgentGraphInput = StandardGraphInput & {\n  edges: GraphEdge[];\n};\n\n/**\n * Structured output mode determines how the agent returns structured data.\n * - 'tool': Uses tool calling to return structured output (works with all tool-calling models)\n * - 'provider': Uses provider-native structured output via LangChain's jsonMode (OpenAI, Anthropic, etc.)\n * - 'native': Uses provider's constrained decoding API directly for guaranteed schema compliance\n *   (Anthropic output_config.format, OpenAI response_format.json_schema). Falls back to 'tool' for unsupported providers.\n * - 'auto': Automatically selects the best strategy — 'native' for supported providers, 'tool' for others\n */\nexport type StructuredOutputMode = 'tool' | 'provider' | 'native' | 'auto';\n\n/**\n * Resolved method used internally after mode resolution.\n * Maps to LangChain's withStructuredOutput method parameter plus our native path.\n */\nexport type ResolvedStructuredOutputMethod =\n  | 'functionCalling'\n  | 'jsonMode'\n  | 'jsonSchema'\n  | 'native'\n  | undefined;\n\n/**\n * Error thrown when the model refuses to produce structured output due to safety policies.\n */\nexport class StructuredOutputRefusalError extends Error {\n  constructor(public refusalText: string) {\n    super(`Model refused to produce structured output: ${refusalText}`);\n    this.name = 'StructuredOutputRefusalError';\n  }\n}\n\n/**\n * Error thrown when the structured output response was truncated due to max_tokens.\n */\nexport class StructuredOutputTruncatedError extends Error {\n  constructor(public stopReason: string) {\n    super(\n      `Structured output was truncated (stop_reason: ${stopReason}). ` +\n        'Increase max_tokens to allow the full JSON response to be generated.'\n    );\n    this.name = 'StructuredOutputTruncatedError';\n  }\n}\n\n/**\n * Configuration for structured JSON output from agents.\n * When configured, the agent will return a validated JSON response\n * instead of streaming text.\n */\nexport interface StructuredOutputConfig {\n  /**\n   * JSON Schema defining the output structure.\n   * The model will be forced to return data conforming to this schema.\n   */\n  schema: Record<string, unknown>;\n  /**\n   * Name for the structured output format (used in tool mode).\n   * @default 'StructuredResponse'\n   */\n  name?: string;\n  /**\n   * Description of what the structured output represents.\n   * Helps the model understand the expected format.\n   */\n  description?: string;\n  /**\n   * Output mode strategy.\n   * @default 'auto'\n   */\n  mode?: StructuredOutputMode;\n  /**\n   * Enable strict schema validation.\n   * When true, the response must exactly match the schema.\n   * @default true\n   */\n  strict?: boolean;\n  /**\n   * Error handling configuration.\n   * - true: Auto-retry on validation errors (default)\n   * - false: Throw error on validation failure\n   * - string: Custom error message for retry\n   */\n  handleErrors?: boolean | string;\n  /**\n   * Maximum number of retry attempts on validation failure.\n   * @default 2\n   */\n  maxRetries?: number;\n  /**\n   * Include the raw AI message along with structured response.\n   * Useful for debugging.\n   * @default false\n   */\n  includeRaw?: boolean;\n}\n\n/**\n * Database/API structured output format (snake_case with enabled flag).\n * This matches the format stored in MongoDB and sent from frontends.\n */\nexport interface StructuredOutputInput {\n  /** Whether structured output is enabled */\n  enabled?: boolean;\n  /** JSON Schema defining the expected response structure */\n  schema?: Record<string, unknown>;\n  /** Name identifier for the structured output */\n  name?: string;\n  /** Description of what the structured output represents */\n  description?: string;\n  /** Mode for structured output: 'tool' | 'provider' | 'native' | 'auto' */\n  mode?: StructuredOutputMode;\n  /** Whether to enforce strict schema validation */\n  strict?: boolean;\n}\n\n/**\n * Trigger strategy for when summarization should activate.\n * - 'contextPercentage': Trigger when context utilization exceeds a threshold percentage\n * - 'messageCount': Trigger when pruned message count exceeds a threshold\n * - 'tokenThreshold': Trigger when total token count exceeds a raw threshold\n */\nexport type SummarizationTriggerType =\n  | 'contextPercentage'\n  | 'messageCount'\n  | 'tokenThreshold';\n\n/**\n * Configuration for summarization behavior within the agent pipeline.\n * All fields are optional — sensible defaults are provided via constants.\n *\n * @see SUMMARIZATION_CONTEXT_THRESHOLD, SUMMARIZATION_RESERVE_RATIO, PRUNING_EMA_ALPHA\n */\nexport interface SummarizationConfig {\n  /**\n   * Strategy for when summarization triggers.\n   * @default 'contextPercentage'\n   */\n  triggerType?: SummarizationTriggerType;\n\n  /**\n   * Threshold value interpreted based on triggerType:\n   * - contextPercentage: 0-100 (percentage of context window)\n   * - messageCount: absolute count of messages pruned\n   * - tokenThreshold: absolute token count\n   * @default 80 (for contextPercentage)\n   */\n  triggerThreshold?: number;\n\n  /**\n   * Fraction of context window (0-1) reserved for recent messages.\n   * Prevents over-pruning by ensuring at least this fraction of the\n   * context budget is preserved as recent conversation history.\n   * @default 0.3\n   */\n  reserveRatio?: number;\n\n  /**\n   * Whether context pruning is enabled (can be disabled for debugging).\n   * @default true\n   */\n  contextPruning?: boolean;\n\n  /**\n   * Initial summary text to seed across runs.\n   * Different from persistedSummary: this is provided by the caller as a\n   * cross-conversation seed (e.g., agent personality or recurring context),\n   * while persistedSummary is loaded from the conversation's own history.\n   */\n  initialSummary?: string;\n}\n\n/**\n * Runtime state for EMA-based pruning calibration.\n * Maintained across iterations within a single run to smooth pruning decisions.\n */\nexport interface PruneCalibrationState {\n  /** Current EMA calibration ratio */\n  ratio: number;\n  /** Number of calibration updates applied */\n  iterations: number;\n}\n\nexport interface AgentInputs {\n  agentId: string;\n  /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */\n  name?: string;\n  /** Description of what this agent does (used to enrich handoff tool descriptions). */\n  description?: string;\n  toolEnd?: boolean;\n  toolMap?: ToolMap;\n  tools?: GraphTools;\n  provider: Providers;\n  instructions?: string;\n  streamBuffer?: number;\n  maxContextTokens?: number;\n  clientOptions?: ClientOptions;\n  additional_instructions?: string;\n  reasoningKey?: 'reasoning_content' | 'reasoning';\n  /** Format content blocks as strings (for legacy compatibility i.e. Ollama/Azure Serverless) */\n  useLegacyContent?: boolean;\n  /**\n   * Tool definitions for all tools, including deferred and programmatic.\n   * Used for tool search and programmatic tool calling.\n   * Maps tool name to LCTool definition.\n   */\n  toolRegistry?: Map<string, LCTool>;\n  /**\n   * Dynamic context that changes per-request (e.g., current time, user info).\n   * This is injected as a user message rather than system prompt to preserve cache.\n   * Keeping this separate from instructions ensures the system message stays static\n   * and can be cached by Bedrock/Anthropic prompt caching.\n   */\n  dynamicContext?: string;\n  /**\n   * Structured output configuration (camelCase).\n   * When set, disables streaming and returns a validated JSON response\n   * conforming to the specified schema.\n   */\n  structuredOutput?: StructuredOutputConfig;\n  /**\n   * Structured output configuration (snake_case - database/API format).\n   * Alternative to structuredOutput for compatibility with MongoDB/frontend.\n   * Uses an `enabled` flag to control activation.\n   * @deprecated Use structuredOutput instead when possible\n   */\n  structured_output?: StructuredOutputInput;\n  /**\n   * Serializable tool definitions for event-driven execution.\n   * When provided, ToolNode operates in event-driven mode, dispatching\n   * ON_TOOL_EXECUTE events instead of invoking tools directly.\n   */\n  toolDefinitions?: LCTool[];\n  /**\n   * Tool names discovered from previous conversation history.\n   * These tools will be pre-marked as discovered so they're included\n   * in tool binding without requiring tool_search.\n   */\n  discoveredTools?: string[];\n  /**\n   * Optional callback for summarizing messages that were pruned from context.\n   * When provided, discarded messages are summarized by the caller (e.g., Ranger)\n   * using a cheap LLM call, and the summary is prepended to the context.\n   */\n  summarizeCallback?: (\n    messagesToRefine: import('@langchain/core/messages').BaseMessage[]\n  ) => Promise<string | undefined>;\n  /**\n   * Pre-existing summary text loaded from persistent storage (MongoDB/Redis).\n   * When provided, this summary is injected into the initial message context\n   * so the agent has prior conversation history even on new turns.\n   * Set by Ranger's SummaryStore when resuming a conversation.\n   */\n  persistedSummary?: string;\n  /**\n   * Summarization configuration controlling trigger strategy, reserve ratio,\n   * and EMA calibration for pruning. When omitted, sensible defaults apply.\n   * @see SummarizationConfig\n   */\n  summarizationConfig?: SummarizationConfig;\n}\n"],"names":[],"mappings":"AA4YA;;AAEG;AACG,MAAO,4BAA6B,SAAQ,KAAK,CAAA;AAClC,IAAA,WAAA;AAAnB,IAAA,WAAA,CAAmB,WAAmB,EAAA;AACpC,QAAA,KAAK,CAAC,CAAA,4CAAA,EAA+C,WAAW,CAAA,CAAE,CAAC;QADlD,IAAA,CAAA,WAAW,GAAX,WAAW;AAE5B,QAAA,IAAI,CAAC,IAAI,GAAG,8BAA8B;IAC5C;AACD;AAED;;AAEG;AACG,MAAO,8BAA+B,SAAQ,KAAK,CAAA;AACpC,IAAA,UAAA;AAAnB,IAAA,WAAA,CAAmB,UAAkB,EAAA;QACnC,KAAK,CACH,CAAA,8CAAA,EAAiD,UAAU,CAAA,GAAA,CAAK;AAC9D,YAAA,sEAAsE,CACzE;QAJgB,IAAA,CAAA,UAAU,GAAV,UAAU;AAK3B,QAAA,IAAI,CAAC,IAAI,GAAG,gCAAgC;IAC9C;AACD;;;;"}
+{"version":3,"file":"graph.mjs","sources":["../../../src/types/graph.ts"],"sourcesContent":["// src/types/graph.ts\nimport type {\n  START,\n  StateType,\n  UpdateType,\n  StateGraph,\n  StateGraphArgs,\n  StateDefinition,\n  CompiledStateGraph,\n  BinaryOperatorAggregate,\n} from '@langchain/langgraph';\nimport type { BindToolsInput } from '@langchain/core/language_models/chat_models';\nimport type {\n  BaseMessage,\n  AIMessageChunk,\n  SystemMessage,\n} from '@langchain/core/messages';\nimport type { RunnableConfig, Runnable } from '@langchain/core/runnables';\nimport type { ChatGenerationChunk } from '@langchain/core/outputs';\nimport type { GoogleAIToolType } from '@langchain/google-common';\nimport type {\n  ToolMap,\n  ToolEndEvent,\n  GenericTool,\n  LCTool,\n  ToolApprovalConfig,\n} from '@/types/tools';\nimport type { Providers, Callback, GraphNodeKeys } from '@/common';\nimport type { StandardGraph, MultiAgentGraph } from '@/graphs';\nimport type { ClientOptions } from '@/types/llm';\nimport type {\n  RunStep,\n  RunStepDeltaEvent,\n  MessageDeltaEvent,\n  ReasoningDeltaEvent,\n} from '@/types/stream';\nimport type { TokenCounter } from '@/types/run';\n\n/** Interface for bound model with stream and invoke methods */\nexport interface ChatModel {\n  stream?: (\n    messages: BaseMessage[],\n    config?: RunnableConfig\n  ) => Promise<AsyncIterable<AIMessageChunk>>;\n  invoke: (\n    messages: BaseMessage[],\n    config?: RunnableConfig\n  ) => Promise<AIMessageChunk>;\n}\n\nexport type GraphNode = GraphNodeKeys | typeof START;\nexport type ClientCallback<T extends unknown[]> = (\n  graph: StandardGraph,\n  ...args: T\n) => void;\n\nexport type ClientCallbacks = {\n  [Callback.TOOL_ERROR]?: ClientCallback<[Error, string]>;\n  [Callback.TOOL_START]?: ClientCallback<unknown[]>;\n  [Callback.TOOL_END]?: ClientCallback<unknown[]>;\n};\n\nexport type SystemCallbacks = {\n  [K in keyof ClientCallbacks]: ClientCallbacks[K] extends ClientCallback<\n    infer Args\n  >\n    ? (...args: Args) => void\n    : never;\n};\n\nexport type BaseGraphState = {\n  messages: BaseMessage[];\n  /**\n   * Structured response when using structured output mode.\n   * Contains the validated JSON response conforming to the configured schema.\n   */\n  structuredResponse?: Record<string, unknown>;\n};\n\nexport type MultiAgentGraphState = BaseGraphState & {\n  agentMessages?: BaseMessage[];\n};\n\nexport type IState = BaseGraphState;\n\nexport interface EventHandler {\n  handle(\n    event: string,\n    data:\n      | StreamEventData\n      | ModelEndData\n      | RunStep\n      | RunStepDeltaEvent\n      | MessageDeltaEvent\n      | ReasoningDeltaEvent\n      | { result: ToolEndEvent },\n    metadata?: Record<string, unknown>,\n    graph?: StandardGraph | MultiAgentGraph\n  ): void | Promise<void>;\n}\n\nexport type GraphStateChannels<T extends BaseGraphState> =\n  StateGraphArgs<T>['channels'];\n\nexport type Workflow<\n  T extends BaseGraphState = BaseGraphState,\n  U extends Partial<T> = Partial<T>,\n  N extends string = string,\n> = StateGraph<T, U, N>;\n\nexport type CompiledWorkflow<\n  T extends BaseGraphState = BaseGraphState,\n  U extends Partial<T> = Partial<T>,\n  N extends string = string,\n> = CompiledStateGraph<T, U, N>;\n\nexport type CompiledStateWorkflow = CompiledStateGraph<\n  StateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  UpdateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  string,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition\n>;\n\nexport type CompiledMultiAgentWorkflow = CompiledStateGraph<\n  StateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  UpdateType<{\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  }>,\n  string,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n    agentMessages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition\n>;\n\nexport type CompiledAgentWorfklow = CompiledStateGraph<\n  {\n    messages: BaseMessage[];\n  },\n  {\n    messages?: BaseMessage[] | undefined;\n  },\n  '__start__' | `agent=${string}` | `tools=${string}`,\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  {\n    messages: BinaryOperatorAggregate<BaseMessage[], BaseMessage[]>;\n  },\n  StateDefinition,\n  {\n    [x: `agent=${string}`]: Partial<BaseGraphState>;\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    [x: `tools=${string}`]: any;\n  }\n>;\n\nexport type SystemRunnable =\n  | Runnable<\n      BaseMessage[],\n      (BaseMessage | SystemMessage)[],\n      RunnableConfig<Record<string, unknown>>\n    >\n  | undefined;\n\n/**\n * Optional compile options passed to workflow.compile().\n * These are intentionally untyped to avoid coupling to library internals.\n */\nexport type CompileOptions = {\n  // A checkpointer instance (e.g., MemorySaver, SQL saver)\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  checkpointer?: any;\n  interruptBefore?: string[];\n  interruptAfter?: string[];\n  /**\n   * Human-in-the-loop tool approval configuration.\n   * When set, tools matching the policy will trigger an interrupt()\n   * before execution, pausing the graph for human approval.\n   * Requires a checkpointer to be set for interrupt/resume to work.\n   */\n  toolApprovalConfig?: ToolApprovalConfig;\n};\n\nexport type EventStreamCallbackHandlerInput =\n  Parameters<CompiledWorkflow['streamEvents']>[2] extends Omit<\n    infer T,\n    'autoClose'\n  >\n    ? T\n    : never;\n\nexport type StreamChunk =\n  | (ChatGenerationChunk & {\n      message: AIMessageChunk;\n    })\n  | AIMessageChunk;\n\n/**\n * Data associated with a StreamEvent.\n */\nexport type StreamEventData = {\n  /**\n   * The input passed to the runnable that generated the event.\n   * Inputs will sometimes be available at the *START* of the runnable, and\n   * sometimes at the *END* of the runnable.\n   * If a runnable is able to stream its inputs, then its input by definition\n   * won't be known until the *END* of the runnable when it has finished streaming\n   * its inputs.\n   */\n  input?: unknown;\n  /**\n   * The output of the runnable that generated the event.\n   * Outputs will only be available at the *END* of the runnable.\n   * For most runnables, this field can be inferred from the `chunk` field,\n   * though there might be some exceptions for special cased runnables (e.g., like\n   * chat models), which may return more information.\n   */\n  output?: unknown;\n  /**\n   * A streaming chunk from the output that generated the event.\n   * chunks support addition in general, and adding them up should result\n   * in the output of the runnable that generated the event.\n   */\n  chunk?: StreamChunk;\n  /**\n   * Runnable config for invoking other runnables within handlers.\n   */\n  config?: RunnableConfig;\n  /**\n   * Custom result from the runnable that generated the event.\n   */\n  result?: unknown;\n  /**\n   * Custom field to indicate the event was manually emitted, and may have been handled already\n   */\n  emitted?: boolean;\n};\n\n/**\n * A streaming event.\n *\n * Schema of a streaming event which is produced from the streamEvents method.\n */\nexport type StreamEvent = {\n  /**\n   * Event names are of the format: on_[runnable_type]_(start|stream|end).\n   *\n   * Runnable types are one of:\n   * - llm - used by non chat models\n   * - chat_model - used by chat models\n   * - prompt --  e.g., ChatPromptTemplate\n   * - tool -- LangChain tools\n   * - chain - most Runnables are of this type\n   *\n   * Further, the events are categorized as one of:\n   * - start - when the runnable starts\n   * - stream - when the runnable is streaming\n   * - end - when the runnable ends\n   *\n   * start, stream and end are associated with slightly different `data` payload.\n   *\n   * Please see the documentation for `EventData` for more details.\n   */\n  event: string;\n  /** The name of the runnable that generated the event. */\n  name: string;\n  /**\n   * An randomly generated ID to keep track of the execution of the given runnable.\n   *\n   * Each child runnable that gets invoked as part of the execution of a parent runnable\n   * is assigned its own unique ID.\n   */\n  run_id: string;\n  /**\n   * Tags associated with the runnable that generated this event.\n   * Tags are always inherited from parent runnables.\n   */\n  tags?: string[];\n  /** Metadata associated with the runnable that generated this event. */\n  metadata: Record<string, unknown>;\n  /**\n   * Event data.\n   *\n   * The contents of the event data depend on the event type.\n   */\n  data: StreamEventData;\n};\n\nexport type GraphConfig = {\n  provider: string;\n  thread_id?: string;\n  run_id?: string;\n};\n\nexport type PartMetadata = {\n  progress?: number;\n  asset_pointer?: string;\n  status?: string;\n  action?: boolean;\n  output?: string;\n};\n\nexport type ModelEndData =\n  | (StreamEventData & { output: AIMessageChunk | undefined })\n  | undefined;\nexport type GraphTools = GenericTool[] | BindToolsInput[] | GoogleAIToolType[];\nexport type StandardGraphInput = {\n  runId?: string;\n  signal?: AbortSignal;\n  agents: AgentInputs[];\n  tokenCounter?: TokenCounter;\n  indexTokenCountMap?: Record<string, number>;\n};\n\nexport type GraphEdge = {\n  /** Agent ID, use a list for multiple sources */\n  from: string | string[];\n  /** Agent ID, use a list for multiple destinations */\n  to: string | string[];\n  description?: string;\n  /** Can return boolean or specific destination(s) */\n  condition?: (state: BaseGraphState) => boolean | string | string[];\n  /** EdgeType.HANDOFF creates tools for dynamic routing, EdgeType.DIRECT creates direct edges with parallel execution */\n  edgeType?: import('@/common').EdgeType;\n  /**\n   * For direct edges: Optional prompt to add when transitioning through this edge.\n   * String prompts can include variables like {results} which will be replaced with\n   * messages from startIndex onwards. When {results} is used, excludeResults defaults to true.\n   *\n   * For handoff edges: Description for the input parameter that the handoff tool accepts,\n   * allowing the supervisor to pass specific instructions/context to the transferred agent.\n   */\n  prompt?:\n    | string\n    | ((\n        messages: BaseMessage[],\n        runStartIndex: number\n      ) => string | Promise<string> | undefined);\n  /**\n   * When true, excludes messages from startIndex when adding prompt.\n   * Automatically set to true when {results} variable is used in prompt.\n   */\n  excludeResults?: boolean;\n  /**\n   * For handoff edges: Customizes the parameter name for the handoff input.\n   * Defaults to \"instructions\" if not specified.\n   * Only applies when prompt is provided for handoff edges.\n   */\n  promptKey?: string;\n};\n\nexport type MultiAgentGraphInput = StandardGraphInput & {\n  edges: GraphEdge[];\n};\n\n/**\n * Structured output mode determines how the agent returns structured data.\n * - 'tool': Uses tool calling to return structured output (works with all tool-calling models)\n * - 'provider': Uses provider-native structured output via LangChain's jsonMode (OpenAI, Anthropic, etc.)\n * - 'native': Uses provider's constrained decoding API directly for guaranteed schema compliance\n *   (Anthropic output_config.format, OpenAI response_format.json_schema). Falls back to 'tool' for unsupported providers.\n * - 'auto': Automatically selects the best strategy — 'native' for supported providers, 'tool' for others\n */\nexport type StructuredOutputMode = 'tool' | 'provider' | 'native' | 'auto';\n\n/**\n * Resolved method used internally after mode resolution.\n * Maps to LangChain's withStructuredOutput method parameter plus our native path.\n */\nexport type ResolvedStructuredOutputMethod =\n  | 'functionCalling'\n  | 'jsonMode'\n  | 'jsonSchema'\n  | 'native'\n  | undefined;\n\n/**\n * Error thrown when the model refuses to produce structured output due to safety policies.\n */\nexport class StructuredOutputRefusalError extends Error {\n  constructor(public refusalText: string) {\n    super(`Model refused to produce structured output: ${refusalText}`);\n    this.name = 'StructuredOutputRefusalError';\n  }\n}\n\n/**\n * Error thrown when the structured output response was truncated due to max_tokens.\n */\nexport class StructuredOutputTruncatedError extends Error {\n  constructor(public stopReason: string) {\n    super(\n      `Structured output was truncated (stop_reason: ${stopReason}). ` +\n        'Increase max_tokens to allow the full JSON response to be generated.'\n    );\n    this.name = 'StructuredOutputTruncatedError';\n  }\n}\n\n/**\n * Configuration for structured JSON output from agents.\n * When configured, the agent will return a validated JSON response\n * instead of streaming text.\n */\nexport interface StructuredOutputConfig {\n  /**\n   * JSON Schema defining the output structure.\n   * The model will be forced to return data conforming to this schema.\n   */\n  schema: Record<string, unknown>;\n  /**\n   * Name for the structured output format (used in tool mode).\n   * @default 'StructuredResponse'\n   */\n  name?: string;\n  /**\n   * Description of what the structured output represents.\n   * Helps the model understand the expected format.\n   */\n  description?: string;\n  /**\n   * Output mode strategy.\n   * @default 'auto'\n   */\n  mode?: StructuredOutputMode;\n  /**\n   * Enable strict schema validation.\n   * When true, the response must exactly match the schema.\n   * @default true\n   */\n  strict?: boolean;\n  /**\n   * Error handling configuration.\n   * - true: Auto-retry on validation errors (default)\n   * - false: Throw error on validation failure\n   * - string: Custom error message for retry\n   */\n  handleErrors?: boolean | string;\n  /**\n   * Maximum number of retry attempts on validation failure.\n   * @default 2\n   */\n  maxRetries?: number;\n  /**\n   * Include the raw AI message along with structured response.\n   * Useful for debugging.\n   * @default false\n   */\n  includeRaw?: boolean;\n}\n\n/**\n * Database/API structured output format (snake_case with enabled flag).\n * This matches the format stored in MongoDB and sent from frontends.\n */\nexport interface StructuredOutputInput {\n  /** Whether structured output is enabled */\n  enabled?: boolean;\n  /** JSON Schema defining the expected response structure */\n  schema?: Record<string, unknown>;\n  /** Name identifier for the structured output */\n  name?: string;\n  /** Description of what the structured output represents */\n  description?: string;\n  /** Mode for structured output: 'tool' | 'provider' | 'native' | 'auto' */\n  mode?: StructuredOutputMode;\n  /** Whether to enforce strict schema validation */\n  strict?: boolean;\n}\n\n/**\n * Trigger strategy for when summarization should activate.\n * - 'contextPercentage': Trigger when context utilization exceeds a threshold percentage\n * - 'messageCount': Trigger when pruned message count exceeds a threshold\n * - 'tokenThreshold': Trigger when total token count exceeds a raw threshold\n */\nexport type SummarizationTriggerType =\n  | 'contextPercentage'\n  | 'messageCount'\n  | 'tokenThreshold';\n\n/**\n * Configuration for summarization behavior within the agent pipeline.\n * All fields are optional — sensible defaults are provided via constants.\n *\n * @see SUMMARIZATION_CONTEXT_THRESHOLD, SUMMARIZATION_RESERVE_RATIO, PRUNING_EMA_ALPHA\n */\nexport interface SummarizationConfig {\n  /**\n   * Strategy for when summarization triggers.\n   * @default 'contextPercentage'\n   */\n  triggerType?: SummarizationTriggerType;\n\n  /**\n   * Threshold value interpreted based on triggerType:\n   * - contextPercentage: 0-100 (percentage of context window)\n   * - messageCount: absolute count of messages pruned\n   * - tokenThreshold: absolute token count\n   * @default 80 (for contextPercentage)\n   */\n  triggerThreshold?: number;\n\n  /**\n   * Fraction of context window (0-1) reserved for recent messages.\n   * Prevents over-pruning by ensuring at least this fraction of the\n   * context budget is preserved as recent conversation history.\n   * @default 0.3\n   */\n  reserveRatio?: number;\n\n  /**\n   * Whether context pruning is enabled (can be disabled for debugging).\n   * @default true\n   */\n  contextPruning?: boolean;\n\n  /**\n   * Initial summary text to seed across runs.\n   * Different from persistedSummary: this is provided by the caller as a\n   * cross-conversation seed (e.g., agent personality or recurring context),\n   * while persistedSummary is loaded from the conversation's own history.\n   */\n  initialSummary?: string;\n}\n\n/**\n * Runtime state for EMA-based pruning calibration.\n * Maintained across iterations within a single run to smooth pruning decisions.\n */\nexport interface PruneCalibrationState {\n  /** Current EMA calibration ratio */\n  ratio: number;\n  /** Number of calibration updates applied */\n  iterations: number;\n}\n\n/**\n * Lightweight file metadata entry for conversation-level file awareness.\n * Contains only IDs and names — NOT full content — so the agent always knows\n * what files exist in the conversation even after compaction pushes old messages\n * behind the summary window. The agent can retrieve full content on-demand\n * via file_search (RAG) or content_tool read (by contentId).\n */\nexport interface FileManifestEntry {\n  /** Unique file identifier (e.g., MongoDB ObjectId or UUID) */\n  fileId: string;\n  /** Original filename (e.g., \"quarterly-report.pdf\") */\n  filename: string;\n  /** Content identifier for on-demand retrieval via content_tool read */\n  contentId?: string;\n  /** File source (e.g., \"local\", \"sharepoint\", \"onedrive\") */\n  source?: string;\n  /** Index of the message that introduced this file (0-based in the original message array) */\n  messageIndex?: number;\n}\n\nexport interface AgentInputs {\n  agentId: string;\n  /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */\n  name?: string;\n  /** Description of what this agent does (used to enrich handoff tool descriptions). */\n  description?: string;\n  toolEnd?: boolean;\n  toolMap?: ToolMap;\n  tools?: GraphTools;\n  provider: Providers;\n  instructions?: string;\n  streamBuffer?: number;\n  maxContextTokens?: number;\n  clientOptions?: ClientOptions;\n  additional_instructions?: string;\n  reasoningKey?: 'reasoning_content' | 'reasoning';\n  /** Format content blocks as strings (for legacy compatibility i.e. Ollama/Azure Serverless) */\n  useLegacyContent?: boolean;\n  /**\n   * Tool definitions for all tools, including deferred and programmatic.\n   * Used for tool search and programmatic tool calling.\n   * Maps tool name to LCTool definition.\n   */\n  toolRegistry?: Map<string, LCTool>;\n  /**\n   * Dynamic context that changes per-request (e.g., current time, user info).\n   * This is injected as a user message rather than system prompt to preserve cache.\n   * Keeping this separate from instructions ensures the system message stays static\n   * and can be cached by Bedrock/Anthropic prompt caching.\n   */\n  dynamicContext?: string;\n  /**\n   * Structured output configuration (camelCase).\n   * When set, disables streaming and returns a validated JSON response\n   * conforming to the specified schema.\n   */\n  structuredOutput?: StructuredOutputConfig;\n  /**\n   * Structured output configuration (snake_case - database/API format).\n   * Alternative to structuredOutput for compatibility with MongoDB/frontend.\n   * Uses an `enabled` flag to control activation.\n   * @deprecated Use structuredOutput instead when possible\n   */\n  structured_output?: StructuredOutputInput;\n  /**\n   * Serializable tool definitions for event-driven execution.\n   * When provided, ToolNode operates in event-driven mode, dispatching\n   * ON_TOOL_EXECUTE events instead of invoking tools directly.\n   */\n  toolDefinitions?: LCTool[];\n  /**\n   * Tool names discovered from previous conversation history.\n   * These tools will be pre-marked as discovered so they're included\n   * in tool binding without requiring tool_search.\n   */\n  discoveredTools?: string[];\n  /**\n   * Optional callback for summarizing messages that were pruned from context.\n   * When provided, discarded messages are summarized by the caller (e.g., Ranger)\n   * using a cheap LLM call, and the summary is prepended to the context.\n   */\n  summarizeCallback?: (\n    messagesToRefine: import('@langchain/core/messages').BaseMessage[]\n  ) => Promise<string | undefined>;\n  /**\n   * Pre-existing summary text loaded from persistent storage (MongoDB/Redis).\n   * When provided, this summary is injected into the initial message context\n   * so the agent has prior conversation history even on new turns.\n   * Set by Ranger's SummaryStore when resuming a conversation.\n   */\n  persistedSummary?: string;\n  /**\n   * Summarization configuration controlling trigger strategy, reserve ratio,\n   * and EMA calibration for pruning. When omitted, sensible defaults apply.\n   * @see SummarizationConfig\n   */\n  summarizationConfig?: SummarizationConfig;\n  /**\n   * Lightweight file manifest for the conversation.\n   * Contains file IDs, names, and metadata — NOT full content.\n   *\n   * Used by the compaction engine to inject a [Conversation Files] block\n   * into the windowed view, ensuring the LLM always knows what files exist\n   * even when old messages (with full file content) are behind the summary.\n   *\n   * The agent can retrieve full content on-demand via:\n   *   - file_search (RAG semantic search over embedded files)\n   *   - content_tool read (by contentId for exact file retrieval)\n   *\n   * Built by the orchestrator (e.g., Ranger) from message_file_map\n   * and metadata.context_files across all conversation messages.\n   */\n  fileManifest?: FileManifestEntry[];\n}\n"],"names":[],"mappings":"AA4YA;;AAEG;AACG,MAAO,4BAA6B,SAAQ,KAAK,CAAA;AAClC,IAAA,WAAA;AAAnB,IAAA,WAAA,CAAmB,WAAmB,EAAA;AACpC,QAAA,KAAK,CAAC,CAAA,4CAAA,EAA+C,WAAW,CAAA,CAAE,CAAC;QADlD,IAAA,CAAA,WAAW,GAAX,WAAW;AAE5B,QAAA,IAAI,CAAC,IAAI,GAAG,8BAA8B;IAC5C;AACD;AAED;;AAEG;AACG,MAAO,8BAA+B,SAAQ,KAAK,CAAA;AACpC,IAAA,UAAA;AAAnB,IAAA,WAAA,CAAmB,UAAkB,EAAA;QACnC,KAAK,CACH,CAAA,8CAAA,EAAiD,UAAU,CAAA,GAAA,CAAK;AAC9D,YAAA,sEAAsE,CACzE;QAJgB,IAAA,CAAA,UAAU,GAAV,UAAU;AAK3B,QAAA,IAAI,CAAC,IAAI,GAAG,gCAAgC;IAC9C;AACD;;;;"}

package/dist/esm/utils/fileManifest.mjs

@@ -0,0 +1,46 @@
+// src/utils/fileManifest.ts
+//
+// Utility for building a lightweight [Conversation Files] context block
+// from a file manifest. Injected into the compaction windowed view so the
+// LLM retains awareness of ALL conversation files, even when old messages
+// (with full file content) are behind the summary.
+/**
+ * Prefix marker for the file manifest block.
+ * Used to detect and deduplicate manifest messages across turns.
+ */
+const FILE_MANIFEST_PREFIX = '[Conversation Files]';
+/**
+ * Builds a compact text block listing all files in the conversation.
+ * Each entry costs ~10-15 tokens, so 10 files ≈ 100-150 tokens total.
+ *
+ * The block includes retrieval hints so the LLM knows how to fetch
+ * full content on demand (via file_search or content_tool).
+ *
+ * @param manifest - Array of file metadata entries
+ * @returns Formatted text block, or empty string if manifest is empty/undefined
+ */
+function buildFileManifestBlock(manifest) {
+    if (!manifest || manifest.length === 0) {
+        return '';
+    }
+    const lines = manifest.map((entry) => {
+        const parts = [`- ${entry.filename}`];
+        if (entry.contentId) {
+            parts.push(`(content_id: ${entry.contentId})`);
+        }
+        if (entry.source) {
+            parts.push(`[${entry.source}]`);
+        }
+        return parts.join(' ');
+    });
+    return [
+        FILE_MANIFEST_PREFIX,
+        'The following files have been shared in this conversation.',
+        'Use file_search or content_tool read (with content_id) to retrieve full content when needed.',
+        '',
+        ...lines,
+    ].join('\n');
+}
+
+export { FILE_MANIFEST_PREFIX, buildFileManifestBlock };
+//# sourceMappingURL=fileManifest.mjs.map

package/dist/esm/utils/fileManifest.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileManifest.mjs","sources":["../../../src/utils/fileManifest.ts"],"sourcesContent":["// src/utils/fileManifest.ts\n//\n// Utility for building a lightweight [Conversation Files] context block\n// from a file manifest. Injected into the compaction windowed view so the\n// LLM retains awareness of ALL conversation files, even when old messages\n// (with full file content) are behind the summary.\n\nimport type { FileManifestEntry } from '@/types/graph';\n\n/**\n * Prefix marker for the file manifest block.\n * Used to detect and deduplicate manifest messages across turns.\n */\nexport const FILE_MANIFEST_PREFIX = '[Conversation Files]';\n\n/**\n * Builds a compact text block listing all files in the conversation.\n * Each entry costs ~10-15 tokens, so 10 files ≈ 100-150 tokens total.\n *\n * The block includes retrieval hints so the LLM knows how to fetch\n * full content on demand (via file_search or content_tool).\n *\n * @param manifest - Array of file metadata entries\n * @returns Formatted text block, or empty string if manifest is empty/undefined\n */\nexport function buildFileManifestBlock(manifest: FileManifestEntry[] | undefined): string {\n  if (!manifest || manifest.length === 0) {\n    return '';\n  }\n\n  const lines = manifest.map((entry) => {\n    const parts: string[] = [`- ${entry.filename}`];\n    if (entry.contentId) {\n      parts.push(`(content_id: ${entry.contentId})`);\n    }\n    if (entry.source) {\n      parts.push(`[${entry.source}]`);\n    }\n    return parts.join(' ');\n  });\n\n  return [\n    FILE_MANIFEST_PREFIX,\n    'The following files have been shared in this conversation.',\n    'Use file_search or content_tool read (with content_id) to retrieve full content when needed.',\n    '',\n    ...lines,\n  ].join('\\n');\n}\n"],"names":[],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AAIA;;;AAGG;AACI,MAAM,oBAAoB,GAAG;AAEpC;;;;;;;;;AASG;AACG,SAAU,sBAAsB,CAAC,QAAyC,EAAA;IAC9E,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE;AACtC,QAAA,OAAO,EAAE;IACX;IAEA,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,KAAI;QACnC,MAAM,KAAK,GAAa,CAAC,CAAA,EAAA,EAAK,KAAK,CAAC,QAAQ,CAAA,CAAE,CAAC;AAC/C,QAAA,IAAI,KAAK,CAAC,SAAS,EAAE;YACnB,KAAK,CAAC,IAAI,CAAC,CAAA,aAAA,EAAgB,KAAK,CAAC,SAAS,CAAA,CAAA,CAAG,CAAC;QAChD;AACA,QAAA,IAAI,KAAK,CAAC,MAAM,EAAE;YAChB,KAAK,CAAC,IAAI,CAAC,CAAA,CAAA,EAAI,KAAK,CAAC,MAAM,CAAA,CAAA,CAAG,CAAC;QACjC;AACA,QAAA,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;AACxB,IAAA,CAAC,CAAC;IAEF,OAAO;QACL,oBAAoB;QACpB,4DAA4D;QAC5D,8FAA8F;QAC9F,EAAE;AACF,QAAA,GAAG,KAAK;AACT,KAAA,CAAC,IAAI,CAAC,IAAI,CAAC;AACd;;;;"}

package/dist/types/agents/AgentContext.d.ts

@@ -118,7 +118,9 @@ export declare class AgentContext {
     persistedSummary?: string;
     /** Summarization configuration controlling trigger strategy, reserve ratio, and EMA calibration */
     summarizationConfig?: t.SummarizationConfig;
-    constructor({ agentId, name, description, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, instructions, additionalInstructions, dynamicContext, reasoningKey, toolEnd, instructionTokens, useLegacyContent, structuredOutput, discoveredTools, summarizeCallback, persistedSummary, summarizationConfig, }: {
+    /** Lightweight file manifest for file-aware compaction (IDs and names only, no content) */
+    fileManifest?: t.FileManifestEntry[];
+    constructor({ agentId, name, description, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, instructions, additionalInstructions, dynamicContext, reasoningKey, toolEnd, instructionTokens, useLegacyContent, structuredOutput, discoveredTools, summarizeCallback, persistedSummary, summarizationConfig, fileManifest, }: {
         agentId: string;
         name?: string;
         description?: string;
@@ -143,6 +145,7 @@ export declare class AgentContext {
         summarizeCallback?: (messages: BaseMessage[]) => Promise<string | undefined>;
         persistedSummary?: string;
         summarizationConfig?: t.SummarizationConfig;
+        fileManifest?: t.FileManifestEntry[];
     });
     /**
      * Checks if structured output mode is enabled for this agent.

package/dist/types/types/graph.d.ts

@@ -400,6 +400,25 @@ export interface PruneCalibrationState {
     /** Number of calibration updates applied */
     iterations: number;
 }
+/**
+ * Lightweight file metadata entry for conversation-level file awareness.
+ * Contains only IDs and names — NOT full content — so the agent always knows
+ * what files exist in the conversation even after compaction pushes old messages
+ * behind the summary window. The agent can retrieve full content on-demand
+ * via file_search (RAG) or content_tool read (by contentId).
+ */
+export interface FileManifestEntry {
+    /** Unique file identifier (e.g., MongoDB ObjectId or UUID) */
+    fileId: string;
+    /** Original filename (e.g., "quarterly-report.pdf") */
+    filename: string;
+    /** Content identifier for on-demand retrieval via content_tool read */
+    contentId?: string;
+    /** File source (e.g., "local", "sharepoint", "onedrive") */
+    source?: string;
+    /** Index of the message that introduced this file (0-based in the original message array) */
+    messageIndex?: number;
+}
 export interface AgentInputs {
     agentId: string;
     /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
@@ -475,4 +494,20 @@ export interface AgentInputs {
      * @see SummarizationConfig
      */
     summarizationConfig?: SummarizationConfig;
+    /**
+     * Lightweight file manifest for the conversation.
+     * Contains file IDs, names, and metadata — NOT full content.
+     *
+     * Used by the compaction engine to inject a [Conversation Files] block
+     * into the windowed view, ensuring the LLM always knows what files exist
+     * even when old messages (with full file content) are behind the summary.
+     *
+     * The agent can retrieve full content on-demand via:
+     *   - file_search (RAG semantic search over embedded files)
+     *   - content_tool read (by contentId for exact file retrieval)
+     *
+     * Built by the orchestrator (e.g., Ranger) from message_file_map
+     * and metadata.context_files across all conversation messages.
+     */
+    fileManifest?: FileManifestEntry[];
 }

package/dist/types/utils/fileManifest.d.ts

@@ -0,0 +1,17 @@
+import type { FileManifestEntry } from '@/types/graph';
+/**
+ * Prefix marker for the file manifest block.
+ * Used to detect and deduplicate manifest messages across turns.
+ */
+export declare const FILE_MANIFEST_PREFIX = "[Conversation Files]";
+/**
+ * Builds a compact text block listing all files in the conversation.
+ * Each entry costs ~10-15 tokens, so 10 files ≈ 100-150 tokens total.
+ *
+ * The block includes retrieval hints so the LLM knows how to fetch
+ * full content on demand (via file_search or content_tool).
+ *
+ * @param manifest - Array of file metadata entries
+ * @returns Formatted text block, or empty string if manifest is empty/undefined
+ */
+export declare function buildFileManifestBlock(manifest: FileManifestEntry[] | undefined): string;

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

@@ -11,3 +11,4 @@ export * from './toolCallContinuation';
 export * from './contextPressure';
 export * from './toolDiscoveryCache';
 export * from './pruneCalibration';
+export * from './fileManifest';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/agents",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/agents/AgentContext.ts

@@ -51,6 +51,7 @@ export class AgentContext {
       summarizeCallback,
       persistedSummary,
       summarizationConfig,
+      fileManifest,
     } = agentConfig;
 
     // Normalize structured output: support both camelCase and snake_case inputs
@@ -97,6 +98,7 @@ export class AgentContext {
       summarizeCallback,
       persistedSummary,
       summarizationConfig,
+      fileManifest,
     });
 
     if (tokenCounter) {
@@ -250,6 +252,8 @@ export class AgentContext {
   persistedSummary?: string;
   /** Summarization configuration controlling trigger strategy, reserve ratio, and EMA calibration */
   summarizationConfig?: t.SummarizationConfig;
+  /** Lightweight file manifest for file-aware compaction (IDs and names only, no content) */
+  fileManifest?: t.FileManifestEntry[];
 
   constructor({
     agentId,
@@ -276,6 +280,7 @@ export class AgentContext {
     summarizeCallback,
     persistedSummary,
     summarizationConfig,
+    fileManifest,
   }: {
     agentId: string;
     name?: string;
@@ -303,6 +308,7 @@ export class AgentContext {
     ) => Promise<string | undefined>;
     persistedSummary?: string;
     summarizationConfig?: t.SummarizationConfig;
+    fileManifest?: t.FileManifestEntry[];
   }) {
     this.agentId = agentId;
     this.name = name;
@@ -323,6 +329,7 @@ export class AgentContext {
     this.summarizeCallback = summarizeCallback;
     this.persistedSummary = persistedSummary;
     this.summarizationConfig = summarizationConfig;
+    this.fileManifest = fileManifest;
     if (reasoningKey) {
       this.reasoningKey = reasoningKey;
     }

package/src/graphs/Graph.ts

@@ -69,7 +69,8 @@ import {
   updatePruneCalibration,
   applyCalibration,
 } from '@/utils';
-import type { PruneCalibrationState } from '@/types/graph';
+import type { PruneCalibrationState, FileManifestEntry } from '@/types/graph';
+import { buildFileManifestBlock, FILE_MANIFEST_PREFIX } from '@/utils/fileManifest';
 import {
   buildContextAnalytics,
   type ContextAnalytics,
@@ -1683,6 +1684,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         const contentStart = systemMsg != null ? 1 : 0;
         let usedTokens = 0;
         let windowStart = messages.length; // index where the recent window begins
+        let fileManifestTokens = 0; // populated in Step 4 if file manifest is injected
 
         if (summary == null || summary === '') {
           // Mode A: No summary — include as many recent messages as fit in budget
@@ -1735,7 +1737,11 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         const hasSummary = summaryMsg != null;
 
         // Step 4: Assemble the windowed view
-        // [system] + [summary (covers compacted messages)] + [recent window]
+        // [system] + [summary] + [file manifest] + [recent window]
+        //
+        // File manifest is injected ONLY when compaction is active (messages behind summary).
+        // It provides the LLM with awareness of all conversation files so it can
+        // retrieve content on demand via file_search or content_tool read.
         const viewParts: BaseMessage[] = [];
         if (systemMsg != null) {
           viewParts.push(systemMsg);
@@ -1743,6 +1749,21 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         if (summaryMsg != null) {
           viewParts.push(summaryMsg);
         }
+
+        // Inject file manifest when files exist and messages are being compacted
+        const fileManifest = agentContext.fileManifest;
+        if (fileManifest && fileManifest.length > 0 && compactedMessages.length > 0) {
+          const manifestBlock = buildFileManifestBlock(fileManifest);
+          if (manifestBlock) {
+            const manifestMsg = new SystemMessage(manifestBlock);
+            viewParts.push(manifestMsg);
+            // Account for manifest tokens in the view token map
+            const manifestTokens = tokenCounter != null ? tokenCounter(manifestMsg) : 0;
+            // Will be inserted at the correct index when rebuilding viewTokenMap below
+            fileManifestTokens = manifestTokens;
+          }
+        }
+
         viewParts.push(...recentMessages);
         messagesToUse = viewParts;
 
@@ -1758,6 +1779,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           viewTokenMap[viewIdx] = summaryTokens;
           viewIdx++;
         }
+        if (fileManifestTokens > 0) {
+          viewTokenMap[viewIdx] = fileManifestTokens;
+          viewIdx++;
+        }
         for (let i = windowStart; i < messages.length; i++) {
           viewTokenMap[viewIdx] = agentContext.indexTokenCountMap[i];
           viewIdx++;
@@ -1765,10 +1790,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         agentContext.indexTokenCountMap = viewTokenMap;
 
         console.debug(
-          `[Graph:Compaction] View: ${messages.length}→${viewParts.length} msgs ` +
-          `(${compactedMessages.length} behind summary, ${recentMessages.length} in window) | ` +
-          `summary=${summarySource}${summary ? ` (len=${summary.length})` : ''} | ` +
-          `budget=${recentBudget}/${calibratedMax} used=${usedTokens}`
+          `[Graph:Compaction] ${messages.length}→${viewParts.length} msgs | ` +
+          `compacted=${compactedMessages.length} window=${recentMessages.length} | ` +
+          `summary=${summarySource} | budget=${usedTokens}/${recentBudget}` +
+          (fileManifestTokens > 0 ? ` | manifest=${fileManifest?.length ?? 0} files (${fileManifestTokens}tok)` : '')
         );
 
         // Step 5: Fire background summary update (non-blocking)

package/src/graphs/gapFeatures.test.ts

@@ -637,6 +637,8 @@ describe('Proactive Summarization — Context Pressure', () => {
 
 import { applyCalibration as _applyCalibration } from '@/utils/pruneCalibration';
 import { COMPACTION_RECENT_ROUNDS } from '@/common/constants';
+import { buildFileManifestBlock, FILE_MANIFEST_PREFIX } from '@/utils/fileManifest';
+import type { FileManifestEntry } from '@/types/graph';
 
 describe('Context Compaction — Windowed View (no message deletion)', () => {
   /**
@@ -651,8 +653,9 @@ describe('Context Compaction — Windowed View (no message deletion)', () => {
     maxTokens: number;
     summary?: string;
     tokenCounter: TokenCounter;
+    fileManifest?: FileManifestEntry[];
   }) {
-    const { messages, indexTokenCountMap, maxTokens, summary, tokenCounter } = opts;
+    const { messages, indexTokenCountMap, maxTokens, summary, tokenCounter, fileManifest } = opts;
 
     const systemMsg = messages[0]?.getType() === 'system' ? messages[0] : null;
     const systemTokens = systemMsg != null ? (indexTokenCountMap[0] ?? 0) : 0;
@@ -705,9 +708,20 @@ describe('Context Compaction — Windowed View (no message deletion)', () => {
     const view: BaseMessage[] = [];
     if (systemMsg) view.push(systemMsg);
     if (summaryMsg) view.push(summaryMsg);
+
+    // Inject file manifest when files exist and messages are being compacted
+    let fileManifestMsg: SystemMessage | null = null;
+    if (fileManifest && fileManifest.length > 0 && compactedMessages.length > 0) {
+      const manifestBlock = buildFileManifestBlock(fileManifest);
+      if (manifestBlock) {
+        fileManifestMsg = new SystemMessage(manifestBlock);
+        view.push(fileManifestMsg);
+      }
+    }
+
     view.push(...recentMessages);
 
-    return { view, compactedMessages, recentMessages, usedTokens };
+    return { view, compactedMessages, recentMessages, usedTokens, fileManifestMsg };
   }
 
   it('builds a windowed view without deleting any messages', () => {
@@ -949,4 +963,141 @@ describe('Context Compaction — Windowed View (no message deletion)', () => {
     expect(messages[0].content).toBe(originalFirstContent);
     expect(messages[messages.length - 1].content).toBe(originalLastContent);
   });
+
+  // ── File Manifest in Windowed View ─────────────────────────────────────
+
+  it('injects file manifest block when files exist and messages are compacted', () => {
+    const messages = buildConversation(20, 400);
+    const indexTokenCountMap: Record<string, number | undefined> = {};
+    for (let i = 0; i < messages.length; i++) {
+      indexTokenCountMap[i] = simpleTokenCounter(messages[i]);
+    }
+
+    const manifest: FileManifestEntry[] = [
+      { fileId: 'f1', filename: 'report.pdf', contentId: 'abc123' },
+      { fileId: 'f2', filename: 'data.csv', contentId: 'def456', source: 'local' },
+    ];
+
+    const { view, compactedMessages, fileManifestMsg } = buildWindowedView({
+      messages,
+      indexTokenCountMap,
+      maxTokens: 600,
+      summary: 'Summary of earlier turns',
+      tokenCounter: simpleTokenCounter,
+      fileManifest: manifest,
+    });
+
+    // File manifest is injected
+    expect(fileManifestMsg).not.toBeNull();
+    expect(compactedMessages.length).toBeGreaterThan(0);
+
+    // Manifest message contains file names and content IDs
+    const manifestContent = fileManifestMsg!.content as string;
+    expect(manifestContent).toContain(FILE_MANIFEST_PREFIX);
+    expect(manifestContent).toContain('report.pdf');
+    expect(manifestContent).toContain('abc123');
+    expect(manifestContent).toContain('data.csv');
+    expect(manifestContent).toContain('def456');
+
+    // View order: [system] + [summary] + [file manifest] + [recent messages]
+    expect(view[0].getType()).toBe('system');
+    expect((view[1].content as string)).toContain('[Conversation Summary]');
+    expect((view[2].content as string)).toContain(FILE_MANIFEST_PREFIX);
+    // Recent messages follow
+    expect(view.length).toBeGreaterThan(3);
+  });
+
+  it('does NOT inject file manifest when no messages are compacted', () => {
+    const messages = buildConversation(4, 100); // small conversation
+    const indexTokenCountMap: Record<string, number | undefined> = {};
+    for (let i = 0; i < messages.length; i++) {
+      indexTokenCountMap[i] = simpleTokenCounter(messages[i]);
+    }
+
+    const manifest: FileManifestEntry[] = [
+      { fileId: 'f1', filename: 'file.txt', contentId: 'aaa' },
+    ];
+
+    const { compactedMessages, fileManifestMsg } = buildWindowedView({
+      messages,
+      indexTokenCountMap,
+      maxTokens: 100_000, // everything fits
+      tokenCounter: simpleTokenCounter,
+      fileManifest: manifest,
+    });
+
+    // No compaction happened, so no manifest injected
+    expect(compactedMessages.length).toBe(0);
+    expect(fileManifestMsg).toBeNull();
+  });
+
+  it('does NOT inject file manifest when manifest is empty', () => {
+    const messages = buildConversation(20, 400);
+    const indexTokenCountMap: Record<string, number | undefined> = {};
+    for (let i = 0; i < messages.length; i++) {
+      indexTokenCountMap[i] = simpleTokenCounter(messages[i]);
+    }
+
+    const { fileManifestMsg } = buildWindowedView({
+      messages,
+      indexTokenCountMap,
+      maxTokens: 600,
+      summary: 'Summary',
+      tokenCounter: simpleTokenCounter,
+      fileManifest: [],
+    });
+
+    expect(fileManifestMsg).toBeNull();
+  });
+});
+
+// ===========================================================================
+// File Manifest Utility — Unit Tests
+// ===========================================================================
+
+describe('buildFileManifestBlock', () => {
+  it('returns empty string for undefined manifest', () => {
+    expect(buildFileManifestBlock(undefined)).toBe('');
+  });
+
+  it('returns empty string for empty manifest', () => {
+    expect(buildFileManifestBlock([])).toBe('');
+  });
+
+  it('builds block with file names and content IDs', () => {
+    const manifest: FileManifestEntry[] = [
+      { fileId: 'f1', filename: 'report.pdf', contentId: 'abc123' },
+      { fileId: 'f2', filename: 'notes.md', contentId: 'def456' },
+    ];
+
+    const block = buildFileManifestBlock(manifest);
+
+    expect(block).toContain(FILE_MANIFEST_PREFIX);
+    expect(block).toContain('report.pdf');
+    expect(block).toContain('(content_id: abc123)');
+    expect(block).toContain('notes.md');
+    expect(block).toContain('(content_id: def456)');
+    expect(block).toContain('file_search or content_tool read');
+  });
+
+  it('includes source when provided', () => {
+    const manifest: FileManifestEntry[] = [
+      { fileId: 'f1', filename: 'doc.pdf', source: 'sharepoint' },
+    ];
+
+    const block = buildFileManifestBlock(manifest);
+    expect(block).toContain('[sharepoint]');
+  });
+
+  it('handles entries without contentId or source', () => {
+    const manifest: FileManifestEntry[] = [
+      { fileId: 'f1', filename: 'image.png' },
+    ];
+
+    const block = buildFileManifestBlock(manifest);
+    expect(block).toContain('- image.png');
+    // No per-file content_id or source brackets in the file line
+    expect(block).not.toContain('(content_id:');
+    expect(block).not.toContain('[local]');
+  });
 });

package/src/types/graph.ts

@@ -555,6 +555,26 @@ export interface PruneCalibrationState {
   iterations: number;
 }
 
+/**
+ * Lightweight file metadata entry for conversation-level file awareness.
+ * Contains only IDs and names — NOT full content — so the agent always knows
+ * what files exist in the conversation even after compaction pushes old messages
+ * behind the summary window. The agent can retrieve full content on-demand
+ * via file_search (RAG) or content_tool read (by contentId).
+ */
+export interface FileManifestEntry {
+  /** Unique file identifier (e.g., MongoDB ObjectId or UUID) */
+  fileId: string;
+  /** Original filename (e.g., "quarterly-report.pdf") */
+  filename: string;
+  /** Content identifier for on-demand retrieval via content_tool read */
+  contentId?: string;
+  /** File source (e.g., "local", "sharepoint", "onedrive") */
+  source?: string;
+  /** Index of the message that introduced this file (0-based in the original message array) */
+  messageIndex?: number;
+}
+
 export interface AgentInputs {
   agentId: string;
   /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
@@ -632,4 +652,20 @@ export interface AgentInputs {
    * @see SummarizationConfig
    */
   summarizationConfig?: SummarizationConfig;
+  /**
+   * Lightweight file manifest for the conversation.
+   * Contains file IDs, names, and metadata — NOT full content.
+   *
+   * Used by the compaction engine to inject a [Conversation Files] block
+   * into the windowed view, ensuring the LLM always knows what files exist
+   * even when old messages (with full file content) are behind the summary.
+   *
+   * The agent can retrieve full content on-demand via:
+   *   - file_search (RAG semantic search over embedded files)
+   *   - content_tool read (by contentId for exact file retrieval)
+   *
+   * Built by the orchestrator (e.g., Ranger) from message_file_map
+   * and metadata.context_files across all conversation messages.
+   */
+  fileManifest?: FileManifestEntry[];
 }