@gianfrancopiana/openclaw-autoresearch 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Tobi Lutke, David Cortés
+Copyright (c) 2026 Gianfranco Piana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# openclaw-autoresearch
+
+Autonomous experiment loop for any optimization target.
+
+Faithful OpenClaw port of [`davebcn87/pi-autoresearch`](https://github.com/davebcn87/pi-autoresearch).
+
+## How it works
+
+The agent runs a loop: edit code, run a benchmark, measure the result, keep or discard. Each iteration is logged. The loop runs autonomously until interrupted.
+
+Three tools drive the loop:
+
+| Tool | What it does |
+|---|---|
+| `init_experiment` | Configures the session: name, primary metric, unit, direction (lower/higher). Re-calling starts a new segment. |
+| `run_experiment` | Executes a shell command, times it, captures stdout/stderr, returns pass/fail via exit code. |
+| `log_experiment` | Records the result. `keep` auto-commits to git. `discard`/`crash` log without committing. Tracks secondary metrics alongside the primary. |
+
+Each tool also accepts an optional `cwd` so callers can target a nested repo explicitly instead of relying on the current session working directory.
+
+All state lives in four repo-root files:
+
+| File | Purpose |
+|---|---|
+| `autoresearch.md` | Session doc: objective, metrics, files in scope, constraints, what's been tried. A fresh agent reads this to resume. |
+| `autoresearch.sh` | Benchmark script. Outputs `METRIC name=number` lines. |
+| `autoresearch.jsonl` | Structured log: config headers + experiment entries (metric, status, timestamp, segment, commit hash). |
+| `autoresearch.ideas.md` | Backlog of promising ideas not yet tried. Optional. |
+
+The design is file-first: any agent can pick up the repo-root files and continue the loop without prior context.
+
+## Install
+
+For local development, link the repo directly into OpenClaw:
+
+```bash
+openclaw plugins install -l /absolute/path/to/openclaw-autoresearch
+```
+
+For a packaged local install, build the tarball and install that artifact:
+
+```bash
+npm install
+npm pack
+openclaw plugins install ./gianfrancopiana-openclaw-autoresearch-1.0.0.tgz
+```
+
+After publishing to npm, the same package can be installed with:
+
+```bash
+openclaw plugins install @gianfrancopiana/openclaw-autoresearch
+```
+
+The installer reads `package.json#openclaw.extensions`, loads the root [`index.ts`](index.ts), and discovers the manifest in [`openclaw.plugin.json`](openclaw.plugin.json).
+
+Verify:
+
+- skill: `autoresearch-create`
+- tools: `init_experiment`, `run_experiment`, `log_experiment`
+- command: `/autoresearch` (recommended)
+- direct skill fallback: `/skill autoresearch-create`
+
+Prefer the explicit `/autoresearch` command surface in OpenClaw. The auto-generated native skill alias `/autoresearch_create` may not trigger reliably on some hosts, so use `/skill autoresearch-create` if you need to invoke the skill directly.
+
+## Use
+
+In the repo you want to optimize:
+
+1. Load the plugin.
+2. Run `/autoresearch` or `/autoresearch setup <goal>`.
+3. Send a normal message with the goal, command, metric (+ direction), files in scope, and constraints.
+4. If you need the raw skill invocation, use `/skill autoresearch-create`.
+5. The agent writes `autoresearch.md` and `autoresearch.sh`, runs a baseline, then starts looping.
+6. Use `/autoresearch` or `/autoresearch status` to re-prime context on a later turn.
+
+To resume an existing session, a new agent reads the repo-root files and continues from where the last one stopped.
+
+### User steers
+
+Messages sent while an experiment is running are queued and surfaced after the next `log_experiment`. The agent finishes the current experiment before incorporating the steer.
+
+### Ideas backlog
+
+When the agent discovers promising but complex ideas mid-loop, it appends them to `autoresearch.ideas.md`. On resume, the agent reads the backlog, prunes stale entries, and uses the remaining ideas as experiment paths.
+
+## Upstream reference
+
+This port preserves upstream semantics, names, and file contracts while adapting presentation to OpenClaw. There is no Pi-style widget, dashboard, or editor shortcut layer. Remaining differences are tracked in [`docs/non-parity.md`](docs/non-parity.md).
+
+- upstream repo: `https://github.com/davebcn87/pi-autoresearch`
+- pinned upstream commit: `2227029fa5712944a36938b5fe59f709cb30ed22` (`2227029f`)
+
+## Validation
+
+```bash
+npm install --include=dev
+npm run typecheck
+npm test
+npm run validate
+npm run release:verify
+```
+
+The local test shim supports typechecking and tests without a full OpenClaw host checkout. Runtime behavior depends on a real OpenClaw host.
+
+## License
+
+MIT

package/docs/non-parity.md

@@ -0,0 +1,95 @@
+# Non-Parity Notes for the OpenClaw Port
+
+This repo aims to be a **faithful port** of `davebcn87/pi-autoresearch`, but it will not be a literal 1:1 port of Pi's UI/runtime.
+
+Pinned upstream reference:
+
+- Repo: `https://github.com/davebcn87/pi-autoresearch`
+- Commit: `2227029fa5712944a36938b5fe59f709cb30ed22` (`2227029f`)
+
+## Principle
+
+Non-parity is acceptable only when it is forced by the host/runtime difference.
+
+That means:
+- preserve semantics first
+- preserve names and file layout second
+- adapt presentation/runtime integration last
+
+## Expected non-parity in v1
+
+### 1. No Pi widget parity
+The Pi extension renders an always-visible status widget above the editor.
+
+OpenClaw may provide a thinner status surface instead, such as:
+- tool output
+- command output
+- lightweight summaries
+
+### 2. No fullscreen dashboard / TUI parity
+Pi provides an inline dashboard with keyboard interaction.
+
+OpenClaw v1 should not try to fake this with a new UI system. If a status view exists, it should be thin and optional.
+
+### 3. No keyboard shortcut parity
+Pi has `Ctrl+X` and `Escape` affordances tied to its editor runtime.
+
+These are considered host-specific and are not part of the core port contract.
+
+### 4. Lifecycle hook names will differ
+Pi uses hooks such as:
+- `session_start`
+- `session_switch`
+- `session_fork`
+- `session_tree`
+- `before_agent_start`
+- `agent_end`
+- `input`
+
+OpenClaw has a different hook model. We should preserve intent, not literal event names.
+
+In practice, this port now uses documented OpenClaw lifecycle hooks such as:
+- `before_prompt_build`
+- `message_received`
+- `agent_end`
+- `session_end`
+
+The result should preserve queued-steer handling and ideas-backlog continuation intent without pretending that Pi's hook names or UI affordances exist in OpenClaw.
+
+### 5. `/autoresearch` command is thinner than Pi
+The upstream repo includes a dedicated `/autoresearch` dashboard/entry surface.
+
+OpenClaw v1 keeps the main UX command-first and implements `/autoresearch` as a mode and status helper that:
+- provides a stable explicit entrypoint when host-native skill aliases vary
+- detects canonical repo-root files
+- enables or disables autoresearch mode for later agent turns
+- offers terse status text
+- points the agent back to `autoresearch.md`
+
+It is intentionally not a dashboard replacement or a fullscreen UI.
+
+## Non-parity that is **not** acceptable
+
+The following would be design drift, not justified non-parity:
+
+- moving canonical runtime files under `.autoresearch/` in v1
+- renaming `init_experiment`, `run_experiment`, or `log_experiment`
+- making a provider/runtime the product identity
+- replacing the explicit command and direct-skill setup surface with a provider-specific worker-first UX
+- changing keep/discard/crash behavior for convenience
+- relying on hidden runtime state instead of file-first resumability
+
+## Honest product statement for v1
+
+The correct way to describe v1 is:
+
+> A faithful OpenClaw port of `pi-autoresearch` that preserves upstream semantics, names, and file contracts, while explicitly not matching Pi's editor widget/dashboard UX.
+
+## Future parity work
+
+Possible later work, if OpenClaw surfaces support it cleanly:
+- richer status presentation
+- optional command polish
+- optional provider adapters behind the plugin boundary
+
+These should remain secondary to semantic fidelity.

package/extensions/openclaw-autoresearch/index.ts

@@ -0,0 +1,30 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  AUTORESEARCH_PLUGIN_DESCRIPTION,
+  AUTORESEARCH_PLUGIN_ID,
+  AUTORESEARCH_PLUGIN_NAME,
+  autoresearchPluginConfigSchema,
+} from "./src/config.js";
+import { createInitExperimentTool } from "./src/tools/init-experiment.js";
+import { createRunExperimentTool } from "./src/tools/run-experiment.js";
+import { createLogExperimentTool } from "./src/tools/log-experiment.js";
+import { createAutoresearchStatusTool } from "./src/tools/autoresearch-status.js";
+import { registerAutoresearchHooks } from "./src/hooks.js";
+import { registerAutoresearchCommand } from "./src/commands/autoresearch.js";
+
+const plugin = {
+  id: AUTORESEARCH_PLUGIN_ID,
+  name: AUTORESEARCH_PLUGIN_NAME,
+  description: AUTORESEARCH_PLUGIN_DESCRIPTION,
+  configSchema: autoresearchPluginConfigSchema,
+  register(api: OpenClawPluginApi) {
+    registerAutoresearchHooks(api);
+    registerAutoresearchCommand(api);
+    api.registerTool(createInitExperimentTool(api));
+    api.registerTool(createRunExperimentTool(api));
+    api.registerTool(createLogExperimentTool(api));
+    api.registerTool(createAutoresearchStatusTool(api));
+  },
+};
+
+export default plugin;

