@opengeni/jev 0.1.0-canary.36199476632001

package/dist/code-search/search.d.ts

@@ -0,0 +1,93 @@
+/**
+ * search.ts - the code_search pipeline (scout-0.3.1 with the Jev judge):
+ *
+ *  1. recall   (ripgrep)                        -> top maxCandidates files by distinct-keyword IDF
+ *  2. wave 1   (file triage, 1 Noul per file)   -> up to maxFiles files (+ lexical guard)
+ *  3. wave 2   (passage verification)           -> relevance + per-sub-question coverage per passage
+ *  4. wave 3   (leads, exactly one round)       -> <= maxLeadsFollowed definitions, verified like wave 2
+ *  5. pack     (bounded, verbatim, line-numbered) + status (1 request over the packed evidence)
+ *
+ * Every file and process access goes through the injected CodeSearchWorkspace. A Jev failure fails the
+ * search (JevUnavailableError / JevRequestError propagate); only a failed final status check keeps the
+ * fully Jev-scored pack and reports the status as unknown.
+ */
+import { JevRequestError, JevUnavailableError, type JevClient } from "../client.js";
+import { type CodeSearchConfig } from "./config.js";
+import { type FileCandidate, type KeywordInfo, type RecallResult } from "./recall.js";
+import type { CodeSearchWorkspace } from "./workspace.js";
+/** The validated research version this engine ports (ranking, thresholds and defaults are unchanged). */
+export declare const CODE_SEARCH_ENGINE_VERSION = "scout-0.3.1";
+export declare const CODE_SEARCH_DEFAULT_BUDGET_TOKENS = 12000;
+export interface CodeSearchInput {
+    question: string;
+    keywords: string[];
+    subQuestions?: string[] | undefined;
+    /** Workspace-relative path prefixes to search; default the whole workspace. */
+    paths?: string[] | undefined;
+    workspace: CodeSearchWorkspace;
+    jev: JevClient;
+    signal?: AbortSignal | undefined;
+    /** Max pack size in tokens (default 12000). */
+    budgetTokens?: number | undefined;
+    /** Tuning and tests only; defaults to DEFAULT_CODE_SEARCH_CONFIG. */
+    config?: CodeSearchConfig | undefined;
+    /** In-memory stage trace (recall, wave1, wave2, leads, pack, summary, and one "jev" event per Jev request). */
+    onStage?: ((stage: string, data: Record<string, unknown>) => void) | undefined;
+}
+export interface CodeSearchStatus {
+    label: "sufficient" | "partial" | "insufficient" | "unknown";
+    overall: number | null;
+    subs: Array<number | null>;
+    /** Set when the final Jev sufficiency check failed (the pack itself is fully Jev-scored). */
+    error?: string;
+}
+export interface CodeSearchStats {
+    wallMs: number;
+    stageMs: Record<string, number>;
+    candidates: number;
+    filesSelected: number;
+    passagesVerified: number;
+    passagesIncluded: number;
+    packChars: number;
+    packTokensEst: number;
+    workspaceCalls: number;
+    /** A ripgrep call returned partial output (byte cap or time limit); the pack header says so. */
+    ripgrepTruncated: boolean;
+    jev: {
+        requests: number;
+        inputTokens: number;
+        costUsd: number;
+        model: string | null;
+    };
+}
+export interface CodeSearchResult {
+    version: string;
+    /** The rendered pack: a status header line, verbatim line-numbered passages, then the footer. */
+    text: string;
+    status: CodeSearchStatus;
+    stats: CodeSearchStats;
+    /** The error of a failed final status check, for a circuit breaker (the search itself succeeded). */
+    statusCheckError?: JevUnavailableError | JevRequestError;
+}
+/** Lexical passage relevance in [0,1]: keyword IDF mass present, question-term overlap, file prior. */
+export declare function lexicalPassageScore(text: string, kwPresent: number[], keywords: KeywordInfo[], qTerms: string[], fileNorm: number): number;
+export declare function selectFiles(cands: FileCandidate[], scores: Map<string, number>, ids: string[], T1: number, cfg: CodeSearchConfig): {
+    selected: number[];
+    ranked: number[];
+};
+/** Round-robin across files (priority order), each file's windows by score, up to max. */
+export declare function capPassages<T extends {
+    score: number;
+}>(perFile: T[][], max: number): T[][];
+/** Evidence text for the status check: included passages, best first, up to maxChars (whole blocks only). */
+export declare function statusEvidence(included: Array<{
+    block: string;
+    rel: number;
+}>, maxChars: number): string;
+export declare function statusLabel(s: {
+    overall: number;
+    subs: number[];
+} | null, cfg: CodeSearchConfig): CodeSearchStatus;
+/** Footer note about paths that were missing, or a search that had to widen to the whole workspace. */
+export declare function prefixNote(rec: Pick<RecallResult, "missingPrefixes" | "widened" | "validPrefixes">): string | undefined;
+export declare function runCodeSearch(input: CodeSearchInput): Promise<CodeSearchResult>;

