@wenathlan/devthink 2.0.13 → 2.0.15

package/dist/core.d.ts

@@ -0,0 +1,361 @@
+/**
+ * FNV-1a 32-bit hash over a UTF-16 string (per code unit), unsigned.
+ * Canonical implementation of the fnv1a32 family — every other module
+ * imports this instead of redefining it.
+ */
+export declare const fnv1a32: (s: string) => number;
+/**
+ * Hex form of {@link fnv1a32}, zero-padded to 8 characters.
+ */
+export declare const fnv1a32Hex: (s: string) => string;
+/**
+ * FNV-1a 64-bit hash over UTF-16 code units, returned as a 16-char
+ * zero-padded lowercase hex string (fingerprint lineage — canonical of the
+ * fnv1a64 family). Uses the FNV-1a 64 offset basis 14695981039346656037 and
+ * prime 1099511628211 as inline literals; the 32-bit FNV constants live in
+ * constants.ts but the 64-bit pair is only used here, so it stays local and
+ * documented rather than imported.
+ */
+export declare function fnv1a64(input: string): string;
+/**
+ * FNV-1a 64-bit hash over UTF-8 BYTES, returned as a bigint (request.ts
+ * lineage — the long deterministic-id digest). Distinct from
+ * {@link fnv1a64}: this variant hashes bytes (Buffer.from(input, "utf8"))
+ * instead of UTF-16 code units, so the two produce different digests for
+ * non-ASCII input and different return types; the accurate split keeps both
+ * historical behaviors available under honest names.
+ */
+export declare function fnv1a64Bytes(input: string): bigint;
+/**
+ * Uniform jitter in [JITTER_MIN_MS, JITTER_MAX_MS] (0-80 ms) for cascade
+ * backoff randomization. Prefers the crypto-strong randomInt and falls back
+ * to Math.random. Same value distribution as {@link getJitter}.
+ */
+export declare const jitter: () => number;
+/**
+ * Jitter draw in [JITTER_MIN_MS, JITTER_MAX_MS] (0-80 ms) — the historical
+ * getJitter name used by the cascade/retry loops. Identical distribution to
+ * {@link jitter}; both names are kept because both are published.
+ */
+export declare function getJitter(): number;
+/**
+ * Bounded jitter value in the inclusive [minMs, maxMs] range (defaults
+ * 0-80 ms). Crypto-strong randomInt with a Math.random fallback; used for
+ * Retry-After throttling and anti-rate-limit delays.
+ */
+export declare function getJitterMs(minMs?: number, maxMs?: number): number;
+/**
+ * Picks a uniformly random element from a readonly pool. Crypto-strong
+ * randomInt with a Math.random fallback (canonical of the pickRandom family;
+ * the former constants.ts Math.random variant and the fingerprint.ts
+ * secureRandom variant merge here — same distribution, stronger draw).
+ */
+export declare function pickRandom<T>(pool: readonly T[]): T;
+/**
+ * Retry classification for the auth/project-discovery flows:
+ * 403, 404, 408, 429 and every 5xx are retryable. Canonical of the
+ * isRetryable family (auth.ts and project.ts lineages; the plugin.ts
+ * 3-condition variant had zero callers and was dropped).
+ */
+export declare function isRetryable(status: number): boolean;
+/**
+ * Retry classification for the endpoint-cascade flows: 403 (project IAM
+ * mismatch), 404 (rollout), 429 (rate limit) and the whole 5xx range.
+ * Canonical of the isRetryableStatus family — the live-validated request.ts
+ * cascade variant (408 is intentionally NOT retryable here; streaming.ts
+ * keeps its own list-driven transient variant under an accurate name).
+ */
+export declare function isRetryableStatus(status: number): boolean;
+/**
+ * Fetch with an abort-controller timeout and external-signal merge. Canonical
+ * of the fetchWithTimeout family (supersedes the auth.ts fetchTimeout alias:
+ * same positional signature and same 10s default). Behavior notes:
+ * - timeout default FETCH_TIMEOUT_MS (10s); pass the third argument to
+ *   override (quota callers pass QUOTA_TIMEOUT_MS, version callers the 5s
+ *   VERSION_FETCH_TIMEOUT_MS);
+ * - an init.signal is merged with the timer: either aborting aborts the
+ *   fetch (an already-aborted external signal aborts immediately);
+ * - a `timeoutMs` property inside init (the models.ts lineage call style)
+ *   takes precedence over the positional default;
+ * - AbortError propagates unwrapped — consumers that historically mapped it
+ *   to a domain error (ProjectDiscoveryError 408 in project.ts, the plain
+ *   timeout Errors in plugin/quota) wrap THIS call at their call sites.
+ */
+export declare function fetchWithTimeout(url: string, init?: RequestInit, timeoutMs?: number): Promise<Response>;
+/**
+ * LRU map with O(1) re-insertion refresh; evicts the least-recently-used
+ * entry once the capacity is exceeded.
+ */
+declare class LRU<K, V> extends Map<K, V> {
+    private max;
+    constructor(max?: number);
+    set(k: K, v: V): this;
+}
+/**
+ * Shared LRU(100) cache keyed by session/model for thinking signatures.
+ * The single shared instance consumed by streaming.ts.
+ */
+export declare const thinkingCache: LRU<string, string>;
+import { DEBUG_BUFFER_TUI_LINES, DEBUG_LOG_MAX_BYTES, DEBUG_LOG_RETENTION_DAYS } from "./constants.js";
+export { DEBUG_BUFFER_TUI_LINES, DEBUG_LOG_MAX_BYTES, DEBUG_LOG_RETENTION_DAYS };
+/** Relative log dir from $HOME: ~/.config/opencode/antigravity-logs/ */
+export declare const DEBUG_LOG_DIR_SUBPATH = ".config/opencode/antigravity-logs";
+/** Active log filename */
+export declare const DEBUG_LOG_FILE_NAME = "antigravity.log";
+/**
+ * Reconciliation note: two numeric scales existed (0/1/2/3/99 legacy and
+ * 10/20/30/40/100 observer). The legacy compact scale is canonical because it
+ * is the merge base; environment parsing accepts BOTH numeric scales (see
+ * {@link parseAntigravityDebugEnv}).
+ */
+export type LogLevelName = "debug" | "info" | "warn" | "error" | "silent";
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    SILENT = 99
+}
+export interface EnvParseResult {
+    /** true = logging active, false = completely silenced */
+    enabled: boolean;
+    /** Minimum level that will be emitted */
+    level: LogLevel;
+    /** Raw env string kept for debugging/introspection */
+    raw: string | undefined;
+}
+/**
+ * Parses the debug env value (ANTIGRAVITY_DEBUG or
+ * OPENCODE_ANTIGRAVITY_DEBUG) into an enabled flag plus minimum level.
+ *
+ * Rules (merged from both variants):
+ * - undefined            => enabled true, level WARN (observer default)
+ * - disabled tokens      => enabled false, SILENT (0/false/off/disabled/no/none/"")
+ * - enable tokens        => DEBUG (1/true/yes/on/star/all/debug/verbose/trace/silly)
+ * - numeric values       => legacy scale 0..3 maps directly onto LogLevel;
+ *                           observer scale 10..40 maps DEBUG/INFO/WARN/ERROR;
+ *                           values >= 99 map to SILENT (legacy sentinel);
+ *                           anything else falls back to WARN
+ * - comma/semicolon/space/pipe separated lists pick the most verbose level
+ *   mentioned (substring matching included, wildcards force DEBUG)
+ * - any other non-empty string defaults to DEBUG (user explicitly opted in)
+ *
+ * @param raw - raw env value
+ */
+export declare function parseAntigravityDebugEnv(raw: string | undefined): EnvParseResult;
+/**
+ * Redacts known secrets inside free-form text using the legacy pattern list.
+ * @param input - raw log line or message
+ */
+export declare function redactSecretsPatterns(input: string): string;
+/**
+ * Text redactor from the observer variant. Complements {@link redactSecretsPatterns}
+ * with JSON/query key=value captures, long Bearer tokens, ya29.* Google OAuth
+ * access tokens and AIza* Google API keys.
+ * @param input - raw log line or message
+ */
+export declare function redactSecretsText(input: string): string;
+/**
+ * Legacy shallow-cloning redaction: redacts sensitive keys and string values
+ * recursively (without circular-reference protection).
+ */
+export declare function redactObject<T>(obj: T): T;
+/**
+ * Deep redaction that clones and redacts sensitive keys and string values.
+ * Handles circular references (replaced with "[Circular]"), Error objects
+ * (name/message/stack plus enumerable props) and arrays. Never throws.
+ *
+ * @param value - arbitrary value to clone/redact
+ * @param seen - internal WeakSet tracking visited objects
+ */
+export declare function redactObjectDeep<T>(value: T, seen?: WeakSet<object>): T;
+export interface LogEntry {
+    timestamp: string;
+    level: LogLevel;
+    levelName: string;
+    message: string;
+    data?: unknown | undefined;
+    scope?: string | undefined;
+}
+export declare class CircularBuffer<T> {
+    readonly capacity: number;
+    private buf;
+    private head;
+    private count;
+    constructor(capacity: number);
+    push(item: T): void;
+    toArray(): T[];
+    clear(): void;
+    get size(): number;
+    getRecent(n: number): T[];
+}
+export interface DebugLoggerOptions {
+    logDir?: string;
+    level?: LogLevel | LogLevelName;
+    tuiEnabled?: boolean;
+    tuiCapacity?: number;
+    quietMode?: boolean;
+    enableFileLogging?: boolean;
+    /** Allows injecting env for tests */
+    env?: NodeJS.ProcessEnv;
+}
+export declare class DebugLogger {
+    private static _instance;
+    readonly logDir: string;
+    readonly logFile: string;
+    private level;
+    /** Observer-style master switch: false means completely silenced. */
+    private enabled;
+    /** Raw debug env value last seen (for introspection). */
+    private rawEnv;
+    private tuiEnabled;
+    private quietMode;
+    private fileLoggingEnabled;
+    private buffer;
+    private dirEnsured;
+    private lastCleanup;
+    private readonly CLEANUP_INTERVAL_MS;
+    private writeCount;
+    private isWriting;
+    private constructor();
+    static getInstance(opts?: DebugLoggerOptions): DebugLogger;
+    /** For tests - resets the singleton. */
+    static _resetForTests(): void;
+    /**
+     * For testing only - resets the singleton and returns a fresh instance that
+     * reads current env. Production code should use getInstance().
+     */
+    static resetInstanceForTests(): DebugLogger;
+    private parseLevelOption;
+    private applyOptions;
+    getLevel(): LogLevel;
+    getLevelName(): LogLevelName;
+    /**
+     * Programmatic level setter - overrides env control for this process.
+     * Accepts enum values, level names, or any string understood by
+     * {@link parseAntigravityDebugEnv}.
+     */
+    setLevel(level: LogLevel | LogLevelName | string): void;
+    isTuiEnabled(): boolean;
+    setTuiEnabled(enabledFlag: boolean): void;
+    isQuietMode(): boolean;
+    setQuietMode(quiet: boolean): void;
+    /**
+     * Whether toast notifications should be shown (quiet_mode suppresses them).
+     */
+    shouldShowToast(): boolean;
+    isDebugEnabled(): boolean;
+    /** Whether file logging is currently enabled (false after disable tokens). */
+    isEnabled(): boolean;
+    /** Whether a given level would be emitted right now. */
+    isLevelEnabled(lvl: LogLevel): boolean;
+    /** Raw debug env value last observed. */
+    getRawEnv(): string | undefined;
+    getLogDir(): string;
+    getLogFilePath(): string;
+    private ensureLogDir;
+    /** Best-effort chmod 0o600 on the active log file. */
+    private ensureLogFilePermissions;
+    private getFileSize;
+    /**
+     * Rotates the active file when it reaches DEBUG_LOG_MAX_BYTES. Renames to
+     * antigravity-YYYY-MM-DD-HH-mm-ss-mmm.log, recreates an empty active file
+     * with mode 0o600, and falls back to truncation if rename fails.
+     */
+    private rotateIfNeeded;
+    /**
+     * Removes rotated logs older than DEBUG_LOG_RETENTION_DAYS days.
+     * Called at boot, after rotation, and every CLEANUP_EVERY_WRITES writes;
+     * throttled to run at most once per hour unless forced.
+     */
+    cleanupOldLogs(force?: boolean): void;
+    private shouldLog;
+    private formatEntry;
+    private writeToFile;
+    private pushToTui;
+    private log;
+    debug(message: string, data?: unknown, scope?: string): LogEntry | null;
+    info(message: string, data?: unknown, scope?: string): LogEntry | null;
+    warn(message: string, data?: unknown, scope?: string): LogEntry | null;
+    error(message: string, data?: unknown, scope?: string): LogEntry | null;
+    /**
+     * Log with custom scope (useful for child loggers).
+     */
+    withScope(scope: string): ScopedLogger;
+    /**
+     * Re-reads OPENCODE_ANTIGRAVITY_DEBUG (or ANTIGRAVITY_DEBUG) and updates
+     * the enabled flag and level accordingly.
+     *
+     * @param env - optional env override (defaults to process.env)
+     * @returns the fresh parse result
+     */
+    refreshFromEnv(env?: NodeJS.ProcessEnv): EnvParseResult;
+    getTuiBuffer(): LogEntry[];
+    getRecentLogs(count: number): LogEntry[];
+    getTuiBufferAsString(maxLines?: number): string;
+    clearTuiBuffer(): void;
+    getTuiBufferSize(): number;
+    getTuiCapacity(): number;
+}
+export declare class ScopedLogger {
+    private readonly parent;
+    private readonly scope;
+    constructor(parent: DebugLogger, scope: string);
+    debug(message: string, data?: unknown): LogEntry | null;
+    info(message: string, data?: unknown): LogEntry | null;
+    warn(message: string, data?: unknown): LogEntry | null;
+    error(message: string, data?: unknown): LogEntry | null;
+    withScope(childScope: string): ScopedLogger;
+    get parentLogger(): DebugLogger;
+}
+export declare const logger: DebugLogger;
+/** Direct-import level helpers: import { debug, info } from "./debug" */
+export declare function debug(message: string, data?: unknown, scope?: string): LogEntry | null;
+export declare function info(message: string, data?: unknown, scope?: string): LogEntry | null;
+export declare function warn(message: string, data?: unknown, scope?: string): LogEntry | null;
+export declare function error(message: string, data?: unknown, scope?: string): LogEntry | null;
+/** Creates a scoped logger (e.g. "auth:gemini", "plugin:load"). */
+export declare function createScopedLogger(scope: string): ScopedLogger;
+/** Compatibility alias for createScopedLogger. */
+export declare function createDebugLogger(scope: string): ScopedLogger;
+/** State helpers controlled by env. */
+export declare function isDebugEnabled(): boolean;
+export declare function isTuiEnabled(): boolean;
+export declare function isQuietMode(): boolean;
+export declare function shouldShowToast(): boolean;
+/** TUI buffer access helpers. */
+export declare function getTuiBuffer(): LogEntry[];
+export declare function getRecentLogs(n: number): LogEntry[];
+export declare function getTuiBufferAsString(maxLines?: number): string;
+export declare function clearTuiBuffer(): void;
+/** Log filesystem info helpers. */
+export declare function getLogDir(): string;
+export declare function getLogFilePathExport(): string;
+/** Dynamic adjustment helpers (useful for TUI commanders). */
+export declare function setLogLevel(level: LogLevel | LogLevelName): void;
+export declare function setQuietMode(enabledFlag: boolean): void;
+export declare function setTuiEnabled(enabledFlag: boolean): void;
+/**
+ * Functional wrapper around {@link DebugLogger.refreshFromEnv}: re-reads the
+ * debug env variables and applies them to the singleton logger.
+ */
+export declare function refreshFromEnv(env?: NodeJS.ProcessEnv): EnvParseResult;
+export default DebugLogger;
+/** Antigravity debug-logs directory inside the config directory. */
+export declare const logsDir: () => string;
+/** Redacts Bearer JWTs and refresh_token substrings from a log line. */
+export declare const redactSecrets: (s: string) => string;
+/**
+ * Mini debug-logger singleton: 1000-line ring buffer, daily log files under
+ * logsDir(), 10MB rotation, 7-day cleanup, secret redaction on every line.
+ */
+export declare class debugLogger {
+    private static inst;
+    private buffer;
+    private maxBuf;
+    static get(): debugLogger;
+    log(msg: string): void;
+    getBuffer(): string[];
+    cleanup(): void;
+}
+//# sourceMappingURL=core.d.ts.map