package/extensions/openclaw-autoresearch/src/commands/autoresearch.ts

@@ -0,0 +1,182 @@
+import * as fs from "node:fs";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  AUTORESEARCH_ROOT_FILES,
+  getAutoresearchRootFilePath,
+  type AutoresearchRootFileKey,
+} from "../files.js";
+import { reconstructStateFromJsonl } from "../state.js";
+import { formatAutoresearchStatusText } from "../tools/autoresearch-status.js";
+import {
+  clearAutoresearchSteers,
+  getAutoresearchRuntimeState,
+  setAutoresearchPendingCommand,
+  setAutoresearchRunInFlight,
+  setAutoresearchRuntimeMode,
+} from "../runtime-state.js";
+
+type CommandContext = {
+  args?: string;
+  channel?: string;
+  senderId?: string;
+  cwd?: string;
+};
+
+const COMMAND_USAGE = [
+  "Enable or inspect repo-root autoresearch mode.",
+  "",
+  "Usage:",
+  "/autoresearch",
+  "/autoresearch on",
+  "/autoresearch off",
+  "/autoresearch setup",
+  "/autoresearch status",
+  "/autoresearch help",
+].join("\n");
+
+export function registerAutoresearchCommand(api: OpenClawPluginApi): void {
+  api.registerCommand({
+    name: "autoresearch",
+    description: "Enable, disable, or inspect repo-root autoresearch mode.",
+    acceptsArgs: true,
+    handler: (ctx: CommandContext) => {
+      const cwd = resolveCommandCwd(api, ctx);
+      const rawArgs = (ctx.args ?? "").trim();
+      const [verb, ...rest] = rawArgs.split(/\s+/).filter(Boolean);
+      const action = (verb ?? "").toLowerCase();
+      const remainder = rest.join(" ").trim() || null;
+
+      if (!rawArgs || action === "resume" || action === "on") {
+        return {
+          text: enableAutoresearchMode(cwd, rawArgs && action !== "resume" && action !== "on" ? rawArgs : remainder),
+        };
+      }
+      if (action === "setup") {
+        return { text: primeAutoresearchSetup(cwd, remainder) };
+      }
+      if (action === "off") {
+        setAutoresearchRuntimeMode(cwd, "off");
+        setAutoresearchPendingCommand(cwd, null);
+        clearAutoresearchSteers(cwd);
+        setAutoresearchRunInFlight(cwd, false);
+        return {
+          text: [
+            "Autoresearch mode OFF.",
+            `Canonical files remain at repo root: ${Object.values(AUTORESEARCH_ROOT_FILES).join(", ")}`,
+          ].join("\n"),
+        };
+      }
+      if (action === "status") {
+        return { text: buildAutoresearchCommandText(cwd, "status") };
+      }
+      if (action === "help") {
+        return { text: `${COMMAND_USAGE}\n\n${buildAutoresearchCommandText(cwd, "default")}` };
+      }
+
+      return {
+        text: enableAutoresearchMode(cwd, rawArgs),
+      };
+    },
+  });
+}
+
+export function buildAutoresearchCommandText(
+  cwd: string,
+  mode: "default" | "status",
+): string {
+  const runtimeState = getAutoresearchRuntimeState(cwd);
+  const presentFiles = getPresentCanonicalFiles(cwd);
+  const hasSession = presentFiles.length > 0;
+
+  if (!hasSession) {
+    return [
+      "No repo-root autoresearch session detected.",
+      "",
+      `Expected canonical files: ${Object.values(AUTORESEARCH_ROOT_FILES).join(", ")}`,
+      "Recommended OpenClaw entrypoint: `/autoresearch` or `/autoresearch setup <goal>`.",
+      "Direct skill fallback: `/skill autoresearch-create`.",
+    ].join("\n");
+  }
+
+  const state = reconstructStateFromJsonl(cwd);
+  const lines = [
+    `Autoresearch session detected at repo root: ${presentFiles.join(", ")}`,
+    `Read \`${AUTORESEARCH_ROOT_FILES.sessionDoc}\` before resuming or changing the loop.`,
+  ];
+
+  if (mode === "status") {
+    lines.push("", formatAutoresearchStatusText(state, runtimeState));
+  } else if (state.mode === "active" || state.hasSessionDoc) {
+    lines.push(
+      "Use `/autoresearch` or `/autoresearch on` to enable mode for the next agent turn, then continue the upstream loop with `init_experiment`, `run_experiment`, and `log_experiment` as needed.",
+    );
+  } else {
+    lines.push(
+      `The canonical files exist, but the session brief looks incomplete. Open \`${AUTORESEARCH_ROOT_FILES.sessionDoc}\` and finish setup, or restart via \`/skill autoresearch-create\` if needed.`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+function enableAutoresearchMode(cwd: string, args: string | null): string {
+  setAutoresearchRuntimeMode(cwd, "on");
+  const presentFiles = getPresentCanonicalFiles(cwd);
+  const hasSession = presentFiles.length > 0;
+
+  if (!hasSession) {
+    setAutoresearchPendingCommand(cwd, {
+      kind: "setup",
+      args,
+    });
+    return [
+      "Autoresearch mode ON.",
+      "No repo-root session was detected, so the next agent turn will be primed for setup.",
+      "Next step: send a normal message so the next agent turn can gather setup details.",
+      "Direct skill fallback: `/skill autoresearch-create`.",
+      args ? `Captured setup instruction: ${args}` : "Run `/autoresearch setup <goal>` to attach a setup hint.",
+    ].join("\n");
+  }
+
+  setAutoresearchPendingCommand(cwd, {
+    kind: "resume",
+    args,
+  });
+  return [
+    "Autoresearch mode ON.",
+    `Next agent turn will be primed from \`${AUTORESEARCH_ROOT_FILES.sessionDoc}\` and the canonical repo-root files.`,
+    args ? `Captured resume instruction: ${args}` : "Send a normal message to continue the loop, or use `/autoresearch status` for a snapshot first.",
+  ].join("\n");
+}
+
+function primeAutoresearchSetup(cwd: string, args: string | null): string {
+  setAutoresearchRuntimeMode(cwd, "on");
+  setAutoresearchPendingCommand(cwd, {
+    kind: "setup",
+    args,
+  });
+
+  return [
+    "Autoresearch setup primed.",
+    "The next agent turn will be told to create the canonical repo-root files and start the loop.",
+    "Continue with a normal message on the next turn, or invoke the skill directly with `/skill autoresearch-create`.",
+    args ? `Captured setup instruction: ${args}` : "Add an argument to `/autoresearch setup` if you want a specific goal or constraint carried forward.",
+  ].join("\n");
+}
+
+function resolveCommandCwd(api: OpenClawPluginApi, ctx: CommandContext): string {
+  if (typeof ctx.cwd === "string" && ctx.cwd.trim().length > 0) {
+    return ctx.cwd;
+  }
+  return api.resolvePath(".");
+}
+
+function getPresentCanonicalFiles(cwd: string): string[] {
+  const present: string[] = [];
+  for (const key of Object.keys(AUTORESEARCH_ROOT_FILES) as AutoresearchRootFileKey[]) {
+    if (fs.existsSync(getAutoresearchRootFilePath(cwd, key))) {
+      present.push(AUTORESEARCH_ROOT_FILES[key]);
+    }
+  }
+  return present;
+}

package/extensions/openclaw-autoresearch/src/config.ts

@@ -0,0 +1,9 @@
+export const AUTORESEARCH_PLUGIN_ID = "openclaw-autoresearch";
+export const AUTORESEARCH_PLUGIN_NAME = "Autoresearch";
+export const AUTORESEARCH_PLUGIN_DESCRIPTION = "Faithful OpenClaw port of pi-autoresearch.";
+
+export const autoresearchPluginConfigSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {},
+} as const;

package/extensions/openclaw-autoresearch/src/execute.ts

@@ -0,0 +1,122 @@
+import { spawn } from "node:child_process";
+
+const OUTPUT_TAIL_LINES = 80;
+const DEFAULT_TIMEOUT_SECONDS = 600;
+const FORCE_KILL_GRACE_MS = 1_000;
+
+export type ExperimentExecutionResult = {
+  readonly command: string;
+  readonly exitCode: number | null;
+  readonly durationSeconds: number;
+  readonly passed: boolean;
+  readonly crashed: boolean;
+  readonly timedOut: boolean;
+  readonly tailOutput: string;
+  readonly stdout: string;
+  readonly stderr: string;
+};
+
+export async function executeExperimentCommand(options: {
+  command: string;
+  cwd: string;
+  timeoutSeconds?: number;
+  signal?: AbortSignal;
+}): Promise<ExperimentExecutionResult> {
+  const timeoutSeconds = options.timeoutSeconds ?? DEFAULT_TIMEOUT_SECONDS;
+  const timeoutMs = Math.max(0, timeoutSeconds) * 1_000;
+  const startedAt = Date.now();
+
+  return await new Promise<ExperimentExecutionResult>((resolve) => {
+    const child = spawn("bash", ["-c", options.command], {
+      cwd: options.cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let timedOut = false;
+    let forceKillTimer: NodeJS.Timeout | undefined;
+
+    const timeoutTimer =
+      timeoutMs > 0
+        ? setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+            forceKillTimer = setTimeout(() => {
+              if (!child.killed) {
+                child.kill("SIGKILL");
+              }
+            }, FORCE_KILL_GRACE_MS);
+          }, timeoutMs)
+        : undefined;
+
+    const abortHandler = () => {
+      child.kill("SIGTERM");
+      forceKillTimer = setTimeout(() => {
+        if (!child.killed) {
+          child.kill("SIGKILL");
+        }
+      }, FORCE_KILL_GRACE_MS);
+    };
+
+    if (options.signal) {
+      if (options.signal.aborted) {
+        abortHandler();
+      } else {
+        options.signal.addEventListener("abort", abortHandler, { once: true });
+      }
+    }
+
+    child.stdout.on("data", (chunk: string | Buffer) => {
+      stdout += chunk.toString();
+    });
+
+    child.stderr.on("data", (chunk: string | Buffer) => {
+      stderr += chunk.toString();
+    });
+
+    child.on("error", (error) => {
+      stderr += `${stderr ? "\n" : ""}${String(error.message || error)}`;
+    });
+
+    child.on("close", (code) => {
+      if (timeoutTimer) {
+        clearTimeout(timeoutTimer);
+      }
+      if (forceKillTimer) {
+        clearTimeout(forceKillTimer);
+      }
+      if (options.signal) {
+        options.signal.removeEventListener("abort", abortHandler);
+      }
+
+      const durationSeconds = (Date.now() - startedAt) / 1_000;
+      const passed = code === 0 && !timedOut;
+
+      resolve({
+        command: options.command,
+        exitCode: code,
+        durationSeconds,
+        passed,
+        crashed: !passed,
+        timedOut,
+        tailOutput: createOutputTail(stdout, stderr),
+        stdout,
+        stderr,
+      });
+    });
+  });
+}
+
+function createOutputTail(stdout: string, stderr: string): string {
+  const combined = [stdout, stderr]
+    .filter((value) => value.trim().length > 0)
+    .join("\n")
+    .trim();
+
+  if (!combined) {
+    return "";
+  }
+
+  return combined.split(/\r?\n/).slice(-OUTPUT_TAIL_LINES).join("\n");
+}

package/extensions/openclaw-autoresearch/src/files.ts

@@ -0,0 +1,37 @@
+import * as fs from "node:fs";
+
+export const AUTORESEARCH_ROOT_FILES = {
+  sessionDoc: "autoresearch.md",
+  runnerScript: "autoresearch.sh",
+  resultsLog: "autoresearch.jsonl",
+  ideasBacklog: "autoresearch.ideas.md",
+} as const;
+
+export type AutoresearchRootFileKey = keyof typeof AUTORESEARCH_ROOT_FILES;
+
+export function getAutoresearchRootFilePath(
+  cwd: string,
+  file: AutoresearchRootFileKey,
+): string {
+  return `${cwd}/${AUTORESEARCH_ROOT_FILES[file]}`;
+}
+
+export function readAutoresearchRootFile(
+  cwd: string,
+  file: AutoresearchRootFileKey,
+): string | null {
+  const filePath = getAutoresearchRootFilePath(cwd, file);
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  return fs.readFileSync(filePath, "utf8");
+}
+
+/**
+ * PR 2 skeleton only.
+ * This module will own canonical root-level file IO helpers in later PRs.
+ */
+export function describeCanonicalFiles(): typeof AUTORESEARCH_ROOT_FILES {
+  return AUTORESEARCH_ROOT_FILES;
+}