@juspay/neurolink 9.52.0 → 9.53.0

package/dist/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("../index.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("../index.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("../index.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("../index.js").ExperimentPhase;
+        runCount: number;
+        error?: undefined;
+    }>;
+};
+/**
+ * Type for the research tools returned by createResearchTools
+ */
+export type ResearchTools = ReturnType<typeof createResearchTools>;