@illuma-ai/agents 1.4.0-alpha.0 → 1.4.0-alpha.2

package/dist/cjs/main.cjs

@@ -23,16 +23,19 @@ var ProgrammaticToolCalling = require('./tools/ProgrammaticToolCalling.cjs');
 var ToolSearch = require('./tools/ToolSearch.cjs');
 var ToolNode = require('./tools/ToolNode.cjs');
 var AskUser = require('./tools/AskUser.cjs');
-var schema$1 = require('./tools/schema.cjs');
+var schema$2 = require('./tools/schema.cjs');
 var handlers$1 = require('./tools/handlers.cjs');
-var tool = require('./tools/search/tool.cjs');
+var tool$1 = require('./tools/search/tool.cjs');
 var schema = require('./tools/search/schema.cjs');
 var index$2 = require('./tools/memory/index.cjs');
+var tool = require('./tools/fileSearch/tool.cjs');
+var ragClient = require('./tools/fileSearch/ragClient.cjs');
+var formatter = require('./tools/fileSearch/formatter.cjs');
+var schema$1 = require('./tools/fileSearch/schema.cjs');
 var proxyTool = require('./tools/proxyTool.cjs');
 var types = require('./providers/types.cjs');
 var capabilityNaming = require('./providers/capabilityNaming.cjs');
 var ToolsServerCapabilityProvider = require('./providers/tools-server/ToolsServerCapabilityProvider.cjs');
-var CompositeCapabilityProvider = require('./providers/composite/CompositeCapabilityProvider.cjs');
 var MCPCapabilityProvider = require('./providers/mcp/MCPCapabilityProvider.cjs');
 var transport = require('./providers/mcp/transport.cjs');
 var config$1 = require('./providers/mcp/config.cjs');
@@ -67,7 +70,7 @@ var run$1 = require('./utils/run.cjs');
 var tokens = require('./utils/tokens.cjs');
 var toonFormat = require('./utils/toonFormat.cjs');
 var contextAnalytics = require('./utils/contextAnalytics.cjs');
-var schema$2 = require('./utils/schema.cjs');
+var schema$3 = require('./utils/schema.cjs');
 var toolCallContinuation = require('./utils/toolCallContinuation.cjs');
 var contextPressure = require('./utils/contextPressure.cjs');
 var toolDiscoveryCache = require('./utils/toolDiscoveryCache.cjs');
@@ -196,13 +199,13 @@ exports.AskUserStepSchema = AskUser.AskUserStepSchema;
 exports.AskUserToolName = AskUser.AskUserToolName;
 exports.HITL_FIELDS = AskUser.HITL_FIELDS;
 exports.createAskUserTool = AskUser.createAskUserTool;
-exports.createSchemaOnlyTool = schema$1.createSchemaOnlyTool;
-exports.createSchemaOnlyTools = schema$1.createSchemaOnlyTools;
+exports.createSchemaOnlyTool = schema$2.createSchemaOnlyTool;
+exports.createSchemaOnlyTools = schema$2.createSchemaOnlyTools;
 exports.handleServerToolResult = handlers$1.handleServerToolResult;
 exports.handleToolCallChunks = handlers$1.handleToolCallChunks;
 exports.handleToolCalls = handlers$1.handleToolCalls;
 exports.toolResultTypes = handlers$1.toolResultTypes;
