@juspay/neurolink 9.51.4 → 9.53.0

package/dist/lib/autoresearch/stateStore.js

@@ -0,0 +1,164 @@
+/**
+ * Research state persistence — file-backed JSON store.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import path from "node:path";
+import { logger } from "../utils/logger.js";
+import { AutoresearchError } from "./errors.js";
+export class ResearchStateStore {
+    filePath;
+    constructor(repoPath, statePath) {
+        this.filePath = path.join(repoPath, statePath);
+    }
+    async load() {
+        if (!existsSync(this.filePath)) {
+            return null;
+        }
+        try {
+            const raw = readFileSync(this.filePath, "utf-8");
+            const parsed = JSON.parse(raw);
+            // Validate required fields
+            const requiredFields = [
+                "branch",
+                "currentPhase",
+                "runCount",
+                "keepCount",
+                "tag",
+                "startedAt",
+                "updatedAt",
+            ];
+            for (const field of requiredFields) {
+                if (!(field in parsed)) {
+                    throw AutoresearchError.create("STATE_CORRUPT", `State file missing required field: ${field}`);
+                }
+            }
+            if (!Number.isInteger(parsed.runCount) ||
+                parsed.runCount < 0 ||
+                !Number.isInteger(parsed.keepCount) ||
+                parsed.keepCount < 0) {
+                throw AutoresearchError.create("STATE_CORRUPT", `State file has invalid numeric fields: runCount=${parsed.runCount}, keepCount=${parsed.keepCount}`);
+            }
+            const validPhases = [
+                "bootstrap",
+                "baseline",
+                "propose",
+                "edit",
+                "commit",
+                "run",
+                "evaluate",
+                "record",
+                "accept_or_revert",
+            ];
+            if (!validPhases.includes(parsed.currentPhase)) {
+                throw AutoresearchError.create("STATE_CORRUPT", `State file has invalid currentPhase: ${parsed.currentPhase}`);
+            }
+            if (isNaN(Date.parse(parsed.startedAt)) ||
+                isNaN(Date.parse(parsed.updatedAt))) {
+                throw AutoresearchError.create("STATE_CORRUPT", "State file has invalid timestamp fields");
+            }
+            return parsed;
+        }
+        catch (error) {
+            // Don't double-wrap our own validation errors
+            if (error instanceof Error && error.message.includes("AUTORESEARCH")) {
+                throw error;
+            }
+            throw AutoresearchError.create("STATE_CORRUPT", `Failed to parse state file: ${this.filePath}`, {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    async save(state) {
+        const dir = path.dirname(this.filePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        // Strip rawTail from lastSummary before persisting (it's arbitrary stdout/stderr,
+        // kept in run.log; storing it in state.json risks leaking sensitive output)
+        const stateToPersist = { ...state };
+        if (stateToPersist.lastSummary?.rawTail) {
+            stateToPersist.lastSummary = {
+                ...stateToPersist.lastSummary,
+                rawTail: "[see run.log]",
+            };
+        }
+        // Atomic write: write to temp file, then rename
+        const tmpPath = `${this.filePath}.tmp`;
+        try {
+            writeFileSync(tmpPath, JSON.stringify(stateToPersist, null, 2), "utf-8");
+            renameSync(tmpPath, this.filePath);
+            logger.debug("[Autoresearch] State saved", {
+                phase: state.currentPhase,
+                runCount: state.runCount,
+            });
+        }
+        catch (error) {
+            throw AutoresearchError.create("STATE_CORRUPT", `Failed to write state file: ${this.filePath}`, {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    async initialize(tag, branch) {
+        const now = new Date().toISOString();
+        const state = {
+            branch,
+            acceptedCommit: null,
+            baselineMetric: null,
+            bestMetric: null,
+            candidateCommit: null,
+            runCount: 0,
+            keepCount: 0,
+            lastStatus: null,
+            currentPhase: "bootstrap",
+            tag,
+            startedAt: now,
+            updatedAt: now,
+        };
+        await this.save(state);
+        logger.info("[Autoresearch] State initialized", { tag, branch });
+        return state;
+    }
+    async update(patch) {
+        const current = await this.load();
+        if (!current) {
+            throw AutoresearchError.create("STATE_NOT_FOUND", "Cannot update: no state file found");
+        }
+        // Validate patch fields before merging
+        const VALID_PHASES = [
+            "bootstrap",
+            "baseline",
+            "propose",
+            "edit",
+            "commit",
+            "run",
+            "evaluate",
+            "record",
+            "accept_or_revert",
+        ];
+        if (patch.runCount !== undefined &&
+            (!Number.isInteger(patch.runCount) || patch.runCount < 0)) {
+            throw AutoresearchError.create("STATE_CORRUPT", `Invalid runCount: ${patch.runCount}`);
+        }
+        if (patch.keepCount !== undefined &&
+            (!Number.isInteger(patch.keepCount) || patch.keepCount < 0)) {
+            throw AutoresearchError.create("STATE_CORRUPT", `Invalid keepCount: ${patch.keepCount}`);
+        }
+        if (patch.currentPhase !== undefined &&
+            !VALID_PHASES.includes(patch.currentPhase)) {
+            throw AutoresearchError.create("STATE_CORRUPT", `Invalid currentPhase: ${patch.currentPhase}`);
+        }
+        if (patch.bestMetric !== undefined &&
+            patch.bestMetric !== null &&
+            !Number.isFinite(patch.bestMetric)) {
+            throw AutoresearchError.create("STATE_CORRUPT", `Invalid bestMetric: ${patch.bestMetric}`);
+        }
+        const updated = {
+            ...current,
+            ...patch,
+            updatedAt: new Date().toISOString(),
+        };
+        await this.save(updated);
+        return updated;
+    }
+}
+//# sourceMappingURL=stateStore.js.map

package/dist/lib/autoresearch/summaryParser.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Deterministic experiment log parser.
+ *
+ * Extracts metrics from run.log output. Never throws — returns
+ * crashed/timedOut summary on parse failure.
+ */
+import type { ExperimentSummary, MetricConfig, MemoryMetricConfig } from "../types/autoresearchTypes.js";
+/**
+ * Parse experiment output into a structured summary.
+ *
+ * This function is deterministic and pure — no side effects, no throws.
+ */
+export declare function parseExperimentSummary(logContent: string, metricConfig: MetricConfig, memoryConfig?: MemoryMetricConfig, options?: {
+    timedOut?: boolean;
+    exitCode?: number;
+}): ExperimentSummary;