package/dist/code-search/session.d.ts

@@ -0,0 +1,33 @@
+/**
+ * session.ts - one search's view of the workspace: counts calls, records partial ripgrep output and
+ * makes every call honour the search's AbortSignal.
+ */
+import { type CodeSearchWorkspace } from "./workspace.js";
+/** Parallel reads per search. */
+export declare const READ_CONCURRENCY = 8;
+/** Parallel ripgrep calls for one pattern split under CODE_SEARCH_MAX_PATTERN_CHARS. */
+export declare const RIPGREP_SPLIT_CONCURRENCY = 4;
+export declare class WorkspaceSession {
+    private readonly workspace;
+    readonly signal: AbortSignal;
+    private readonly ripgrepTimeoutMs;
+    calls: number;
+    /** A ripgrep call returned output cut at the adapter's byte cap. */
+    truncated: boolean;
+    /** A ripgrep call hit its time limit (its output is partial). */
+    timedOut: boolean;
+    constructor(workspace: CodeSearchWorkspace, signal: AbortSignal, ripgrepTimeoutMs: number);
+    get partial(): boolean;
+    /**
+     * ripgrep stdout. Exit code 2 (error) with some output keeps the output (for example unreadable files);
+     * with no output it throws unless `allowFailure`, which then yields "".
+     */
+    ripgrep(args: readonly string[], options?: {
+        allowFailure?: boolean;
+    }): Promise<string>;
+    /** File text, or null when missing or binary (NUL bytes). */
+    readText(path: string, maxBytes: number): Promise<string | null>;
+    pathKinds(paths: readonly string[]): Promise<Record<string, "file" | "directory" | "missing">>;
+}
+/** Map with at most `limit` calls in flight; results keep the input order. */
+export declare function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]>;

package/dist/code-search/text.d.ts

@@ -0,0 +1,35 @@
+/**
+ * text.ts - keyword variants, word splitting, stopwords and small text helpers.
+ */
+/** Split an identifier or phrase into lowercase words: fooBarBAZ_qux-v2 -> [foo, bar, baz, qux, v2]. */
+export declare function splitWords(s: string): string[];
+/**
+ * Identifier variants of a keyword. The search is case-insensitive, so only the
+ * separator forms matter: concatenated (camel/Pascal/flat), snake/SCREAMING, kebab, spaced phrase.
+ * Returned in display casing (camel, snake, kebab, spaced) for the trace; deduped case-insensitively.
+ */
+export declare function keywordVariants(kw: string): string[];
+/** Contiguous 2-word fragments of a compound with >= 3 words (fallback when the full name has no hits). */
+export declare function compoundFragments(kw: string): string[];
+/** A single plain word (no case change, no separator) short enough to need a word boundary. */
+export declare function isShortPlainWord(kw: string, maxLen: number): boolean;
+/** Escape for Rust regex (ripgrep). */
+export declare function escapeRegex(s: string): string;
+export declare const STOPWORDS: Set<string>;
+/** Crude stemmer: good enough for overlap scoring (not for display). */
+export declare function stem(w: string): string;
+/** Content terms of a text (identifiers split into words, stopwords dropped, stemmed, deduped). */
+export declare function contentTerms(text: string, minLen?: number): string[];
+/** Fraction of `terms` present in `textTerms`. */
+export declare function overlap(terms: string[], textTerms: Set<string>): number;
+export declare function isTestPath(p: string): boolean;
+/** Release notes: CHANGELOG*, HISTORY*, RELEASE_NOTES*, .changeset/ entries (describe past changes, not current code). */
+export declare function isChangelogPath(p: string): boolean;
+/** Is the question about history / releases (then release notes are not down-weighted)? */
+export declare function questionMentionsHistory(q: string): boolean;
+export declare function isDocPath(p: string): boolean;
+export declare function questionMentionsTests(q: string): boolean;
+/** Trim a line to maxChars around the first occurrence of any needle (case-insensitive). */
+export declare function trimAround(line: string, needles: string[], maxChars: number): string;
+export declare function estTokens(chars: number, charsPerToken: number): number;
+export declare function fmtK(n: number): string;

