@dudousxd/nestjs-agent-rag 0.11.0 → 0.13.0

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DEFAULT_STOP_WORDS: () => DEFAULT_STOP_WORDS,
   EmbeddingRetriever: () => EmbeddingRetriever,
   FilteredRetriever: () => FilteredRetriever,
   HttpModelError: () => HttpModelError,
@@ -28,7 +29,9 @@ __export(index_exports, {
   HybridRetriever: () => HybridRetriever,
   KeywordRetriever: () => KeywordRetriever,
   LexicalRetriever: () => LexicalRetriever,
+  MemoryDocumentTreeStore: () => MemoryDocumentTreeStore,
   MemoryVectorStore: () => MemoryVectorStore,
+  PgDocumentTreeStore: () => PgDocumentTreeStore,
   PgLexicalVectorStore: () => PgLexicalVectorStore,
   PgVectorStore: () => PgVectorStore,
   RAG_DIAGNOSTIC_LIB: () => RAG_DIAGNOSTIC_LIB,
@@ -37,31 +40,52 @@ __export(index_exports, {
   RedisVectorSchemaMismatchError: () => RedisVectorSchemaMismatchError,
   RedisVectorStore: () => RedisVectorStore,
   RerankingRetriever: () => RerankingRetriever,
+  TreeBudgetExceededError: () => TreeBudgetExceededError,
+  TreeNavigationRetriever: () => TreeNavigationRetriever,
+  TwoStageRetriever: () => TwoStageRetriever,
   UnsafeRemovalError: () => UnsafeRemovalError,
+  anyTermTsquery: () => anyTermTsquery,
   applyMetadataPatch: () => applyMetadataPatch,
+  buildDocumentTree: () => buildDocumentTree,
+  cachedTreeLlm: () => cachedTreeLlm,
   chunkDocuments: () => chunkDocuments,
   chunkIndexOf: () => chunkIndexOf,
   chunkText: () => chunkText,
+  createNavigateDocumentTool: () => createNavigateDocumentTool,
   createRetrievalTool: () => createRetrievalTool,
   describeRetrieval: () => describeRetrieval,
   describeSharedSource: () => describeSharedSource,
   describeSource: () => describeSource,
   describesRetrieval: () => describesRetrieval,
+  detectHeadings: () => detectHeadings,
   documentIdOf: () => documentIdOf,
   emitRagRetrieval: () => emitRagRetrieval,
+  estimateTokens: () => estimateTokens,
+  hasSearchSyntax: () => hasSearchSyntax,
+  indexDocumentTree: () => indexDocumentTree,
+  indexTree: () => indexTree,
   ingestChunks: () => ingestChunks,
   ingestDocuments: () => ingestDocuments,
   instrumentRetriever: () => instrumentRetriever,
+  isBatchTooLarge: () => isBatchTooLarge,
   isLexicalVectorStore: () => isLexicalVectorStore,
+  keywordTerms: () => keywordTerms,
+  keywordTreeLlm: () => keywordTreeLlm,
+  openAiChatTreeLlm: () => openAiChatTreeLlm,
   openAiEmbeddings: () => openAiEmbeddings,
-  toPgClient: () => toPgClient
+  parseJsonReply: () => parseJsonReply,
+  spanText: () => spanText,
+  stableHash: () => stableHash,
+  toPgClient: () => toPgClient,
+  treeLlmFromModelProvider: () => treeLlmFromModelProvider,
+  walkTree: () => walkTree
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/chunk.ts
 function chunkText(text, options = {}) {
   const chunkSize = options.chunkSize ?? 800;
-  const overlap = options.overlap ?? 100;
+  const overlap2 = options.overlap ?? 100;
   const normalized = text.trim();
   if (normalized.length === 0) {
     return [];
@@ -93,7 +117,7 @@ function chunkText(text, options = {}) {
     if (breakAt >= normalized.length) {
       break;
     }
-    start = Math.max(breakAt - overlap, start + 1);
+    start = Math.max(breakAt - overlap2, start + 1);
   }
   return chunks;
 }
@@ -120,12 +144,12 @@ function chunkByRecord(text, chunkSize, separator) {
       }));
       continue;
     }
-    const candidate = current.length > 0 ? `${current}${separator}${trimmed}` : trimmed;
-    if (candidate.length > chunkSize) {
+    const candidate2 = current.length > 0 ? `${current}${separator}${trimmed}` : trimmed;
+    if (candidate2.length > chunkSize) {
       flush();
       current = trimmed;
     } else {
-      current = candidate;
+      current = candidate2;
     }
   }
   flush();
@@ -413,6 +437,81 @@ function cosineSimilarity(a, b) {
 }
 __name(cosineSimilarity, "cosineSimilarity");
 
+// src/lexical-query.ts
+var words = /* @__PURE__ */ __name((s) => new Set(s.split(/\s+/).filter(Boolean)), "words");
+var DEFAULT_STOP_WORDS = {
+  english: words(`
+    me my myself we our ours ourselves you your yours yourself yourselves he him his himself she
+    her hers herself it its itself they them their theirs themselves what which who whom this that
+    these those am is are was were be been being have has had having do does did doing an the and
+    but if or because as until while of at by for with about against between into through during
+    before after above below to from up down in out on off over under again further then once here
+    there when where why how all any both each few more most other some such no nor not only own
+    same so than too very can will just don should now`),
+  portuguese: words(`
+    de que do da em um para com n\xE3o uma os no se na por mais as dos como mas ao ele das seu sua ou
+    quando muito nos j\xE1 eu tamb\xE9m s\xF3 pelo pela at\xE9 isso ela entre depois sem mesmo aos seus quem
+    nas me esse eles voc\xEA essa num nem suas meu \xE0s minha numa pelos elas qual n\xF3s lhe deles essas
+    esses pelas este dele tu te voc\xEAs vos lhes meus minhas teu tua teus tuas nosso nossa nossos
+    nossas dela delas esta estes estas aquele aquela aqueles aquelas isto aquilo estou est\xE1 estamos
+    est\xE3o estive esteve estivemos estiveram estava est\xE1vamos estavam estivera estiv\xE9ramos esteja
+    estejamos estejam estivesse estiv\xE9ssemos estivessem estiver estivermos estiverem hei h\xE1 havemos
+    h\xE3o houve houvemos houveram houvera houv\xE9ramos haja hajamos hajam houvesse houv\xE9ssemos
+    houvessem houver houvermos houverem houverei houver\xE1 houveremos houver\xE3o houveria houver\xEDamos
+    houveriam sou somos s\xE3o era \xE9ramos eram fui foi fomos foram fora f\xF4ramos seja sejamos sejam
+    fosse f\xF4ssemos fossem for formos forem serei ser\xE1 seremos ser\xE3o seria ser\xEDamos seriam tenho tem
+    temos t\xE9m tinha t\xEDnhamos tinham tive teve tivemos tiveram tivera tiv\xE9ramos tenha tenhamos
+    tenham tivesse tiv\xE9ssemos tivessem tiver tivermos tiverem terei ter\xE1 teremos ter\xE3o teria
+    ter\xEDamos teriam`),
+  spanish: words(`
+    de la que el en los del se las por un para con no una su al lo como m\xE1s pero sus le ya este s\xED
+    porque esta entre cuando muy sin sobre tambi\xE9n me hasta hay donde quien desde todo nos durante
+    todos uno les ni contra otros ese eso ante ellos esto m\xED antes algunos qu\xE9 unos yo otro otras
+    otra \xE9l tanto esa estos mucho quienes nada muchos cual poco ella estar estas algunas algo
+    nosotros mi mis t\xFA te ti tu tus ellas nosotras vosotros vosotras os m\xEDo m\xEDa m\xEDos m\xEDas tuyo
+    tuya tuyos tuyas suyo suya suyos suyas nuestro nuestra nuestros nuestras vuestro vuestra
+    vuestros vuestras esos esas estoy est\xE1s est\xE1 estamos est\xE1is est\xE1n est\xE9 est\xE9s estemos est\xE9is
+    est\xE9n estar\xE9 estar\xE1s estar\xE1 estaremos estar\xE9is estar\xE1n estar\xEDa estar\xEDas estar\xEDamos estar\xEDais
+    estar\xEDan estaba estabas est\xE1bamos estabais estaban estuve estuviste estuvo estuvimos
+    estuvisteis estuvieron estuviera estuvieras estuvi\xE9ramos estuvierais estuvieran estuviese
+    estuvieses estuvi\xE9semos estuvieseis estuviesen estando estad he has ha hemos hab\xE9is han haya
+    hayas hayamos hay\xE1is hayan habr\xE9 habr\xE1s habr\xE1 habremos habr\xE9is habr\xE1n habr\xEDa habr\xEDas habr\xEDamos
+    habr\xEDais habr\xEDan hab\xEDa hab\xEDas hab\xEDamos hab\xEDais hab\xEDan hube hubiste hubo hubimos hubisteis
+    hubieron hubiera hubieras hubi\xE9ramos hubierais hubieran hubiese hubieses hubi\xE9semos hubieseis
+    hubiesen habiendo habido habida habidos habidas soy eres es somos sois son sea seas seamos
+    se\xE1is sean ser\xE9 ser\xE1s ser\xE1 seremos ser\xE9is ser\xE1n ser\xEDa ser\xEDas ser\xEDamos ser\xEDais ser\xEDan era eras
+    \xE9ramos erais eran fui fuiste fue fuimos fuisteis fueron fuera fueras fu\xE9ramos fuerais fueran
+    fuese fueses fu\xE9semos fueseis fuesen tengo tienes tiene tenemos ten\xE9is tienen tenga tengas
+    tengamos teng\xE1is tengan tendr\xE9 tendr\xE1s tendr\xE1 tendremos tendr\xE9is tendr\xE1n tendr\xEDa tendr\xEDas
+    tendr\xEDamos tendr\xEDais tendr\xEDan ten\xEDa ten\xEDas ten\xEDamos ten\xEDais ten\xEDan tuve tuviste tuvo tuvimos
+    tuvisteis tuvieron tuviera tuvieras tuvi\xE9ramos tuvierais tuvieran tuviese tuvieses tuvi\xE9semos
+    tuvieseis tuviesen teniendo tenido tenida tenidos tenidas tened`)
+};
+var TOKEN = /[\p{L}\p{N}]{2,}/gu;
+function keywordTerms(query, max = 24, stopWords = DEFAULT_STOP_WORDS) {
+  const tokens = [
+    ...new Set(query.toLowerCase().normalize("NFC").match(TOKEN) ?? [])
+  ];
+  const counts = Object.entries(stopWords).map(([, stop2]) => [
+    stop2,
+    tokens.filter((t) => stop2.has(t)).length
+  ]);
+  const best = Math.max(0, ...counts.map(([, n]) => n));
+  if (best === 0) return tokens.slice(0, max);
+  const stop = counts.filter(([, n]) => n === best).map(([s]) => s);
+  const terms2 = tokens.filter((t) => !stop.some((s) => s.has(t)));
+  return (terms2.length > 0 ? terms2 : tokens).slice(0, max);
+}
+__name(keywordTerms, "keywordTerms");
+function hasSearchSyntax(query) {
+  return /"[^"]+"/.test(query) || /(^|\s)-[\p{L}\p{N}]/u.test(query);
+}
+__name(hasSearchSyntax, "hasSearchSyntax");
+function anyTermTsquery(terms2) {
+  return terms2.map((t) => `'${t.replace(/'/g, "")}'`).join(" | ");
+}
+__name(anyTermTsquery, "anyTermTsquery");
+
 // src/pg-client.ts
 var ADAPTED = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent-rag/pg-client");
 function toPgClient(source) {
@@ -871,6 +970,7 @@ var PgLexicalVectorStore = class extends PgVectorStore {
   tsConfig;
   tsColumn;
   anyTermFallback;
+  stopWords;
   constructor(client, options = {}) {
     super(client, options);
     const config = options.fullText?.config ?? "simple";
@@ -884,6 +984,8 @@ var PgLexicalVectorStore = class extends PgVectorStore {
     this.tsConfig = config;
     this.tsColumn = column;
     this.anyTermFallback = options.fullText?.anyTermFallback ?? true;
+    const stopWords = options.fullText?.stopWords;
+    this.stopWords = stopWords === false ? {} : stopWords ?? DEFAULT_STOP_WORDS;
   }
   schemaStatements() {
     const statements = super.schemaStatements();
@@ -897,19 +999,18 @@ var PgLexicalVectorStore = class extends PgVectorStore {
     if (filterMatchesNothing(options.filter) || query.trim() === "") {
       return [];
     }
-    const all = await this.runTextSearch(`websearch_to_tsquery('${this.tsConfig}', $1)`, query, options);
-    if (all.length > 0 || !this.anyTermFallback) {
-      return all;
-    }
-    const terms = [
-      ...new Set(query.toLowerCase().match(/[\p{L}\p{N}]{2,}/gu) ?? [])
-    ].slice(0, 24);
-    if (terms.length < 2) {
-      return all;
+    if (!this.anyTermFallback || hasSearchSyntax(query)) {
+      const strict = await this.runTextSearch(query, options);
+      if (strict.length > 0 || !this.anyTermFallback) {
+        return strict;
+      }
     }
-    return this.runTextSearch(`to_tsquery('${this.tsConfig}', $1)`, terms.map((term) => `'${term}'`).join(" | "), options);
+    const terms2 = keywordTerms(query, 24, this.stopWords);
+    return terms2.length === 0 ? [] : this.runRankedTermSearch(terms2, options);
   }
-  async runTextSearch(tsquery, query, options) {
+  /** `websearch_to_tsquery` on the query as written: every word, quoted phrases, `-exclusions`. */
+  async runTextSearch(query, options) {
+    const tsquery = `websearch_to_tsquery('${this.tsConfig}', $1)`;
     const params = [
       query,
       options.topK
@@ -925,6 +1026,47 @@ var PgLexicalVectorStore = class extends PgVectorStore {
        LIMIT $2`, params);
     return rows.map(toPassage);
   }
+  /**
+  * Rows holding any of `terms`, ranked by the sum of the matched terms' IDF among those rows,
+  * `ln(1 + (N - df + 0.5) / (df + 0.5))`, then `ts_rank_cd`. Each (row, term) match is evaluated
+  * once, and `ts_rank_cd` only for the rows ranked within `topK` (ties included): a question full
+  * of common words can match most of the table.
+  */
+  async runRankedTermSearch(terms2, options) {
+    const any = `to_tsquery('${this.tsConfig}', $1)`;
+    const params = [
+      anyTermTsquery(terms2),
+      options.topK,
+      terms2
+    ];
+    const conditions = [
+      `${this.tsvector()} @@ ${any}`,
+      ...this.whereConditions(options.filter, params)
+    ];
+    const rows = await this.client.query(`WITH __terms AS (
+         SELECT DISTINCT to_tsquery('${this.tsConfig}', quote_literal(t)) AS q
+         FROM unnest($3::text[]) AS t
+       ), __cand AS MATERIALIZED (
+         SELECT id, text, source, metadata, ${this.tsvector()} AS __tsv
+         FROM ${this.table}
+         WHERE ${conditions.join(" AND ")}
+       ), __hits AS MATERIALIZED (
+         SELECT __cand.id AS __id, __terms.q FROM __cand JOIN __terms ON __cand.__tsv @@ __terms.q
+       ), __idf AS (
+         SELECT q, ln(1 + ((SELECT count(*) FROM __cand) - count(*) + 0.5) / (count(*) + 0.5)) AS w
+         FROM __hits GROUP BY q
+       ), __scored AS (
+         SELECT __hits.__id, sum(__idf.w) AS s, rank() OVER (ORDER BY sum(__idf.w) DESC) AS r
+         FROM __hits JOIN __idf USING (q) GROUP BY __hits.__id
+       )
+       SELECT __cand.id, __cand.text, __cand.source, __cand.metadata,
+              __scored.s + ts_rank_cd(__cand.__tsv, ${any}, 32) AS score
+       FROM __scored JOIN __cand ON __cand.id = __scored.__id
+       WHERE __scored.r <= $2
+       ORDER BY __scored.s DESC, ts_rank_cd(__cand.__tsv, ${any}, 32) DESC, __cand.id
+       LIMIT $2`, params);
+    return rows.map(toPassage);
+  }
   /** Must be character-for-character the index expression, or the planner won't use the index. */
   tsvector() {
     return this.tsColumn ?? `to_tsvector('${this.tsConfig}'::regconfig, text)`;
@@ -1599,12 +1741,12 @@ var RedisVectorStore = class {
     if (filterMatchesNothing(options.filter)) {
       return [];
     }
-    const terms = tokenizeQuery(query);
-    if (terms.length === 0) {
+    const terms2 = tokenizeQuery(query);
+    if (terms2.length === 0) {
       return [];
     }
     const filterQuery = buildFilter(options.filter);
-    const textQuery = `@text:(${terms.join("|")})`;
+    const textQuery = `@text:(${terms2.join("|")})`;
     const reply = await this.client.sendCommand([
       "FT.SEARCH",
       this.index,
@@ -1858,8 +2000,8 @@ function describesRetrieval(value) {
   return typeof value === "object" && value !== null && typeof Reflect.get(value, "describeRetrieval") === "function";
 }
 __name(describesRetrieval, "describesRetrieval");
-function describeRetrieval(candidate) {
-  return describesRetrieval(candidate) ? candidate.describeRetrieval() : {};
+function describeRetrieval(candidate2) {
+  return describesRetrieval(candidate2) ? candidate2.describeRetrieval() : {};
 }
 __name(describeRetrieval, "describeRetrieval");
 function describeSource(base) {
@@ -2392,53 +2534,94 @@ var HttpModelError = class extends Error {
     this.name = "HttpModelError";
   }
 };
+function isBatchTooLarge(error) {
+  if (!(error instanceof HttpModelError)) {
+    return false;
+  }
+  if (error.status === 413) {
+    return true;
+  }
+  return (error.status === 400 || error.status === 422) && /batch.?size|too many inputs|maximum allowed batch|payload too large|max.*(inputs|batch)/i.test(error.message);
+}
+__name(isBatchTooLarge, "isBatchTooLarge");
+var learnedBatchLimits = /* @__PURE__ */ new Map();
 function openAiEmbeddings(options) {
   const url = `${(options.baseUrl ?? "https://api.openai.com/v1").replace(/\/+$/, "")}/embeddings`;
-  const batchSize = Math.max(1, Math.floor(options.batchSize ?? 64));
+  const limitKey = `${url} ${options.model}`;
+  const configured = Math.max(1, Math.floor(options.batchSize ?? 64));
+  let batchSize = Math.min(configured, learnedBatchLimits.get(limitKey) ?? configured);
   const maxInputChars = options.maxInputChars ?? 24e3;
   const timeoutMs = options.timeoutMs ?? 12e4;
   const doFetch = options.fetch ?? fetch;
+  const request = /* @__PURE__ */ __name(async (input) => {
+    const response = await doFetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...options.apiKey ? {
+          authorization: `Bearer ${options.apiKey}`
+        } : {},
+        ...options.headers
+      },
+      body: JSON.stringify({
+        model: options.model,
+        input,
+        ...options.dimensions !== void 0 ? {
+          dimensions: options.dimensions
+        } : {}
+      }),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    const body = await response.text();
+    if (!response.ok) {
+      throw new HttpModelError(response.status, `Embeddings request failed (${response.status}): ${errorMessageOf(body)}`);
+    }
+    const json2 = parseJson(body);
+    const items = [
+      ...json2?.data ?? []
+    ].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+    if (items.length !== input.length || !items.every((item) => Array.isArray(item.embedding))) {
+      throw new HttpModelError(502, `Embeddings returned ${items.length} vectors for ${input.length} inputs`);
+    }
+    const tokens = json2?.usage?.total_tokens ?? json2?.usage?.prompt_tokens;
+    if (typeof tokens === "number" && Number.isFinite(tokens)) {
+      options.onUsage?.(tokens);
+    }
+    return items.map((item) => item.embedding);
+  }, "request");
+  const requestSplitting = /* @__PURE__ */ __name(async (input) => {
+    if (input.length > batchSize) {
+      const vectors = [];
+      for (let start = 0; start < input.length; start += batchSize) {
+        vectors.push(...await requestSplitting(input.slice(start, start + batchSize)));
+      }
+      return vectors;
+    }
+    try {
+      return await request(input);
+    } catch (error) {
+      if (!isBatchTooLarge(error) || input.length <= 1) {
+        throw error;
+      }
+      const half = Math.ceil(input.length / 2);
+      if (half < batchSize) {
+        batchSize = half;
+        learnedBatchLimits.set(limitKey, half);
+        options.onWarn?.(`embeddings server ${url} refused a batch of ${input.length} inputs (${error.message}); retrying in batches of ${half}. Raise the server's batch limit (TEI: --max-client-batch-size) or lower batchSize.`);
+      }
+      return [
+        ...await requestSplitting(input.slice(0, half)),
+        ...await requestSplitting(input.slice(half))
+      ];
+    }
+  }, "requestSplitting");
   return {
     async embed(texts) {
       const vectors = [];
-      for (let start = 0; start < texts.length; start += batchSize) {
+      for (let start = 0; start < texts.length; ) {
         const input = texts.slice(start, start + batchSize).map((text) => (text.length > maxInputChars ? text.slice(0, maxInputChars) : text) || " ");
-        const response = await doFetch(url, {
-          method: "POST",
-          headers: {
-            "content-type": "application/json",
-            ...options.apiKey ? {
-              authorization: `Bearer ${options.apiKey}`
-            } : {},
-            ...options.headers
-          },
-          body: JSON.stringify({
-            model: options.model,
-            input,
-            ...options.dimensions !== void 0 ? {
-              dimensions: options.dimensions
-            } : {}
-          }),
-          signal: AbortSignal.timeout(timeoutMs)
-        });
-        const body = await response.text();
-        if (!response.ok) {
-          throw new HttpModelError(response.status, `Embeddings request failed (${response.status}): ${errorMessageOf(body)}`);
-        }
-        const json = parseJson(body);
-        const items = [
-          ...json?.data ?? []
-        ].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
-        if (items.length !== input.length || !items.every((item) => Array.isArray(item.embedding))) {
-          throw new HttpModelError(502, `Embeddings returned ${items.length} vectors for ${input.length} inputs`);
-        }
-        for (const item of items) {
-          vectors.push(item.embedding);
-        }
-        const tokens = json?.usage?.total_tokens ?? json?.usage?.prompt_tokens;
-        if (typeof tokens === "number" && Number.isFinite(tokens)) {
-          options.onUsage?.(tokens);
-        }
+        vectors.push(...await requestSplitting(input));
+        start += input.length;
       }
       return vectors;
     }
@@ -2454,8 +2637,8 @@ function parseJson(body) {
 }
 __name(parseJson, "parseJson");
 function errorMessageOf(body) {
-  const json = parseJson(body);
-  const message = typeof json?.error === "string" ? json.error : json?.error?.message ?? json?.message ?? void 0;
+  const json2 = parseJson(body);
+  const message = typeof json2?.error === "string" ? json2.error : json2?.error?.message ?? json2?.message ?? void 0;
   return typeof message === "string" ? message : body.slice(0, 300);
 }
 __name(errorMessageOf, "errorMessageOf");
@@ -2530,22 +2713,2287 @@ var HttpReranker = class {
   }
 };
 function itemsOf(body) {
-  let json;
+  let json2;
   try {
-    json = JSON.parse(body);
+    json2 = JSON.parse(body);
   } catch {
     return void 0;
   }
-  if (Array.isArray(json)) {
-    return json;
+  if (Array.isArray(json2)) {
+    return json2;
   }
-  const wrapped = json;
+  const wrapped = json2;
   const items = wrapped?.results ?? wrapped?.data;
   return Array.isArray(items) ? items : void 0;
 }
 __name(itemsOf, "itemsOf");
+
+// src/tree/types.ts
+function* walkTree(nodes, path = []) {
+  for (const node of nodes) {
+    yield {
+      node,
+      path
+    };
+    yield* walkTree(node.children, [
+      ...path,
+      node
+    ]);
+  }
+}
+__name(walkTree, "walkTree");
+function indexTree(tree) {
+  const index = /* @__PURE__ */ new Map();
+  for (const entry of walkTree(tree.nodes)) {
+    index.set(entry.node.id, entry);
+  }
+  return index;
+}
+__name(indexTree, "indexTree");
+
+// src/tree/headings.ts
+var MARKDOWN = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+var KEYWORD_LEVEL = {
+  part: 1,
+  chapter: 1,
+  title: 1,
+  appendix: 1,
+  annex: 1,
+  exhibit: 1,
+  schedule: 1,
+  subpart: 2,
+  article: 2,
+  item: 2,
+  section: 3
+};
+var KEYWORD = /^(PART|Part|CHAPTER|Chapter|TITLE|APPENDIX|Appendix|ANNEX|Annex|EXHIBIT|Exhibit|SCHEDULE|Schedule|SUBPART|Subpart|ARTICLE|Article|ITEM|Item|SECTION|Section)\s+([0-9]{1,4}[A-Z]?(?:[.\-–][0-9A-Z]{1,4}){0,3}|[IVXLC]{1,6}|[A-Z])\b\.?(?:\s*[—–:\-.]\s*|\s+)?(.{0,110})$/;
+var NUMBERED = /^(\d{1,3}(?:\.\d{1,4}){1,4})([-–]\d{1,4})?\.?\s+([A-Z[][^\n]{1,100})$/;
+function clean(title) {
+  return title.replace(/\s+/g, " ").replace(/[\s.:—–-]+$/, "").trim();
+}
+__name(clean, "clean");
+function looksLikeBody(rest) {
+  return /(\d\)?|[%$])\s*$/.test(rest) || rest.split(" ").length > 16;
+}
+__name(looksLikeBody, "looksLikeBody");
+var DANGLING = new Set("a an the of to in for and or as by with on at from that which is are be than under".split(" "));
+function dangling(title) {
+  if (/[,;(]$/.test(title)) {
+    return true;
+  }
+  const last = title.split(/\s+/).pop()?.toLowerCase() ?? "";
+  return DANGLING.has(last);
+}
+__name(dangling, "dangling");
+function detectHeadings(texts, markdownOnly = false) {
+  const headings = [];
+  let inFence = false;
+  let run = [];
+  const dropped = /* @__PURE__ */ new Set();
+  const closeRun = /* @__PURE__ */ __name(() => {
+    if (run.length >= 5) {
+      run.forEach((entry, position) => {
+        const heading = headings[entry.index];
+        const keep = position === run.length - 1 || position === 0 && entry.keyword && heading !== void 0 && heading.level === 1;
+        if (!keep) {
+          dropped.add(entry.index);
+        }
+      });
+    }
+    run = [];
+  }, "closeRun");
+  texts.forEach((text, unit) => {
+    let seenText = false;
+    const lines = text.split("\n").map((raw) => raw.trim());
+    for (let at = 0; at < lines.length; at++) {
+      let line = lines[at] ?? "";
+      if (line.startsWith("```")) {
+        inFence = !inFence;
+        seenText = true;
+        closeRun();
+        continue;
+      }
+      if (line === "") {
+        continue;
+      }
+      if (inFence || line.length > 140) {
+        seenText = true;
+        closeRun();
+        continue;
+      }
+      const atUnitStart = !seenText;
+      seenText = true;
+      const markdown = MARKDOWN.exec(line);
+      if (markdown?.[1] !== void 0 && markdown[2] !== void 0) {
+        closeRun();
+        const title = clean(markdown[2].replace(/\*\*/g, ""));
+        if (title !== "") {
+          headings.push({
+            title,
+            level: markdown[1].length,
+            unit,
+            atUnitStart
+          });
+        }
+        continue;
+      }
+      if (markdownOnly) {
+        continue;
+      }
+      const candidate2 = KEYWORD.test(line) || NUMBERED.test(line);
+      if (candidate2) {
+        for (let joined = 0; joined < 2; joined++) {
+          const next = lines[at + 1];
+          if (!/[a-z]-$/.test(line) || next === void 0 || next === "" || next.length > 80) {
+            break;
+          }
+          line = `${line.slice(0, -1)}${next}`;
+          at += 1;
+        }
+      }
+      const keyword = KEYWORD.exec(line);
+      if (keyword?.[1] !== void 0 && keyword[2] !== void 0) {
+        const rest = keyword[3] ?? "";
+        const allCaps = keyword[1] === keyword[1].toUpperCase();
+        if (!looksLikeBody(rest) && !/^[a-z,;)]/.test(rest) && (rest !== "" || allCaps) && !dangling(clean(line))) {
+          const level = KEYWORD_LEVEL[keyword[1].toLowerCase()] ?? 2;
+          run.push({
+            index: headings.length,
+            keyword: true
+          });
+          headings.push({
+            title: clean(line),
+            level,
+            unit,
+            atUnitStart
+          });
+          continue;
+        }
+      }
+      const numbered = NUMBERED.exec(line);
+      if (numbered?.[1] !== void 0 && numbered[3] !== void 0 && !looksLikeBody(numbered[3]) && !dangling(clean(numbered[3]))) {
+        const level = Math.min(6, numbered[1].split(".").length + 1 + (numbered[2] ? 1 : 0));
+        run.push({
+          index: headings.length,
+          keyword: false
+        });
+        headings.push({
+          title: clean(line),
+          level,
+          unit,
+          atUnitStart
+        });
+        continue;
+      }
+      if (!candidate2 && /[A-Za-z]{3,}/.test(line) && !isPageFurniture(line) && !isTitleCase(line)) {
+        closeRun();
+      }
+    }
+  });
+  closeRun();
+  return dropContentsDuplicates(dropRunningHeaders(headings.filter((_, index) => !dropped.has(index)), texts.length));
+}
+__name(detectHeadings, "detectHeadings");
+function dropContentsDuplicates(headings) {
+  const last = /* @__PURE__ */ new Map();
+  headings.forEach((heading, index) => {
+    if (/\d/.test(heading.title)) {
+      last.set(heading.title.toLowerCase(), index);
+    }
+  });
+  return headings.filter((heading, index) => {
+    const key = heading.title.toLowerCase();
+    return !last.has(key) || last.get(key) === index;
+  });
+}
+__name(dropContentsDuplicates, "dropContentsDuplicates");
+function isTitleCase(line) {
+  if (line.length > 70 || /\.\s*$/.test(line)) {
+    return false;
+  }
+  const words2 = line.split(/\s+/).filter((word) => /^[A-Za-z]{4,}/.test(word));
+  return words2.length > 0 && words2.filter((word) => /^[A-Z]/.test(word)).length / words2.length >= 0.6;
+}
+__name(isTitleCase, "isTitleCase");
+function isPageFurniture(line) {
+  return line.length < 50 && /^[\d\s\-–—.()]*(\d+\s*CFR|Federal Acquisition Regulation|Page \d+)/i.test(line);
+}
+__name(isPageFurniture, "isPageFurniture");
+function runningLines(texts) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const text of texts) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const raw of text.split("\n")) {
+      const key = raw.trim().replace(/\d+/g, "#").toLowerCase();
+      if (key && !seen.has(key)) {
+        seen.add(key);
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+      }
+    }
+  }
+  const threshold = Math.max(3, Math.ceil(texts.length * 0.2));
+  return new Set([
+    ...counts
+  ].filter(([, count]) => count >= threshold).map(([key]) => key));
+}
+__name(runningLines, "runningLines");
+function dropRunningHeaders(headings, unitCount) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const heading of headings) {
+    const key = heading.title.toLowerCase();
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const threshold = Math.max(3, Math.ceil(unitCount * 0.2));
+  return headings.filter((heading) => {
+    const key = heading.title.toLowerCase();
+    if ((counts.get(key) ?? 0) >= threshold) {
+      if (seen.has(key)) {
+        return false;
+      }
+    }
+    seen.add(key);
+    return true;
+  });
+}
+__name(dropRunningHeaders, "dropRunningHeaders");
+
+// src/tree/llm.ts
+var TreeBudgetExceededError = class extends Error {
+  static {
+    __name(this, "TreeBudgetExceededError");
+  }
+  limit;
+  constructor(limit) {
+    super(`tree LLM budget exhausted (${limit})`), this.limit = limit;
+    this.name = "TreeBudgetExceededError";
+  }
+};
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+__name(estimateTokens, "estimateTokens");
+var BudgetedLlm = class {
+  static {
+    __name(this, "BudgetedLlm");
+  }
+  llm;
+  budget;
+  outerSignal;
+  calls = 0;
+  inputTokens = 0;
+  outputTokens = 0;
+  exhausted = false;
+  deadline;
+  constructor(llm, budget, outerSignal) {
+    this.llm = llm;
+    this.budget = budget;
+    this.outerSignal = outerSignal;
+    this.deadline = budget.timeoutMs !== void 0 ? Date.now() + budget.timeoutMs : Number.POSITIVE_INFINITY;
+  }
+  /** Time left before the deadline, ms (`Infinity` without one). */
+  remainingMs() {
+    return this.deadline - Date.now();
+  }
+  /** Would a call with this prompt fit? Does not reserve anything; a `false` marks the budget exhausted. */
+  fits(prompt, maxOutputTokens) {
+    const fits = this.limitHit(prompt, maxOutputTokens) === void 0;
+    if (!fits) {
+      this.exhausted = true;
+    }
+    return fits;
+  }
+  limitHit(prompt, maxOutputTokens) {
+    if (this.calls >= this.budget.maxCalls) {
+      return "calls";
+    }
+    if (this.inputTokens + estimateTokens(prompt) > this.budget.maxInputTokens) {
+      return "inputTokens";
+    }
+    if (this.outputTokens + Math.min(maxOutputTokens, 16) > this.budget.maxOutputTokens) {
+      return "outputTokens";
+    }
+    if (this.remainingMs() <= 0 || this.outerSignal?.aborted) {
+      return "timeout";
+    }
+    return void 0;
+  }
+  /**
+  * Make one call, or throw {@link TreeBudgetExceededError} without calling. Provider errors
+  * propagate (after being counted). Never retries.
+  */
+  async call(task, system, prompt, maxOutputTokens) {
+    const limit = this.limitHit(system + prompt, maxOutputTokens);
+    if (limit !== void 0) {
+      this.exhausted = true;
+      throw new TreeBudgetExceededError(limit);
+    }
+    const outputCap = Math.max(16, Math.min(maxOutputTokens, this.budget.maxOutputTokens - this.outputTokens));
+    const timeoutMs = Math.min(this.budget.callTimeoutMs ?? Number.POSITIVE_INFINITY, this.remainingMs());
+    const reservedInput = estimateTokens(system + prompt);
+    this.inputTokens += reservedInput;
+    this.outputTokens += outputCap;
+    const controller = new AbortController();
+    const onOuterAbort = /* @__PURE__ */ __name(() => controller.abort(this.outerSignal?.reason), "onOuterAbort");
+    this.outerSignal?.addEventListener("abort", onOuterAbort, {
+      once: true
+    });
+    let timer;
+    this.calls += 1;
+    try {
+      const response = await Promise.race([
+        this.llm({
+          task,
+          system,
+          prompt,
+          maxOutputTokens: outputCap,
+          signal: controller.signal
+        }),
+        new Promise((_, reject) => {
+          if (Number.isFinite(timeoutMs)) {
+            timer = setTimeout(() => {
+              controller.abort(new TreeBudgetExceededError("timeout"));
+              reject(new TreeBudgetExceededError("timeout"));
+            }, Math.max(0, timeoutMs));
+          }
+        })
+      ]);
+      this.inputTokens += (response.usage?.inputTokens ?? reservedInput) - reservedInput;
+      this.outputTokens += (response.usage?.outputTokens ?? estimateTokens(response.text)) - outputCap;
+      return response.text;
+    } catch (error) {
+      this.outputTokens -= outputCap;
+      if (error instanceof TreeBudgetExceededError) {
+        this.exhausted = true;
+      }
+      throw error;
+    } finally {
+      if (timer !== void 0) {
+        clearTimeout(timer);
+      }
+      this.outerSignal?.removeEventListener("abort", onOuterAbort);
+    }
+  }
+};
+function parseJsonReply(text) {
+  const tryParse = /* @__PURE__ */ __name((candidate2) => {
+    try {
+      const value = JSON.parse(candidate2);
+      return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+    } catch {
+      return void 0;
+    }
+  }, "tryParse");
+  const trimmed = text.trim();
+  const direct = tryParse(trimmed);
+  if (direct !== void 0) {
+    return direct;
+  }
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(trimmed);
+  if (fenced?.[1] !== void 0) {
+    const inner = tryParse(fenced[1].trim());
+    if (inner !== void 0) {
+      return inner;
+    }
+  }
+  const start = trimmed.indexOf("{");
+  const end = trimmed.lastIndexOf("}");
+  if (start >= 0 && end > start) {
+    return tryParse(trimmed.slice(start, end + 1));
+  }
+  return void 0;
+}
+__name(parseJsonReply, "parseJsonReply");
+function stringList(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((item) => typeof item === "number" ? String(item) : item).filter((item) => typeof item === "string");
+}
+__name(stringList, "stringList");
+var NOOP_SINK = {
+  write() {
+  },
+  end() {
+  },
+  fail() {
+  }
+};
+function treeLlmFromModelProvider(provider) {
+  return async (request) => {
+    const result = await provider.runTurn({
+      system: request.system,
+      messages: [
+        {
+          role: "user",
+          content: request.prompt
+        }
+      ],
+      tools: [],
+      sink: NOOP_SINK,
+      abortSignal: request.signal
+    });
+    return {
+      text: result.text,
+      usage: {
+        inputTokens: result.usage.inputTokens,
+        outputTokens: result.usage.outputTokens
+      }
+    };
+  };
+}
+__name(treeLlmFromModelProvider, "treeLlmFromModelProvider");
+function openAiChatTreeLlm(options) {
+  const url = `${(options.baseUrl ?? "https://api.openai.com/v1").replace(/\/+$/, "")}/chat/completions`;
+  const doFetch = options.fetch ?? fetch;
+  return async (request) => {
+    const json2 = request.task.kind !== "summarize";
+    const response = await doFetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...options.apiKey ? {
+          authorization: `Bearer ${options.apiKey}`
+        } : {},
+        ...options.headers
+      },
+      body: JSON.stringify({
+        model: options.model,
+        messages: [
+          {
+            role: "system",
+            content: request.system
+          },
+          {
+            role: "user",
+            content: request.prompt
+          }
+        ],
+        temperature: options.temperature ?? 0,
+        max_tokens: request.maxOutputTokens,
+        ...options.jsonMode && json2 ? {
+          response_format: {
+            type: "json_object"
+          }
+        } : {},
+        ...options.body
+      }),
+      signal: request.signal
+    });
+    const body = await response.text();
+    if (!response.ok) {
+      throw new HttpModelError(response.status, `Chat completion failed (${response.status}): ${errorMessageOf(body)}`);
+    }
+    const parsed = parseJsonReply(body);
+    const content = parsed?.choices?.[0]?.message?.content;
+    if (typeof content !== "string") {
+      throw new HttpModelError(502, "Chat completion returned no message content");
+    }
+    const usage = {};
+    if (typeof parsed?.usage?.prompt_tokens === "number") {
+      usage.inputTokens = parsed.usage.prompt_tokens;
+    }
+    if (typeof parsed?.usage?.completion_tokens === "number") {
+      usage.outputTokens = parsed.usage.completion_tokens;
+    }
+    return {
+      text: content,
+      usage
+    };
+  };
+}
+__name(openAiChatTreeLlm, "openAiChatTreeLlm");
+function cachedTreeLlm(llm, cache = /* @__PURE__ */ new Map()) {
+  return async (request) => {
+    const key = stableHash(`${request.task.kind}\0${request.maxOutputTokens}\0${request.system}\0${request.prompt}`);
+    const hit = await cache.get(key);
+    if (hit !== void 0) {
+      return {
+        text: hit.text,
+        usage: {
+          inputTokens: 0,
+          outputTokens: 0
+        }
+      };
+    }
+    const response = await llm(request);
+    await cache.set(key, response);
+    return response;
+  };
+}
+__name(cachedTreeLlm, "cachedTreeLlm");
+function stableHash(text) {
+  let h1 = 2166136261;
+  let h2 = 16777619 ^ text.length;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 16777619);
+    h2 = Math.imul(h2 ^ c, 1540483477);
+    h2 ^= h2 >>> 13;
+  }
+  h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507);
+  h2 = Math.imul(h2 ^ h2 >>> 15, 3266489909);
+  return (h1 >>> 0).toString(16).padStart(8, "0") + (h2 >>> 0).toString(16).padStart(8, "0");
+}
+__name(stableHash, "stableHash");
+
+// src/tree/build.ts
+var DEFAULT_BUDGET = {
+  maxCalls: 60,
+  maxInputTokens: 4e5,
+  maxOutputTokens: 4e4,
+  timeoutMs: 3e5,
+  callTimeoutMs: 6e4
+};
+var STRUCTURE_SYSTEM = "You extract the table of contents of a document. You answer with JSON only, no prose.";
+var SUMMARY_SYSTEM = "You summarize sections of a document so a reader can decide whether a section answers their question. Be specific: name the topics, clauses, figures and defined terms it covers.";
+function toUnits(input) {
+  if (input.pages !== void 0 && input.sections !== void 0) {
+    throw new Error("buildDocumentTree: give `pages` or `sections`, not both");
+  }
+  if (input.sections !== void 0) {
+    const units = input.sections.map((section, index) => ({
+      index,
+      text: section.text,
+      ...section.page !== void 0 ? {
+        page: section.page
+      } : {}
+    }));
+    const titled = input.sections.some((section) => section.title?.trim());
+    const declared = titled ? input.sections.flatMap((section, unit) => section.title?.trim() ? [
+      {
+        title: section.title.trim(),
+        level: Math.max(1, Math.min(6, section.level ?? 1)),
+        unit,
+        atUnitStart: true
+      }
+    ] : []) : void 0;
+    return {
+      units,
+      declared,
+      kind: "sections"
+    };
+  }
+  const pages2 = input.pages ?? [];
+  return {
+    units: pages2.map((text, index) => ({
+      index,
+      text,
+      page: index + 1
+    })),
+    declared: void 0,
+    kind: "pages"
+  };
+}
+__name(toUnits, "toUnits");
+function outlineHeadings(input, units) {
+  const headings = [];
+  for (const entry of input.outline ?? []) {
+    let unit = entry.unit;
+    if (unit === void 0 && entry.page !== void 0) {
+      unit = units.findIndex((candidate2) => candidate2.page === entry.page);
+      if (unit < 0) {
+        unit = entry.page - 1;
+      }
+    }
+    if (unit === void 0 || unit < 0 || unit >= units.length || !entry.title.trim()) {
+      continue;
+    }
+    headings.push({
+      title: entry.title.trim(),
+      level: Math.max(1, Math.min(6, Math.floor(entry.level))),
+      unit,
+      atUnitStart: false
+    });
+  }
+  return headings.sort((a, b) => a.unit - b.unit);
+}
+__name(outlineHeadings, "outlineHeadings");
+function nestHeadings(headings, unitCount) {
+  const roots = [];
+  const stack = [];
+  headings.forEach((heading, index) => {
+    let end = unitCount - 1;
+    for (let next = index + 1; next < headings.length; next++) {
+      const candidate2 = headings[next];
+      if (candidate2 !== void 0 && candidate2.level <= heading.level) {
+        end = candidate2.atUnitStart ? candidate2.unit - 1 : candidate2.unit;
+        break;
+      }
+    }
+    const node = {
+      title: heading.title,
+      unitStart: heading.unit,
+      unitEnd: Math.max(heading.unit, end),
+      children: []
+    };
+    while (stack.length > 0 && (stack[stack.length - 1]?.level ?? 0) >= heading.level) {
+      stack.pop();
+    }
+    const parent = stack[stack.length - 1];
+    if (parent === void 0) {
+      roots.push(node);
+    } else {
+      parent.node.children.push(node);
+      parent.node.unitEnd = Math.max(parent.node.unitEnd, node.unitEnd);
+    }
+    stack.push({
+      node,
+      level: heading.level
+    });
+  });
+  const first = roots[0];
+  if (first !== void 0 && first.unitStart > 0) {
+    roots.unshift({
+      title: "Front matter",
+      unitStart: 0,
+      unitEnd: first.unitStart - 1,
+      children: []
+    });
+  }
+  return roots;
+}
+__name(nestHeadings, "nestHeadings");
+function firstLine(text, running) {
+  const line = text.split("\n").map((candidate2) => candidate2.trim()).find((candidate2) => /[A-Za-z]{3,}/.test(candidate2) && !running.has(candidate2.replace(/\d+/g, "#").toLowerCase()));
+  return line === void 0 ? "" : line.length > 80 ? `${line.slice(0, 77)}\u2026` : line;
+}
+__name(firstLine, "firstLine");
+function rangeLabel(units, start, end) {
+  const first = units[start];
+  const last = units[end];
+  if (first?.page !== void 0 && last?.page !== void 0) {
+    return first.page === last.page ? `Page ${first.page}` : `Pages ${first.page}\u2013${last.page}`;
+  }
+  return start === end ? `Section ${start + 1}` : `Sections ${start + 1}\u2013${end + 1}`;
+}
+__name(rangeLabel, "rangeLabel");
+function groupNodes(units, start, end, groupSize, maxChildren, levelsLeft, running) {
+  let level = [];
+  for (let from = start; from <= end; from += groupSize) {
+    const to = Math.min(end, from + groupSize - 1);
+    const lead = firstLine(units[from]?.text ?? "", running);
+    level.push({
+      title: `${rangeLabel(units, from, to)}${lead ? `: ${lead}` : ""}`,
+      unitStart: from,
+      unitEnd: to,
+      children: []
+    });
+  }
+  let depth = 1;
+  while (level.length > maxChildren && depth < levelsLeft) {
+    const parents = [];
+    const per = Math.max(maxChildren, Math.ceil(level.length / maxChildren));
+    for (let index = 0; index < level.length; index += per) {
+      const children = level.slice(index, index + per);
+      const from = children[0]?.unitStart ?? start;
+      const to = children[children.length - 1]?.unitEnd ?? end;
+      parents.push({
+        title: rangeLabel(units, from, to),
+        unitStart: from,
+        unitEnd: to,
+        children
+      });
+    }
+    level = parents;
+    depth += 1;
+  }
+  return level;
+}
+__name(groupNodes, "groupNodes");
+function descendantTitles(nodes, into = []) {
+  for (const { node } of walkDraft(nodes)) {
+    if (into.length < 30) {
+      into.push(node.title);
+    }
+  }
+  return into;
+}
+__name(descendantTitles, "descendantTitles");
+function shape(nodes, units, depth, options) {
+  const shaped = nodes.map((node) => {
+    if (depth >= options.maxDepth || node.unitStart === node.unitEnd && node.children.length > 0) {
+      const keyItems = descendantTitles(node.children, [
+        ...node.keyItems ?? []
+      ]);
+      return {
+        ...node,
+        ...keyItems.length > 0 ? {
+          keyItems
+        } : {},
+        children: []
+      };
+    }
+    let children = node.children;
+    const only = children[0];
+    if (children.length === 1 && only !== void 0 && only.unitStart === node.unitStart && only.unitEnd === node.unitEnd) {
+      children = only.children;
+    }
+    if (children.length === 0 && node.unitEnd - node.unitStart + 1 > options.maxLeafUnits) {
+      children = groupNodes(units, node.unitStart, node.unitEnd, options.groupSize, options.maxChildren, options.maxDepth - depth, options.running);
+    }
+    return {
+      ...node,
+      children: shape(children, units, depth + 1, options)
+    };
+  });
+  const merged = [];
+  for (const node of shaped) {
+    const previous = merged[merged.length - 1];
+    if (previous !== void 0 && previous.children.length === 0 && node.children.length === 0 && previous.unitStart === node.unitStart && previous.unitEnd === node.unitEnd) {
+      previous.keyItems = [
+        ...previous.keyItems ?? [],
+        node.title,
+        ...node.keyItems ?? []
+      ].slice(0, 30);
+      continue;
+    }
+    merged.push(node);
+  }
+  return merged;
+}
+__name(shape, "shape");
+function* walkDraft(nodes) {
+  for (const node of nodes) {
+    yield {
+      node
+    };
+    yield* walkDraft(node.children);
+  }
+}
+__name(walkDraft, "walkDraft");
+function spanText(units, start, end) {
+  const parts = [];
+  for (let index = Math.max(0, start); index <= end && index < units.length; index++) {
+    parts.push(units[index]?.text ?? "");
+  }
+  return parts.join("\n\n");
+}
+__name(spanText, "spanText");
+function ownTexts(units, node) {
+  const first = node.children[0];
+  const end = first === void 0 ? node.unitEnd : Math.max(node.unitStart, first.unitStart - 1);
+  const texts = [];
+  for (let index = node.unitStart; index <= end && index < units.length; index++) {
+    texts.push(units[index]?.text ?? "");
+  }
+  const head = texts[0];
+  if (head !== void 0) {
+    const probe = node.title.slice(0, 30);
+    const at = probe.length >= 4 ? head.indexOf(probe) : -1;
+    if (at > 0) {
+      texts[0] = head.slice(at);
+    }
+  }
+  return texts;
+}
+__name(ownTexts, "ownTexts");
+function excerptOf(texts, max) {
+  const total = texts.reduce((sum, text) => sum + text.length, 0);
+  if (total <= max) {
+    return texts.join("\n\n");
+  }
+  const per = Math.max(400, Math.floor(max / texts.length));
+  const parts = [];
+  let used = 0;
+  for (const text of texts) {
+    if (used >= max) {
+      break;
+    }
+    const part = text.length > per ? `${text.slice(0, per)}\u2026` : text;
+    parts.push(part);
+    used += part.length;
+  }
+  return parts.join("\n\n");
+}
+__name(excerptOf, "excerptOf");
+function collapse(text, max) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}\u2026` : flat;
+}
+__name(collapse, "collapse");
+async function llmHeadings(llm, units, options) {
+  const perUnit = Math.max(500, Math.floor(options.windowChars / 4));
+  const windows = [];
+  let current = [];
+  let size = 0;
+  for (const unit of units) {
+    const length = Math.min(unit.text.length, perUnit);
+    if (current.length > 0 && size + length > options.windowChars) {
+      windows.push(current);
+      current = [];
+      size = 0;
+    }
+    current.push(unit);
+    size += length;
+  }
+  if (current.length > 0) {
+    windows.push(current);
+  }
+  if (windows.length > options.maxCalls) {
+    throw new Error(`document needs ${windows.length} structuring calls, more than maxStructureCalls (${options.maxCalls})`);
+  }
+  const headings = [];
+  for (const window of windows) {
+    const shown = window.map((unit) => ({
+      unit: unit.index,
+      ...unit.page !== void 0 ? {
+        page: unit.page
+      } : {},
+      text: unit.text.length > perUnit ? `${unit.text.slice(0, perUnit)}\u2026` : unit.text
+    }));
+    const body = shown.map((unit) => `<unit ${unit.unit}>
+${unit.text}
+</unit ${unit.unit}>`).join("\n");
+    const prompt = `Below is part of a document, split into numbered units (pages or sections).
+List the headings of the sections that START in these units, in reading order, with their nesting level (1 = top-level chapter/part, 2 = its subsections, ...) and the unit number they start in.
+Only list real headings (titles of parts, chapters, sections, clauses, items), not running page headers, table rows or sentences. If no section starts here, return an empty list.
+
+${body}
+
+Reply with JSON only: {"sections": [{"title": "...", "level": 1, "unit": 0}]}`;
+    const reply = parseJsonReply(await llm.call({
+      kind: "structure",
+      units: shown
+    }, STRUCTURE_SYSTEM, prompt, 2e3));
+    const sections = reply?.sections;
+    if (!Array.isArray(sections)) {
+      throw new Error("structuring reply had no `sections` list");
+    }
+    const first = window[0]?.index ?? 0;
+    const last = window[window.length - 1]?.index ?? first;
+    for (const entry of sections) {
+      if (entry === null || typeof entry !== "object") {
+        continue;
+      }
+      const { title, level, unit } = entry;
+      const at = typeof unit === "number" ? unit : Number(unit);
+      if (typeof title !== "string" || !title.trim() || !Number.isInteger(at) || at < first || at > last) {
+        continue;
+      }
+      const previous = headings[headings.length - 1];
+      if (previous !== void 0 && at < previous.unit) {
+        continue;
+      }
+      headings.push({
+        title: collapse(title, 160),
+        level: Math.max(1, Math.min(6, Math.floor(typeof level === "number" ? level : 1))),
+        unit: at,
+        atUnitStart: false
+      });
+    }
+  }
+  return headings;
+}
+__name(llmHeadings, "llmHeadings");
+async function mapLimit(items, limit, work) {
+  const results = new Array(items.length);
+  let next = 0;
+  const workers = Array.from({
+    length: Math.max(1, Math.min(limit, items.length))
+  }, async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await work(items[index], index);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+__name(mapLimit, "mapLimit");
+async function buildDocumentTree(input, options) {
+  const started = Date.now();
+  const { units, declared, kind } = toUnits(input);
+  const maxDepth = Math.max(1, options.maxDepth ?? 4);
+  const groupSize = Math.max(1, options.groupSize ?? 5);
+  const maxLeafUnits = Math.max(groupSize, options.maxLeafUnits ?? 10);
+  const maxChildren = Math.max(2, options.maxChildren ?? 12);
+  const minHeadings = Math.max(1, options.minHeadings ?? 3);
+  const llmEnabled = options.llm !== void 0;
+  const summaries = options.summaries ?? llmEnabled;
+  const describe = options.describe ?? llmEnabled;
+  const llmStructure = options.llmStructure ?? llmEnabled;
+  const detect = options.detectHeadings ?? true;
+  const summaryMinChars = options.summaryMinChars ?? 600;
+  const summaryInputChars = options.summaryInputChars ?? 8e3;
+  const unitHashes = units.map((unit) => stableHash(unit.text));
+  const fingerprint = stableHash(JSON.stringify({
+    v: 1,
+    kind,
+    title: input.title ?? null,
+    outline: input.outline ?? null,
+    sections: input.sections?.map((section) => [
+      section.title ?? null,
+      section.level ?? null,
+      section.page ?? null
+    ]) ?? null,
+    units: unitHashes,
+    maxDepth,
+    groupSize,
+    maxLeafUnits,
+    maxChildren,
+    minHeadings,
+    detect,
+    summaries,
+    describe,
+    llmStructure: llmStructure && llmEnabled,
+    summaryMinChars,
+    summaryInputChars
+  }));
+  if (options.previous?.fingerprint === fingerprint) {
+    const { metadata: _metadata, source: _source, ...previous } = options.previous;
+    const metadata = options.metadata ?? options.previous.metadata;
+    const source = options.source ?? options.previous.source;
+    return {
+      tree: {
+        ...previous,
+        ...metadata !== void 0 ? {
+          metadata
+        } : {},
+        ...source !== void 0 ? {
+          source
+        } : {}
+      },
+      units,
+      unchanged: true
+    };
+  }
+  const budget = new BudgetedLlm(options.llm ?? (() => Promise.reject(new Error("no llm"))), {
+    ...DEFAULT_BUDGET,
+    ...options.budget
+  }, options.signal);
+  let fallbackReason;
+  let structure = "flat";
+  let headings = [];
+  const running = runningLines(units.map((unit) => unit.text));
+  const outline = outlineHeadings(input, units);
+  if (outline.length >= Math.min(minHeadings, 2)) {
+    structure = "outline";
+    headings = outline;
+  } else if (declared !== void 0 && declared.length >= 1) {
+    structure = "headings";
+    headings = declared;
+  } else if (detect !== false && units.length > 0) {
+    const found = detectHeadings(units.map((unit) => unit.text), detect === "markdown");
+    if (found.length >= minHeadings) {
+      structure = "headings";
+      headings = found;
+    }
+  }
+  if (structure === "flat" && llmStructure && llmEnabled && units.length > 1) {
+    try {
+      const found = await llmHeadings(budget, units, {
+        windowChars: options.structureWindowChars ?? 24e3,
+        maxCalls: Math.max(1, options.maxStructureCalls ?? 12)
+      });
+      if (found.length >= Math.min(minHeadings, 2)) {
+        structure = "llm";
+        headings = found;
+      } else {
+        fallbackReason = "LLM found no usable structure";
+      }
+    } catch (error) {
+      fallbackReason = error instanceof TreeBudgetExceededError ? `LLM structuring stopped: ${error.message}` : `LLM structuring failed: ${error.message}`;
+    }
+  }
+  const draft = structure === "flat" ? units.length === 0 ? [] : groupNodes(units, 0, units.length - 1, groupSize, maxChildren, maxDepth, running) : nestHeadings(headings, units.length);
+  const shaped = shape(draft, units, 1, {
+    maxDepth,
+    maxLeafUnits,
+    groupSize,
+    maxChildren,
+    running
+  });
+  let counter = 0;
+  const finalize = /* @__PURE__ */ __name((nodes2) => nodes2.map((node) => {
+    counter += 1;
+    const id = String(counter).padStart(4, "0");
+    const pageStart = units[node.unitStart]?.page;
+    const pageEnd = units[node.unitEnd]?.page;
+    return {
+      id,
+      title: node.title,
+      unitStart: node.unitStart,
+      unitEnd: node.unitEnd,
+      ...pageStart !== void 0 ? {
+        pageStart
+      } : {},
+      ...pageEnd !== void 0 ? {
+        pageEnd
+      } : {},
+      ...node.keyItems !== void 0 ? {
+        keyItems: node.keyItems
+      } : {},
+      contentHash: stableHash(`${node.title}\0${unitHashes.slice(node.unitStart, node.unitEnd + 1).join(",")}`),
+      children: finalize(node.children)
+    };
+  }), "finalize");
+  const nodes = finalize(shaped);
+  const previousSummaries = /* @__PURE__ */ new Map();
+  if (options.previous !== void 0) {
+    for (const { node } of walkTree(options.previous.nodes)) {
+      if (node.summary !== void 0 && (node.summarySource === "llm" || node.summarySource === "reused")) {
+        previousSummaries.set(node.contentHash, node.summary);
+      }
+    }
+  }
+  const breadthFirst = [];
+  for (let queue = [
+    ...nodes
+  ]; queue.length > 0; ) {
+    const node = queue.shift();
+    breadthFirst.push(node);
+    queue = queue.concat(node.children);
+  }
+  let reusedSummaries = 0;
+  const pending = [];
+  for (const node of breadthFirst) {
+    const reused = previousSummaries.get(node.contentHash);
+    const own = ownTexts(units, node).join("\n\n");
+    if (reused !== void 0) {
+      node.summary = reused;
+      node.summarySource = "reused";
+      reusedSummaries += 1;
+    } else if (own.trim().length < summaryMinChars && node.children.length === 0) {
+      const text = collapse(own, summaryMinChars);
+      if (text) {
+        node.summary = text;
+        node.summarySource = "text";
+      }
+    } else if (summaries && llmEnabled) {
+      pending.push(node);
+    } else {
+      const text = collapse(own, 300);
+      if (text) {
+        node.summary = text;
+        node.summarySource = "text";
+      }
+    }
+  }
+  let summariesCut = false;
+  await mapLimit(pending, Math.max(1, options.concurrency ?? 4), async (node) => {
+    const own = ownTexts(units, node);
+    const childTitles = [
+      ...node.children.map((child) => child.title),
+      ...node.keyItems ?? []
+    ].map((title) => `- ${title}`).join("\n");
+    const excerpt = excerptOf(own, summaryInputChars);
+    const prompt = `Summarize this section of ${input.title ? `"${input.title}"` : "a document"} in 2-4 sentences (at most 80 words). Name the specific topics, requirements, clauses, figures and defined terms it covers, so a reader can tell whether it answers their question.
+
+Section title: ${node.title}
+${childTitles ? `Subsections:
+${childTitles}
+` : ""}
+Section text:
+${excerpt}
+
+Reply with the summary only.`;
+    if (!summariesCut && budget.fits(SUMMARY_SYSTEM + prompt, 300)) {
+      try {
+        const reply = await budget.call({
+          kind: "summarize",
+          title: node.title,
+          text: excerpt
+        }, SUMMARY_SYSTEM, prompt, 300);
+        const json2 = parseJsonReply(reply);
+        const summary = typeof json2?.summary === "string" ? json2.summary : reply;
+        if (summary.trim()) {
+          node.summary = collapse(summary, 800);
+          node.summarySource = "llm";
+          return;
+        }
+      } catch (error) {
+        if (error instanceof TreeBudgetExceededError) {
+          summariesCut = true;
+        }
+        fallbackReason ??= `summary failed: ${error.message}`;
+      }
+    } else {
+      summariesCut = true;
+    }
+    const text = collapse(own.join("\n\n"), 300);
+    if (text) {
+      node.summary = text;
+      node.summarySource = "text";
+    }
+  });
+  if (summariesCut) {
+    fallbackReason ??= "LLM budget exhausted before every node was summarized";
+  }
+  let description;
+  const outlineForDescription = nodes.slice(0, 40).map((node) => ({
+    title: node.title,
+    ...node.summary !== void 0 ? {
+      summary: node.summary
+    } : {}
+  }));
+  if (describe && llmEnabled && nodes.length > 0) {
+    const prompt = `Write a one-paragraph description (at most 80 words) of the document ${input.title ? `"${input.title}"` : ""} from its table of contents below, so a reader can tell which questions it can answer.
+
+${outlineForDescription.map((entry) => `- ${entry.title}${entry.summary ? `: ${entry.summary}` : ""}`).join("\n")}
+
+Reply with the description only.`;
+    if (budget.fits(SUMMARY_SYSTEM + prompt, 300)) {
+      try {
+        description = collapse(await budget.call({
+          kind: "describe",
+          ...input.title !== void 0 ? {
+            title: input.title
+          } : {},
+          outline: outlineForDescription
+        }, SUMMARY_SYSTEM, prompt, 300), 1e3);
+      } catch (error) {
+        fallbackReason ??= `description failed: ${error.message}`;
+      }
+    }
+  }
+  if (description === void 0 && options.previous?.description !== void 0 && reusedSummaries > 0) {
+    description = options.previous.description;
+  }
+  const tree = {
+    documentId: options.documentId,
+    version: 1,
+    ...input.title !== void 0 ? {
+      title: input.title
+    } : {},
+    ...description ? {
+      description
+    } : {},
+    structure,
+    fingerprint,
+    unitCount: units.length,
+    nodes,
+    stats: {
+      llmCalls: budget.calls,
+      inputTokens: budget.inputTokens,
+      outputTokens: budget.outputTokens,
+      durationMs: Date.now() - started,
+      ...fallbackReason !== void 0 ? {
+        fallbackReason
+      } : {},
+      budgetExhausted: budget.exhausted,
+      reusedSummaries
+    },
+    ...options.metadata !== void 0 ? {
+      metadata: options.metadata
+    } : {},
+    ...options.source !== void 0 ? {
+      source: options.source
+    } : {},
+    builtAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return {
+    tree,
+    units,
+    unchanged: false
+  };
+}
+__name(buildDocumentTree, "buildDocumentTree");
+
+// src/tree/keyword-tree-llm.ts
+var STOP = new Set("the and for are was were with that this from which what when where who whom how does did has have had not but its into under over than then there their about any all can may must shall should would could will our your they them his her per each other such only also more most".split(" "));
+function terms(text) {
+  return new Set((text.toLowerCase().match(/[\p{L}\p{N}][\p{L}\p{N}.\-]*[\p{L}\p{N}]|[\p{L}\p{N}]{3,}/gu) ?? []).filter((term) => term.length >= 3 && !STOP.has(term)));
+}
+__name(terms, "terms");
+function overlap(query, text) {
+  let score = 0;
+  for (const term of terms(text)) {
+    if (query.has(term)) {
+      score += 1;
+    }
+  }
+  return score;
+}
+__name(overlap, "overlap");
+function keywordTreeLlm() {
+  return async (request) => {
+    const { task } = request;
+    let text;
+    switch (task.kind) {
+      case "navigate": {
+        const query = terms(task.query);
+        const ranked = task.candidates.map((candidate2, order) => ({
+          candidate: candidate2,
+          order,
+          score: overlap(query, `${candidate2.title} ${candidate2.summary ?? ""}`)
+        })).filter((entry) => entry.score > 0).sort((a, b) => b.score - a.score || (b.candidate.depth ?? 0) - (a.candidate.depth ?? 0) || a.order - b.order).slice(0, task.maxNodes).map((entry) => entry.candidate);
+        text = task.mode === "single-pass" ? JSON.stringify({
+          thinking: "keyword overlap",
+          read: ranked.map((c) => c.id)
+        }) : JSON.stringify({
+          thinking: "keyword overlap",
+          expand: ranked.filter((c) => c.hasChildren).map((c) => c.id),
+          read: ranked.filter((c) => !c.hasChildren).map((c) => c.id)
+        });
+        break;
+      }
+      case "select": {
+        const query = terms(task.query);
+        const ranked = task.documents.map((document) => ({
+          id: document.id,
+          score: overlap(query, `${document.title ?? ""} ${document.description ?? ""}`)
+        })).filter((entry) => entry.score > 0).sort((a, b) => b.score - a.score).slice(0, task.maxDocuments).map((entry) => entry.id);
+        text = JSON.stringify({
+          thinking: "keyword overlap",
+          documents: ranked
+        });
+        break;
+      }
+      case "summarize": {
+        const flat = task.text.replace(/\s+/g, " ").trim();
+        const sentence = /^.*?[.!?](\s|$)/.exec(flat)?.[0] ?? flat;
+        text = `${task.title}: ${sentence.slice(0, 200).trim()}`;
+        break;
+      }
+      case "describe":
+        text = `${task.title ?? "Document"} covering ${task.outline.map((entry) => entry.title).join(", ")}.`;
+        break;
+      case "structure": {
+        const sections = [];
+        for (const unit of task.units) {
+          for (const line of unit.text.split("\n")) {
+            const trimmed = line.trim();
+            const markdown = /^(#{1,6})\s+(.+)$/.exec(trimmed);
+            if (markdown?.[1] !== void 0 && markdown[2] !== void 0) {
+              sections.push({
+                title: markdown[2],
+                level: markdown[1].length,
+                unit: unit.unit
+              });
+            } else if (/^[A-Z][A-Z0-9 ,.'&-]{3,80}$/.test(trimmed) && /[A-Z]{3}/.test(trimmed)) {
+              sections.push({
+                title: trimmed,
+                level: 1,
+                unit: unit.unit
+              });
+            }
+          }
+        }
+        text = JSON.stringify({
+          sections
+        });
+        break;
+      }
+    }
+    return {
+      text,
+      usage: {
+        inputTokens: Math.ceil(request.prompt.length / 4),
+        outputTokens: Math.ceil(text.length / 4)
+      }
+    };
+  };
+}
+__name(keywordTreeLlm, "keywordTreeLlm");
+
+// src/tree/store.ts
+function headerOf(tree) {
+  return {
+    documentId: tree.documentId,
+    ...tree.title !== void 0 ? {
+      title: tree.title
+    } : {},
+    ...tree.description !== void 0 ? {
+      description: tree.description
+    } : {},
+    structure: tree.structure,
+    fingerprint: tree.fingerprint,
+    unitCount: tree.unitCount,
+    ...tree.metadata !== void 0 ? {
+      metadata: tree.metadata
+    } : {},
+    ...tree.source !== void 0 ? {
+      source: tree.source
+    } : {},
+    builtAt: tree.builtAt
+  };
+}
+__name(headerOf, "headerOf");
+function passes(tree, filter) {
+  if (filter === void 0 || Object.keys(filter).length === 0) {
+    return true;
+  }
+  if (filterMatchesNothing(filter)) {
+    return false;
+  }
+  return matchesFilter(tree.metadata, filter);
+}
+__name(passes, "passes");
+var MemoryDocumentTreeStore = class {
+  static {
+    __name(this, "MemoryDocumentTreeStore");
+  }
+  trees = /* @__PURE__ */ new Map();
+  async put(tree, units) {
+    this.trees.set(tree.documentId, {
+      tree: structuredClone(tree),
+      units: units.map((unit) => ({
+        ...unit
+      }))
+    });
+  }
+  async get(documentId, filter) {
+    const entry = this.trees.get(documentId);
+    return entry !== void 0 && passes(entry.tree, filter) ? structuredClone(entry.tree) : void 0;
+  }
+  async getMany(documentIds, filter) {
+    const trees = [];
+    for (const id of new Set(documentIds)) {
+      const tree = await this.get(id, filter);
+      if (tree !== void 0) {
+        trees.push(tree);
+      }
+    }
+    return trees;
+  }
+  async list(options = {}) {
+    const ids = options.documentIds !== void 0 ? new Set(options.documentIds) : void 0;
+    const headers = [
+      ...this.trees.values()
+    ].filter(({ tree }) => (ids === void 0 || ids.has(tree.documentId)) && passes(tree, options.filter)).map(({ tree }) => headerOf(tree)).sort((a, b) => a.documentId.localeCompare(b.documentId));
+    return options.limit !== void 0 ? headers.slice(0, options.limit) : headers;
+  }
+  async readUnits(documentId, start, end) {
+    const units = this.trees.get(documentId)?.units ?? [];
+    return units.slice(Math.max(0, start), Math.max(0, end + 1)).map((unit) => ({
+      ...unit
+    }));
+  }
+  async remove(documentId) {
+    this.trees.delete(documentId);
+  }
+};
+
+// src/tree/pg-tree-store.ts
+var IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
+function json(value) {
+  if (value === null || value === void 0) {
+    return void 0;
+  }
+  return typeof value === "string" ? JSON.parse(value) : value;
+}
+__name(json, "json");
+var PgDocumentTreeStore = class {
+  static {
+    __name(this, "PgDocumentTreeStore");
+  }
+  client;
+  table;
+  unitsTable;
+  insertBatchSize;
+  constructor(client, options = {}) {
+    this.client = toPgClient(client);
+    this.table = options.table ?? "agent_rag_trees";
+    this.unitsTable = options.unitsTable ?? `${this.table}_units`;
+    for (const name of [
+      this.table,
+      this.unitsTable
+    ]) {
+      if (!IDENTIFIER.test(name)) {
+        throw new Error(`PgDocumentTreeStore: invalid table name ${JSON.stringify(name)}`);
+      }
+    }
+    this.insertBatchSize = Math.max(1, Math.floor(options.insertBatchSize ?? 200));
+  }
+  /** The idempotent DDL {@link PgDocumentTreeStore.ensureSchema} runs, in order — for a migration. */
+  schemaStatements() {
+    const index = this.table.replace(".", "_");
+    return [
+      `CREATE TABLE IF NOT EXISTS ${this.table} (
+        document_id TEXT PRIMARY KEY,
+        title TEXT,
+        description TEXT,
+        structure TEXT NOT NULL,
+        fingerprint TEXT NOT NULL,
+        unit_count INTEGER NOT NULL,
+        source TEXT,
+        metadata JSONB,
+        tree JSONB NOT NULL,
+        built_at TIMESTAMPTZ NOT NULL
+      )`,
+      `CREATE INDEX IF NOT EXISTS ${index}_metadata_idx ON ${this.table} USING gin (metadata)`,
+      `CREATE TABLE IF NOT EXISTS ${this.unitsTable} (
+        document_id TEXT NOT NULL,
+        idx INTEGER NOT NULL,
+        page INTEGER,
+        text TEXT NOT NULL,
+        PRIMARY KEY (document_id, idx)
+      )`
+    ];
+  }
+  async ensureSchema() {
+    for (const statement of this.schemaStatements()) {
+      await this.client.query(statement);
+    }
+  }
+  /**
+  * The SQL conditions a metadata `filter` compiles to (ANDed), appending bindings to `params`.
+  * Override to map a filter onto your own columns. Return `['false']` to deny.
+  */
+  whereConditions(filter, params) {
+    return buildWhere(filter, params);
+  }
+  /** Replace the tree and its units in one transaction (when the client has one). */
+  async put(tree, units) {
+    const clean2 = stripNulBytes(tree);
+    const { metadata, ...rest } = clean2;
+    const write = /* @__PURE__ */ __name(async (client) => {
+      await client.query(`DELETE FROM ${this.unitsTable} WHERE document_id = $1`, [
+        clean2.documentId
+      ]);
+      for (let start = 0; start < units.length; start += this.insertBatchSize) {
+        const batch = units.slice(start, start + this.insertBatchSize);
+        const params = [];
+        const rows = batch.map((unit) => {
+          params.push(clean2.documentId, unit.index, unit.page ?? null, stripNulBytes(unit.text));
+          const at = params.length;
+          return `($${at - 3}, $${at - 2}, $${at - 1}, $${at})`;
+        });
+        await client.query(`INSERT INTO ${this.unitsTable} (document_id, idx, page, text) VALUES ${rows.join(", ")}`, params);
+      }
+      await client.query(`INSERT INTO ${this.table}
+           (document_id, title, description, structure, fingerprint, unit_count, source, metadata, tree, built_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9::jsonb, $10)
+         ON CONFLICT (document_id) DO UPDATE SET
+           title = EXCLUDED.title, description = EXCLUDED.description, structure = EXCLUDED.structure,
+           fingerprint = EXCLUDED.fingerprint, unit_count = EXCLUDED.unit_count, source = EXCLUDED.source,
+           metadata = EXCLUDED.metadata, tree = EXCLUDED.tree, built_at = EXCLUDED.built_at`, [
+        clean2.documentId,
+        clean2.title ?? null,
+        clean2.description ?? null,
+        clean2.structure,
+        clean2.fingerprint,
+        clean2.unitCount,
+        clean2.source ?? null,
+        metadata === void 0 ? null : JSON.stringify(metadata),
+        JSON.stringify(rest),
+        clean2.builtAt
+      ]);
+    }, "write");
+    const transaction = this.client.transaction?.bind(this.client);
+    await (transaction !== void 0 ? transaction(write) : write(this.client));
+  }
+  async get(documentId, filter) {
+    return (await this.getMany([
+      documentId
+    ], filter))[0];
+  }
+  async getMany(documentIds, filter) {
+    if (documentIds.length === 0) {
+      return [];
+    }
+    const params = [
+      [
+        ...new Set(documentIds)
+      ]
+    ];
+    const conditions = [
+      "document_id = ANY($1::text[])",
+      ...this.whereConditions(filter, params)
+    ];
+    const rows = await this.client.query(`SELECT document_id, metadata, tree FROM ${this.table} WHERE ${conditions.join(" AND ")}`, params);
+    return rows.map((row) => {
+      const tree = json(row.tree);
+      const metadata = json(row.metadata);
+      return {
+        ...tree,
+        ...metadata !== void 0 ? {
+          metadata
+        } : {}
+      };
+    });
+  }
+  async list(options = {}) {
+    const params = [];
+    const conditions = this.whereConditions(options.filter, params);
+    if (options.documentIds !== void 0) {
+      params.push([
+        ...options.documentIds
+      ]);
+      conditions.push(`document_id = ANY($${params.length}::text[])`);
+    }
+    let limit = "";
+    if (options.limit !== void 0) {
+      params.push(Math.max(0, Math.floor(options.limit)));
+      limit = `LIMIT $${params.length}`;
+    }
+    const rows = await this.client.query(`SELECT document_id, title, description, structure, fingerprint, unit_count, source, metadata, built_at
+         FROM ${this.table}
+         ${conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : ""}
+         ORDER BY document_id ${limit}`, params);
+    return rows.map((row) => {
+      const metadata = json(row.metadata);
+      return headerOf({
+        documentId: row.document_id,
+        version: 1,
+        ...row.title !== null ? {
+          title: row.title
+        } : {},
+        ...row.description !== null ? {
+          description: row.description
+        } : {},
+        structure: row.structure,
+        fingerprint: row.fingerprint,
+        unitCount: Number(row.unit_count),
+        nodes: [],
+        stats: {
+          llmCalls: 0,
+          inputTokens: 0,
+          outputTokens: 0,
+          durationMs: 0,
+          budgetExhausted: false,
+          reusedSummaries: 0
+        },
+        ...metadata !== void 0 ? {
+          metadata
+        } : {},
+        ...row.source !== null ? {
+          source: row.source
+        } : {},
+        builtAt: row.built_at instanceof Date ? row.built_at.toISOString() : String(row.built_at)
+      });
+    });
+  }
+  async readUnits(documentId, start, end) {
+    const rows = await this.client.query(`SELECT idx, page, text FROM ${this.unitsTable}
+        WHERE document_id = $1 AND idx BETWEEN $2 AND $3 ORDER BY idx`, [
+      documentId,
+      Math.max(0, start),
+      end
+    ]);
+    return rows.map((row) => ({
+      index: Number(row.idx),
+      text: row.text,
+      ...row.page !== null ? {
+        page: Number(row.page)
+      } : {}
+    }));
+  }
+  async remove(documentId) {
+    const work = /* @__PURE__ */ __name(async (client) => {
+      await client.query(`DELETE FROM ${this.unitsTable} WHERE document_id = $1`, [
+        documentId
+      ]);
+      await client.query(`DELETE FROM ${this.table} WHERE document_id = $1`, [
+        documentId
+      ]);
+    }, "work");
+    const transaction = this.client.transaction?.bind(this.client);
+    await (transaction !== void 0 ? transaction(work) : work(this.client));
+  }
+};
+
+// src/tree/index-document.ts
+async function indexDocumentTree(input, options) {
+  const { store, minUnits = 20, minChars = 6e4, ...build } = options;
+  const { units } = toUnits(input);
+  const chars = units.reduce((total, unit) => total + unit.text.length, 0);
+  if (units.length < minUnits && chars < minChars) {
+    await store.remove(options.documentId);
+    return {
+      status: "skipped",
+      reason: `${units.length} units / ${chars} chars is below the threshold (${minUnits} units or ${minChars} chars)`
+    };
+  }
+  const previous = await store.get(options.documentId);
+  const built = await buildDocumentTree(input, {
+    ...build,
+    ...previous !== void 0 ? {
+      previous
+    } : {}
+  });
+  if (built.unchanged) {
+    const metadataMoved = JSON.stringify(previous?.metadata ?? null) !== JSON.stringify(built.tree.metadata ?? null) || previous?.source !== built.tree.source;
+    if (metadataMoved) {
+      await store.put(built.tree, built.units);
+    }
+    return {
+      status: "unchanged",
+      tree: built.tree
+    };
+  }
+  await store.put(built.tree, built.units);
+  return {
+    status: "built",
+    tree: built.tree
+  };
+}
+__name(indexDocumentTree, "indexDocumentTree");
+
+// src/tree/navigate.ts
+var NAVIGATE_SYSTEM = "You navigate the table of contents of a document to find where a question is answered. You answer with JSON only.";
+var DEFAULT_BUDGET2 = {
+  maxCalls: 6,
+  maxInputTokens: 6e4,
+  maxOutputTokens: 4e3,
+  timeoutMs: 6e4
+};
+function pages(node) {
+  if (node.pageStart === void 0) {
+    return void 0;
+  }
+  return node.pageEnd === void 0 || node.pageEnd === node.pageStart ? `p. ${node.pageStart}` : `pp. ${node.pageStart}-${node.pageEnd}`;
+}
+__name(pages, "pages");
+function candidate(node, summaryChars, depth) {
+  const shownPages = pages(node);
+  let summary = node.summary;
+  if (summary !== void 0 && summary.length > summaryChars) {
+    summary = `${summary.slice(0, Math.max(0, summaryChars - 1))}\u2026`;
+  }
+  if (node.keyItems !== void 0 && node.keyItems.length > 0 && summaryChars > 0) {
+    summary = `${summary ?? ""}${summary ? " " : ""}Includes: ${node.keyItems.slice(0, 12).join("; ")}`;
+  }
+  return {
+    id: node.id,
+    title: node.title,
+    ...summary && summaryChars > 0 ? {
+      summary
+    } : {},
+    ...shownPages !== void 0 ? {
+      pages: shownPages
+    } : {},
+    ...depth !== void 0 ? {
+      depth
+    } : {
+      hasChildren: node.children.length > 0
+    }
+  };
+}
+__name(candidate, "candidate");
+function render(candidates) {
+  return candidates.map((entry) => {
+    const indent = "  ".repeat(entry.depth ?? 0);
+    const meta = [
+      entry.pages,
+      entry.hasChildren ? "has subsections" : void 0
+    ].filter(Boolean).join(", ");
+    return `${indent}[${entry.id}] ${entry.title}${meta ? ` (${meta})` : ""}${entry.summary ? ` \u2014 ${entry.summary}` : ""}`;
+  }).join("\n");
+}
+__name(render, "render");
+function fit(nodes, maxChars) {
+  let last;
+  for (const summaryChars of [
+    400,
+    160,
+    0
+  ]) {
+    const candidates = nodes.map(({ node, depth }) => candidate(node, summaryChars, depth));
+    const text = render(candidates);
+    last = {
+      candidates,
+      text
+    };
+    if (text.length <= maxChars) {
+      break;
+    }
+  }
+  return last;
+}
+__name(fit, "fit");
+var TreeNavigationRetriever = class {
+  static {
+    __name(this, "TreeNavigationRetriever");
+  }
+  options;
+  store;
+  llm;
+  constructor(options) {
+    this.options = options;
+    this.store = options.store;
+    this.llm = options.llm;
+  }
+  describeRetrieval() {
+    return {
+      retriever: "tree-navigation"
+    };
+  }
+  async retrieve(query, options = {}) {
+    const result = await this.search(query, options.filter !== void 0 ? {
+      filter: options.filter
+    } : {});
+    return result.passages.slice(0, options.topK ?? result.passages.length);
+  }
+  /** {@link retrieve} with the audit trail: which documents, which nodes, why. */
+  async search(query, options = {}) {
+    const maxDocuments = Math.max(1, this.options.maxDocuments ?? 3);
+    const maxCandidates = Math.max(maxDocuments, this.options.maxSelectionCandidates ?? 200);
+    const headers = await this.store.list({
+      ...options.filter !== void 0 ? {
+        filter: options.filter
+      } : {},
+      limit: maxCandidates
+    });
+    if (headers.length <= maxDocuments) {
+      return this.navigate(query, headers.map((header) => header.documentId), options);
+    }
+    const budget = new BudgetedLlm(this.llm, {
+      ...DEFAULT_BUDGET2,
+      ...this.options.budget,
+      ...options.budget
+    }, options.signal);
+    const documents = headers.map((header) => ({
+      id: header.documentId,
+      ...header.title !== void 0 ? {
+        title: header.title
+      } : {},
+      ...header.description !== void 0 ? {
+        description: header.description.slice(0, 600)
+      } : {}
+    }));
+    const prompt = `Select the documents that may contain the answer to the question, most relevant first, at most ${maxDocuments}.
+
+Question: ${query}
+
+Documents:
+${documents.map((document) => `[${document.id}] ${document.title ?? ""}${document.description ? ` \u2014 ${document.description}` : ""}`).join("\n")}
+
+Reply with JSON only: {"thinking": "<why>", "documents": ["<document id>", ...]} \u2014 an empty list if none is relevant.`;
+    const known = new Set(documents.map((document) => document.id));
+    try {
+      const reply = parseJsonReply(await budget.call({
+        kind: "select",
+        query,
+        documents,
+        maxDocuments
+      }, NAVIGATE_SYSTEM, prompt, 800));
+      const selected = [
+        ...new Set(stringList(reply?.documents ?? reply?.answer).filter((id) => known.has(id)))
+      ].slice(0, maxDocuments);
+      const result = await this.navigate(query, selected, options);
+      const reasoning = typeof reply?.thinking === "string" ? reply.thinking.slice(0, 2e3) : void 0;
+      return {
+        ...result,
+        selection: {
+          candidates: documents.length,
+          selected,
+          ...reasoning !== void 0 ? {
+            reasoning
+          } : {}
+        }
+      };
+    } catch (error) {
+      return {
+        passages: [],
+        documents: [],
+        selection: {
+          candidates: documents.length,
+          selected: [],
+          error: error.message
+        }
+      };
+    }
+  }
+  /**
+  * Navigate the given documents (in parallel, up to `concurrency`) and return their passages in
+  * the order given, within `maxContextChars`. Documents without a tree, or whose tree fails
+  * `filter`, yield no passages and `stoppedBy: 'not-found'`.
+  */
+  async navigate(query, documentIds, options = {}) {
+    const ids = [
+      ...new Set(documentIds)
+    ];
+    const trees = new Map((await this.store.getMany(ids, options.filter)).map((tree) => [
+      tree.documentId,
+      tree
+    ]));
+    const navigations = await mapLimit(ids, Math.max(1, this.options.concurrency ?? 3), async (id) => {
+      const tree = trees.get(id);
+      if (tree === void 0) {
+        return {
+          navigation: {
+            documentId: id,
+            mode: "single-pass",
+            steps: [],
+            nodes: [],
+            llmCalls: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            stoppedBy: "not-found"
+          },
+          passages: []
+        };
+      }
+      const navigation = await this.walk(query, tree, options);
+      return {
+        navigation,
+        passages: await this.passagesOf(tree, navigation)
+      };
+    });
+    const maxContextChars = this.options.maxContextChars ?? 48e3;
+    let used = 0;
+    const passages = [];
+    for (const entry of navigations) {
+      for (const passage of entry.passages) {
+        if (used >= maxContextChars) {
+          break;
+        }
+        const text = passage.text.slice(0, maxContextChars - used);
+        used += text.length;
+        passages.push({
+          ...passage,
+          text
+        });
+      }
+    }
+    return {
+      passages,
+      documents: navigations.map((entry) => entry.navigation)
+    };
+  }
+  async walk(query, tree, options) {
+    const budget = new BudgetedLlm(this.llm, {
+      ...DEFAULT_BUDGET2,
+      ...this.options.budget,
+      ...options.budget
+    }, options.signal);
+    const maxNodes = Math.max(1, this.options.maxNodes ?? 5);
+    const singlePassMaxChars = this.options.singlePassMaxChars ?? 4e4;
+    const index = indexTree(tree);
+    const whole = [
+      ...walkTree(tree.nodes)
+    ].map(({ node, path }) => ({
+      node,
+      depth: path.length
+    }));
+    const outline = fit(whole, Number.POSITIVE_INFINITY);
+    const title = tree.title ?? tree.source ?? tree.documentId;
+    const steps = [];
+    const chosen = [];
+    let stoppedBy;
+    let error;
+    const mode = outline.text.length <= singlePassMaxChars ? "single-pass" : "beam";
+    const stop = /* @__PURE__ */ __name((caught) => {
+      if (caught instanceof TreeBudgetExceededError) {
+        stoppedBy = caught.limit === "timeout" ? "timeout" : "budget";
+      } else {
+        stoppedBy = "error";
+      }
+      error = caught.message;
+    }, "stop");
+    if (mode === "single-pass") {
+      const prompt = `Find the sections of the document that are likely to contain the answer to the question. Prefer the most specific (deepest) sections; list at most ${maxNodes}, most relevant first.
+
+Question: ${query}
+
+Document: ${title}${tree.description ? `
+About: ${tree.description}` : ""}
+Table of contents ([id] title (pages) \u2014 summary):
+${outline.text}
+
+Reply with JSON only: {"thinking": "<which sections answer and why>", "read": ["<id>", ...]} \u2014 an empty list if none does.`;
+      try {
+        const reply = requireJson(await budget.call({
+          kind: "navigate",
+          query,
+          mode,
+          candidates: outline.candidates,
+          maxNodes
+        }, NAVIGATE_SYSTEM, prompt, 1500));
+        const read = [
+          ...new Set(stringList(reply?.read ?? reply?.node_list ?? reply?.nodes))
+        ].map((id) => resolveId(index, id)).filter((id) => id !== void 0).slice(0, maxNodes);
+        chosen.push(...read);
+        steps.push({
+          step: 1,
+          shown: outline.candidates.map((entry) => entry.id),
+          expanded: [],
+          read,
+          ...reasoningOf(reply)
+        });
+      } catch (caught) {
+        stop(caught);
+      }
+    } else {
+      const beamWidth = Math.max(1, this.options.beamWidth ?? 4);
+      const maxSteps = Math.max(1, this.options.maxSteps ?? 4);
+      let frontier = tree.nodes;
+      let pendingExpand = [];
+      for (let step = 1; frontier.length > 0 && chosen.length < maxNodes; step++) {
+        if (step > maxSteps) {
+          stoppedBy = "maxSteps";
+          break;
+        }
+        const shown = fit(frontier.map((node) => ({
+          node
+        })), singlePassMaxChars);
+        const path = index.get(frontier[0]?.id ?? "")?.path ?? [];
+        const where = path.length > 0 ? `
+You are inside: ${path.map((node) => node.title).join(" > ")}` : "";
+        const prompt = `Find where the question is answered in the document by walking its table of contents.
+For each relevant section below, either "expand" it (open its subsections, only for sections that have subsections) or "read" it (its text answers the question). Choose at most ${beamWidth} in total, most relevant first; choose none if nothing here is relevant.
+
+Question: ${query}
+
+Document: ${title}${tree.description ? `
+About: ${tree.description}` : ""}${where}
+Sections ([id] title (pages) \u2014 summary):
+${shown.text}
+
+Reply with JSON only: {"thinking": "<why>", "expand": ["<id>", ...], "read": ["<id>", ...]}`;
+        let reply;
+        try {
+          reply = requireJson(await budget.call({
+            kind: "navigate",
+            query,
+            mode,
+            candidates: shown.candidates,
+            maxNodes: beamWidth
+          }, NAVIGATE_SYSTEM, prompt, 1200));
+        } catch (caught) {
+          stop(caught);
+          break;
+        }
+        const onFrontier = new Set(frontier.map((node) => node.id));
+        const pick = /* @__PURE__ */ __name((value) => [
+          ...new Set(stringList(value))
+        ].map((id) => resolveId(index, id)).filter((id) => id !== void 0 && onFrontier.has(id)), "pick");
+        let expand = pick(reply?.expand);
+        let read = pick(reply?.read);
+        read = [
+          ...read,
+          ...expand.filter((id) => (index.get(id)?.node.children.length ?? 0) === 0)
+        ];
+        expand = expand.filter((id) => (index.get(id)?.node.children.length ?? 0) > 0);
+        const limited = [
+          ...expand,
+          ...read
+        ].slice(0, beamWidth);
+        expand = expand.filter((id) => limited.includes(id));
+        read = [
+          ...new Set(read.filter((id) => limited.includes(id)))
+        ];
+        steps.push({
+          step,
+          shown: shown.candidates.map((entry) => entry.id),
+          expanded: expand,
+          read,
+          ...reasoningOf(reply)
+        });
+        chosen.push(...read);
+        pendingExpand = expand;
+        frontier = expand.flatMap((id) => index.get(id)?.node.children ?? []);
+        if (frontier.length === 0) {
+          pendingExpand = [];
+        }
+      }
+      if (stoppedBy !== void 0) {
+        chosen.push(...pendingExpand);
+      }
+    }
+    const unique = [
+      ...new Set(chosen)
+    ];
+    const specific = unique.filter((id) => !unique.some((other) => other !== id && index.get(other)?.path.some((node) => node.id === id)));
+    const nodes = specific.slice(0, maxNodes).flatMap((id) => {
+      const entry = index.get(id);
+      if (entry === void 0) {
+        return [];
+      }
+      const { node, path } = entry;
+      return [
+        {
+          nodeId: node.id,
+          title: node.title,
+          path: [
+            ...path,
+            node
+          ].map((step) => ({
+            id: step.id,
+            title: step.title
+          })),
+          ...node.pageStart !== void 0 ? {
+            pageStart: node.pageStart
+          } : {},
+          ...node.pageEnd !== void 0 ? {
+            pageEnd: node.pageEnd
+          } : {},
+          unitStart: node.unitStart,
+          unitEnd: node.unitEnd
+        }
+      ];
+    });
+    return {
+      documentId: tree.documentId,
+      ...tree.title !== void 0 ? {
+        title: tree.title
+      } : {},
+      mode,
+      steps,
+      nodes,
+      llmCalls: budget.calls,
+      inputTokens: budget.inputTokens,
+      outputTokens: budget.outputTokens,
+      ...stoppedBy !== void 0 ? {
+        stoppedBy
+      } : {},
+      ...error !== void 0 ? {
+        error
+      } : {}
+    };
+  }
+  async passagesOf(tree, navigation) {
+    const maxPassageChars = this.options.maxPassageChars ?? 12e3;
+    const maxUnits = Math.max(1, this.options.maxUnitsPerNode ?? 25);
+    const reasoning = navigation.steps.map((step) => step.reasoning).filter((text) => text !== void 0).join("\n");
+    const passages = [];
+    for (const [rank, node] of navigation.nodes.entries()) {
+      const units = await this.store.readUnits(tree.documentId, node.unitStart, Math.min(node.unitEnd, node.unitStart + maxUnits - 1));
+      let text = units.map((unit) => unit.text).join("\n\n");
+      if (text.length > maxPassageChars) {
+        text = `${text.slice(0, maxPassageChars - 1)}\u2026`;
+      }
+      passages.push({
+        id: `${tree.documentId}#node:${node.nodeId}`,
+        text,
+        // Rank within the document's choice; not a similarity.
+        score: 1 / (rank + 1),
+        source: tree.source ?? tree.title ?? tree.documentId,
+        metadata: {
+          ...tree.metadata,
+          documentId: tree.documentId,
+          nodeId: node.nodeId,
+          title: node.title,
+          ...node.pageStart !== void 0 ? {
+            pageStart: node.pageStart
+          } : {},
+          ...node.pageEnd !== void 0 ? {
+            pageEnd: node.pageEnd
+          } : {},
+          path: node.path,
+          retrieval: "tree-navigation",
+          ...reasoning ? {
+            reasoning: reasoning.slice(0, 2e3)
+          } : {}
+        }
+      });
+    }
+    return passages;
+  }
+};
+function resolveId(index, raw) {
+  const id = raw.trim().replace(/^\[|\]$/g, "");
+  if (index.has(id)) {
+    return id;
+  }
+  if (/^\d+$/.test(id)) {
+    const padded = id.padStart(4, "0");
+    if (index.has(padded)) {
+      return padded;
+    }
+  }
+  return void 0;
+}
+__name(resolveId, "resolveId");
+function requireJson(reply) {
+  const json2 = parseJsonReply(reply);
+  if (json2 === void 0) {
+    throw new Error(`navigation reply was not JSON: ${JSON.stringify(reply.slice(0, 120))}`);
+  }
+  return json2;
+}
+__name(requireJson, "requireJson");
+function reasoningOf(reply) {
+  const thinking = reply?.thinking ?? reply?.reasoning;
+  return typeof thinking === "string" && thinking.trim() ? {
+    reasoning: thinking.slice(0, 2e3)
+  } : {};
+}
+__name(reasoningOf, "reasoningOf");
+
+// src/tree/two-stage.ts
+function defaultDocumentIdOf(passage) {
+  const fromMetadata = passage.metadata?.documentId;
+  return typeof fromMetadata === "string" ? fromMetadata : documentIdOf(passage.id);
+}
+__name(defaultDocumentIdOf, "defaultDocumentIdOf");
+var TwoStageRetriever = class {
+  static {
+    __name(this, "TwoStageRetriever");
+  }
+  firstStage;
+  navigator;
+  options;
+  constructor(firstStage, navigator, options = {}) {
+    this.firstStage = firstStage;
+    this.navigator = navigator;
+    this.options = options;
+  }
+  describeRetrieval() {
+    return {
+      retriever: "two-stage"
+    };
+  }
+  async retrieve(query, options = {}) {
+    return (await this.search(query, options)).passages;
+  }
+  /** {@link retrieve} with the navigations that were run. */
+  async search(query, options = {}) {
+    const topK = options.topK ?? 5;
+    const docOf = this.options.documentIdOf ?? defaultDocumentIdOf;
+    const first = await this.firstStage.retrieve(query, {
+      topK: Math.max(topK, this.options.fetchTopK ?? 20),
+      ...options.filter !== void 0 ? {
+        filter: options.filter
+      } : {}
+    });
+    const ranked = [];
+    for (const passage of first) {
+      const id = docOf(passage);
+      if (!ranked.includes(id)) {
+        ranked.push(id);
+      }
+    }
+    const considered = ranked.slice(0, Math.max(1, this.options.considerDocuments ?? 3));
+    const withTrees = new Set((await this.navigator.store.list({
+      documentIds: considered,
+      ...options.filter !== void 0 ? {
+        filter: options.filter
+      } : {}
+    })).map((header) => header.documentId));
+    const toNavigate = considered.filter((id) => withTrees.has(id)).slice(0, Math.max(0, this.options.navigateDocuments ?? 2));
+    const navigated = /* @__PURE__ */ new Map();
+    let navigations = [];
+    if (toNavigate.length > 0) {
+      const result = await this.navigator.navigate(query, toNavigate, {
+        ...options.filter !== void 0 ? {
+          filter: options.filter
+        } : {},
+        ...this.options.budget !== void 0 ? {
+          budget: this.options.budget
+        } : {}
+      });
+      navigations = result.documents;
+      for (const passage of result.passages) {
+        const id = String(passage.metadata?.documentId ?? "");
+        navigated.set(id, [
+          ...navigated.get(id) ?? [],
+          passage
+        ]);
+      }
+      for (const navigation of navigations) {
+        this.options.onNavigation?.(navigation);
+      }
+    }
+    const merged = [];
+    const emitted = /* @__PURE__ */ new Set();
+    for (const passage of first) {
+      const id = docOf(passage);
+      const replacement = navigated.get(id);
+      if (replacement === void 0 || replacement.length === 0) {
+        merged.push(passage);
+        continue;
+      }
+      if (!emitted.has(id)) {
+        emitted.add(id);
+        merged.push(...replacement);
+      }
+      if (this.options.keepFirstStageChunks) {
+        merged.push(passage);
+      }
+    }
+    return {
+      passages: merged.slice(0, topK),
+      navigations
+    };
+  }
+};
+
+// src/tree/navigate-tool.ts
+function isInput(value) {
+  return typeof value === "object" && value !== null && typeof value.documentId === "string" && typeof value.question === "string";
+}
+__name(isInput, "isInput");
+var inputSchema = {
+  "~standard": {
+    version: 1,
+    vendor: "nestjs-agent-rag",
+    validate(value) {
+      return isInput(value) ? {
+        value: {
+          documentId: value.documentId,
+          question: value.question
+        }
+      } : {
+        issues: [
+          {
+            message: "navigate_document expects { documentId: string, question: string }"
+          }
+        ]
+      };
+    }
+  }
+};
+function createNavigateDocumentTool(navigator, options = {}) {
+  return {
+    spec: {
+      name: options.name ?? "navigate_document",
+      kind: "read",
+      description: options.description ?? "Read inside one long document (regulation, contract, filing, manual) by navigating its table of contents to the sections that answer a question. Use it after a search returned a long document: pass that document id and the question. Returns the matching sections with titles and page ranges for citation.",
+      inputSchema
+    },
+    handler: {
+      async execute(input, ctx) {
+        if (!isInput(input)) {
+          throw new Error("navigate_document expects { documentId: string, question: string }");
+        }
+        const filter = options.filter?.(ctx);
+        const navigateOptions = {
+          ...filter !== void 0 ? {
+            filter
+          } : {},
+          ...options.budget !== void 0 ? {
+            budget: options.budget
+          } : {}
+        };
+        let documentId = input.documentId.trim();
+        let result = await navigator.navigate(input.question, [
+          documentId
+        ], navigateOptions);
+        let navigation = result.documents[0];
+        if (navigation?.stoppedBy === "not-found") {
+          const bare = documentIdOf(documentId.replace(/#node:\d+$/, ""));
+          if (bare !== documentId) {
+            documentId = bare;
+            result = await navigator.navigate(input.question, [
+              documentId
+            ], navigateOptions);
+            navigation = result.documents[0];
+          }
+        }
+        if (navigation === void 0 || navigation.stoppedBy === "not-found") {
+          return {
+            documentId,
+            found: false,
+            passages: [],
+            nodes: [],
+            steps: [],
+            note: "This document has no navigable table of contents (it is short, not indexed, or not accessible). Use the search passages instead."
+          };
+        }
+        return {
+          documentId,
+          found: true,
+          passages: result.passages,
+          nodes: navigation.nodes,
+          steps: navigation.steps,
+          ...navigation.stoppedBy !== void 0 ? {
+            stoppedBy: navigation.stoppedBy
+          } : {},
+          ...navigation.nodes.length === 0 ? {
+            note: "No section of this document looked relevant to the question."
+          } : {}
+        };
+      }
+    }
+  };
+}
+__name(createNavigateDocumentTool, "createNavigateDocumentTool");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_STOP_WORDS,
   EmbeddingRetriever,
   FilteredRetriever,
   HttpModelError,
@@ -2553,7 +5001,9 @@ __name(itemsOf, "itemsOf");
   HybridRetriever,
   KeywordRetriever,
   LexicalRetriever,
+  MemoryDocumentTreeStore,
   MemoryVectorStore,
+  PgDocumentTreeStore,
   PgLexicalVectorStore,
   PgVectorStore,
   RAG_DIAGNOSTIC_LIB,
@@ -2562,23 +5012,44 @@ __name(itemsOf, "itemsOf");
   RedisVectorSchemaMismatchError,
   RedisVectorStore,
   RerankingRetriever,
+  TreeBudgetExceededError,
+  TreeNavigationRetriever,
+  TwoStageRetriever,
   UnsafeRemovalError,
+  anyTermTsquery,
   applyMetadataPatch,
+  buildDocumentTree,
+  cachedTreeLlm,
   chunkDocuments,
   chunkIndexOf,
   chunkText,
+  createNavigateDocumentTool,
   createRetrievalTool,
   describeRetrieval,
   describeSharedSource,
   describeSource,
   describesRetrieval,
+  detectHeadings,
   documentIdOf,
   emitRagRetrieval,
+  estimateTokens,
+  hasSearchSyntax,
+  indexDocumentTree,
+  indexTree,
   ingestChunks,
   ingestDocuments,
   instrumentRetriever,
+  isBatchTooLarge,
   isLexicalVectorStore,
+  keywordTerms,
+  keywordTreeLlm,
+  openAiChatTreeLlm,
   openAiEmbeddings,
-  toPgClient
+  parseJsonReply,
+  spanText,
+  stableHash,
+  toPgClient,
+  treeLlmFromModelProvider,
+  walkTree
 });
 //# sourceMappingURL=index.cjs.map