-exports.createSearchTool = tool.createSearchTool;
+exports.createSearchTool = tool$1.createSearchTool;
 Object.defineProperty(exports, "DATE_RANGE", {
 	enumerable: true,
 	get: function () { return schema.DATE_RANGE; }
@@ -220,6 +223,14 @@ exports.newsSchema = schema.newsSchema;
 exports.querySchema = schema.querySchema;
 exports.videosSchema = schema.videosSchema;
 exports.buildMemoryTools = index$2.buildMemoryTools;
+exports.createFileSearchTool = tool.createFileSearchTool;
+exports.HttpRagClient = ragClient.HttpRagClient;
+exports.RAG_API_URL_ENV = ragClient.RAG_API_URL_ENV;
+exports.getRagBaseUrl = ragClient.getRagBaseUrl;
+exports.createCitationAnchorFormatter = formatter.createCitationAnchorFormatter;
+exports.plainTextFormatter = formatter.plainTextFormatter;
+exports.FileSearchToolName = schema$1.FileSearchToolName;
+exports.fileSearchInputSchema = schema$1.fileSearchInputSchema;
 exports.buildProxyTool = proxyTool.buildProxyTool;
 Object.defineProperty(exports, "AuthSource", {
 	enumerable: true,
@@ -233,7 +244,6 @@ exports.CAPABILITY_NAME_SEPARATOR = capabilityNaming.CAPABILITY_NAME_SEPARATOR;
 exports.formatCapabilityName = capabilityNaming.formatCapabilityName;
 exports.parseCapabilityName = capabilityNaming.parseCapabilityName;
 exports.ToolsServerCapabilityProvider = ToolsServerCapabilityProvider.ToolsServerCapabilityProvider;
-exports.CompositeCapabilityProvider = CompositeCapabilityProvider.CompositeCapabilityProvider;
 exports.MCPCapabilityProvider = MCPCapabilityProvider.MCPCapabilityProvider;
 exports.flattenToolCallResponse = MCPCapabilityProvider.flattenToolCallResponse;
 exports.createTransport = transport.createTransport;
@@ -453,8 +463,8 @@ exports.isToonFormat = toonFormat.isToonFormat;
 exports.jsonToToon = toonFormat.jsonToToon;
 exports.processToolOutput = toonFormat.processToolOutput;
 exports.buildContextAnalytics = contextAnalytics.buildContextAnalytics;
-exports.isZodSchema = schema$2.isZodSchema;
-exports.toJsonSchema = schema$2.toJsonSchema;
+exports.isZodSchema = schema$3.isZodSchema;
+exports.toJsonSchema = schema$3.toJsonSchema;
 exports.extractFinishReason = toolCallContinuation.extractFinishReason;
 exports.isMaxTokensFinish = toolCallContinuation.isMaxTokensFinish;
 exports.buildMultiDocHintContent = contextPressure.buildMultiDocHintContent;

package/dist/cjs/main.cjs.map

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

package/dist/cjs/tools/fileSearch/formatter.cjs

@@ -0,0 +1,95 @@
+'use strict';
+
+/**
+ * Default result formatters.
+ *
+ * - `plainTextFormatter`: CLI / A2A / generic output. No citation anchors.
+ * - `citationAnchorFormatter`: ranger-style `\ue202turn0fileN` anchors with
+ *   a monotonic `sourceOffset` so multi-call turns stay globally unique.
+ *
+ * Runtimes can supply their own `FileSearchResultFormatter` to override.
+ */
+const plainTextFormatter = {
+    format(chunks, { files: _files }) {
+        if (chunks.length === 0) {
+            return { message: 'No relevant results found in the available files.' };
+        }
+        const body = chunks
+            .map((c) => {
+            const page = getPage(c);
+            const rel = (1 - c.distance).toFixed(4);
+            return (`File: ${c.filename}` +
+                (page != null ? `\nPage: ${page}` : '') +
+                `\nRelevance: ${rel}\nContent: ${c.page_content}\n`);
+        })
+            .join('\n---\n');
+        const sources = chunks.map((c) => ({
+            type: 'file',
+            fileId: c.file_id,
+            content: c.page_content,
+            fileName: c.filename,
+            relevance: 1 - c.distance,
+            pages: getPage(c) != null ? [getPage(c)] : [],
+        }));
+        return { message: body, artifact: { file_search: { sources } } };
+    },
+};
+function createCitationAnchorFormatter(opts = {}) {
+    const toolName = opts.toolName ?? 'file_search';
+    const getOffset = opts.getSourceOffset ?? (() => 0);
+    const advance = opts.advanceSourceOffset ?? (() => { });
+    return {
+        format(chunks) {
+            if (chunks.length === 0) {
+                return {
+                    message: 'No results found or errors occurred while searching the files.',
+                };
+            }
+            const base = getOffset();
+            const body = chunks
+                .map((c, i) => {
+                const globalIndex = base + i;
+                const page = getPage(c);
+                const rel = (1 - c.distance).toFixed(4);
+                return (`[Source ${globalIndex}] File: ${c.filename} | Anchor: \\ue202turn0file${globalIndex}` +
+                    (page != null ? ` | Page: ${page}` : '') +
+                    ` | Relevance: ${rel}\nContent: ${c.page_content}\n` +
+                    `↑ Cite this source using: \\ue202turn0file${globalIndex}`);
+            })
+                .join('\n---\n');
+            const sources = chunks.map((c) => ({
+                type: 'file',
+                fileId: c.file_id,
+                content: c.page_content,
+                fileName: c.filename,
+                relevance: 1 - c.distance,
+                pages: getPage(c) != null ? [getPage(c)] : [],
+                pageRelevance: getPage(c) != null
+                    ? { [getPage(c)]: 1 - c.distance }
+                    : {},
+            }));
+            advance(chunks.length);
+            return {
+                message: body,
+                artifact: { [toolName]: { sources, fileCitations: true } },
+            };
+        },
+    };
+}
+/** Extract a 1-indexed page number from the chunk metadata, or null. */
+function getPage(chunk) {
+    const raw = chunk.metadata?.page ??
+        chunk.metadata?.page_number ??
+        null;
+    if (raw == null)
+        return null;
+    const parsed = typeof raw === 'number' ? raw : parseInt(String(raw), 10);
+    if (Number.isNaN(parsed) || parsed < 0)
+        return null;
+    // rag_api stores 0-indexed; display is 1-indexed
+    return parsed + 1;
+}
+
+exports.createCitationAnchorFormatter = createCitationAnchorFormatter;
+exports.plainTextFormatter = plainTextFormatter;
+//# sourceMappingURL=formatter.cjs.map

package/dist/cjs/tools/fileSearch/formatter.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.cjs","sources":["../../../../src/tools/fileSearch/formatter.ts"],"sourcesContent":["/**\n * Default result formatters.\n *\n * - `plainTextFormatter`: CLI / A2A / generic output. No citation anchors.\n * - `citationAnchorFormatter`: ranger-style `\\ue202turn0fileN` anchors with\n *   a monotonic `sourceOffset` so multi-call turns stay globally unique.\n *\n * Runtimes can supply their own `FileSearchResultFormatter` to override.\n */\n\nimport type {\n  FileSearchResultFormatter,\n  FileSearchFile,\n  RagChunk,\n} from './types';\n\ntype AnnotatedChunk = RagChunk & {\n  filename: string;\n  isCurrentMessage: boolean;\n};\n\nexport const plainTextFormatter: FileSearchResultFormatter = {\n  format(chunks, { files: _files }) {\n    if (chunks.length === 0) {\n      return { message: 'No relevant results found in the available files.' };\n    }\n    const body = chunks\n      .map((c) => {\n        const page = getPage(c);\n        const rel = (1 - c.distance).toFixed(4);\n        return (\n          `File: ${c.filename}` +\n          (page != null ? `\\nPage: ${page}` : '') +\n          `\\nRelevance: ${rel}\\nContent: ${c.page_content}\\n`\n        );\n      })\n      .join('\\n---\\n');\n\n    const sources = chunks.map((c) => ({\n      type: 'file' as const,\n      fileId: c.file_id,\n      content: c.page_content,\n      fileName: c.filename,\n      relevance: 1 - c.distance,\n      pages: getPage(c) != null ? [getPage(c) as number] : [],\n    }));\n\n    return { message: body, artifact: { file_search: { sources } } };\n  },\n};\n\nexport interface CitationAnchorFormatterOptions {\n  /** Tool name used in the `file_search` artifact wrapper. Defaults to `'file_search'`. */\n  toolName?: string;\n  /**\n   * Monotonic counter for source indices within a turn. Pass the SAME\n   * function to the formatter across multiple calls in the same turn so\n   * anchors stay globally unique.\n   */\n  getSourceOffset?: () => number;\n  /** Called after formatting to advance the offset. */\n  advanceSourceOffset?: (by: number) => void;\n}\n\nexport function createCitationAnchorFormatter(\n  opts: CitationAnchorFormatterOptions = {},\n): FileSearchResultFormatter {\n  const toolName = opts.toolName ?? 'file_search';\n  const getOffset = opts.getSourceOffset ?? (() => 0);\n  const advance = opts.advanceSourceOffset ?? (() => {});\n\n  return {\n    format(chunks) {\n      if (chunks.length === 0) {\n        return {\n          message:\n            'No results found or errors occurred while searching the files.',\n        };\n      }\n      const base = getOffset();\n      const body = chunks\n        .map((c, i) => {\n          const globalIndex = base + i;\n          const page = getPage(c);\n          const rel = (1 - c.distance).toFixed(4);\n          return (\n            `[Source ${globalIndex}] File: ${c.filename} | Anchor: \\\\ue202turn0file${globalIndex}` +\n            (page != null ? ` | Page: ${page}` : '') +\n            ` | Relevance: ${rel}\\nContent: ${c.page_content}\\n` +\n            `↑ Cite this source using: \\\\ue202turn0file${globalIndex}`\n          );\n        })\n        .join('\\n---\\n');\n\n      const sources = chunks.map((c) => ({\n        type: 'file' as const,\n        fileId: c.file_id,\n        content: c.page_content,\n        fileName: c.filename,\n        relevance: 1 - c.distance,\n        pages: getPage(c) != null ? [getPage(c) as number] : [],\n        pageRelevance:\n          getPage(c) != null\n            ? { [getPage(c) as number]: 1 - c.distance }\n            : {},\n      }));\n\n      advance(chunks.length);\n      return {\n        message: body,\n        artifact: { [toolName]: { sources, fileCitations: true } },\n      };\n    },\n  };\n}\n\n/** Extract a 1-indexed page number from the chunk metadata, or null. */\nfunction getPage(chunk: AnnotatedChunk | RagChunk): number | null {\n  const raw =\n    (chunk.metadata?.page as unknown) ??\n    (chunk.metadata?.page_number as unknown) ??\n    null;\n  if (raw == null) return null;\n  const parsed = typeof raw === 'number' ? raw : parseInt(String(raw), 10);\n  if (Number.isNaN(parsed) || parsed < 0) return null;\n  // rag_api stores 0-indexed; display is 1-indexed\n  return parsed + 1;\n}\n\n// Re-export so consumers only import from the formatter module.\nexport type { FileSearchResultFormatter, FileSearchFile, RagChunk };\n"],"names":[],"mappings":"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"}

package/dist/cjs/tools/fileSearch/ragClient.cjs

@@ -0,0 +1,104 @@
+'use strict';
+
+var fetch = require('node-fetch');
+var env = require('@langchain/core/utils/env');
+
+/**
+ * Default HTTP RAG client. Posts to `${baseUrl}/query` with the shape
+ * rag_api expects (`{ file_id, query, k, entity_id? }`). Runtimes that
+ * use a different vector backend implement their own `RagClient`.
+ *
+ * Auth is runtime-provided per call (via `authHeaders` on the params) so
+ * short-lived tokens can be minted per request without the client
+ * caching stale credentials.
+ */
+const RAG_API_URL_ENV = 'RAG_API_URL';
+/** Resolve base URL at call time so env-var changes propagate. */
+function getRagBaseUrl(override) {
+    const url = override ??
+        env.getEnvironmentVariable(RAG_API_URL_ENV) ??
+        '';
+    if (!url) {
+        throw new Error(`file_search: ${RAG_API_URL_ENV} is not configured. ` +
+            `Set the env var or pass baseUrl to HttpRagClient.`);
+    }
+    return url.replace(/\/$/, '');
+}
+class HttpRagClient {
+    baseUrlOverride;
+    defaultHeaders;
+    defaultTimeoutMs;
+    logger;
+    constructor(opts = {}) {
+        this.baseUrlOverride = opts.baseUrl;
+        this.defaultHeaders = opts.defaultHeaders ?? {};
+        this.defaultTimeoutMs = opts.defaultTimeoutMs ?? 15_000;
+        this.logger = opts.logger;
+    }
+    async query(params) {
+        const baseUrl = getRagBaseUrl(this.baseUrlOverride);
+        const url = `${baseUrl}/query`;
+        const body = {
+            file_id: params.file_id,
+            query: params.query,
+            k: params.k ?? 10,
+        };
+        if (params.entity_id)
+            body.entity_id = params.entity_id;
+        if (params.scope)
+            body.scope = params.scope;
+        const headers = {
+            'Content-Type': 'application/json',
+            ...this.defaultHeaders,
+            ...(params.authHeaders ?? {}),
+        };
+        const timeoutMs = params.timeoutMs ?? this.defaultTimeoutMs;
+        const controller = typeof AbortController !== 'undefined' ? new AbortController() : null;
+        const timer = controller
+            ? setTimeout(() => controller.abort(), timeoutMs)
+            : null;
+        this.logger?.debug('[file_search] RAG query', {
+            url,
+            file_id: params.file_id,
+            k: body.k,
+        });
+        try {
+            const res = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify(body),
+                signal: controller?.signal,
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                throw new Error(`RAG query failed: ${res.status} ${res.statusText} — ${text.slice(0, 200)}`);
+            }
+            const json = (await res.json());
+            return this.normalize(params.file_id, json);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    /** Convert rag_api's tuple format into the library's normalized shape. */
+    normalize(file_id, resp) {
+        if (!Array.isArray(resp)) {
+            this.logger?.warn('[file_search] RAG response not an array', { resp });
+            return [];
+        }
+        return resp
+            .filter((row) => Array.isArray(row) && row.length === 2)
+            .map(([doc, distance]) => ({
+            file_id: doc?.metadata?.file_id ?? file_id,
+            page_content: doc?.page_content ?? '',
+            distance: typeof distance === 'number' ? distance : 1,
+            metadata: doc?.metadata,
+        }));
+    }
+}
+
+exports.HttpRagClient = HttpRagClient;
+exports.RAG_API_URL_ENV = RAG_API_URL_ENV;
+exports.getRagBaseUrl = getRagBaseUrl;
+//# sourceMappingURL=ragClient.cjs.map

package/dist/cjs/tools/fileSearch/ragClient.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ragClient.cjs","sources":["../../../../src/tools/fileSearch/ragClient.ts"],"sourcesContent":["/**\n * Default HTTP RAG client. Posts to `${baseUrl}/query` with the shape\n * rag_api expects (`{ file_id, query, k, entity_id? }`). Runtimes that\n * use a different vector backend implement their own `RagClient`.\n *\n * Auth is runtime-provided per call (via `authHeaders` on the params) so\n * short-lived tokens can be minted per request without the client\n * caching stale credentials.\n */\n\nimport fetch from 'node-fetch';\nimport { getEnvironmentVariable } from '@langchain/core/utils/env';\nimport type {\n  RagClient,\n  RagQueryParams,\n  RagChunk,\n  FileSearchToolLogger,\n} from './types';\n\nexport const RAG_API_URL_ENV = 'RAG_API_URL';\n\n/** Resolve base URL at call time so env-var changes propagate. */\nexport function getRagBaseUrl(override?: string): string {\n  const url =\n    override ??\n    getEnvironmentVariable(RAG_API_URL_ENV) ??\n    '';\n  if (!url) {\n    throw new Error(\n      `file_search: ${RAG_API_URL_ENV} is not configured. ` +\n        `Set the env var or pass baseUrl to HttpRagClient.`,\n    );\n  }\n  return url.replace(/\\/$/, '');\n}\n\nexport interface HttpRagClientOptions {\n  /** Base URL of the RAG service (no trailing slash). Falls back to env. */\n  baseUrl?: string;\n  /** Default headers sent on every request (e.g., a static API key). */\n  defaultHeaders?: Record<string, string>;\n  /** Default timeout if params don't override. Default 15_000. */\n  defaultTimeoutMs?: number;\n  logger?: FileSearchToolLogger;\n}\n\n/**\n * Expected rag_api response shape: `[[{ page_content, metadata }, distance], ...]`\n * — an array of [doc, score] tuples. Normalized here into `RagChunk[]`.\n */\ntype RagApiResponse = Array<\n  [\n    {\n      page_content: string;\n      metadata?: Record<string, unknown>;\n    },\n    number,\n  ]\n>;\n\nexport class HttpRagClient implements RagClient {\n  private readonly baseUrlOverride?: string;\n  private readonly defaultHeaders: Record<string, string>;\n  private readonly defaultTimeoutMs: number;\n  private readonly logger?: FileSearchToolLogger;\n\n  constructor(opts: HttpRagClientOptions = {}) {\n    this.baseUrlOverride = opts.baseUrl;\n    this.defaultHeaders = opts.defaultHeaders ?? {};\n    this.defaultTimeoutMs = opts.defaultTimeoutMs ?? 15_000;\n    this.logger = opts.logger;\n  }\n\n  async query(params: RagQueryParams): Promise<RagChunk[]> {\n    const baseUrl = getRagBaseUrl(this.baseUrlOverride);\n    const url = `${baseUrl}/query`;\n\n    const body: Record<string, unknown> = {\n      file_id: params.file_id,\n      query: params.query,\n      k: params.k ?? 10,\n    };\n    if (params.entity_id) body.entity_id = params.entity_id;\n    if (params.scope) body.scope = params.scope;\n\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n      ...this.defaultHeaders,\n      ...(params.authHeaders ?? {}),\n    };\n\n    const timeoutMs = params.timeoutMs ?? this.defaultTimeoutMs;\n    const controller =\n      typeof AbortController !== 'undefined' ? new AbortController() : null;\n    const timer = controller\n      ? setTimeout(() => controller.abort(), timeoutMs)\n      : null;\n\n    this.logger?.debug('[file_search] RAG query', {\n      url,\n      file_id: params.file_id,\n      k: body.k,\n    });\n\n    try {\n      const res = await fetch(url, {\n        method: 'POST',\n        headers,\n        body: JSON.stringify(body),\n        signal: controller?.signal as unknown as undefined,\n      });\n      if (!res.ok) {\n        const text = await res.text().catch(() => '');\n        throw new Error(\n          `RAG query failed: ${res.status} ${res.statusText} — ${text.slice(0, 200)}`,\n        );\n      }\n      const json = (await res.json()) as RagApiResponse;\n      return this.normalize(params.file_id, json);\n    } finally {\n      if (timer) clearTimeout(timer);\n    }\n  }\n\n  /** Convert rag_api's tuple format into the library's normalized shape. */\n  private normalize(file_id: string, resp: RagApiResponse): RagChunk[] {\n    if (!Array.isArray(resp)) {\n      this.logger?.warn('[file_search] RAG response not an array', { resp });\n      return [];\n    }\n    return resp\n      .filter((row) => Array.isArray(row) && row.length === 2)\n      .map(([doc, distance]) => ({\n        file_id:\n          (doc?.metadata?.file_id as string | undefined) ?? file_id,\n        page_content: doc?.page_content ?? '',\n        distance: typeof distance === 'number' ? distance : 1,\n        metadata: doc?.metadata,\n      }));\n  }\n}\n"],"names":["getEnvironmentVariable"],"mappings":"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"}

package/dist/cjs/tools/fileSearch/schema.cjs

@@ -0,0 +1,18 @@
+'use strict';
+
+var zod = require('zod');
+
+const fileSearchInputSchema = zod.z.object({
+    query: zod.z
+        .string()
+        .describe("A natural language query to search for relevant information in the files. Be SPECIFIC and TARGETED — use keywords for the specific section or topic you need. For comprehensive tasks (summaries, overviews), call this tool multiple times with different targeted queries (e.g., 'introduction', 'methodology', 'results', 'conclusions') rather than one broad query."),
+    target_files: zod.z
+        .array(zod.z.string())
+        .optional()
+        .describe('Optional list of filenames (or partial names) to limit the search to. When provided, only files whose name contains one of these strings will be searched. Use this to avoid searching irrelevant files. Omit to search all available files.'),
+});
+const FileSearchToolName = 'file_search';
+
+exports.FileSearchToolName = FileSearchToolName;
+exports.fileSearchInputSchema = fileSearchInputSchema;
+//# sourceMappingURL=schema.cjs.map

package/dist/cjs/tools/fileSearch/schema.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.cjs","sources":["../../../../src/tools/fileSearch/schema.ts"],"sourcesContent":["import { z } from 'zod';\n\nexport const fileSearchInputSchema = z.object({\n  query: z\n    .string()\n    .describe(\n      \"A natural language query to search for relevant information in the files. Be SPECIFIC and TARGETED — use keywords for the specific section or topic you need. For comprehensive tasks (summaries, overviews), call this tool multiple times with different targeted queries (e.g., 'introduction', 'methodology', 'results', 'conclusions') rather than one broad query.\",\n    ),\n  target_files: z\n    .array(z.string())\n    .optional()\n    .describe(\n      'Optional list of filenames (or partial names) to limit the search to. When provided, only files whose name contains one of these strings will be searched. Use this to avoid searching irrelevant files. Omit to search all available files.',\n    ),\n});\n\nexport type FileSearchInput = z.infer<typeof fileSearchInputSchema>;\n\nexport const FileSearchToolName = 'file_search';\n"],"names":["z"],"mappings":";;;;AAEO,MAAM,qBAAqB,GAAGA,KAAC,CAAC,MAAM,CAAC;AAC5C,IAAA,KAAK,EAAEA;AACJ,SAAA,MAAM;SACN,QAAQ,CACP,0WAA0W,CAC3W;AACH,IAAA,YAAY,EAAEA;AACX,SAAA,KAAK,CAACA,KAAC,CAAC,MAAM,EAAE;AAChB,SAAA,QAAQ;SACR,QAAQ,CACP,8OAA8O,CAC/O;AACJ,CAAA;AAIM,MAAM,kBAAkB,GAAG;;;;;"}

package/dist/cjs/tools/fileSearch/tool.cjs

@@ -0,0 +1,155 @@
+'use strict';
+
+var tools = require('@langchain/core/tools');
+var schema = require('./schema.cjs');
+var formatter = require('./formatter.cjs');
+
+/**
+ * file_search tool factory — library-native equivalent of the CodeExecutor
+ * pattern. Runtimes supply a `RagClient`, the file list for this turn, and
+ * an optional formatter (ranger uses citation anchors; CLI/A2A use plain
+ * text).
+ *
+ * The tool itself:
+ *   1. Accepts `{ query, target_files? }` from the LLM.
+ *   2. Filters files by `target_files` substring match when provided.
+ *   3. Queries each file in bounded concurrent batches.
+ *   4. Enforces per-file timeouts (failures isolated per file).
+ *   5. Flattens chunks, deprioritizes stale-turn files, caps results.
+ *   6. Hands formatted output to the runtime's formatter for final shape.
+ */
+const DEFAULT_QUERY_TIMEOUT_MS = 15_000;
+const DEFAULT_CONCURRENCY = 10;
+const DEFAULT_TOP_K = 10;
+/**
+ * Build the tool description. Runtimes that use citation anchors supply
+ * `fileCitations: true` (via the formatter); the description includes the
+ * citation ruleset only when that's on.
+ */
+function buildDescription(opts) {
+    const core = `Performs semantic search across the attached "${schema.FileSearchToolName}" documents using natural language queries. Analyzes the content of loaded files to find relevant information, quotes, and passages matching the query.
+
+**Use target_files to narrow the search:**
+When you know which file(s) contain the relevant information, ALWAYS pass target_files. This is faster and returns more focused results. Pass partial filenames — they match via substring.
+
+**Multiple searches for thorough analysis:**
+For summaries/overviews, call this tool MULTIPLE times with DIFFERENT queries targeting different aspects (intro, methodology, results, conclusions). A single search only returns chunks from one part of the document.`;
+    if (!opts.fileCitations)
+        return core;
+    return `${core}
+
+**CITING FILE SEARCH RESULTS — MANDATORY:**
+Cite EVERY statement derived from file content. Place the citation anchor IMMEDIATELY after each paragraph using that source. Each search result has a unique source index — use DIFFERENT indices for different claims; do not reuse the same anchor for all paragraphs. Format: \`\\ue202turn0fileN\`. With a page: include \`(p. N)\` inline. Multiple sources: \`\\ue200\\ue202turn0file0\\ue202turn0file1\\ue201\`. NEVER substitute with footnotes, brackets, or symbols.`;
+}
+function createFileSearchTool(config) {
+    const { ragClient, files, entity_id, scope, getAuthHeaders, formatter: formatter$1 = formatter.plainTextFormatter, queryTimeoutMs = DEFAULT_QUERY_TIMEOUT_MS, concurrencyLimit = DEFAULT_CONCURRENCY, topK = DEFAULT_TOP_K, resultCap, callbacks, logger, } = config;
+    // Monotonic call counter used by citation-style formatters to keep source
+    // indices unique across multiple invocations within a single turn.
+    let callIndex = 0;
+    // Infer whether the formatter wants citations from the artifact it emits
+    // on an empty-chunk format. This keeps the description/behavior aligned
+    // without forcing the host to declare `fileCitations` twice.
+    const fileCitations = formatter$1 !== formatter.plainTextFormatter;
+    return tools.tool(async (rawInput) => {
+        const { query, target_files } = rawInput;
+        if (files.length === 0) {
+            return [
+                'No files to search. Instruct the user to add files for the search.',
+                undefined,
+            ];
+        }
+        // target_files: case-insensitive substring match, fallback to all
+        // files with a warning if the filter excludes everything.
+        let filesToQuery = files;
+        if (target_files && target_files.length > 0) {
+            const lowerTargets = target_files.map((t) => t.toLowerCase());
+            const matched = files.filter((f) => lowerTargets.some((t) => f.filename.toLowerCase().includes(t)));
+            if (matched.length === 0) {
+                logger?.warn(`[file_search] No files matched target_files ${target_files.join(', ')}; falling back to all files`);
+                filesToQuery = files;
+            }
+            else {
+                logger?.info(`[file_search] Filtered to ${matched.length}/${files.length} via target_files`);
+                filesToQuery = matched;
+            }
+        }
+        const authHeaders = getAuthHeaders ? await getAuthHeaders() : undefined;
+        const queryOne = async (file) => {
+            const params = {
+                file_id: file.file_id,
+                query,
+                k: topK,
+                entity_id,
+                scope,
+                authHeaders,
+                timeoutMs: queryTimeoutMs,
+            };
+            try {
+                const chunks = await ragClient.query(params);
+                callbacks?.onFileQueried?.(file, chunks.length);
+                return chunks;
+            }
+            catch (err) {
+                const e = err instanceof Error ? err : new Error(String(err));
+                logger?.error(`[file_search] Query failed for ${file.filename}: ${e.message}`);
+                callbacks?.onFileError?.(file, e);
+                return [];
+            }
+        };
+        // Bounded-concurrency batching. Server-side rerankers handle their
+        // own concurrency; this protects the HTTP connection pool when the
+        // agent has many files.
+        const allChunks = [];
+        for (let i = 0; i < filesToQuery.length; i += concurrencyLimit) {
+            const batch = filesToQuery.slice(i, i + concurrencyLimit);
+            const batchResults = await Promise.all(batch.map(queryOne));
+            for (const chunks of batchResults)
+                allChunks.push(...chunks);
+        }
+        if (allChunks.length === 0) {
+            return [
+                'No content found in the files. The files may not have been processed correctly or the query may need refinement.',
+                undefined,
+            ];
+        }
+        // Build annotated results: attach filename + isCurrentMessage via
+        // a file-id lookup (metadata wins, factory list is fallback).
+        const fileById = new Map(files.map((f) => [f.file_id, f]));
+        const annotated = allChunks.map((c) => {
+            const matched = fileById.get(c.file_id);
+            const filename = (c.metadata?.source
+                ? String(c.metadata.source).split(/[/\\]/).pop()
+                : undefined) ??
+                matched?.filename ??
+                'Unknown';
+            return {
+                ...c,
+                filename,
+                isCurrentMessage: matched?.isCurrentMessage === true,
+            };
+        });
+        // Sort: current-turn files first, then by relevance (lower distance).
+        annotated.sort((a, b) => {
+            if (a.isCurrentMessage !== b.isCurrentMessage)
+                return a.isCurrentMessage ? -1 : 1;
+            return a.distance - b.distance;
+        });
+        const cap = resultCap ?? Math.max(10, filesToQuery.length * 3);
+        const limited = annotated.slice(0, cap);
+        const { message, artifact } = formatter$1.format(limited, {
+            callIndex,
+            files,
+        });
+        callIndex += 1;
+        return [message, artifact];
+    }, {
+        name: schema.FileSearchToolName,
+        responseFormat: 'content_and_artifact',
+        description: buildDescription({ fileCitations }),
+        schema: schema.fileSearchInputSchema,
+    });
+}
+
+exports.FileSearchToolName = schema.FileSearchToolName;
+exports.createFileSearchTool = createFileSearchTool;
+//# sourceMappingURL=tool.cjs.map

package/dist/cjs/tools/fileSearch/tool.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.cjs","sources":["../../../../src/tools/fileSearch/tool.ts"],"sourcesContent":["/**\n * file_search tool factory — library-native equivalent of the CodeExecutor\n * pattern. Runtimes supply a `RagClient`, the file list for this turn, and\n * an optional formatter (ranger uses citation anchors; CLI/A2A use plain\n * text).\n *\n * The tool itself:\n *   1. Accepts `{ query, target_files? }` from the LLM.\n *   2. Filters files by `target_files` substring match when provided.\n *   3. Queries each file in bounded concurrent batches.\n *   4. Enforces per-file timeouts (failures isolated per file).\n *   5. Flattens chunks, deprioritizes stale-turn files, caps results.\n *   6. Hands formatted output to the runtime's formatter for final shape.\n */\n\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport {\n  fileSearchInputSchema,\n  type FileSearchInput,\n  FileSearchToolName,\n} from './schema';\nimport type {\n  FileSearchToolConfig,\n  FileSearchFile,\n  RagChunk,\n  RagQueryParams,\n} from './types';\nimport { plainTextFormatter } from './formatter';\n\nconst DEFAULT_QUERY_TIMEOUT_MS = 15_000;\nconst DEFAULT_CONCURRENCY = 10;\nconst DEFAULT_TOP_K = 10;\n\n/**\n * Build the tool description. Runtimes that use citation anchors supply\n * `fileCitations: true` (via the formatter); the description includes the\n * citation ruleset only when that's on.\n */\nfunction buildDescription(opts: { fileCitations: boolean }): string {\n  const core = `Performs semantic search across the attached \"${FileSearchToolName}\" documents using natural language queries. Analyzes the content of loaded files to find relevant information, quotes, and passages matching the query.\n\n**Use target_files to narrow the search:**\nWhen you know which file(s) contain the relevant information, ALWAYS pass target_files. This is faster and returns more focused results. Pass partial filenames — they match via substring.\n\n**Multiple searches for thorough analysis:**\nFor summaries/overviews, call this tool MULTIPLE times with DIFFERENT queries targeting different aspects (intro, methodology, results, conclusions). A single search only returns chunks from one part of the document.`;\n\n  if (!opts.fileCitations) return core;\n\n  return `${core}\n\n**CITING FILE SEARCH RESULTS — MANDATORY:**\nCite EVERY statement derived from file content. Place the citation anchor IMMEDIATELY after each paragraph using that source. Each search result has a unique source index — use DIFFERENT indices for different claims; do not reuse the same anchor for all paragraphs. Format: \\`\\\\ue202turn0fileN\\`. With a page: include \\`(p. N)\\` inline. Multiple sources: \\`\\\\ue200\\\\ue202turn0file0\\\\ue202turn0file1\\\\ue201\\`. NEVER substitute with footnotes, brackets, or symbols.`;\n}\n\nexport function createFileSearchTool(\n  config: FileSearchToolConfig,\n): DynamicStructuredTool {\n  const {\n    ragClient,\n    files,\n    entity_id,\n    scope,\n    getAuthHeaders,\n    formatter = plainTextFormatter,\n    queryTimeoutMs = DEFAULT_QUERY_TIMEOUT_MS,\n    concurrencyLimit = DEFAULT_CONCURRENCY,\n    topK = DEFAULT_TOP_K,\n    resultCap,\n    callbacks,\n    logger,\n  } = config;\n\n  // Monotonic call counter used by citation-style formatters to keep source\n  // indices unique across multiple invocations within a single turn.\n  let callIndex = 0;\n\n  // Infer whether the formatter wants citations from the artifact it emits\n  // on an empty-chunk format. This keeps the description/behavior aligned\n  // without forcing the host to declare `fileCitations` twice.\n  const fileCitations = formatter !== plainTextFormatter;\n\n  return tool(\n    async (rawInput: FileSearchInput) => {\n      const { query, target_files } = rawInput;\n\n      if (files.length === 0) {\n        return [\n          'No files to search. Instruct the user to add files for the search.',\n          undefined,\n        ];\n      }\n\n      // target_files: case-insensitive substring match, fallback to all\n      // files with a warning if the filter excludes everything.\n      let filesToQuery: FileSearchFile[] = files;\n      if (target_files && target_files.length > 0) {\n        const lowerTargets = target_files.map((t) => t.toLowerCase());\n        const matched = files.filter((f) =>\n          lowerTargets.some((t) => f.filename.toLowerCase().includes(t)),\n        );\n        if (matched.length === 0) {\n          logger?.warn(\n            `[file_search] No files matched target_files ${target_files.join(', ')}; falling back to all files`,\n          );\n          filesToQuery = files;\n        } else {\n          logger?.info(\n            `[file_search] Filtered to ${matched.length}/${files.length} via target_files`,\n          );\n          filesToQuery = matched;\n        }\n      }\n\n      const authHeaders = getAuthHeaders ? await getAuthHeaders() : undefined;\n\n      const queryOne = async (file: FileSearchFile): Promise<RagChunk[]> => {\n        const params: RagQueryParams = {\n          file_id: file.file_id,\n          query,\n          k: topK,\n          entity_id,\n          scope,\n          authHeaders,\n          timeoutMs: queryTimeoutMs,\n        };\n        try {\n          const chunks = await ragClient.query(params);\n          callbacks?.onFileQueried?.(file, chunks.length);\n          return chunks;\n        } catch (err) {\n          const e = err instanceof Error ? err : new Error(String(err));\n          logger?.error(\n            `[file_search] Query failed for ${file.filename}: ${e.message}`,\n          );\n          callbacks?.onFileError?.(file, e);\n          return [];\n        }\n      };\n\n      // Bounded-concurrency batching. Server-side rerankers handle their\n      // own concurrency; this protects the HTTP connection pool when the\n      // agent has many files.\n      const allChunks: RagChunk[] = [];\n      for (let i = 0; i < filesToQuery.length; i += concurrencyLimit) {\n        const batch = filesToQuery.slice(i, i + concurrencyLimit);\n        const batchResults = await Promise.all(batch.map(queryOne));\n        for (const chunks of batchResults) allChunks.push(...chunks);\n      }\n\n      if (allChunks.length === 0) {\n        return [\n          'No content found in the files. The files may not have been processed correctly or the query may need refinement.',\n          undefined,\n        ];\n      }\n\n      // Build annotated results: attach filename + isCurrentMessage via\n      // a file-id lookup (metadata wins, factory list is fallback).\n      const fileById = new Map(files.map((f) => [f.file_id, f]));\n      const annotated = allChunks.map((c) => {\n        const matched = fileById.get(c.file_id);\n        const filename =\n          (c.metadata?.source\n            ? String(c.metadata.source).split(/[/\\\\]/).pop()\n            : undefined) ??\n          matched?.filename ??\n          'Unknown';\n        return {\n          ...c,\n          filename,\n          isCurrentMessage: matched?.isCurrentMessage === true,\n        };\n      });\n\n      // Sort: current-turn files first, then by relevance (lower distance).\n      annotated.sort((a, b) => {\n        if (a.isCurrentMessage !== b.isCurrentMessage)\n          return a.isCurrentMessage ? -1 : 1;\n        return a.distance - b.distance;\n      });\n\n      const cap = resultCap ?? Math.max(10, filesToQuery.length * 3);\n      const limited = annotated.slice(0, cap);\n\n      const { message, artifact } = formatter.format(limited, {\n        callIndex,\n        files,\n      });\n      callIndex += 1;\n\n      // Suppress unused-variable warning for fileCitations (currently only\n      // used to gate description; kept in case formatters need it).\n      void fileCitations;\n\n      return [message, artifact];\n    },\n    {\n      name: FileSearchToolName,\n      responseFormat: 'content_and_artifact',\n      description: buildDescription({ fileCitations }),\n      schema: fileSearchInputSchema,\n    },\n  );\n}\n\nexport { FileSearchToolName } from './schema';\n"],"names":["FileSearchToolName","formatter","plainTextFormatter","tool","fileSearchInputSchema"],"mappings":"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"}

package/dist/esm/main.mjs

@@ -26,11 +26,14 @@ export { handleServerToolResult, handleToolCallChunks, handleToolCalls, toolResu
 export { createSearchTool } from './tools/search/tool.mjs';
 export { DATE_RANGE, DEFAULT_COUNTRY_DESCRIPTION, DEFAULT_QUERY_DESCRIPTION, WebSearchToolDefinition, WebSearchToolDescription, WebSearchToolName, WebSearchToolSchema, countrySchema, dateSchema, imagesSchema, newsSchema, querySchema, videosSchema } from './tools/search/schema.mjs';
 export { buildMemoryTools } from './tools/memory/index.mjs';
+export { createFileSearchTool } from './tools/fileSearch/tool.mjs';
+export { HttpRagClient, RAG_API_URL_ENV, getRagBaseUrl } from './tools/fileSearch/ragClient.mjs';
+export { createCitationAnchorFormatter, plainTextFormatter } from './tools/fileSearch/formatter.mjs';
+export { FileSearchToolName, fileSearchInputSchema } from './tools/fileSearch/schema.mjs';
 export { buildProxyTool } from './tools/proxyTool.mjs';
 export { AuthSource, CapabilityKind } from './providers/types.mjs';
 export { CAPABILITY_NAME_SEPARATOR, formatCapabilityName, parseCapabilityName } from './providers/capabilityNaming.mjs';
 export { ToolsServerCapabilityProvider } from './providers/tools-server/ToolsServerCapabilityProvider.mjs';
-export { CompositeCapabilityProvider } from './providers/composite/CompositeCapabilityProvider.mjs';
 export { MCPCapabilityProvider, flattenToolCallResponse } from './providers/mcp/MCPCapabilityProvider.mjs';
 export { createTransport } from './providers/mcp/transport.mjs';
 export { getMCPEnvDefaults, consoleLogger as mcpConsoleLogger } from './providers/mcp/config.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/tools/fileSearch/formatter.mjs

@@ -0,0 +1,92 @@
+/**
+ * Default result formatters.
+ *
+ * - `plainTextFormatter`: CLI / A2A / generic output. No citation anchors.
+ * - `citationAnchorFormatter`: ranger-style `\ue202turn0fileN` anchors with
+ *   a monotonic `sourceOffset` so multi-call turns stay globally unique.
+ *
+ * Runtimes can supply their own `FileSearchResultFormatter` to override.
+ */
+const plainTextFormatter = {
+    format(chunks, { files: _files }) {
+        if (chunks.length === 0) {
+            return { message: 'No relevant results found in the available files.' };
+        }
+        const body = chunks
+            .map((c) => {
+            const page = getPage(c);
+            const rel = (1 - c.distance).toFixed(4);
+            return (`File: ${c.filename}` +
+                (page != null ? `\nPage: ${page}` : '') +
+                `\nRelevance: ${rel}\nContent: ${c.page_content}\n`);
+        })
+            .join('\n---\n');
+        const sources = chunks.map((c) => ({
+            type: 'file',
+            fileId: c.file_id,
+            content: c.page_content,
+            fileName: c.filename,
+            relevance: 1 - c.distance,
+            pages: getPage(c) != null ? [getPage(c)] : [],
+        }));
+        return { message: body, artifact: { file_search: { sources } } };
+    },
+};
+function createCitationAnchorFormatter(opts = {}) {
+    const toolName = opts.toolName ?? 'file_search';
+    const getOffset = opts.getSourceOffset ?? (() => 0);
+    const advance = opts.advanceSourceOffset ?? (() => { });
+    return {
+        format(chunks) {
+            if (chunks.length === 0) {
+                return {
+                    message: 'No results found or errors occurred while searching the files.',
+                };
+            }
+            const base = getOffset();
+            const body = chunks
+                .map((c, i) => {
+                const globalIndex = base + i;
+                const page = getPage(c);
+                const rel = (1 - c.distance).toFixed(4);
+                return (`[Source ${globalIndex}] File: ${c.filename} | Anchor: \\ue202turn0file${globalIndex}` +
+                    (page != null ? ` | Page: ${page}` : '') +
+                    ` | Relevance: ${rel}\nContent: ${c.page_content}\n` +
+                    `↑ Cite this source using: \\ue202turn0file${globalIndex}`);
+            })
+                .join('\n---\n');
+            const sources = chunks.map((c) => ({
+                type: 'file',
+                fileId: c.file_id,
+                content: c.page_content,
+                fileName: c.filename,
+                relevance: 1 - c.distance,
+                pages: getPage(c) != null ? [getPage(c)] : [],
+                pageRelevance: getPage(c) != null
+                    ? { [getPage(c)]: 1 - c.distance }
+                    : {},
+            }));
+            advance(chunks.length);
+            return {
+                message: body,
+                artifact: { [toolName]: { sources, fileCitations: true } },
+            };
+        },
+    };
+}
+/** Extract a 1-indexed page number from the chunk metadata, or null. */
+function getPage(chunk) {
+    const raw = chunk.metadata?.page ??
+        chunk.metadata?.page_number ??
+        null;
+    if (raw == null)
+        return null;
+    const parsed = typeof raw === 'number' ? raw : parseInt(String(raw), 10);
+    if (Number.isNaN(parsed) || parsed < 0)
+        return null;
+    // rag_api stores 0-indexed; display is 1-indexed
+    return parsed + 1;
+}
+
+export { createCitationAnchorFormatter, plainTextFormatter };
+//# sourceMappingURL=formatter.mjs.map