@juspay/neurolink 9.51.4 → 9.53.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [9.53.0](https://github.com/juspay/neurolink/compare/v9.52.0...v9.53.0) (2026-04-12)
+
+### Features
+
+- **(autoresearch):** add autonomous experiment engine with scheduling and docs ([22be8c8](https://github.com/juspay/neurolink/commit/22be8c857940eeb7c42e8581483d1244ef890158))
+
+## [9.52.0](https://github.com/juspay/neurolink/compare/v9.51.4...v9.52.0) (2026-04-12)
+
+### Features
+
+- **(credentials):** add per-request and per-instance credential support for all providers ([edd07bb](https://github.com/juspay/neurolink/commit/edd07bb5475d4ef33a9ce29915913ebcd8a6904b))
+
 ## [9.51.4](https://github.com/juspay/neurolink/compare/v9.51.3...v9.51.4) (2026-04-12)
 
 ### Bug Fixes

package/README.md

@@ -42,6 +42,7 @@ Extracted from production systems at Juspay and battle-tested at enterprise scal
 
 | Feature                             | Version | Description                                                                                                                                                   | Guide                                                                 |
 | ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| **AutoResearch**                    | v9.17.0 | Autonomous AI experiment engine: proposes code changes, runs experiments, evaluates metrics, keeps improvements — unattended for hours.                       | [AutoResearch Guide](docs/features/autoresearch.md)                   |
 | **MCP Enhancements**                | v9.16.0 | Advanced MCP features: tool routing, result caching, request batching, annotations, elicitation, custom server base, multi-server management                  | [MCP Enhancements Guide](docs/features/mcp-enhancements.md)           |
 | **Memory**                          | v9.12.0 | Per-user condensed memory that persists across conversations. LLM-powered condensation with S3, Redis, or SQLite backends.                                    | [Memory Guide](docs/features/memory.md)                               |
 | **Context Window Management**       | v9.2.0  | 4-stage compaction pipeline with auto-detection, budget gate at 80% usage, per-provider token estimation                                                      | [Context Compaction Guide](docs/features/context-compaction.md)       |
@@ -55,6 +56,7 @@ Extracted from production systems at Juspay and battle-tested at enterprise scal
 | **Image Generation with Gemini**    | v8.31.0 | Native image generation using Gemini 2.0 Flash Experimental (`imagen-3.0-generate-002`). High-quality image synthesis directly from Google AI.                | [Image Generation Guide](docs/image-generation-streaming.md)          |
 | **HTTP/Streamable HTTP Transport**  | v8.29.0 | Connect to remote MCP servers via HTTP with authentication headers, automatic retry with exponential backoff, and configurable rate limiting.                 | [HTTP Transport Guide](docs/mcp-http-transport.md)                    |
 
+- **AutoResearch** – Autonomous AI experiment engine inspired by Karpathy's autoresearch. Phase-gated tool access, git-backed safety, deterministic metric evaluation, and TaskManager integration for continuous unattended research. 12 research tools, 10 typed events, 9 CLI subcommands. → [AutoResearch Guide](docs/features/autoresearch.md)
 - **Memory** – Per-user condensed memory that persists across all conversations. Automatically retrieves and stores memory on each `generate()`/`stream()` call. Supports S3, Redis, and SQLite storage with LLM-powered condensation. → [Memory Guide](docs/features/memory.md)
 - **External TracerProvider Support** – Integrate NeuroLink with applications that already have OpenTelemetry instrumentation. Supports auto-detection and manual configuration. → [Observability Guide](docs/features/observability.md)
 - **Claude Proxy Telemetry** – Bootstrap a local OpenObserve + OTEL collector stack with `neurolink proxy telemetry setup`, import the maintained NeuroLink Proxy Observability dashboard, and inspect proxy logs, traces, metrics, cache reuse, and routing behavior. → [Claude Proxy Guide](docs/features/claude-proxy.md) | [Proxy Observability Guide](docs/features/claude-proxy-observability.md)
@@ -90,6 +92,23 @@ const image = await neurolink.generate({
 });
 console.log(image.imageOutput?.base64); // Base64-encoded image
 
+// AutoResearch — autonomous experiment loop (v9.17.0)
+import { resolveConfig, ResearchWorker } from "@juspay/neurolink/autoresearch";
+
+const config = resolveConfig({
+  repoPath: "/path/to/repo",
+  mutablePaths: ["train.py"],
+  runCommand: "python3 train.py",
+  metric: {
+    name: "val_bpb",
+    direction: "lower",
+    pattern: "^val_bpb:\\s+([\\d.]+)",
+  },
+});
+const worker = new ResearchWorker(config);
+await worker.initialize("experiment-1");
+const result = await worker.runExperimentCycle("Try lower learning rate");
+
 // HTTP Transport for Remote MCP (v8.29.0)
 await neurolink.addExternalMCPServer("remote-tools", {
   transport: "http",

package/dist/agent/directTools.d.ts

@@ -101,7 +101,7 @@ export declare const directAgentTools: {
     writeFile: import("ai").Tool<{
         path: string;
         content: string;
-        mode: "create" | "append" | "overwrite";
+        mode: "append" | "create" | "overwrite";
     }, {
         success: boolean;
         error: string;
@@ -112,7 +112,7 @@ export declare const directAgentTools: {
     } | {
         success: boolean;
         path: string;
-        mode: "create" | "append" | "overwrite";
+        mode: "append" | "create" | "overwrite";
         size: number;
         written: number;
         error?: undefined;

package/dist/auth/errors.d.ts

@@ -55,7 +55,7 @@ export declare const AuthError: {
         readonly JWKS_FETCH_FAILED: "AUTH-070";
         readonly JWKS_KEY_NOT_FOUND: "AUTH-071";
     };
-    create: (code: "SESSION_NOT_FOUND" | "INVALID_TOKEN" | "EXPIRED_TOKEN" | "MISSING_TOKEN" | "TOKEN_DECODE_FAILED" | "INVALID_SIGNATURE" | "SESSION_EXPIRED" | "SESSION_REVOKED" | "INSUFFICIENT_PERMISSIONS" | "INSUFFICIENT_ROLES" | "ACCESS_DENIED" | "USER_NOT_FOUND" | "USER_DISABLED" | "EMAIL_NOT_VERIFIED" | "MFA_REQUIRED" | "PROVIDER_ERROR" | "PROVIDER_NOT_FOUND" | "PROVIDER_INIT_FAILED" | "CONFIGURATION_ERROR" | "CREATION_FAILED" | "REGISTRATION_FAILED" | "DUPLICATE_REGISTRATION" | "MIDDLEWARE_ERROR" | "RATE_LIMITED" | "JWKS_FETCH_FAILED" | "JWKS_KEY_NOT_FOUND", message: string, options?: {
+    create: (code: "SESSION_NOT_FOUND" | "PROVIDER_ERROR" | "CONFIGURATION_ERROR" | "RATE_LIMITED" | "INVALID_TOKEN" | "EXPIRED_TOKEN" | "MISSING_TOKEN" | "TOKEN_DECODE_FAILED" | "INVALID_SIGNATURE" | "SESSION_EXPIRED" | "SESSION_REVOKED" | "INSUFFICIENT_PERMISSIONS" | "INSUFFICIENT_ROLES" | "ACCESS_DENIED" | "USER_NOT_FOUND" | "USER_DISABLED" | "EMAIL_NOT_VERIFIED" | "MFA_REQUIRED" | "PROVIDER_NOT_FOUND" | "PROVIDER_INIT_FAILED" | "CREATION_FAILED" | "REGISTRATION_FAILED" | "DUPLICATE_REGISTRATION" | "MIDDLEWARE_ERROR" | "JWKS_FETCH_FAILED" | "JWKS_KEY_NOT_FOUND", message: string, options?: {
         retryable?: boolean;
         details?: Record<string, unknown>;
         cause?: Error;

package/dist/auth/middleware/AuthMiddleware.d.ts

@@ -31,7 +31,7 @@ export declare const AuthMiddlewareError: {
         readonly PROVIDER_ERROR: "AUTH_MIDDLEWARE-005";
         readonly CONFIGURATION_ERROR: "AUTH_MIDDLEWARE-006";
     };
-    create: (code: "INVALID_TOKEN" | "MISSING_TOKEN" | "PROVIDER_ERROR" | "CONFIGURATION_ERROR" | "FORBIDDEN" | "UNAUTHORIZED", message: string, options?: {
+    create: (code: "PROVIDER_ERROR" | "CONFIGURATION_ERROR" | "INVALID_TOKEN" | "MISSING_TOKEN" | "FORBIDDEN" | "UNAUTHORIZED", message: string, options?: {
         retryable?: boolean;
         details?: Record<string, unknown>;
         cause?: Error;

package/dist/auth/providers/BaseAuthProvider.d.ts

@@ -44,7 +44,7 @@ export declare const AuthProviderError: {
         readonly JWKS_FETCH_FAILED: "AUTH-070";
         readonly JWKS_KEY_NOT_FOUND: "AUTH-071";
     };
-    create: (code: "SESSION_NOT_FOUND" | "INVALID_TOKEN" | "EXPIRED_TOKEN" | "MISSING_TOKEN" | "TOKEN_DECODE_FAILED" | "INVALID_SIGNATURE" | "SESSION_EXPIRED" | "SESSION_REVOKED" | "INSUFFICIENT_PERMISSIONS" | "INSUFFICIENT_ROLES" | "ACCESS_DENIED" | "USER_NOT_FOUND" | "USER_DISABLED" | "EMAIL_NOT_VERIFIED" | "MFA_REQUIRED" | "PROVIDER_ERROR" | "PROVIDER_NOT_FOUND" | "PROVIDER_INIT_FAILED" | "CONFIGURATION_ERROR" | "CREATION_FAILED" | "REGISTRATION_FAILED" | "DUPLICATE_REGISTRATION" | "MIDDLEWARE_ERROR" | "RATE_LIMITED" | "JWKS_FETCH_FAILED" | "JWKS_KEY_NOT_FOUND", message: string, options?: {
+    create: (code: "SESSION_NOT_FOUND" | "PROVIDER_ERROR" | "CONFIGURATION_ERROR" | "RATE_LIMITED" | "INVALID_TOKEN" | "EXPIRED_TOKEN" | "MISSING_TOKEN" | "TOKEN_DECODE_FAILED" | "INVALID_SIGNATURE" | "SESSION_EXPIRED" | "SESSION_REVOKED" | "INSUFFICIENT_PERMISSIONS" | "INSUFFICIENT_ROLES" | "ACCESS_DENIED" | "USER_NOT_FOUND" | "USER_DISABLED" | "EMAIL_NOT_VERIFIED" | "MFA_REQUIRED" | "PROVIDER_NOT_FOUND" | "PROVIDER_INIT_FAILED" | "CREATION_FAILED" | "REGISTRATION_FAILED" | "DUPLICATE_REGISTRATION" | "MIDDLEWARE_ERROR" | "JWKS_FETCH_FAILED" | "JWKS_KEY_NOT_FOUND", message: string, options?: {
         retryable?: boolean;
         details?: Record<string, unknown>;
         cause?: Error;

package/dist/autoresearch/config.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Research configuration validation and resolution.
+ */
+import type { ResearchConfig } from "../types/autoresearchTypes.js";
+export declare function resolveConfig(partial: Partial<ResearchConfig> & {
+    repoPath: string;
+    mutablePaths: string[];
+    runCommand: string;
+    metric: ResearchConfig["metric"];
+}): ResearchConfig;
+export declare function validateConfig(config: ResearchConfig): void;

package/dist/autoresearch/config.js

@@ -0,0 +1,108 @@
+/**
+ * Research configuration validation and resolution.
+ */
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { logger } from "../utils/logger.js";
+import { AutoresearchError } from "./errors.js";
+import { AUTORESEARCH_DEFAULTS } from "../types/autoresearchTypes.js";
+export function resolveConfig(partial) {
+    const config = {
+        repoPath: path.resolve(partial.repoPath),
+        programPath: partial.programPath ?? AUTORESEARCH_DEFAULTS.programPath,
+        mutablePaths: partial.mutablePaths,
+        immutablePaths: partial.immutablePaths ?? [],
+        resultsPath: partial.resultsPath ?? AUTORESEARCH_DEFAULTS.resultsPath,
+        statePath: partial.statePath ?? AUTORESEARCH_DEFAULTS.statePath,
+        runCommand: partial.runCommand,
+        logPath: partial.logPath ?? AUTORESEARCH_DEFAULTS.logPath,
+        metric: partial.metric,
+        memoryMetric: partial.memoryMetric,
+        timeoutMs: partial.timeoutMs ?? AUTORESEARCH_DEFAULTS.timeoutMs,
+        branchPrefix: partial.branchPrefix ?? AUTORESEARCH_DEFAULTS.branchPrefix,
+        provider: partial.provider,
+        model: partial.model,
+        maxExperiments: partial.maxExperiments,
+        thinkingLevel: partial.thinkingLevel ?? AUTORESEARCH_DEFAULTS.thinkingLevel,
+    };
+    return config;
+}
+export function validateConfig(config) {
+    // Verify repoPath exists and is a directory
+    if (!existsSync(config.repoPath) ||
+        !statSync(config.repoPath).isDirectory()) {
+        throw AutoresearchError.create("CONFIG_INVALID", `repoPath does not exist or is not a directory: ${config.repoPath}`);
+    }
+    // Verify it's a git repo
+    if (!existsSync(path.join(config.repoPath, ".git"))) {
+        throw AutoresearchError.create("REPO_NOT_FOUND", `repoPath is not a git repository: ${config.repoPath}`);
+    }
+    // Verify mutablePaths is non-empty
+    if (config.mutablePaths.length === 0) {
+        throw AutoresearchError.create("CONFIG_INVALID", "mutablePaths must contain at least one path");
+    }
+    // Verify mutable and immutable don't overlap (normalize paths first)
+    const normMutable = config.mutablePaths.map((p) => path.normalize(p).replace(/\/+$/, ""));
+    const normImmutable = config.immutablePaths.map((p) => path.normalize(p).replace(/\/+$/, ""));
+    const overlap = normMutable.filter((p) => normImmutable.includes(p));
+    if (overlap.length > 0) {
+        throw AutoresearchError.create("CONFIG_INVALID", `mutablePaths and immutablePaths overlap: ${overlap.join(", ")}`);
+    }
+    // Verify metric pattern — length limit and basic ReDoS safety
+    const MAX_PATTERN_LENGTH = 200;
+    if (config.metric.pattern.length > MAX_PATTERN_LENGTH) {
+        throw AutoresearchError.create("CONFIG_INVALID", `metric.pattern exceeds ${MAX_PATTERN_LENGTH} characters: ${config.metric.pattern.slice(0, 50)}...`);
+    }
+    // Reject patterns with obvious catastrophic backtracking (nested quantifiers)
+    if (/(\+|\*|\{)\s*(\+|\*|\{)/.test(config.metric.pattern) ||
+        /\(\?[^)]*\)\+\+/.test(config.metric.pattern)) {
+        throw AutoresearchError.create("CONFIG_INVALID", `metric.pattern contains nested quantifiers (potential ReDoS): ${config.metric.pattern}`);
+    }
+    // Verify metric pattern is valid regex with exactly one capture group
+    try {
+        const _regex = new RegExp(config.metric.pattern);
+        const match = new RegExp(config.metric.pattern + "|").exec("");
+        const groupCount = (match?.length ?? 1) - 1;
+        if (groupCount !== 1) {
+            throw AutoresearchError.create("CONFIG_INVALID", `metric.pattern must have exactly one capture group, found ${groupCount}: ${config.metric.pattern}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            "code" in error &&
+            typeof error.code === "string") {
+            throw error; // Rethrow structured AutoresearchError
+        }
+        throw AutoresearchError.create("CONFIG_INVALID", `metric.pattern is not a valid regex: ${config.metric.pattern}`);
+    }
+    // Validate memoryMetric.pattern with the same checks if present
+    if (config.memoryMetric) {
+        if (config.memoryMetric.pattern.length > MAX_PATTERN_LENGTH) {
+            throw AutoresearchError.create("CONFIG_INVALID", `memoryMetric.pattern exceeds ${MAX_PATTERN_LENGTH} characters`);
+        }
+        if (/(\+|\*|\{)\s*(\+|\*|\{)/.test(config.memoryMetric.pattern) ||
+            /\(\?[^)]*\)\+\+/.test(config.memoryMetric.pattern)) {
+            throw AutoresearchError.create("CONFIG_INVALID", `memoryMetric.pattern contains nested quantifiers (potential ReDoS)`);
+        }
+        try {
+            const _memRegex = new RegExp(config.memoryMetric.pattern);
+            const memMatch = new RegExp(config.memoryMetric.pattern + "|").exec("");
+            const memGroupCount = (memMatch?.length ?? 1) - 1;
+            if (memGroupCount !== 1) {
+                throw AutoresearchError.create("CONFIG_INVALID", `memoryMetric.pattern must have exactly one capture group, found ${memGroupCount}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                "code" in error &&
+                typeof error.code === "string") {
+                throw error; // Rethrow structured AutoresearchError
+            }
+            throw AutoresearchError.create("CONFIG_INVALID", `memoryMetric.pattern is not a valid regex: ${config.memoryMetric.pattern}`);
+        }
+    }
+    logger.info("[Autoresearch] Config validated", {
+        repoPath: config.repoPath,
+        mutablePaths: config.mutablePaths,
+    });
+}

package/dist/autoresearch/errors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Error definitions for the NeuroLink AutoResearch system.
+ */
+export declare const AutoresearchErrorCodes: {
+    readonly CONFIG_INVALID: "AUTORESEARCH-001";
+    readonly STATE_CORRUPT: "AUTORESEARCH-002";
+    readonly STATE_NOT_FOUND: "AUTORESEARCH-003";
+    readonly REPO_NOT_FOUND: "AUTORESEARCH-004";
+    readonly BRANCH_ERROR: "AUTORESEARCH-005";
+    readonly PATH_VIOLATION: "AUTORESEARCH-006";
+    readonly COMMIT_REJECTED: "AUTORESEARCH-007";
+    readonly EXPERIMENT_TIMEOUT: "AUTORESEARCH-008";
+    readonly EXPERIMENT_FAILED: "AUTORESEARCH-009";
+    readonly PARSE_FAILED: "AUTORESEARCH-010";
+    readonly RESULTS_WRITE_FAILED: "AUTORESEARCH-011";
+    readonly REVERT_FAILED: "AUTORESEARCH-012";
+    readonly WORKER_NOT_INITIALIZED: "AUTORESEARCH-013";
+};
+export declare const AutoresearchError: {
+    codes: {
+        readonly CONFIG_INVALID: "AUTORESEARCH-001";
+        readonly STATE_CORRUPT: "AUTORESEARCH-002";
+        readonly STATE_NOT_FOUND: "AUTORESEARCH-003";
+        readonly REPO_NOT_FOUND: "AUTORESEARCH-004";
+        readonly BRANCH_ERROR: "AUTORESEARCH-005";
+        readonly PATH_VIOLATION: "AUTORESEARCH-006";
+        readonly COMMIT_REJECTED: "AUTORESEARCH-007";
+        readonly EXPERIMENT_TIMEOUT: "AUTORESEARCH-008";
+        readonly EXPERIMENT_FAILED: "AUTORESEARCH-009";
+        readonly PARSE_FAILED: "AUTORESEARCH-010";
+        readonly RESULTS_WRITE_FAILED: "AUTORESEARCH-011";
+        readonly REVERT_FAILED: "AUTORESEARCH-012";
+        readonly WORKER_NOT_INITIALIZED: "AUTORESEARCH-013";
+    };
+    create: (code: "CONFIG_INVALID" | "STATE_CORRUPT" | "STATE_NOT_FOUND" | "REPO_NOT_FOUND" | "BRANCH_ERROR" | "PATH_VIOLATION" | "COMMIT_REJECTED" | "EXPERIMENT_TIMEOUT" | "EXPERIMENT_FAILED" | "PARSE_FAILED" | "RESULTS_WRITE_FAILED" | "REVERT_FAILED" | "WORKER_NOT_INITIALIZED", message: string, options?: {
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+        cause?: Error;
+    } | undefined) => import("../index.js").NeuroLinkFeatureError;
+};

package/dist/autoresearch/errors.js

@@ -0,0 +1,20 @@
+/**
+ * Error definitions for the NeuroLink AutoResearch system.
+ */
+import { createErrorFactory } from "../core/infrastructure/baseError.js";
+export const AutoresearchErrorCodes = {
+    CONFIG_INVALID: "AUTORESEARCH-001",
+    STATE_CORRUPT: "AUTORESEARCH-002",
+    STATE_NOT_FOUND: "AUTORESEARCH-003",
+    REPO_NOT_FOUND: "AUTORESEARCH-004",
+    BRANCH_ERROR: "AUTORESEARCH-005",
+    PATH_VIOLATION: "AUTORESEARCH-006",
+    COMMIT_REJECTED: "AUTORESEARCH-007",
+    EXPERIMENT_TIMEOUT: "AUTORESEARCH-008",
+    EXPERIMENT_FAILED: "AUTORESEARCH-009",
+    PARSE_FAILED: "AUTORESEARCH-010",
+    RESULTS_WRITE_FAILED: "AUTORESEARCH-011",
+    REVERT_FAILED: "AUTORESEARCH-012",
+    WORKER_NOT_INITIALIZED: "AUTORESEARCH-013",
+};
+export const AutoresearchError = createErrorFactory("Autoresearch", AutoresearchErrorCodes);

package/dist/autoresearch/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * NeuroLink AutoResearch — Autonomous Experiment Engine
+ *
+ * An autonomous experiment loop that proposes code changes, executes
+ * experiments, evaluates results against a deterministic metric, and
+ * keeps or discards each change — running unattended for hours.
+ *
+ * @example
+ * ```typescript
+ * import { resolveConfig, validateConfig, ResearchStateStore, RepoPolicy, ExperimentRunner, ResultRecorder } from "@juspay/neurolink/autoresearch";
+ * ```
+ */
+export { resolveConfig, validateConfig } from "./config.js";
+export { ResearchStateStore } from "./stateStore.js";
+export { RepoPolicy } from "./repoPolicy.js";
+export { ExperimentRunner } from "./runner.js";
+export { ResultRecorder } from "./resultRecorder.js";
+export { parseExperimentSummary } from "./summaryParser.js";
+export { getPhaseToolPolicy, getAllResearchToolNames } from "./phasePolicy.js";
+export { PromptCompiler } from "./promptCompiler.js";
+export { createResearchTools } from "./tools.js";
+export { ResearchWorker } from "./worker.js";
+export { AutoresearchError, AutoresearchErrorCodes } from "./errors.js";

package/dist/autoresearch/index.js

@@ -0,0 +1,34 @@
+/**
+ * NeuroLink AutoResearch — Autonomous Experiment Engine
+ *
+ * An autonomous experiment loop that proposes code changes, executes
+ * experiments, evaluates results against a deterministic metric, and
+ * keeps or discards each change — running unattended for hours.
+ *
+ * @example
+ * ```typescript
+ * import { resolveConfig, validateConfig, ResearchStateStore, RepoPolicy, ExperimentRunner, ResultRecorder } from "@juspay/neurolink/autoresearch";
+ * ```
+ */
+// Configuration
+export { resolveConfig, validateConfig } from "./config.js";
+// State management
+export { ResearchStateStore } from "./stateStore.js";
+// Policy enforcement
+export { RepoPolicy } from "./repoPolicy.js";
+// Experiment execution
+export { ExperimentRunner } from "./runner.js";
+// Result tracking
+export { ResultRecorder } from "./resultRecorder.js";
+// Log parsing
+export { parseExperimentSummary } from "./summaryParser.js";
+// Phase policy
+export { getPhaseToolPolicy, getAllResearchToolNames } from "./phasePolicy.js";
+// Prompt compilation
+export { PromptCompiler } from "./promptCompiler.js";
+// Research tools
+export { createResearchTools } from "./tools.js";
+// Worker orchestrator
+export { ResearchWorker } from "./worker.js";
+// Errors
+export { AutoresearchError, AutoresearchErrorCodes } from "./errors.js";

package/dist/autoresearch/phasePolicy.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Phase-based tool access policy for the autoresearch experiment loop.
+ */
+import type { ExperimentPhase, PhaseToolPolicy } from "../types/autoresearchTypes.js";
+export declare function getPhaseToolPolicy(phase: ExperimentPhase): PhaseToolPolicy;
+/**
+ * Returns all research tool names across all phases.
+ */
+export declare function getAllResearchToolNames(): string[];

package/dist/autoresearch/phasePolicy.js

@@ -0,0 +1,69 @@
+/**
+ * Phase-based tool access policy for the autoresearch experiment loop.
+ */
+const PHASE_POLICIES = {
+    bootstrap: {
+        activeTools: [
+            "research_get_context",
+            "research_read_file",
+            "research_checkpoint",
+        ],
+        forcedTool: "research_get_context",
+    },
+    baseline: {
+        activeTools: [
+            "research_run_experiment",
+            "research_parse_log",
+            "research_record",
+            "research_accept",
+            "research_checkpoint",
+        ],
+        forcedTool: "research_run_experiment",
+    },
+    propose: {
+        activeTools: ["research_get_context", "research_read_file"],
+        forcedTool: "research_get_context",
+    },
+    edit: {
+        activeTools: [
+            "research_read_file",
+            "research_write_candidate",
+            "research_diff",
+        ],
+    },
+    commit: {
+        activeTools: ["research_commit_candidate"],
+        forcedTool: "research_commit_candidate",
+    },
+    run: {
+        activeTools: ["research_run_experiment"],
+        forcedTool: "research_run_experiment",
+    },
+    evaluate: {
+        activeTools: ["research_parse_log", "research_inspect_failure"],
+        forcedTool: "research_parse_log",
+    },
+    record: {
+        activeTools: ["research_record", "research_checkpoint"],
+        forcedTool: "research_record",
+    },
+    accept_or_revert: {
+        activeTools: ["research_accept", "research_revert", "research_checkpoint"],
+    },
+};
+export function getPhaseToolPolicy(phase) {
+    const p = PHASE_POLICIES[phase];
+    return { activeTools: [...p.activeTools], forcedTool: p.forcedTool };
+}
+/**
+ * Returns all research tool names across all phases.
+ */
+export function getAllResearchToolNames() {
+    const names = new Set();
+    for (const policy of Object.values(PHASE_POLICIES)) {
+        for (const tool of policy.activeTools) {
+            names.add(tool);
+        }
+    }
+    return [...names];
+}

package/dist/autoresearch/promptCompiler.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Prompt compilation for the autoresearch worker.
+ *
+ * Reads program.md and combines it with current state and recent
+ * results to build the system prompt and per-cycle prompt.
+ */
+import type { ResearchConfig, ResearchState, ExperimentRecord } from "../types/autoresearchTypes.js";
+export declare class PromptCompiler {
+    private config;
+    constructor(config: ResearchConfig);
+    /** Reads program.md and builds the system prompt */
+    buildSystemPrompt(): Promise<string>;
+    /** Builds the per-cycle prompt with current state + recent results */
+    buildCyclePrompt(state: ResearchState, recentResults: ExperimentRecord[]): Promise<string>;
+}

package/dist/autoresearch/promptCompiler.js

@@ -0,0 +1,120 @@
+/**
+ * Prompt compilation for the autoresearch worker.
+ *
+ * Reads program.md and combines it with current state and recent
+ * results to build the system prompt and per-cycle prompt.
+ */
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { logger } from "../utils/logger.js";
+import { getPhaseToolPolicy } from "./phasePolicy.js";
+export class PromptCompiler {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /** Reads program.md and builds the system prompt */
+    async buildSystemPrompt() {
+        const MAX_PROGRAM_BYTES = 1_048_576; // 1 MB
+        let programContent = "";
+        try {
+            const programPath = path.join(this.config.repoPath, this.config.programPath);
+            const stat = statSync(programPath);
+            if (stat.size > MAX_PROGRAM_BYTES) {
+                logger.warn("[Autoresearch] program.md exceeds 1MB, truncating");
+                programContent = readFileSync(programPath, "utf-8").slice(0, MAX_PROGRAM_BYTES);
+            }
+            else {
+                programContent = readFileSync(programPath, "utf-8");
+            }
+        }
+        catch {
+            logger.warn("[Autoresearch] program.md not found, using minimal system prompt");
+        }
+        const toolList = [
+            "research_get_context — Get current research state (branch, metric, recent results)",
+            "research_read_file — Read a file from the repo (must be in allowed paths)",
+            "research_write_candidate — Write to a mutable file (only allowed paths)",
+            "research_diff — Show git diff for mutable files",
+            "research_commit_candidate — Commit staged mutable files",
+            "research_run_experiment — Run the experiment command with timeout",
+            "research_parse_log — Parse the experiment log for metrics",
+            "research_record — Record experiment result (keep/discard/crash/timeout)",
+            "research_accept — Accept candidate (update best metric, advance branch)",
+            "research_revert — Revert to last accepted commit",
+            "research_inspect_failure — Read last 50 lines of run.log for crash diagnosis",
+            "research_checkpoint — Save current state to disk",
+        ];
+        return [
+            "You are an autonomous research agent running experiments in a loop.",
+            "",
+            programContent ? "## Research Program" : "",
+            programContent,
+            "",
+            "## Available Tools",
+            ...toolList.map((t) => `- ${t}`),
+            "",
+            "## Constraints",
+            `- You may ONLY modify these files: ${this.config.mutablePaths.join(", ")}`,
+            `- You must NEVER modify: ${this.config.immutablePaths.join(", ")}`,
+            `- The primary metric is: ${this.config.metric.name} (${this.config.metric.direction} is better)`,
+            `- Experiment timeout: ${Math.round(this.config.timeoutMs / 1000)} seconds`,
+            "",
+            "## Workflow",
+            "1. Call research_get_context to understand current state",
+            "2. Read relevant files to understand the code",
+            "3. Propose and implement a single experiment change",
+            "4. Commit the change",
+            "5. Run the experiment",
+            "6. Parse the results",
+            "7. Record the outcome",
+            "8. Accept (if improved) or revert (if not)",
+            "",
+            "NEVER STOP. Continue proposing experiments indefinitely.",
+            "Prefer simplicity — deleting code is better than adding complexity.",
+        ]
+            .filter(Boolean)
+            .join("\n");
+    }
+    /** Builds the per-cycle prompt with current state + recent results */
+    async buildCyclePrompt(state, recentResults) {
+        const parts = [
+            `## Current Research State`,
+            `- Branch: ${state.branch}`,
+            `- Run count: ${state.runCount}`,
+            `- Keep count: ${state.keepCount}`,
+            `- Best ${this.config.metric.name}: ${state.bestMetric ?? "no baseline yet"}`,
+            `- Last status: ${state.lastStatus ?? "none"}`,
+            `- Current phase: ${state.currentPhase}`,
+            `- Accepted commit: ${state.acceptedCommit ?? "none"}`,
+        ];
+        if (recentResults.length > 0) {
+            parts.push("");
+            parts.push("## Recent Results (last 10)");
+            parts.push(`commit\t${this.config.metric.name}\tstatus\tdescription`);
+            for (const r of recentResults.slice(-10)) {
+                const metricStr = r.metric !== null && Number.isFinite(r.metric)
+                    ? r.metric.toFixed(6)
+                    : "N/A";
+                parts.push(`${r.commit}\t${metricStr}\t${r.status}\t${r.description}`);
+            }
+        }
+        parts.push("");
+        // Phase-aware first action suggestion (avoid biasing accept_or_revert toward accept)
+        const phasePolicy = getPhaseToolPolicy(state.currentPhase);
+        let firstAction;
+        if (phasePolicy.forcedTool) {
+            firstAction = phasePolicy.forcedTool;
+        }
+        else if (state.currentPhase === "accept_or_revert") {
+            // Don't bias toward accept or revert — the deterministic policy decides.
+            // Use checkpoint (neutral) since accept/revert are both in activeTools.
+            firstAction = "research_checkpoint";
+        }
+        else {
+            firstAction = phasePolicy.activeTools[0] || "research_get_context";
+        }
+        parts.push(`Continue the experiment loop. Start by calling ${firstAction}.`);
+        return parts.join("\n");
+    }
+}

package/dist/autoresearch/repoPolicy.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Repository policy enforcement for autoresearch.
+ *
+ * Controls which files can be read/written and validates
+ * git operations against the research branch.
+ */
+import type { ResearchConfig } from "../types/autoresearchTypes.js";
+export declare class RepoPolicy {
+    private config;
+    private resolvedMutablePaths;
+    private resolvedImmutablePaths;
+    constructor(config: ResearchConfig);
+    /** Returns true if resolved path is inside repoPath (handles prefix collision) */
+    private isInsideRepo;
+    /** Returns true if path is within mutablePaths and NOT in immutablePaths */
+    isWriteAllowed(filePath: string): boolean;
+    /** Returns true if path is in immutablePaths */
+    isProtected(filePath: string): boolean;
+    /** Returns true if path is readable (mutable, immutable, or program path) */
+    isReadAllowed(filePath: string): boolean;
+    /** Validates staged files are all in mutablePaths and on the right branch */
+    validateCommit(expectedBranch: string): Promise<{
+        valid: boolean;
+        violations: string[];
+    }>;
+    /** Returns list of staged file paths. Throws on git failure. */
+    getStagedFiles(): Promise<string[]>;
+    /** Returns current git branch */
+    getCurrentBranch(): string;
+    /** Returns short commit hash */
+    getHeadCommit(): string;
+}