package/dist/lib/autoresearch/summaryParser.js

@@ -0,0 +1,95 @@
+/**
+ * Deterministic experiment log parser.
+ *
+ * Extracts metrics from run.log output. Never throws — returns
+ * crashed/timedOut summary on parse failure.
+ */
+/**
+ * Parse experiment output into a structured summary.
+ *
+ * This function is deterministic and pure — no side effects, no throws.
+ */
+export function parseExperimentSummary(logContent, metricConfig, memoryConfig, options) {
+    const lines = logContent.split("\n");
+    const tailLines = lines.slice(-50);
+    const rawTail = tailLines.join("\n");
+    // Check for crash indicators (only if not already determined by exit code)
+    let crashed = options?.exitCode !== undefined &&
+        options.exitCode !== 0 &&
+        !options?.timedOut;
+    if (!crashed) {
+        const lastMeaningfulLine = [...lines]
+            .reverse()
+            .find((l) => l.trim().length > 0)
+            ?.trim() ?? "";
+        crashed =
+            lastMeaningfulLine === "FAIL" ||
+                lastMeaningfulLine.toLowerCase().includes("traceback") ||
+                lastMeaningfulLine.toLowerCase().includes("error:");
+    }
+    // Parse primary metric
+    let metric = null;
+    try {
+        const regex = new RegExp(metricConfig.pattern, "m");
+        const match = regex.exec(logContent);
+        if (match && match[1]) {
+            const parsed = parseFloat(match[1]);
+            if (!isNaN(parsed) && isFinite(parsed)) {
+                metric = parsed;
+            }
+        }
+    }
+    catch {
+        // Invalid regex — treat as parse failure
+    }
+    // Parse memory metric
+    let memoryValue = null;
+    if (memoryConfig) {
+        try {
+            const regex = new RegExp(memoryConfig.pattern, "m");
+            const match = regex.exec(logContent);
+            if (match && match[1]) {
+                const parsed = parseFloat(match[1]);
+                if (!isNaN(parsed) && isFinite(parsed)) {
+                    memoryValue = parsed;
+                    // Convert MB to GB if the name suggests MB.
+                    // Uses binary divisor (1024 = MiB→GiB). For decimal MB→GB use 1000.
+                    // The 1024 convention matches GPU monitoring tools (nvidia-smi, etc.).
+                    const MIB_TO_GIB_DIVISOR = 1024;
+                    if (memoryConfig.name.toLowerCase().includes("mb")) {
+                        memoryValue =
+                            Math.round((memoryValue / MIB_TO_GIB_DIVISOR) * 100) / 100;
+                    }
+                }
+            }
+        }
+        catch {
+            // Invalid regex — treat as parse failure
+        }
+    }
+    // Parse training time
+    let trainingSeconds = null;
+    try {
+        const timeRegex = /^training_seconds:\s+([\d.]+)/m;
+        const match = timeRegex.exec(logContent);
+        if (match && match[1]) {
+            trainingSeconds = parseFloat(match[1]);
+        }
+    }
+    catch {
+        // Ignore
+    }
+    // Only treat as timeout if explicitly signaled by the runner — don't infer from missing metric
+    const timedOut = options?.timedOut ?? false;
+    // Missing metric without explicit timeout is a crash (regex failure, spawn error, etc.)
+    const finalCrashed = crashed || (metric === null && !timedOut);
+    return {
+        crashed: finalCrashed,
+        timedOut,
+        metric,
+        memoryValue,
+        trainingSeconds,
+        rawTail,
+    };
+}
+//# sourceMappingURL=summaryParser.js.map