package/dist/code-search/tool.d.ts

@@ -0,0 +1,34 @@
+export declare const CODE_SEARCH_TOOL_NAME = "code_search";
+export declare const CODE_SEARCH_TOOL_DESCRIPTION: string;
+export declare const CODE_SEARCH_LIMITS: {
+    readonly questionMinChars: 3;
+    readonly questionMaxChars: 2000;
+    readonly keywordsMax: 20;
+    readonly keywordMaxChars: 120;
+    readonly subQuestionsMax: 3;
+    readonly subQuestionMaxChars: 1000;
+    readonly pathsMax: 8;
+    readonly pathMaxChars: 1000;
+};
+/** Plain JSON (mutable arrays), so it fits any JSON-schema slot of a tool definition. */
+export type CodeSearchJsonValue = string | number | boolean | null | CodeSearchJsonValue[] | {
+    [key: string]: CodeSearchJsonValue;
+};
+/** JSON schema of the tool input; parseCodeSearchArguments enforces the same rules. */
+export declare const codeSearchInputSchema: {
+    [key: string]: CodeSearchJsonValue;
+};
+export interface CodeSearchArguments {
+    question: string;
+    keywords: string[];
+    subQuestions: string[];
+    paths: string[];
+}
+/** Invalid tool arguments; the message is written for the model. */
+export declare class CodeSearchArgumentError extends Error {
+    constructor(message: string);
+}
+/** Validate and normalize tool arguments (trim, drop empty entries, dedupe, workspace-relative paths). */
+export declare function parseCodeSearchArguments(args: Record<string, unknown>): CodeSearchArguments;
+/** Short model-facing text for a failed code_search call. */
+export declare function renderCodeSearchError(error: unknown): string;

package/dist/code-search/windows.d.ts

