jevprune 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,462 @@
+import { EntryType, Fetch } from '@typesafe-ai/sdk';
+
+declare class JevCoreError extends Error {
+    readonly name: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class JevConfigError extends JevCoreError {
+    readonly name = "JevConfigError";
+}
+declare class JevInputError extends JevCoreError {
+    readonly name = "JevInputError";
+}
+declare class JevBudgetError extends JevCoreError {
+    readonly name = "JevBudgetError";
+}
+declare class JevRequestError extends JevCoreError {
+    readonly name = "JevRequestError";
+    readonly status: number | undefined;
+    readonly retryable: boolean;
+    readonly requestId: string | undefined;
+    constructor(message: string, details: {
+        status?: number;
+        retryable: boolean;
+        requestId?: string;
+        cause?: unknown;
+    });
+}
+declare class JevTimeoutError extends JevCoreError {
+    readonly name = "JevTimeoutError";
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number, message?: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class JevAbortError extends JevCoreError {
+    readonly name = "JevAbortError";
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class JevResponseError extends JevCoreError {
+    readonly name = "JevResponseError";
+}
+declare function describeError(error: unknown): string;
+
+type JevState = EntryType;
+interface JevUsage {
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+}
+interface NoulRequest {
+    readonly state: JevState;
+    readonly questions: Readonly<Record<string, string>>;
+}
+interface NoulResult {
+    readonly model: string;
+    readonly answers: Readonly<Record<string, number>>;
+    readonly usage: JevUsage;
+}
+interface ChoiceQuestionSpec<L extends string> {
+    readonly instructions: string;
+    readonly labels: readonly L[];
+    readonly descriptions?: Readonly<Partial<Record<L, string>>>;
+}
+interface ChoiceRequest<L extends string> {
+    readonly state: JevState;
+    readonly questions: Readonly<Record<string, ChoiceQuestionSpec<L>>>;
+}
+interface ChoiceAnswer<L extends string> {
+    readonly choice: L;
+    readonly confidence: number;
+    readonly probabilities: Readonly<Record<L, number>>;
+}
+interface ChoiceResult<L extends string> {
+    readonly model: string;
+    readonly answers: Readonly<Record<string, ChoiceAnswer<L>>>;
+    readonly usage: JevUsage;
+}
+interface JevRequestOptions {
+    readonly signal?: AbortSignal;
+    readonly timeoutMs?: number;
+}
+interface JevClient {
+    noul(request: NoulRequest, options?: JevRequestOptions): Promise<NoulResult>;
+    choice<L extends string>(request: ChoiceRequest<L>, options?: JevRequestOptions): Promise<ChoiceResult<L>>;
+}
+interface TypeSafeJevClientConfig {
+    readonly apiKey: string;
+    readonly baseUrl?: string;
+    readonly model?: string;
+    readonly timeoutMs?: number;
+    readonly maxRetries?: number;
+    readonly fetch?: Fetch;
+}
+declare const DEFAULT_JEV_MODEL = "jev-latest";
+declare const DEFAULT_JEV_TIMEOUT_MS = 10000;
+declare const DEFAULT_JEV_MAX_RETRIES = 1;
+declare const TYPESAFE_API_KEY_ENV = "TYPESAFE_API_KEY";
+declare const TYPESAFE_BASE_URL_ENV = "TYPESAFE_BASE_URL";
+declare class TypeSafeJevClient implements JevClient {
+    #private;
+    constructor(config: TypeSafeJevClientConfig);
+    noul(request: NoulRequest, options?: JevRequestOptions): Promise<NoulResult>;
+    choice<L extends string>(request: ChoiceRequest<L>, options?: JevRequestOptions): Promise<ChoiceResult<L>>;
+}
+declare function createJevClientFromEnv(env?: Readonly<Record<string, string | undefined>>, overrides?: Partial<Omit<TypeSafeJevClientConfig, "apiKey">>): TypeSafeJevClient;
+declare function toJevError(error: unknown): Error;
+declare function validateNoulAnswers(ids: readonly string[], answers: unknown): Record<string, number>;
+declare function validateChoiceAnswers<L extends string>(questions: Readonly<Record<string, ChoiceQuestionSpec<L>>>, answers: unknown): Record<string, ChoiceAnswer<L>>;
+
+declare const CHARS_PER_TOKEN = 3;
+declare const DEFAULT_WINDOW_TOKENS = 25000;
+declare const MAX_REQUEST_TOKENS = 32000;
+declare function estimateTokens(text: string): number;
+declare function estimateJsonTokens(value: unknown): number;
+
+interface WindowItem {
+    readonly id: string;
+    readonly text: string;
+}
+interface PlanWindowsOptions<T extends WindowItem> {
+    readonly budgetTokens?: number;
+    readonly overheadTokens?: number;
+    readonly itemOverheadTokens?: number;
+    readonly costTokens?: (item: T) => number;
+}
+interface WindowPlan<T extends WindowItem> {
+    readonly windows: readonly (readonly T[])[];
+    readonly oversize: readonly T[];
+}
+declare function planWindows<T extends WindowItem>(items: readonly T[], options?: PlanWindowsOptions<T>): WindowPlan<T>;
+declare const DEFAULT_WINDOW_CONCURRENCY = 4;
+declare const DEFAULT_WINDOW_TIMEOUT_MS = 10000;
+interface RunWindowsOptions {
+    readonly concurrency?: number;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+type WindowJudge<T, R> = (window: readonly T[], index: number, options: JevRequestOptions) => Promise<R>;
+declare function runWindows<T, R>(windows: readonly (readonly T[])[], judge: WindowJudge<T, R>, options?: RunWindowsOptions): Promise<R[]>;
+
+type NoulScorer = (id: string, instructions: string, state: JevState) => number;
+type ChoiceScorer = (id: string, spec: ChoiceQuestionSpec<string>, state: JevState) => string | ChoiceAnswer<string>;
+interface FakeJevCall {
+    readonly kind: "noul" | "choice";
+    readonly state: JevState;
+    readonly ids: readonly string[];
+}
+interface FakeJevOptions {
+    readonly noul?: NoulScorer;
+    readonly choice?: ChoiceScorer;
+    readonly delayMs?: number;
+    readonly failWith?: (call: number) => Error | undefined;
+    readonly model?: string;
+}
+declare class FakeJevClient implements JevClient {
+    #private;
+    readonly calls: FakeJevCall[];
+    constructor(options?: FakeJevOptions);
+    noul(request: NoulRequest, options?: JevRequestOptions): Promise<NoulResult>;
+    choice<L extends string>(request: ChoiceRequest<L>, options?: JevRequestOptions): Promise<ChoiceResult<L>>;
+}
+
+declare function isValidUtf8(bytes: Buffer): boolean;
+declare function byteLineStarts(bytes: Buffer): number[];
+declare function countByteLines(bytes: Buffer): number;
+
+interface RetentionConfig {
+    readonly maxRuns: number;
+    readonly maxBytes: number;
+}
+interface Config {
+    readonly threshold: number;
+    readonly fastPathLines: number;
+    readonly tailLines: number;
+    readonly headLines: number;
+    readonly contextLines: number;
+    readonly minCollapseLines: number;
+    readonly windowTokens: number;
+    readonly windowTimeoutMs: number;
+    readonly concurrency: number;
+    readonly maxPruneBytes: number;
+    readonly retention: RetentionConfig;
+    readonly autoWrap: boolean;
+    readonly allowlist: readonly string[];
+}
+interface ResolvedConfig extends Config {
+    readonly home: string;
+}
+declare const DEFAULT_ALLOWLIST: readonly string[];
+declare const DEFAULT_CONFIG: Config;
+declare function resolveHome(env?: NodeJS.ProcessEnv): string;
+declare function loadConfig(env?: NodeJS.ProcessEnv): Promise<ResolvedConfig>;
+declare function parseThreshold(value: string): number;
+
+declare class JevpruneError extends Error {
+    readonly name: string;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class ConfigError extends JevpruneError {
+    readonly name = "ConfigError";
+}
+declare class UsageError extends JevpruneError {
+    readonly name = "UsageError";
+}
+declare class RunStoreError extends JevpruneError {
+    readonly name = "RunStoreError";
+    readonly code: string | undefined;
+    constructor(message: string, details?: {
+        code?: string;
+        cause?: unknown;
+    });
+}
+declare class SpawnError extends JevpruneError {
+    readonly name = "SpawnError";
+    readonly executable: string;
+    readonly code: string | undefined;
+    constructor(message: string, details: {
+        executable: string;
+        code?: string;
+        cause?: unknown;
+    });
+}
+declare class TranscriptError extends JevpruneError {
+    readonly name = "TranscriptError";
+    readonly path: string;
+    constructor(message: string, details: {
+        path: string;
+        cause?: unknown;
+    });
+}
+declare class RunNotFoundError extends JevpruneError {
+    readonly name = "RunNotFoundError";
+    readonly id: string;
+    constructor(id: string, options?: {
+        cause?: unknown;
+    });
+}
+declare class LineRangeError extends JevpruneError {
+    readonly name = "LineRangeError";
+}
+
+type SelectionMode = "fast-path" | "passthrough" | "jev" | "fallback";
+type DecisionReason = "fast-path" | "passthrough" | "tail" | "signature" | "context" | "blank" | "oversize" | "jev" | "collapse-min" | "head" | "fallback";
+interface Decision {
+    keep: boolean;
+    reason: DecisionReason;
+    noul?: number;
+}
+interface DroppedRange {
+    readonly from: number;
+    readonly to: number;
+    readonly count: number;
+}
+
+interface FooterInput {
+    readonly mode: SelectionMode;
+    readonly linesIn: number;
+    readonly linesOut: number;
+    readonly exitCode?: number | null;
+    readonly logPath?: string;
+    readonly fallbackReason?: string;
+    readonly passthroughNote?: string;
+    readonly storeFailureCode?: string;
+    readonly home?: string;
+}
+declare function formatFooter(input: FooterInput): string;
+declare function footerAfter(lastByte: number | undefined, footer: string): string;
+declare function withFooter(kept: string, footer: string): string;
+declare function formatCount(value: number): string;
+declare function displayPath(path: string, home?: string): string;
+
+type LineTerminator = "" | "\n" | "\r\n" | "\r";
+interface Line {
+    readonly n: number;
+    readonly text: string;
+    readonly terminator: LineTerminator;
+}
+declare function splitLines(text: string): Line[];
+declare function joinLines(lines: Iterable<Line>): string;
+
+type KeepReason = "tail" | "signature" | "context";
+declare const SIGNATURE_CASE_SENSITIVE: RegExp;
+declare const SIGNATURE_CASE_INSENSITIVE: RegExp;
+declare function isSignatureLine(text: string): boolean;
+declare function computeKeeps(lines: readonly Line[], options: {
+    tailLines: number;
+    contextLines: number;
+}): Map<number, KeepReason>;
+
+interface MergeOptions {
+    readonly minCollapseLines: number;
+    readonly runId: string;
+    readonly totalLines?: number;
+}
+interface MergeResult {
+    readonly kept: string;
+    readonly dropped: DroppedRange[];
+}
+declare function collapseMarker(range: DroppedRange, runId: string): string;
+declare function mergeDecisions(lines: readonly Line[], decisions: Map<number, Decision>, options: MergeOptions): MergeResult;
+
+interface OversizeCapture {
+    readonly lines: number;
+    readonly headSegmentLines: number;
+}
+declare const NOT_UTF8_REASON = "not valid UTF-8";
+declare const NOT_UTF8_NOTE = "output is not valid UTF-8";
+declare const RUBRIC = "A line is needed when a developer acting on the task would want to read it: errors, failures, assertions, stack frames, diagnostics, timings or statuses that bear on the task, and the lines that give them meaning. Progress bars, download counters, repeated banners, unchanged status lines and routine success noise are not needed.";
+interface SelectInput {
+    readonly text: string;
+    readonly task: string;
+    readonly command: string;
+    readonly exitCode?: number | null;
+    readonly interrupted?: boolean;
+    readonly oversize?: OversizeCapture;
+    readonly client: JevClient | null;
+    readonly config: ResolvedConfig;
+    readonly runId: string;
+    readonly signal?: AbortSignal;
+}
+interface PassthroughInput {
+    readonly bytes: number;
+    readonly lines: number;
+    readonly reason?: string;
+}
+interface SelectionResult {
+    readonly mode: SelectionMode;
+    readonly kept: string;
+    readonly dropped: DroppedRange[];
+    readonly linesIn: number;
+    readonly linesOut: number;
+    readonly bytesIn: number;
+    readonly bytesOut: number;
+    readonly windows: number;
+    readonly jevRequests: number;
+    readonly jevInputTokens: number;
+    readonly fallbackReason?: string;
+    readonly decisions: Map<number, Decision>;
+}
+declare function passthroughSelection(input: PassthroughInput): SelectionResult;
+declare function questionFor(n: number): string;
+declare function selectLines(input: SelectInput): Promise<SelectionResult>;
+
+interface RunMeta {
+    readonly id: string;
+    readonly command: string;
+    readonly argv: readonly string[];
+    readonly startedAt: string;
+    readonly endedAt: string;
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+    readonly bytes: number;
+    readonly lines: number;
+    readonly mode: SelectionMode;
+    readonly linesOut: number;
+    readonly fallbackReason?: string;
+    readonly task: string;
+}
+interface GainEntry {
+    readonly ts: string;
+    readonly id: string;
+    readonly mode: SelectionMode;
+    readonly linesIn: number;
+    readonly linesOut: number;
+    readonly bytesIn: number;
+    readonly bytesOut: number;
+    readonly reason?: string;
+}
+interface GainTotals {
+    readonly runs: number;
+    readonly linesIn: number;
+    readonly linesOut: number;
+    readonly bytesIn: number;
+    readonly bytesOut: number;
+}
+interface RunRecord {
+    readonly id: string;
+    readonly path: string;
+    readonly text: string;
+    readonly meta: RunMeta | null;
+}
+interface RunWriter {
+    readonly path: string;
+    readonly failure: RunStoreError | undefined;
+    write(chunk: Buffer): boolean;
+    onDrain(listener: () => void): void;
+    close(): Promise<void>;
+}
+declare function newRunId(): string;
+declare class RunStore {
+    #private;
+    readonly home: string;
+    constructor(options: {
+        home: string;
+        retention?: RetentionConfig;
+    });
+    get runsDir(): string;
+    get gainPath(): string;
+    logPath(id: string): string;
+    metaPath(id: string): string;
+    openRun(run: {
+        id: string;
+    }): Promise<RunWriter>;
+    finalizeRun(id: string, meta: RunMeta): Promise<void>;
+    readRunBytes(id: string): Promise<Buffer>;
+    readRunChunks(id: string): AsyncGenerator<Buffer>;
+    readRun(id: string): Promise<RunRecord>;
+    readRunLineBytes(id: string, from?: number, to?: number): Promise<Buffer>;
+    readRunLines(id: string, from?: number, to?: number): Promise<string>;
+    appendGain(entry: GainEntry): Promise<void>;
+    readGain(): Promise<GainTotals>;
+    enforceRetention(): Promise<void>;
+    discardRun(id: string): Promise<void>;
+}
+
+interface PruneInput {
+    readonly text: string;
+    readonly task: string;
+    readonly command?: string;
+    readonly exitCode?: number | null;
+    readonly client?: JevClient | null;
+    readonly config?: Partial<Config>;
+    readonly save?: boolean;
+    readonly env?: NodeJS.ProcessEnv;
+}
+interface PruneStreamInput extends Omit<PruneInput, "text"> {
+    readonly stream: NodeJS.ReadableStream;
+}
+interface PruneResult {
+    readonly kept: string;
+    readonly dropped: DroppedRange[];
+    readonly runId: string;
+    readonly mode: SelectionMode;
+    readonly linesIn: number;
+    readonly linesOut: number;
+    readonly fallbackReason?: string;
+    readonly logPath?: string;
+    readonly footer: string;
+}
+declare function pruneOutput(input: PruneInput): Promise<PruneResult>;
+declare function pruneStream(input: PruneStreamInput): Promise<PruneResult>;
+
+declare const MAX_TASK_LENGTH = 400;
+type TaskSource = "flag" | "env" | "transcript" | "command";
+interface TaskInput {
+    readonly flag?: string;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly transcriptPath?: string;
+    readonly command: string;
+}
+interface ResolvedTask {
+    readonly task: string;
+    readonly source: TaskSource;
+}
+declare function resolveTask(input: TaskInput): Promise<ResolvedTask>;
+
+export { CHARS_PER_TOKEN, type ChoiceAnswer, type ChoiceQuestionSpec, type ChoiceRequest, type ChoiceResult, type ChoiceScorer, type Config, ConfigError, DEFAULT_ALLOWLIST, DEFAULT_CONFIG, DEFAULT_JEV_MAX_RETRIES, DEFAULT_JEV_MODEL, DEFAULT_JEV_TIMEOUT_MS, DEFAULT_WINDOW_CONCURRENCY, DEFAULT_WINDOW_TIMEOUT_MS, DEFAULT_WINDOW_TOKENS, type Decision, type DecisionReason, type DroppedRange, type FakeJevCall, FakeJevClient, type FakeJevOptions, type FooterInput, type GainEntry, type GainTotals, JevAbortError, JevBudgetError, type JevClient, JevConfigError, JevCoreError, JevInputError, JevRequestError, type JevRequestOptions, JevResponseError, type JevState, JevTimeoutError, type JevUsage, JevpruneError, type KeepReason, type Line, LineRangeError, type LineTerminator, MAX_REQUEST_TOKENS, MAX_TASK_LENGTH, type MergeOptions, type MergeResult, NOT_UTF8_NOTE, NOT_UTF8_REASON, type NoulRequest, type NoulResult, type NoulScorer, type OversizeCapture, type PassthroughInput, type PlanWindowsOptions, type PruneInput, type PruneResult, type PruneStreamInput, RUBRIC, type ResolvedConfig, type ResolvedTask, type RetentionConfig, type RunMeta, RunNotFoundError, type RunRecord, RunStore, RunStoreError, type RunWindowsOptions, type RunWriter, SIGNATURE_CASE_INSENSITIVE, SIGNATURE_CASE_SENSITIVE, type SelectInput, type SelectionMode, type SelectionResult, SpawnError, TYPESAFE_API_KEY_ENV, TYPESAFE_BASE_URL_ENV, type TaskInput, type TaskSource, TranscriptError, TypeSafeJevClient, type TypeSafeJevClientConfig, UsageError, type WindowItem, type WindowJudge, type WindowPlan, byteLineStarts, collapseMarker, computeKeeps, countByteLines, createJevClientFromEnv, describeError, displayPath, estimateJsonTokens, estimateTokens, footerAfter, formatCount, formatFooter, isSignatureLine, isValidUtf8, joinLines, loadConfig, mergeDecisions, newRunId, parseThreshold, passthroughSelection, planWindows, pruneOutput, pruneStream, questionFor, resolveHome, resolveTask, runWindows, selectLines, splitLines, toJevError, validateChoiceAnswers, validateNoulAnswers, withFooter };