package/dist/lib/autoresearch/tools.d.ts

@@ -0,0 +1,257 @@
+/**
+ * Research tools factory for AutoResearch system.
+ *
+ * These tools allow an AI agent to conduct autonomous experiments:
+ * reading/writing code, running experiments, recording results, and
+ * managing the research lifecycle (accept/revert/checkpoint).
+ *
+ * @module autoresearch/tools
+ */
+import type { ExperimentRecord, ResearchConfig } from "../types/autoresearchTypes.js";
+import type { RepoPolicy } from "./repoPolicy.js";
+import type { ResultRecorder } from "./resultRecorder.js";
+import type { ExperimentRunner } from "./runner.js";
+import type { ResearchStateStore } from "./stateStore.js";
+/**
+ * Dependencies required to create research tools.
+ */
+export type ResearchToolsDeps = {
+    config: ResearchConfig;
+    stateStore: ResearchStateStore;
+    repoPolicy: RepoPolicy;
+    runner: ExperimentRunner;
+    recorder: ResultRecorder;
+};
+/**
+ * Create research management tools bound to a research session.
+ *
+ * These tools follow the same factory pattern as `createTaskTools()` in
+ * `src/lib/tasks/tools/taskTools.ts`. Dependencies are captured via closure,
+ * eliminating the need for module-level singleton state.
+ *
+ * @param deps - The research dependencies to bind to
+ * @returns Record of tool name to tool definition
+ *
+ * @example
+ * ```typescript
+ * const tools = createResearchTools({ config, stateStore, repoPolicy, runner, recorder });
+ * // tools.research_get_context, tools.research_read_file, etc.
+ * ```
+ */
+export declare function createResearchTools(deps: ResearchToolsDeps): {
+    /**
+     * Get current research context including state, config, and recent results.
+     */
+    research_get_context: import("ai").Tool<Record<string, never>, {
+        success: boolean;
+        error: string;
+        branch?: undefined;
+        acceptedCommit?: undefined;
+        bestMetric?: undefined;
+        recentResults?: undefined;
+        mutablePaths?: undefined;
+        immutablePaths?: undefined;
+        currentPhase?: undefined;
+        runCount?: undefined;
+        tag?: undefined;
+        keepCount?: undefined;
+    } | {
+        success: boolean;
+        branch: string;
+        acceptedCommit: string | null;
+        bestMetric: number | null;
+        recentResults: ExperimentRecord[];
+        mutablePaths: string[];
+        immutablePaths: string[];
+        currentPhase: import("../types/autoresearchTypes.js").ExperimentPhase;
+        runCount: number;
+        tag: string;
+        keepCount: number;
+        error?: undefined;
+    }>;
+    /**
+     * Read a file from the repository if allowed by policy.
+     */
+    research_read_file: import("ai").Tool<{
+        path: string;
+    }, {
+        success: boolean;
+        error: string;
+        path?: undefined;
+        content?: undefined;
+    } | {
+        success: boolean;
+        path: string;
+        content: string;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        path: string;
+        content?: undefined;
+    }>;
+    /**
+     * Write a candidate file to the repository if allowed by policy.
+     */
+    research_write_candidate: import("ai").Tool<{
+        path: string;
+        content: string;
+    }, {
+        success: boolean;
+        error: string;
+        path?: undefined;
+        bytesWritten?: undefined;
+    } | {
+        success: boolean;
+        path: string;
+        bytesWritten: number;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        path: string;
+        bytesWritten?: undefined;
+    }>;
+    /**
+     * Get git diff of mutable paths only.
+     */
+    research_diff: import("ai").Tool<Record<string, never>, {
+        success: boolean;
+        diff: string;
+        hasChanges: boolean;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        diff?: undefined;
+        hasChanges?: undefined;
+    }>;
+    /**
+     * Commit staged changes as a candidate.
+     */
+    research_commit_candidate: import("ai").Tool<{
+        message: string;
+    }, {
+        success: boolean;
+        error: string;
+        violations?: undefined;
+        candidateCommit?: undefined;
+        message?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        violations: string[];
+        candidateCommit?: undefined;
+        message?: undefined;
+    } | {
+        success: boolean;
+        candidateCommit: string;
+        message: string;
+        error?: undefined;
+        violations?: undefined;
+    }>;
+    /**
+     * Run the experiment.
+     */
+    research_run_experiment: import("ai").Tool<{
+        description: string;
+    }, {
+        success: boolean;
+        description: string;
+        summary: import("../types/autoresearchTypes.js").ExperimentSummary;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        description?: undefined;
+        summary?: undefined;
+    }>;
+    /**
+     * Parse the experiment log file.
+     */
+    research_parse_log: import("ai").Tool<Record<string, never>, {
+        success: boolean;
+        summary: import("../types/autoresearchTypes.js").ExperimentSummary;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        summary?: undefined;
+    }>;
+    /**
+     * Record an experiment result.
+     */
+    research_record: import("ai").Tool<{
+        description: string;
+    }, {
+        success: boolean;
+        error: string;
+        record?: undefined;
+    } | {
+        success: boolean;
+        record: ExperimentRecord;
+        error?: undefined;
+    }>;
+    /**
+     * Accept the candidate commit as the new baseline.
+     */
+    research_accept: import("ai").Tool<Record<string, never>, {
+        success: boolean;
+        error: string;
+        acceptedCommit?: undefined;
+        bestMetric?: undefined;
+        keepCount?: undefined;
+    } | {
+        success: boolean;
+        acceptedCommit: string;
+        bestMetric: number;
+        keepCount: number;
+        error?: undefined;
+    }>;
+    /**
+     * Revert to the accepted commit.
+     */
+    research_revert: import("ai").Tool<Record<string, never>, {
+        success: boolean;
+        error: string;
+        revertedTo?: undefined;
+    } | {
+        success: boolean;
+        revertedTo: string;
+        error?: undefined;
+    }>;
+    /**
+     * Inspect the last 50 lines of the run log for debugging.
+     */
+    research_inspect_failure: import("ai").Tool<Record<string, never>, {
+        success: boolean;
+        tail: string;
+        totalLines: number;
+        error?: undefined;
+    } | {
+        success: boolean;
+        error: string;
+        tail?: undefined;
+        totalLines?: undefined;
+    }>;
+    /**
+     * Save the current state to disk.
+     */
+    research_checkpoint: import("ai").Tool<Record<string, never>, {
+        success: boolean;
+        error: string;
+        checkpointedAt?: undefined;
+        phase?: undefined;
+        runCount?: undefined;
+    } | {
+        success: boolean;
+        checkpointedAt: string;
+        phase: import("../types/autoresearchTypes.js").ExperimentPhase;
+        runCount: number;
+        error?: undefined;
+    }>;
+};
+/**
+ * Type for the research tools returned by createResearchTools
+ */
+export type ResearchTools = ReturnType<typeof createResearchTools>;