@@ -0,0 +1,85 @@
+/**
+ * windows.ts - turn hit lines into readable passages.
+ *
+ * For each hit: walk up (<= maxUp lines) to the nearest declaration line at lower-or-equal indentation
+ * whose block encloses the hit (function/class/const/export/interface/type/enum/describe/route handler,
+ * markdown heading, SQL statement, python def/class), then walk down to where that block closes
+ * (<= maxDown lines below the hit). No enclosing declaration -> fixed context around the hit, labelled
+ * with the nearest enclosing declaration further up. Overlapping windows merge; windows longer than
+ * maxWindowLines split around hit clusters; each file keeps its best windowsPerFile windows.
+ * All line numbers in this module's public API are 1-based. A line past the end of the file as read (it
+ * changed after ripgrep saw it, or could not be read) is skipped by the callers and treated as blank here.
+ */
+import type { CodeSearchConfig } from "./config.js";
+import type { HitLine, KeywordInfo } from "./recall.js";
+export type Lang = "brace" | "indent" | "markdown" | "sql" | "other";
+export interface Window {
+    start: number;
+    end: number;
+    /** Hit lines inside the window (1-based). */
+    hits: number[];
+    /** Enclosing declaration when it is above the window start (or the window starts at it). */
+    label?: {
+        line: number;
+        text: string;
+    } | undefined;
+    kind: "hit" | "header" | "def";
+    score: number;
+}
+export declare function langOf(path: string): Lang;
+export declare function indentOf(line: string): number;
+export declare function isDeclLine(line: string, lang: Lang): boolean;
+/** Remove string literals and comments so bracket counting is roughly right. */
+export declare function stripForBrackets(line: string): string;
+/**
+ * 0-based index of the last line of the block starting at 0-based line d, or null if unknown
+ * (no structure, or longer than maxScan lines).
+ */
+export declare function blockEnd(lines: string[], d: number, lang: Lang, maxScan?: number): number | null;
+/** Nearest declaration above (0-based idx) with indentation below the given one; cheap, for labels only. */
+export declare function nearestEnclosingLabel(lines: string[], idx: number, lang: Lang, maxScan?: number): {
+    line: number;
+    text: string;
+} | undefined;
+/** The window around one hit line (1-based in, 1-based out). */
+export declare function enclosingWindow(lines: string[], hitLine: number, lang: Lang, cfg: CodeSearchConfig): Window;
+/** Grow windows shorter than minWindowLines with surrounding context (1/3 above, 2/3 below). */
+export declare function padWindow(win: Window, nLines: number, cfg: CodeSearchConfig): Window;
+/** Merge overlapping windows or windows separated by <= gap lines. Input any order; output by start. */
+export declare function mergeWindows(ws: Window[], gap: number): Window[];
+/** Split a window longer than maxLines into chunks around its hit clusters (chunks without hits are dropped). */
+export declare function splitWindow(w: Window, maxLines: number, before?: number): Window[];
+export declare function keywordRegex(k: KeywordInfo): RegExp | null;
+export declare function textHasKeyword(text: string, k: KeywordInfo): boolean;
+export declare function keywordsInRange(lines: string[], start: number, end: number, keywords: KeywordInfo[]): number[];
+export declare function scoreWindow(lines: string[], w: Window, keywords: KeywordInfo[], hitWeight?: number): number;
+/**
+ * Windows for one file: window the strongest hit lines (skipping hits already covered), merge,
+ * split long ones, score, keep the best windowsPerFile, return in line order.
+ */
+export declare function buildFileWindows(lines: string[], hitLines: HitLine[], keywords: KeywordInfo[], lang: Lang, cfg: CodeSearchConfig, render?: RenderOpts): Window[];
+/** Window for a definition found at 1-based defLine (lead following). */
+export declare function definitionWindow(lines: string[], defLine: number, lang: Lang, cfg: CodeSearchConfig, render?: RenderOpts): Window;
+export interface RenderOpts {
+    /** Lines longer than this are cut (with an explicit marker). */
+    maxLineChars: number;
+    /** When a cut line has a match beyond the head, the cut keeps the region around the first match. */
+    needles?: RegExp[];
+}
+/**
+ * Cut one over-long line to about maxChars, marked explicitly. If a needle matches beyond the first ~60% of
+ * the budget, keep a short head plus the region around the match (prose docs such as AGENTS.md have
+ * single-line paragraphs of 1-6k chars whose key sentence is often far from the start).
+ */
+export declare function cutLine(t: string, maxChars: number, needles?: RegExp[]): string;
+/** Render lines[start..end] (1-based inclusive) as `N| text`, cutting very long lines with an explicit marker. */
+export declare function renderLines(lines: string[], start: number, end: number, opts: number | RenderOpts): string;
+/** Rendered length of one line (as renderLines would produce it, plus the newline). */
+export declare function renderedLineLength(lines: string[], i: number, o: RenderOpts): number;
+/**
+ * Split a window whose rendered text exceeds maxChars into whole-line sub-windows around its hits:
+ * each sub-window starts a few lines above the first uncovered hit (up to a quarter of the budget) and
+ * extends down until the budget is used. Windows without hits (headers, definitions) keep their top.
+ */
+export declare function splitByChars(lines: string[], w: Window, maxChars: number, o: RenderOpts, ctxUp?: number): Window[];
+export declare function splitLines(text: string): string[];

