@vpxa/kb 0.1.12 → 0.1.15

package/packages/tools/dist/stratum-card.d.ts

@@ -1,31 +1,31 @@
-/**
- * kb_stratum_card — STRATUM T1/T2 context card generator.
- *
- * Generates compact context cards from files. T1 = structural metadata only
- * (~100 tokens/file). T2 = T1 + compressed content (~300 tokens/file).
- * Uses file-summary for structure and embedder for T2 content scoring.
- */
-import type { IEmbedder } from '@kb/embeddings';
-export interface StratumCardOptions {
-    files: string[];
-    query: string;
-    tier?: 'T1' | 'T2';
-    maxContentChars?: number;
+import { FileCache } from "./file-cache.js";
+import { IEmbedder } from "@kb/embeddings";
+
+//#region packages/tools/src/stratum-card.d.ts
+interface StratumCardOptions {
+  files: string[];
+  query: string;
+  tier?: 'T1' | 'T2';
+  maxContentChars?: number;
+  /** Optional file cache — avoids redundant reads and eliminates double-read with fileSummary */
+  cache?: FileCache;
 }
-export interface StratumCard {
-    path: string;
-    tier: 'T1' | 'T2';
-    card: string;
-    unknowns: string[];
-    riskTier: 'low' | 'medium' | 'high';
-    tokenEstimate: number;
-    originalTokenEstimate: number;
+interface StratumCard {
+  path: string;
+  tier: 'T1' | 'T2';
+  card: string;
+  unknowns: string[];
+  riskTier: 'low' | 'medium' | 'high';
+  tokenEstimate: number;
+  originalTokenEstimate: number;
 }
-export interface StratumCardResult {
-    cards: StratumCard[];
-    totalTokenEstimate: number;
-    totalOriginalTokenEstimate: number;
-    compressionRatio: number;
+interface StratumCardResult {
+  cards: StratumCard[];
+  totalTokenEstimate: number;
+  totalOriginalTokenEstimate: number;
+  compressionRatio: number;
 }
-export declare function stratumCard(embedder: IEmbedder, options: StratumCardOptions): Promise<StratumCardResult>;
+declare function stratumCard(embedder: IEmbedder, options: StratumCardOptions): Promise<StratumCardResult>;
+//#endregion
+export { StratumCard, StratumCardOptions, StratumCardResult, stratumCard };
 //# sourceMappingURL=stratum-card.d.ts.map

package/packages/tools/dist/stratum-card.js

@@ -1,6 +1,5 @@
-import{readFile as F}from"node:fs/promises";import{basename as h,extname as I,relative as A}from"node:path";import{fileSummary as j}from"./file-summary.js";import{cosineSimilarity as X,estimateTokens as y,segment as D}from"./text-utils.js";const M=800,S=3;async function B(t,e){const{files:r,query:o,tier:n="T1",maxContentChars:m=M}=e,u=n==="T2"?await t.embedQuery(o):null,l=await Promise.all(r.map(async i=>{try{const c=await F(i,"utf-8"),p=y(c);if(c.includes("\0"))return C(i,n,"binary","binary file",p);if(c.trim().length===0){const g=x({displayPath:T(i),tier:n,role:"empty",deps:[],exports:[],unknowns:[],riskTier:"low"});return{path:i,tier:n,card:g,unknowns:[],riskTier:"low",tokenEstimate:y(g),originalTokenEstimate:p}}const d=await j({path:i}),N=U(i,d),E=W(c,d),w=_(i,d),O=$(d),R=[...new Set(d.exports)].slice(0,5);let f=x({displayPath:T(i),tier:n,role:N,deps:O,exports:R,unknowns:E,riskTier:w});if(n==="T2"&&u){const g=await v(t,u,c,m);g.length>0&&(f=`${f}
-CONTEXT:
-${g}`)}return{path:i,tier:n,card:f,unknowns:E,riskTier:w,tokenEstimate:y(f),originalTokenEstimate:p}}catch(c){const p=c.code==="ENOENT"?"file missing":"unreadable file",d=c.code==="ENOENT"?"missing":"unreadable";return C(i,n,d,p,0)}})),s=l.reduce((i,c)=>i+c.tokenEstimate,0),a=l.reduce((i,c)=>i+c.originalTokenEstimate,0);return{cards:l,totalTokenEstimate:s,totalOriginalTokenEstimate:a,compressionRatio:a===0?0:s/a}}function C(t,e,r,o,n){const m=x({displayPath:T(t),tier:e,role:r,deps:[],exports:[],unknowns:[o],riskTier:"low"});return{path:t,tier:e,card:m,unknowns:[o],riskTier:"low",tokenEstimate:y(m),originalTokenEstimate:n}}function x(t){const{displayPath:e,tier:r,role:o,deps:n,exports:m,unknowns:u,riskTier:l}=t;return[`[${r}: ${e}]`,`ROLE: ${o}`,`DEPS: ${k(n)}`,`EXPORTS: ${k(m)}`,`UNKNOWNS: ${k(u,"; ")}`,`RISK: ${l}`].join(`
-`)}function T(t){const e=A(process.cwd(),t).replace(/\\/g,"/");return!e||e.startsWith("..")?h(t):e}function k(t,e=", "){return t.length>0?t.join(e):"none"}function U(t,e){const r=h(t),o=I(r).toLowerCase();return[".json",".yaml",".yml",".env"].includes(o)||/config|settings/i.test(r)?"configuration":/types?\.ts$|\.d\.ts$/i.test(r)?"type-definitions":/schema/i.test(r)?"schema":/test|spec/i.test(r)?"test":/index\.[jt]sx?$/i.test(r)?"barrel-export":/handler|controller|route/i.test(r)?"entry-point":/model|entity/i.test(r)?"data-model":/util|helper/i.test(r)?"utility":/service|provider/i.test(r)?"service":e.classes.length>0?"class-module":e.interfaces.length>2?"type-definitions":"implementation"}function W(t,e){const r=[],o=new Set;for(const n of t.matchAll(/\/\/\s*(TODO|FIXME|HACK|XXX)\s*:?\s*(.+)?$/gm)){const m=`${n[1]}: ${(n[2]??"").trim()}`.trim();b(r,o,m.replace(/:\s*$/,""))}K(t)&&b(r,o,"exported any usage");for(const n of $(e))b(r,o,`cross-package import: ${n}`);return r.slice(0,S)}function b(t,e,r){t.length>=S||!r||e.has(r)||(e.add(r),t.push(r))}function K(t){return[/export\s+(?:async\s+)?function\s+\w+[^\n{;]*\bany\b/g,/export\s+interface\s+\w+[\s\S]*?\{[\s\S]*?\bany\b[\s\S]*?\}/g,/export\s+type\s+\w+\s*=.*\bany\b/g,/export\s+const\s+\w+[^\n=]*\bany\b/g].some(r=>r.test(t))}function _(t,e){return/auth|token|permission|secret|credential|encrypt/i.test(t)?"high":/types?\.ts$|schema|contract|\.d\.ts$/i.test(h(t))||e.exports.length>10?"medium":"low"}function $(t){return t.imports.map(q).filter(e=>!!e).filter(e=>!e.startsWith("./")&&!e.startsWith("../")).slice(0,3)}function q(t){const e=t.match(/from\s+['"]([^'"]+)['"]/);if(e)return e[1];const r=t.match(/^import\s+['"]([^'"]+)['"]/);return r?r[1]:null}async function v(t,e,r,o){if(o<=0)return"";const n=D(r,"paragraph");if(n.length===0)return"";const m=await Promise.all(n.map(async(s,a)=>{const i=await t.embed(s);return{index:a,text:s,score:X(e,i)}})),u=[];let l=0;for(const s of m.sort((a,i)=>i.score-a.score)){const a=o-l;if(a<=0)break;if(s.text.length<=a){u.push({index:s.index,text:s.text}),l+=s.text.length;continue}u.length===0&&(u.push({index:s.index,text:s.text.slice(0,a).trimEnd()}),l=o);break}return u.sort((s,a)=>s.index-a.index).map(s=>s.text).filter(s=>s.length>0).join(`
+import{cosineSimilarity as e,estimateTokens as t,segment as n}from"./text-utils.js";import{fileSummary as r}from"./file-summary.js";import{readFile as i}from"node:fs/promises";import{basename as a,extname as o,relative as s}from"node:path";async function c(e,n){let{files:a,query:o,tier:s=`T1`,maxContentChars:c=800}=n,{cache:f}=n,h=s===`T2`?await e.embedQuery(o):null,g=await Promise.all(a.map(async n=>{try{let a=f?(await f.get(n)).content:await i(n,`utf-8`),o=t(a);if(a.includes(`\0`))return l(n,s,`binary`,`binary file`,o);if(a.trim().length===0){let e=u({displayPath:d(n),tier:s,role:`empty`,deps:[],exports:[],unknowns:[],riskTier:`low`});return{path:n,tier:s,card:e,unknowns:[],riskTier:`low`,tokenEstimate:t(e),originalTokenEstimate:o}}let g=await r({path:n,content:a}),y=p(n,g),x=m(a,g),S=_(n,g),C=v(g),w=[...new Set(g.exports)].slice(0,5),T=u({displayPath:d(n),tier:s,role:y,deps:C,exports:w,unknowns:x,riskTier:S});if(s===`T2`&&h){let t=await b(e,h,a,c);t.length>0&&(T=`${T}\nCONTEXT:\n${t}`)}return{path:n,tier:s,card:T,unknowns:x,riskTier:S,tokenEstimate:t(T),originalTokenEstimate:o}}catch(e){let t=e.code===`ENOENT`?`file missing`:`unreadable file`;return l(n,s,e.code===`ENOENT`?`missing`:`unreadable`,t,0)}})),y=g.reduce((e,t)=>e+t.tokenEstimate,0),x=g.reduce((e,t)=>e+t.originalTokenEstimate,0);return{cards:g,totalTokenEstimate:y,totalOriginalTokenEstimate:x,compressionRatio:x===0?0:y/x}}function l(e,n,r,i,a){let o=u({displayPath:d(e),tier:n,role:r,deps:[],exports:[],unknowns:[i],riskTier:`low`});return{path:e,tier:n,card:o,unknowns:[i],riskTier:`low`,tokenEstimate:t(o),originalTokenEstimate:a}}function u(e){let{displayPath:t,tier:n,role:r,deps:i,exports:a,unknowns:o,riskTier:s}=e;return[`[${n}: ${t}]`,`ROLE: ${r}`,`DEPS: ${f(i)}`,`EXPORTS: ${f(a)}`,`UNKNOWNS: ${f(o,`; `)}`,`RISK: ${s}`].join(`
+`)}function d(e){let t=s(process.cwd(),e).replace(/\\/g,`/`);return!t||t.startsWith(`..`)?a(e):t}function f(e,t=`, `){return e.length>0?e.join(t):`none`}function p(e,t){let n=a(e),r=o(n).toLowerCase();return[`.json`,`.yaml`,`.yml`,`.env`].includes(r)||/config|settings/i.test(n)?`configuration`:/types?\.ts$|\.d\.ts$/i.test(n)?`type-definitions`:/schema/i.test(n)?`schema`:/test|spec/i.test(n)?`test`:/index\.[jt]sx?$/i.test(n)?`barrel-export`:/handler|controller|route/i.test(n)?`entry-point`:/model|entity/i.test(n)?`data-model`:/util|helper/i.test(n)?`utility`:/service|provider/i.test(n)?`service`:t.classes.length>0?`class-module`:t.interfaces.length>2?`type-definitions`:`implementation`}function m(e,t){let n=[],r=new Set;for(let t of e.matchAll(/\/\/\s*(TODO|FIXME|HACK|XXX)\s*:?\s*(.+)?$/gm))h(n,r,`${t[1]}: ${(t[2]??``).trim()}`.trim().replace(/:\s*$/,``));g(e)&&h(n,r,`exported any usage`);for(let e of v(t))h(n,r,`cross-package import: ${e}`);return n.slice(0,3)}function h(e,t,n){e.length>=3||!n||t.has(n)||(t.add(n),e.push(n))}function g(e){return[/export\s+(?:async\s+)?function\s+\w+[^\n{;]*\bany\b/g,/export\s+interface\s+\w+[\s\S]*?\{[\s\S]*?\bany\b[\s\S]*?\}/g,/export\s+type\s+\w+\s*=.*\bany\b/g,/export\s+const\s+\w+[^\n=]*\bany\b/g].some(t=>t.test(e))}function _(e,t){return/auth|token|permission|secret|credential|encrypt/i.test(e)?`high`:/types?\.ts$|schema|contract|\.d\.ts$/i.test(a(e))||t.exports.length>10?`medium`:`low`}function v(e){return e.imports.map(y).filter(e=>!!e).filter(e=>!e.startsWith(`./`)&&!e.startsWith(`../`)).slice(0,3)}function y(e){let t=e.match(/from\s+['"]([^'"]+)['"]/);if(t)return t[1];let n=e.match(/^import\s+['"]([^'"]+)['"]/);return n?n[1]:null}async function b(t,r,i,a){if(a<=0)return``;let o=n(i,`paragraph`);if(o.length===0)return``;let s=await Promise.all(o.map(async(n,i)=>({index:i,text:n,score:e(r,await t.embed(n))}))),c=[],l=0;for(let e of s.sort((e,t)=>t.score-e.score)){let t=a-l;if(t<=0)break;if(e.text.length<=t){c.push({index:e.index,text:e.text}),l+=e.text.length;continue}c.length===0&&(c.push({index:e.index,text:e.text.slice(0,t).trimEnd()}),l=a);break}return c.sort((e,t)=>e.index-t.index).map(e=>e.text).filter(e=>e.length>0).join(`
 
-`)}export{B as stratumCard};
+`)}export{c as stratumCard};
+//# sourceMappingURL=stratum-card.js.map

package/packages/tools/dist/symbol.d.ts

@@ -1,28 +1,32 @@
-import type { IEmbedder } from '@kb/embeddings';
-import type { IKnowledgeStore } from '@kb/store';
-export interface SymbolInfo {
-    name: string;
-    definedIn?: {
-        path: string;
-        line: number;
-        kind: string;
-    };
-    importedBy: Array<{
-        path: string;
-        line: number;
-        importStatement: string;
-    }>;
-    referencedIn: Array<{
-        path: string;
-        line: number;
-        context: string;
-    }>;
+import { IEmbedder } from "@kb/embeddings";
+import { IKnowledgeStore } from "@kb/store";
+
+//#region packages/tools/src/symbol.d.ts
+interface SymbolInfo {
+  name: string;
+  definedIn?: {
+    path: string;
+    line: number;
+    kind: string;
+  };
+  importedBy: Array<{
+    path: string;
+    line: number;
+    importStatement: string;
+  }>;
+  referencedIn: Array<{
+    path: string;
+    line: number;
+    context: string;
+  }>;
 }
-export interface SymbolOptions {
-    /** Symbol name to look up */
-    name: string;
-    /** Limit results */
-    limit?: number;
+interface SymbolOptions {
+  /** Symbol name to look up */
+  name: string;
+  /** Limit results */
+  limit?: number;
 }
-export declare function symbol(embedder: IEmbedder, store: IKnowledgeStore, options: SymbolOptions): Promise<SymbolInfo>;
+declare function symbol(embedder: IEmbedder, store: IKnowledgeStore, options: SymbolOptions): Promise<SymbolInfo>;
+//#endregion
+export { SymbolInfo, SymbolOptions, symbol };
 //# sourceMappingURL=symbol.d.ts.map

package/packages/tools/dist/symbol.js

@@ -1,3 +1,4 @@
-function l(i){return i.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}async function P(i,d,h){const{name:t,limit:s=20}=h,m=i.embedQuery?.bind(i)??i.embed.bind(i),g=[`export function ${t}`,`export class ${t}`,`export const ${t}`,`export interface ${t}`,`export type ${t}`,`export enum ${t}`].join(" | "),x=await d.search(await m(g),{limit:s*2}),I=new RegExp(`^export\\s+(?:default\\s+)?(?:async\\s+)?(?:function|class|const|let|interface|type|enum)\\s+${l(t)}\\b`,"m");let a;for(const e of x){if(!I.test(e.record.content))continue;const r=e.record.content.match(/export\s+(?:default\s+)?(?:async\s+)?(\w+)/)?.[1]??"unknown";a={path:e.record.sourcePath,line:e.record.startLine,kind:r};break}const p=new RegExp(`import\\s+.*\\b${l(t)}\\b.*from\\s+`,"m"),$=await d.search(await m(`import ${t} from`),{limit:s*3}),f=[],u=new Set;for(const e of $){const r=e.record.content.split(`
-`);for(let n=0;n<r.length;n++){const o=r[n];if(!p.test(o))continue;const c=`${e.record.sourcePath}:${o.trim()}`;u.has(c)||(u.add(c),f.push({path:e.record.sourcePath,line:e.record.startLine+n,importStatement:o.trim()}))}}const w=new RegExp(`\\b${l(t)}\\b`),S=await d.search(await m(t),{limit:s*3}),y=[],b=new Set;for(const e of S){if(a&&e.record.sourcePath===a.path)continue;const r=e.record.content.split(`
-`);for(let n=0;n<r.length;n++){const o=r[n];if(!w.test(o)||p.test(o))continue;const c=`${e.record.sourcePath}:${e.record.startLine+n}`;if(!b.has(c)){b.add(c),y.push({path:e.record.sourcePath,line:e.record.startLine+n,context:o.trim().slice(0,120)});break}}}return{name:t,definedIn:a,importedBy:f.slice(0,s),referencedIn:y.slice(0,s)}}export{P as symbol};
+function e(e){return e.replace(/[.*+?^${}()|[\]\\]/g,`\\$&`)}async function t(t,n,r){let{name:i,limit:a=20}=r,o=t.embedQuery?.bind(t)??t.embed.bind(t),s=[`export function ${i}`,`export class ${i}`,`export const ${i}`,`export interface ${i}`,`export type ${i}`,`export enum ${i}`].join(` | `),c=await n.search(await o(s),{limit:a*2}),l=RegExp(`^export\\s+(?:default\\s+)?(?:async\\s+)?(?:function|class|const|let|interface|type|enum)\\s+${e(i)}\\b`,`m`),u;for(let e of c){if(!l.test(e.record.content))continue;let t=e.record.content.match(/export\s+(?:default\s+)?(?:async\s+)?(\w+)/)?.[1]??`unknown`;u={path:e.record.sourcePath,line:e.record.startLine,kind:t};break}let d=RegExp(`import\\s+.*\\b${e(i)}\\b.*from\\s+`,`m`),f=await n.search(await o(`import ${i} from`),{limit:a*3}),p=[],m=new Set;for(let e of f){let t=e.record.content.split(`
+`);for(let n=0;n<t.length;n++){let r=t[n];if(!d.test(r))continue;let i=`${e.record.sourcePath}:${r.trim()}`;m.has(i)||(m.add(i),p.push({path:e.record.sourcePath,line:e.record.startLine+n,importStatement:r.trim()}))}}let h=RegExp(`\\b${e(i)}\\b`),g=await n.search(await o(i),{limit:a*3}),_=[],v=new Set;for(let e of g){if(u&&e.record.sourcePath===u.path)continue;let t=e.record.content.split(`
+`);for(let n=0;n<t.length;n++){let r=t[n];if(!h.test(r)||d.test(r))continue;let i=`${e.record.sourcePath}:${e.record.startLine+n}`;if(!v.has(i)){v.add(i),_.push({path:e.record.sourcePath,line:e.record.startLine+n,context:r.trim().slice(0,120)});break}}}return{name:i,definedIn:u,importedBy:p.slice(0,a),referencedIn:_.slice(0,a)}}export{t as symbol};
+//# sourceMappingURL=symbol.js.map

package/packages/tools/dist/test-run.d.ts

@@ -1,23 +1,27 @@
-import { type ParsedTestSummary } from './parse-output.js';
-export interface TestRunOptions {
-    files?: string[];
-    cwd?: string;
-    timeout?: number;
-    grep?: string;
+import { ParsedTestSummary } from "./parse-output.js";
+
+//#region packages/tools/src/test-run.d.ts
+interface TestRunOptions {
+  files?: string[];
+  cwd?: string;
+  timeout?: number;
+  grep?: string;
 }
-export interface TestRunResult {
-    summary: ParsedTestSummary;
-    passed: boolean;
-    raw: string;
-    durationMs: number;
+interface TestRunResult {
+  summary: ParsedTestSummary;
+  passed: boolean;
+  raw: string;
+  durationMs: number;
 }
-export declare function testRun(options?: TestRunOptions): Promise<TestRunResult>;
+declare function testRun(options?: TestRunOptions): Promise<TestRunResult>;
 /**
  * Classify non-zero exit codes — some tools use exit code 1 for
  * non-error conditions (e.g., grep returns 1 for "no matches").
  */
-export declare function classifyExitCode(exitCode: number, _stdout: string, command?: string): {
-    isError: boolean;
-    reason?: string;
+declare function classifyExitCode(exitCode: number, _stdout: string, command?: string): {
+  isError: boolean;
+  reason?: string;
 };
+//#endregion
+export { TestRunOptions, TestRunResult, classifyExitCode, testRun };
 //# sourceMappingURL=test-run.d.ts.map

package/packages/tools/dist/test-run.js

@@ -1,2 +1,3 @@
-import{execFile as f}from"node:child_process";import{promisify as c}from"node:util";import{parseVitest as u}from"./parse-output.js";const m=c(f);async function w(r={}){const e=r.cwd??process.cwd(),t=r.timeout??6e4,n=Date.now(),i=["vitest","run","--reporter=verbose"];r.files?.length&&i.push(...r.files),r.grep&&i.push("--testNamePattern",r.grep);try{const{stdout:o}=await m("npx",i,{cwd:e,shell:!0,timeout:t}),s=o.toString(),a=u(s);return{summary:a,passed:a.failed===0,raw:s,durationMs:Date.now()-n}}catch(o){const s=g(o);return{summary:u(s),passed:!1,raw:s,durationMs:Date.now()-n}}}function g(r){const e=r,t=e.stdout?.toString()??"",n=e.stderr?.toString()??"";return[t,n].filter(Boolean).join(`
-`).trim()||e.message||"Test run failed"}function y(r,e,t){if(r===0)return{isError:!1};if(r===1&&t){if(/\b(grep|rg|ripgrep|ag|ack|findstr)\b/i.test(t))return{isError:!1,reason:"grep: no matches (exit 1 is normal)"};if(/\bdiff\b/i.test(t))return{isError:!1,reason:"diff: files differ (exit 1 is normal)"}}return{isError:!0}}export{y as classifyExitCode,w as testRun};
+import{parseVitest as e}from"./parse-output.js";import{execFile as t}from"node:child_process";import{promisify as n}from"node:util";const r=n(t);let i=0;async function a(e={}){if(i>=2)throw Error(`Too many concurrent test runs (max 2). Try again later.`);i++;try{return await o(e)}finally{i--}}async function o(t){let n=t.cwd??process.cwd(),i=t.timeout??6e4,a=Date.now(),o=[`vitest`,`run`,`--reporter=verbose`];t.files?.length&&o.push(...t.files),t.grep&&o.push(`--testNamePattern`,t.grep);try{let{stdout:t}=await r(`npx`,o,{cwd:n,shell:!0,timeout:i}),s=t.toString(),c=e(s);return{summary:c,passed:c.failed===0,raw:s,durationMs:Date.now()-a}}catch(t){let n=s(t);return{summary:e(n),passed:!1,raw:n,durationMs:Date.now()-a}}}function s(e){let t=e;return[t.stdout?.toString()??``,t.stderr?.toString()??``].filter(Boolean).join(`
+`).trim()||t.message||`Test run failed`}function c(e,t,n){if(e===0)return{isError:!1};if(e===1&&n){if(/\b(grep|rg|ripgrep|ag|ack|findstr)\b/i.test(n))return{isError:!1,reason:`grep: no matches (exit 1 is normal)`};if(/\bdiff\b/i.test(n))return{isError:!1,reason:`diff: files differ (exit 1 is normal)`}}return{isError:!0}}export{c as classifyExitCode,a as testRun};
+//# sourceMappingURL=test-run.js.map

package/packages/tools/dist/text-utils.d.ts

@@ -1,16 +1,19 @@
+//#region packages/tools/src/text-utils.d.ts
 /**
  * Shared text utilities used by compact, digest, stratum-card, and other tools.
  */
 /**
  * Approximate token count from character count (~4 chars/token).
  */
-export declare function estimateTokens(text: string): number;
+declare function estimateTokens(text: string): number;
 /**
  * Segment text into chunks for scoring.
  */
-export declare function segment(text: string, strategy: 'paragraph' | 'sentence' | 'line'): string[];
+declare function segment(text: string, strategy: 'paragraph' | 'sentence' | 'line'): string[];
 /**
  * Cosine similarity between two vectors.
  */
-export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+//#endregion
+export { cosineSimilarity, estimateTokens, segment };
 //# sourceMappingURL=text-utils.d.ts.map

package/packages/tools/dist/text-utils.js

@@ -1,2 +1,3 @@
-function a(e){return Math.ceil(e.length/4)}function o(e,n){switch(n){case"paragraph":return e.split(/\n\s*\n/).map(t=>t.trim()).filter(t=>t.length>0);case"sentence":return e.split(/(?<=[.!?])\s+/).map(t=>t.trim()).filter(t=>t.length>0);case"line":return e.split(`
-`).map(t=>t.trim()).filter(t=>t.length>0)}}function m(e,n){let t=0,i=0,l=0;for(let r=0;r<e.length;r++)t+=e[r]*n[r],i+=e[r]*e[r],l+=n[r]*n[r];const s=Math.sqrt(i)*Math.sqrt(l);return s===0?0:t/s}export{m as cosineSimilarity,a as estimateTokens,o as segment};
+function e(e){return Math.ceil(e.length/4)}function t(e,t){switch(t){case`paragraph`:return e.split(/\n\s*\n/).map(e=>e.trim()).filter(e=>e.length>0);case`sentence`:return e.split(/(?<=[.!?])\s+/).map(e=>e.trim()).filter(e=>e.length>0);case`line`:return e.split(`
+`).map(e=>e.trim()).filter(e=>e.length>0)}}function n(e,t){let n=0,r=0,i=0;for(let a=0;a<e.length;a++)n+=e[a]*t[a],r+=e[a]*e[a],i+=t[a]*t[a];let a=Math.sqrt(r)*Math.sqrt(i);return a===0?0:n/a}export{n as cosineSimilarity,e as estimateTokens,t as segment};
+//# sourceMappingURL=text-utils.js.map

package/packages/tools/dist/time-utils.d.ts

@@ -1,18 +1,21 @@
+//#region packages/tools/src/time-utils.d.ts
 /**
  * kb_time — Timezone conversion, date parsing, duration calculation.
  */
-export type TimeOperation = 'now' | 'parse' | 'convert' | 'diff' | 'add';
-export interface TimeOptions {
-    operation: TimeOperation;
-    input?: string;
-    timezone?: string;
-    duration?: string;
+type TimeOperation = 'now' | 'parse' | 'convert' | 'diff' | 'add';
+interface TimeOptions {
+  operation: TimeOperation;
+  input?: string;
+  timezone?: string;
+  duration?: string;
 }
-export interface TimeResult {
-    output: string;
-    iso: string;
-    unix: number;
-    details?: Record<string, string | number>;
+interface TimeResult {
+  output: string;
+  iso: string;
+  unix: number;
+  details?: Record<string, string | number>;
 }
-export declare function timeUtils(options: TimeOptions): TimeResult;
+declare function timeUtils(options: TimeOptions): TimeResult;
+//#endregion
+export { TimeOperation, TimeOptions, TimeResult, timeUtils };
 //# sourceMappingURL=time-utils.d.ts.map

package/packages/tools/dist/time-utils.js

@@ -1 +1,2 @@
-function h(o){const{operation:e,input:t,timezone:n}=o;switch(e){case"now":return m(new Date,n);case"parse":{if(!t)throw new Error("input required for parse");return m(u(t),n)}case"convert":{if(!t)throw new Error("input required for convert");if(!n)throw new Error("timezone required for convert");return m(u(t),n)}case"diff":{if(!t)throw new Error("input required for diff (two comma-separated dates)");const r=t.split(",").map(c=>c.trim());if(r.length<2)throw new Error("diff requires two comma-separated dates");const i=u(r[0]),a=u(r[1]),s=Math.abs(a.getTime()-i.getTime());return{output:f(s),iso:`PT${Math.floor(s/1e3)}S`,unix:s,details:{milliseconds:s,seconds:Math.floor(s/1e3),minutes:Math.floor(s/6e4),hours:Math.floor(s/36e5),days:Math.floor(s/864e5)}}}case"add":{if(!t)throw new Error("input required for add");const{duration:r}=o;if(!r)throw new Error('duration required for add (e.g., "2h30m")');const i=u(t),a=d(r);return m(new Date(i.getTime()+a),n)}default:throw new Error(`Unknown operation: ${e}`)}}function u(o){const e=Number(o);if(!Number.isNaN(e))return new Date(e>1e12?e:e*1e3);const t=new Date(o);if(Number.isNaN(t.getTime()))throw new Error(`Cannot parse date: ${o}`);return t}function m(o,e){const t=e??"UTC",n=o.toLocaleString("en-US",{timeZone:t,dateStyle:"full",timeStyle:"long"}),r=new Intl.DateTimeFormat("en-US",{timeZone:t,year:"numeric",month:"numeric",day:"numeric",hour:"numeric",minute:"numeric",second:"numeric",hour12:!1}).formatToParts(o).reduce((i,a)=>(a.type!=="literal"&&(i[a.type]=Number.parseInt(a.value,10)),i),{});return{output:n,iso:o.toISOString(),unix:Math.floor(o.getTime()/1e3),details:{timezone:t,year:r.year,month:r.month,day:r.day,hour:r.hour===24?0:r.hour,minute:r.minute,second:r.second}}}function f(o){const e=[],t=Math.floor(o/864e5);t&&e.push(`${t}d`);const n=Math.floor(o%864e5/36e5);n&&e.push(`${n}h`);const r=Math.floor(o%36e5/6e4);r&&e.push(`${r}m`);const i=Math.floor(o%6e4/1e3);return(i||e.length===0)&&e.push(`${i}s`),e.join(" ")}function d(o){let e=0;const t=o.matchAll(/(\d+)\s*(d|h|m|s|ms)/gi);for(const n of t){const r=Number(n[1]);switch(n[2].toLowerCase()){case"d":e+=r*864e5;break;case"h":e+=r*36e5;break;case"m":e+=r*6e4;break;case"s":e+=r*1e3;break;case"ms":e+=r;break}}if(e===0)throw new Error(`Cannot parse duration: ${o}`);return e}export{h as timeUtils};
+function e(e){let{operation:a,input:o,timezone:s}=e;switch(a){case`now`:return n(new Date,s);case`parse`:if(!o)throw Error(`input required for parse`);return n(t(o),s);case`convert`:if(!o)throw Error(`input required for convert`);if(!s)throw Error(`timezone required for convert`);return n(t(o),s);case`diff`:{if(!o)throw Error(`input required for diff (two comma-separated dates)`);let e=o.split(`,`).map(e=>e.trim());if(e.length<2)throw Error(`diff requires two comma-separated dates`);let n=t(e[0]),i=t(e[1]),a=Math.abs(i.getTime()-n.getTime());return{output:r(a),iso:`PT${Math.floor(a/1e3)}S`,unix:a,details:{milliseconds:a,seconds:Math.floor(a/1e3),minutes:Math.floor(a/6e4),hours:Math.floor(a/36e5),days:Math.floor(a/864e5)}}}case`add`:{if(!o)throw Error(`input required for add`);let{duration:r}=e;if(!r)throw Error(`duration required for add (e.g., "2h30m")`);let a=t(o),c=i(r);return n(new Date(a.getTime()+c),s)}default:throw Error(`Unknown operation: ${a}`)}}function t(e){let t=Number(e);if(!Number.isNaN(t))return new Date(t>0xe8d4a51000?t:t*1e3);let n=new Date(e);if(Number.isNaN(n.getTime()))throw Error(`Cannot parse date: ${e}`);return n}function n(e,t){let n=t??`UTC`,r=e.toLocaleString(`en-US`,{timeZone:n,dateStyle:`full`,timeStyle:`long`}),i=new Intl.DateTimeFormat(`en-US`,{timeZone:n,year:`numeric`,month:`numeric`,day:`numeric`,hour:`numeric`,minute:`numeric`,second:`numeric`,hour12:!1}).formatToParts(e).reduce((e,t)=>(t.type!==`literal`&&(e[t.type]=Number.parseInt(t.value,10)),e),{});return{output:r,iso:e.toISOString(),unix:Math.floor(e.getTime()/1e3),details:{timezone:n,year:i.year,month:i.month,day:i.day,hour:i.hour===24?0:i.hour,minute:i.minute,second:i.second}}}function r(e){let t=[],n=Math.floor(e/864e5);n&&t.push(`${n}d`);let r=Math.floor(e%864e5/36e5);r&&t.push(`${r}h`);let i=Math.floor(e%36e5/6e4);i&&t.push(`${i}m`);let a=Math.floor(e%6e4/1e3);return(a||t.length===0)&&t.push(`${a}s`),t.join(` `)}function i(e){let t=0,n=e.matchAll(/(\d+)\s*(d|h|m|s|ms)/gi);for(let e of n){let n=Number(e[1]);switch(e[2].toLowerCase()){case`d`:t+=n*864e5;break;case`h`:t+=n*36e5;break;case`m`:t+=n*6e4;break;case`s`:t+=n*1e3;break;case`ms`:t+=n;break}}if(t===0)throw Error(`Cannot parse duration: ${e}`);return t}export{e as timeUtils};
+//# sourceMappingURL=time-utils.js.map

package/packages/tools/dist/trace.d.ts

@@ -1,24 +1,28 @@
-import type { IEmbedder } from '@kb/embeddings';
-import type { IKnowledgeStore } from '@kb/store';
-export interface TraceOptions {
-    /** Starting point — a symbol or file:line reference */
-    start: string;
-    /** Direction */
-    direction: 'forward' | 'backward' | 'both';
-    /** Max depth (default: 3) */
-    maxDepth?: number;
+import { IEmbedder } from "@kb/embeddings";
+import { IKnowledgeStore } from "@kb/store";
+
+//#region packages/tools/src/trace.d.ts
+interface TraceOptions {
+  /** Starting point — a symbol or file:line reference */
+  start: string;
+  /** Direction */
+  direction: 'forward' | 'backward' | 'both';
+  /** Max depth (default: 3) */
+  maxDepth?: number;
 }
-export interface TraceNode {
-    path: string;
-    symbol: string;
-    line: number;
-    relationship: 'calls' | 'called-by' | 'imports' | 'imported-by' | 'references';
+interface TraceNode {
+  path: string;
+  symbol: string;
+  line: number;
+  relationship: 'calls' | 'called-by' | 'imports' | 'imported-by' | 'references';
 }
-export interface TraceResult {
-    start: string;
-    direction: string;
-    nodes: TraceNode[];
-    depth: number;
+interface TraceResult {
+  start: string;
+  direction: string;
+  nodes: TraceNode[];
+  depth: number;
 }
-export declare function trace(embedder: IEmbedder, store: IKnowledgeStore, options: TraceOptions): Promise<TraceResult>;
+declare function trace(embedder: IEmbedder, store: IKnowledgeStore, options: TraceOptions): Promise<TraceResult>;
+//#endregion
+export { TraceNode, TraceOptions, TraceResult, trace };
 //# sourceMappingURL=trace.d.ts.map

package/packages/tools/dist/trace.js

@@ -1,2 +1,3 @@
-async function v(e,a,r){const{start:s,direction:d,maxDepth:T=3}=r,i=[],x=new Set,p=new Set,R=await e.embed(s);if((await a.search(R,{limit:10})).length===0)return{start:s,direction:d,nodes:i,depth:0};const u=[{target:s,depth:0}];let n=0;for(;u.length>0;){const t=u.shift();if(!t)break;if(t.depth>=T||x.has(t.target))continue;x.add(t.target);const N=await e.embed(t.target),P=await a.search(N,{limit:20}),c=E(t.target),l=k(t.target);for(const b of P){const w=b.record.content.split(`
-`);for(let h=0;h<w.length;h+=1){const o=w[h],m=b.record.startLine+h,f=b.record.sourcePath;if(d!=="forward"&&(l?new RegExp(`from\\s+['"]${c}['"]`):new RegExp(`import\\s+.*\\b${c}\\b.*from\\s+`)).test(o)){g(p,i,{path:f,symbol:t.target,line:m,relationship:"imported-by"}),n=Math.max(n,t.depth+1);const $=o.match(/from\s+['"]([^'"]+)['"]/);!l&&$&&u.push({target:$[1],depth:t.depth+1})}d!=="backward"&&(l?new RegExp(`from\\s+['"]${c}['"]`).test(o)&&(g(p,i,{path:f,symbol:t.target,line:m,relationship:"imports"}),n=Math.max(n,t.depth+1)):new RegExp(`\\b${c}\\s*\\(`).test(o)&&!/^\s*(?:export\s+)?(?:async\s+)?function\s/.test(o)&&(g(p,i,{path:f,symbol:t.target,line:m,relationship:"calls"}),n=Math.max(n,t.depth+1))),(l?new RegExp(`['"]${c}['"]`):new RegExp(`\\b${c}\\b`)).test(o)&&!/^\s*import\s/.test(o)&&!/^\s*(?:export\s+)?(?:async\s+)?function\s/.test(o)&&(g(p,i,{path:f,symbol:t.target,line:m,relationship:"references"}),n=Math.max(n,t.depth+1))}}}return{start:s,direction:d,nodes:M(i),depth:n}}function g(e,a,r){const s=`${r.path}:${r.line}:${r.relationship}`;e.has(s)||(e.add(s),a.push(r))}function E(e){return e.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}function k(e){return/[./\\]/.test(e)}function M(e){const a=new Set;return e.filter(r=>{const s=`${r.path}:${r.line}:${r.relationship}`;return a.has(s)?!1:(a.add(s),!0)})}export{v as trace};
+async function e(e,a,o){let{start:s,direction:c,maxDepth:l=3}=o,u=[],d=new Set,f=new Set,p=await e.embed(s);if((await a.search(p,{limit:10})).length===0)return{start:s,direction:c,nodes:u,depth:0};let m=[{target:s,depth:0}],h=0;for(;m.length>0;){let i=m.shift();if(!i)break;if(i.depth>=l||d.has(i.target))continue;d.add(i.target);let o=await e.embed(i.target),s=await a.search(o,{limit:20}),p=n(i.target),g=r(i.target);for(let e of s){let n=e.record.content.split(`
+`);for(let r=0;r<n.length;r+=1){let a=n[r],o=e.record.startLine+r,s=e.record.sourcePath;if(c!==`forward`&&RegExp(g?`from\\s+['"]${p}['"]`:`import\\s+.*\\b${p}\\b.*from\\s+`).test(a)){t(f,u,{path:s,symbol:i.target,line:o,relationship:`imported-by`}),h=Math.max(h,i.depth+1);let e=a.match(/from\s+['"]([^'"]+)['"]/);!g&&e&&m.push({target:e[1],depth:i.depth+1})}c!==`backward`&&(g?RegExp(`from\\s+['"]${p}['"]`).test(a)&&(t(f,u,{path:s,symbol:i.target,line:o,relationship:`imports`}),h=Math.max(h,i.depth+1)):RegExp(`\\b${p}\\s*\\(`).test(a)&&!/^\s*(?:export\s+)?(?:async\s+)?function\s/.test(a)&&(t(f,u,{path:s,symbol:i.target,line:o,relationship:`calls`}),h=Math.max(h,i.depth+1))),RegExp(g?`['"]${p}['"]`:`\\b${p}\\b`).test(a)&&!/^\s*import\s/.test(a)&&!/^\s*(?:export\s+)?(?:async\s+)?function\s/.test(a)&&(t(f,u,{path:s,symbol:i.target,line:o,relationship:`references`}),h=Math.max(h,i.depth+1))}}}return{start:s,direction:c,nodes:i(u),depth:h}}function t(e,t,n){let r=`${n.path}:${n.line}:${n.relationship}`;e.has(r)||(e.add(r),t.push(n))}function n(e){return e.replace(/[.*+?^${}()|[\]\\]/g,`\\$&`)}function r(e){return/[./\\]/.test(e)}function i(e){let t=new Set;return e.filter(e=>{let n=`${e.path}:${e.line}:${e.relationship}`;return t.has(n)?!1:(t.add(n),!0)})}export{e as trace};
+//# sourceMappingURL=trace.js.map

package/packages/tools/dist/truncation.d.ts

@@ -1,3 +1,4 @@
+//#region packages/tools/src/truncation.d.ts
 /**
  * Smart truncation utilities.
  *
@@ -13,10 +14,21 @@
  * @param headRatio - Fraction for head portion (default 0.6)
  * @returns Truncated text with separator showing omitted line/char count
  */
-export declare function headTailTruncate(text: string, maxLen: number, headRatio?: number): string;
+declare function headTailTruncate(text: string, maxLen: number, headRatio?: number): string;
 /**
  * Truncate at a paragraph boundary near maxLength (head-only).
  * Best for web content and markdown where structure is at the top.
  */
-export declare function paragraphTruncate(text: string, maxLen: number): string;
+declare function paragraphTruncate(text: string, maxLen: number): string;
+/**
+ * Truncate text to fit within a token budget.
+ * Uses ~4 chars/token approximation. Snaps to line boundaries.
+ *
+ * @param text - Full text to truncate
+ * @param maxTokens - Maximum token count
+ * @returns Original text if within budget, or truncated with notice
+ */
+declare function truncateToTokenBudget(text: string, maxTokens: number): string;
+//#endregion
+export { headTailTruncate, paragraphTruncate, truncateToTokenBudget };
 //# sourceMappingURL=truncation.d.ts.map

package/packages/tools/dist/truncation.js

@@ -1,14 +1,8 @@
-const T=.6;function m(t,n,c=.6){if(t.length<=n)return t;const o=Math.max(0,n-120),e=Math.floor(o*c),a=o-e,s=t.slice(0,e),h=s.lastIndexOf(`
-`),i=h>0?s.slice(0,h):s,p=t.length-a,l=t.slice(p),d=l.indexOf(`
-`),r=d>=0?l.slice(d+1):l,$=t.length-i.length-r.length;let u=1;const B=i.length,R=t.length-r.length;for(let g=B;g<R;g++)t.charCodeAt(g)===10&&u++;return`${i}
-
-[\u2026 ${u} lines / ${($/1024).toFixed(1)}KB truncated \u2014 showing first ${i.split(`
-`).length} + last ${r.split(`
-`).length} lines]
-
-${r}`}function A(t,n){if(t.length<=n)return t;const c=Math.max(0,n-200),o=t.slice(c,n).lastIndexOf(`
-
-`),e=o>=0?c+o:n,a=t.slice(0,e).trimEnd(),s=Math.round(e/t.length*100);return`${a}
-
----
-*[Truncated at ${e.toLocaleString()} chars \u2014 ${s}% of original content]*`}export{m as headTailTruncate,A as paragraphTruncate};
+function e(e,t,n=.6){if(e.length<=t)return e;let r=Math.max(0,t-120),i=Math.floor(r*n),a=r-i,o=e.slice(0,i),s=o.lastIndexOf(`
+`),c=s>0?o.slice(0,s):o,l=e.length-a,u=e.slice(l),d=u.indexOf(`
+`),f=d>=0?u.slice(d+1):u,p=e.length-c.length-f.length,m=1,h=c.length,g=e.length-f.length;for(let t=h;t<g;t++)e.charCodeAt(t)===10&&m++;return`${c}\n\n[… ${m} lines / ${(p/1024).toFixed(1)}KB truncated — showing first ${c.split(`
+`).length} + last ${f.split(`
+`).length} lines]\n\n${f}`}function t(e,t){if(e.length<=t)return e;let n=Math.max(0,t-200),r=e.slice(n,t).lastIndexOf(`
+
+`),i=r>=0?n+r:t,a=e.slice(0,i).trimEnd(),o=Math.round(i/e.length*100);return`${a}\n\n---\n*[Truncated at ${i.toLocaleString()} chars — ${o}% of original content]*`}function n(t,n){let r=n*4;return t.length<=r?t:e(t,r)}export{e as headTailTruncate,t as paragraphTruncate,n as truncateToTokenBudget};
+//# sourceMappingURL=truncation.js.map

package/packages/tools/dist/watch.d.ts

@@ -1,30 +1,33 @@
-export interface WatchEvent {
-    type: 'change' | 'rename';
-    path: string;
-    timestamp: string;
+//#region packages/tools/src/watch.d.ts
+interface WatchEvent {
+  type: 'change' | 'rename';
+  path: string;
+  timestamp: string;
 }
-export interface WatchOptions {
-    /** Directory to watch */
-    path: string;
-    /** Glob patterns to exclude */
-    exclude?: string[];
-    /** Max events to buffer (default: 100) */
-    maxEvents?: number;
+interface WatchOptions {
+  /** Directory to watch */
+  path: string;
+  /** Glob patterns to exclude */
+  exclude?: string[];
+  /** Max events to buffer (default: 100) */
+  maxEvents?: number;
 }
-export interface WatchHandle {
-    id: string;
-    path: string;
-    events: WatchEvent[];
-    status: 'watching' | 'stopped';
-    stop: () => void;
-    getEvents: (since?: string) => WatchEvent[];
+interface WatchHandle {
+  id: string;
+  path: string;
+  events: WatchEvent[];
+  status: 'watching' | 'stopped';
+  stop: () => void;
+  getEvents: (since?: string) => WatchEvent[];
 }
-export declare function watchStart(options: WatchOptions): WatchHandle;
-export declare function watchStop(id: string): boolean;
-export declare function watchList(): Array<{
-    id: string;
-    path: string;
-    status: string;
-    eventCount: number;
+declare function watchStart(options: WatchOptions): WatchHandle;
+declare function watchStop(id: string): boolean;
+declare function watchList(): Array<{
+  id: string;
+  path: string;
+  status: string;
+  eventCount: number;
 }>;
+//#endregion
+export { WatchEvent, WatchHandle, WatchOptions, watchList, watchStart, watchStop };
 //# sourceMappingURL=watch.d.ts.map

package/packages/tools/dist/watch.js

@@ -1 +1,2 @@
-import{watch as g}from"node:fs";const r=new Map,m=["node_modules",".git","dist",".turbo",".kb-data","cdk.out"];function v(t){const{path:s,maxEvents:p=100}=t,d=t.exclude??m,c=`watch-${Date.now()}`,e=[],l=n=>d.some(a=>o(n).includes(o(a))),u=g(s,{recursive:!0},(n,a)=>{if(a==null)return;const h=String(a);!h||l(h)||(e.push({type:n,path:o(h),timestamp:new Date().toISOString()}),e.length>p&&e.shift())}),i={id:c,path:s,events:e,status:"watching",stop:()=>{u.close(),i.status="stopped",r.delete(c)},getEvents:n=>n?e.filter(a=>a.timestamp>n):e};return r.set(c,{watcher:u,handle:i}),i}function w(t){const s=r.get(t);return s?(s.handle.stop(),!0):!1}function x(){return[...r.values()].map(t=>({id:t.handle.id,path:t.handle.path,status:t.handle.status,eventCount:t.handle.events.length}))}function o(t){return t.replace(/\\/g,"/")}export{x as watchList,v as watchStart,w as watchStop};
+import{watch as e}from"node:fs";const t=new Map,n=[`node_modules`,`.git`,`dist`,`.turbo`,`.kb-data`,`cdk.out`];function r(r){if(t.size>=20)throw Error(`Watcher limit reached (20). Stop existing watchers first.`);let{path:i,maxEvents:a=100}=r,s=r.exclude??n,c=`watch-${Date.now()}`,l=[],u=e=>s.some(t=>o(e).includes(o(t))),d=e(i,{recursive:!0},(e,t)=>{if(t==null)return;let n=String(t);!n||u(n)||(l.push({type:e,path:o(n),timestamp:new Date().toISOString()}),l.length>a&&l.shift())});d.on(`error`,()=>{f.status=`stopped`,t.delete(c);try{d.close()}catch{}});let f={id:c,path:i,events:l,status:`watching`,stop:()=>{d.close(),f.status=`stopped`,t.delete(c)},getEvents:e=>e?l.filter(t=>t.timestamp>e):l};return t.set(c,{watcher:d,handle:f}),f}function i(e){let n=t.get(e);return n?(n.handle.stop(),!0):!1}function a(){return[...t.values()].map(e=>({id:e.handle.id,path:e.handle.path,status:e.handle.status,eventCount:e.handle.events.length}))}function o(e){return e.replace(/\\/g,`/`)}export{a as watchList,r as watchStart,i as watchStop};
+//# sourceMappingURL=watch.js.map

package/packages/tools/dist/web-fetch.d.ts

@@ -1,3 +1,4 @@
+//#region packages/tools/src/web-fetch.d.ts
 /**
  * kb_web_fetch — Fetch a web page and convert to LLM-friendly format.
  *
@@ -5,41 +6,43 @@
  * extracted links, or heading outline. Strips scripts, styles,
  * and non-content elements for compact, token-efficient output.
  */
-export type WebFetchMode = 'markdown' | 'raw' | 'links' | 'outline';
-export interface WebFetchOptions {
-    /** URL to fetch */
-    url: string;
-    /** Output mode */
-    mode?: WebFetchMode;
-    /** CSS selector to extract specific element (default: auto-detect main content) */
-    selector?: string;
-    /** Max characters in output — smart truncation at paragraph boundaries */
-    maxLength?: number;
-    /** Include page metadata header (title, description, URL) */
-    includeMetadata?: boolean;
-    /** Append extracted links list at the end */
-    includeLinks?: boolean;
-    /** Include image alt texts inline */
-    includeImages?: boolean;
-    /** Request timeout in milliseconds */
-    timeout?: number;
+type WebFetchMode = 'markdown' | 'raw' | 'links' | 'outline';
+interface WebFetchOptions {
+  /** URL to fetch */
+  url: string;
+  /** Output mode */
+  mode?: WebFetchMode;
+  /** CSS selector to extract specific element (default: auto-detect main content) */
+  selector?: string;
+  /** Max characters in output — smart truncation at paragraph boundaries */
+  maxLength?: number;
+  /** Include page metadata header (title, description, URL) */
+  includeMetadata?: boolean;
+  /** Append extracted links list at the end */
+  includeLinks?: boolean;
+  /** Include image alt texts inline */
+  includeImages?: boolean;
+  /** Request timeout in milliseconds */
+  timeout?: number;
 }
-export interface WebFetchResult {
-    /** The converted content */
-    content: string;
-    /** Page title */
-    title: string;
-    /** Page description (from meta) */
-    description: string;
-    /** Final URL after redirects */
-    url: string;
-    /** Content length before truncation */
-    originalLength: number;
-    /** Whether content was truncated */
-    truncated: boolean;
+interface WebFetchResult {
+  /** The converted content */
+  content: string;
+  /** Page title */
+  title: string;
+  /** Page description (from meta) */
+  description: string;
+  /** Final URL after redirects */
+  url: string;
+  /** Content length before truncation */
+  originalLength: number;
+  /** Whether content was truncated */
+  truncated: boolean;
 }
 /**
  * Fetch a web page and convert to an LLM-friendly format.
  */
-export declare function webFetch(options: WebFetchOptions): Promise<WebFetchResult>;
+declare function webFetch(options: WebFetchOptions): Promise<WebFetchResult>;
+//#endregion
+export { WebFetchMode, WebFetchOptions, WebFetchResult, webFetch };
 //# sourceMappingURL=web-fetch.d.ts.map