package/dist/code-search/workspace.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The only way the code_search engine touches files and processes. The sandbox side implements it.
+ *
+ * The engine passes ripgrep only these flags, so an adapter may enforce an allowlist:
+ * --files, --null, --line-number, --with-filename, --no-heading, --color never, -i, -w, --no-require-git,
+ * --hidden, -m N, --max-columns N, --max-filesize N, -g GLOB, -e PATTERN, then `--` followed by
+ * workspace-relative paths ("." or paths without a leading "-", no absolute paths, no "..").
+ * A PATTERN is never longer than CODE_SEARCH_MAX_PATTERN_CHARS: the engine splits a longer alternation
+ * into several ripgrep calls and merges their output.
+ */
+/**
+ * Longest `-e` pattern the engine passes to ripgrep, so an adapter may cap pattern length (the sandbox
+ * adapter rejects patterns over 16,384 characters).
+ */
+export declare const CODE_SEARCH_MAX_PATTERN_CHARS = 16000;
+export type CodeSearchRipgrepResult = {
+    stdout: string;
+    exitCode: number | null;
+    truncated: boolean;
+    timedOut: boolean;
+};
+export interface CodeSearchWorkspace {
+    /** Run ripgrep in the workspace root. `args` excludes the binary. stdout is exactly what rg prints (up to the adapter's byte cap; `truncated` reports a cut). exitCode follows rg: 0 matches, 1 none, 2 error. Throws CodeSearchWorkspaceError when ripgrep is missing or the workspace is unreachable. */
+    ripgrep(args: readonly string[], options: {
+        signal?: AbortSignal;
+        timeoutMs: number;
+    }): Promise<CodeSearchRipgrepResult>;
+    /** Read a workspace-relative file as UTF-8. Null when missing. */
+    readText(path: string, options: {
+        signal?: AbortSignal;
+        maxBytes: number;
+    }): Promise<{
+        text: string;
+        truncated: boolean;
+        binary: boolean;
+    } | null>;
+    /** Classify workspace-relative paths. */
+    pathKinds(paths: readonly string[], options: {
+        signal?: AbortSignal;
+    }): Promise<Record<string, "file" | "directory" | "missing">>;
+}
+export declare class CodeSearchWorkspaceError extends Error {
+}
+/**
+ * Thrown by an adapter when the ripgrep binary is not installed, so the tool can tell the model to use
+ * other search commands. A plain CodeSearchWorkspaceError whose message says ripgrep is missing is
+ * recognised too.
+ */
+export declare class CodeSearchRipgrepMissingError extends CodeSearchWorkspaceError {
+    constructor(message?: string);
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { JEV_CHARS_PER_TOKEN, JEV_DEFAULT_BASE_URL, JEV_DEFAULT_LIMITS, JEV_DEFAULT_MODEL, JEV_PRICE_PER_MILLION_INPUT_TOKENS_USD, JevClient, JevError, JevLimiter, JevRequestError, JevUnavailableError, estimateJevTokens, jevCostUsd, noul, planChunks, type JevAnswer, type JevAnswerFor, type JevAskOptions, type JevAskResult, type JevChoiceAnswer, type JevChoiceQuestion, type JevClientOptions, type JevFetch, type JevInstructions, type JevLimits, type JevNoulAnswer, type JevNoulQuestion, type JevQuestion, type JevScoreAnswer, type JevScoreQuestion, } from "./client.js";
+export { JevCircuitBreaker, type JevCircuitBreakerOptions, type JevCircuitLease, type JevCircuitState, type JevCircuitStatus, } from "./circuit-breaker.js";
+export { CODE_SEARCH_DEFAULT_BUDGET_TOKENS, CODE_SEARCH_ENGINE_VERSION, runCodeSearch, type CodeSearchInput, type CodeSearchResult, type CodeSearchStats, type CodeSearchStatus, } from "./code-search/search.js";
+export { CODE_SEARCH_MAX_PATTERN_CHARS, CodeSearchRipgrepMissingError, CodeSearchWorkspaceError, type CodeSearchRipgrepResult, type CodeSearchWorkspace, } from "./code-search/workspace.js";
+export { DEFAULT_CODE_SEARCH_CONFIG, codeSearchConfig, type CodeSearchConfig, type CodeSearchConfigOverride, } from "./code-search/config.js";
+export { CODE_SEARCH_LIMITS, CODE_SEARCH_TOOL_DESCRIPTION, CODE_SEARCH_TOOL_NAME, CodeSearchArgumentError, codeSearchInputSchema, parseCodeSearchArguments, renderCodeSearchError, type CodeSearchArguments, type CodeSearchJsonValue, } from "./code-search/tool.js";