@gianfrancopiana/openclaw-autoresearch 1.0.0 → 1.0.2

package/README.md

@@ -31,27 +31,37 @@ The design is file-first: any agent can pick up the repo-root files and continue
 
 ## Install
 
-For local development, link the repo directly into OpenClaw:
+Requires OpenClaw `2026.3.13` or newer.
+
+Use OpenClaw's plugin installer:
 
 ```bash
-openclaw plugins install -l /absolute/path/to/openclaw-autoresearch
+openclaw plugins install @gianfrancopiana/openclaw-autoresearch
 ```
 
-For a packaged local install, build the tarball and install that artifact:
+If you're running from a local OpenClaw checkout, use:
 
 ```bash
-npm install
-npm pack
-openclaw plugins install ./gianfrancopiana-openclaw-autoresearch-1.0.0.tgz
+pnpm openclaw plugins install @gianfrancopiana/openclaw-autoresearch
 ```
 
-After publishing to npm, the same package can be installed with:
+For local plugin development, link your working copy instead of copying files:
 
 ```bash
-openclaw plugins install @gianfrancopiana/openclaw-autoresearch
+openclaw plugins install --link /absolute/path/to/openclaw-autoresearch
+# or from a local OpenClaw checkout:
+# pnpm openclaw plugins install --link /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-<version>.tgz
 ```
 
-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).
+The install command records the plugin, enables it, and exposes the plugin surfaces on restart. 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:
 
@@ -100,6 +110,8 @@ npm run validate
 npm run release:verify
 ```
 
+Release instructions, including npm 2FA publishing, live in [`RELEASING.md`](RELEASING.md).
+
 The local test shim supports typechecking and tests without a full OpenClaw host checkout. Runtime behavior depends on a real OpenClaw host.
 
 ## License

package/RELEASING.md

@@ -0,0 +1,43 @@
+# Releasing
+
+## Prerequisites
+
+- npm access to `@gianfrancopiana`
+- either npm account 2FA enabled for publishing, or a granular access token with `Bypass 2FA` enabled
+
+## Release
+
+1. Update `package.json` and `openclaw.plugin.json` if you are changing the version.
+2. Run the release checks:
+
+   ```bash
+   npm install
+   npm run release:verify
+   ```
+
+3. Publish:
+
+   ```bash
+   npm publish --otp=123456
+   ```
+
+   Replace `123456` with the current code from your authenticator app.
+
+4. Verify install:
+
+   ```bash
+   openclaw plugins install @gianfrancopiana/openclaw-autoresearch
+   ```
+
+   For a local OpenClaw checkout:
+
+   ```bash
+   pnpm openclaw plugins install @gianfrancopiana/openclaw-autoresearch
+   ```
+
+## Common failure
+
+If `npm publish` fails with `E403` and mentions 2FA or bypass tokens, the current auth on this machine is not sufficient to publish. Either:
+
+- re-run `npm publish --otp=<current-code>`
+- or switch to a granular npm token with publish rights and `Bypass 2FA` enabled

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

@@ -1,8 +1,10 @@
-import { spawn } from "node:child_process";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 
 const OUTPUT_TAIL_LINES = 80;
 const DEFAULT_TIMEOUT_SECONDS = 600;
-const FORCE_KILL_GRACE_MS = 1_000;
+const NO_TIMEOUT_MS = 2_147_483_647;
+
+type RunCommandWithTimeout = OpenClawPluginApi["runtime"]["system"]["runCommandWithTimeout"];
 
 export type ExperimentExecutionResult = {
   readonly command: string;
@@ -17,95 +19,42 @@ export type ExperimentExecutionResult = {
 };
 
 export async function executeExperimentCommand(options: {
+  runCommandWithTimeout: RunCommandWithTimeout;
   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 timeoutMs =
+    timeoutSeconds > 0 ? Math.max(1, Math.floor(timeoutSeconds * 1_000)) : NO_TIMEOUT_MS;
   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;
+  if (options.signal?.aborted) {
+    const error = new Error("Experiment run aborted before start.");
+    error.name = "AbortError";
+    throw error;
+  }
 
-      resolve({
-        command: options.command,
-        exitCode: code,
-        durationSeconds,
-        passed,
-        crashed: !passed,
-        timedOut,
-        tailOutput: createOutputTail(stdout, stderr),
-        stdout,
-        stderr,
-      });
-    });
+  const result = await options.runCommandWithTimeout(["bash", "-c", options.command], {
+    cwd: options.cwd,
+    timeoutMs,
   });
+  const durationSeconds = (Date.now() - startedAt) / 1_000;
+  const timedOut = result.termination === "timeout";
+  const passed = result.code === 0 && result.termination === "exit";
+
+  return {
+    command: options.command,
+    exitCode: result.code,
+    durationSeconds,
+    passed,
+    crashed: !passed,
+    timedOut,
+    tailOutput: createOutputTail(result.stdout, result.stderr),
+    stdout: result.stdout,
+    stderr: result.stderr,
+  };
 }
 
 function createOutputTail(stdout: string, stderr: string): string {

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

@@ -1,4 +1,8 @@
-import { spawnSync } from "node:child_process";
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+const GIT_TIMEOUT_MS = 30_000;
+
+type RunCommandWithTimeout = OpenClawPluginApi["runtime"]["system"]["runCommandWithTimeout"];
 
 export type GitCommandResult = {
   readonly code: number | null;
@@ -15,24 +19,29 @@ export type GitKeepResult = {
   readonly command: GitCommandResult;
 };
 
-function runGitCommand(cwd: string, args: readonly string[]): GitCommandResult {
-  const result = spawnSync("git", [...args], {
+async function runGitCommand(
+  runCommandWithTimeout: RunCommandWithTimeout,
+  cwd: string,
+  args: readonly string[],
+): Promise<GitCommandResult> {
+  const result = await runCommandWithTimeout(["git", ...args], {
     cwd,
-    encoding: "utf8",
+    timeoutMs: GIT_TIMEOUT_MS,
   });
-
   const stdout = result.stdout ?? "";
   const stderr = result.stderr ?? "";
+  const combinedOutput = `${stdout}${stderr}`.trim() || describeTermination(result.termination);
 
   return {
-    code: result.status,
+    code: result.code,
     stdout,
     stderr,
-    combinedOutput: `${stdout}${stderr}`.trim(),
+    combinedOutput,
   };
 }
 
-export function commitKeptExperiment(options: {
+export async function commitKeptExperiment(options: {
+  runCommandWithTimeout: RunCommandWithTimeout;
   cwd: string;
   description: string;
   metricName: string;
@@ -40,7 +49,7 @@ export function commitKeptExperiment(options: {
   metrics: Record<string, number>;
   commit: string;
   status: "keep";
-}): GitKeepResult {
+}): Promise<GitKeepResult> {
   const resultData: Record<string, unknown> = {
     status: options.status,
     [options.metricName || "metric"]: options.metric,
@@ -48,7 +57,10 @@ export function commitKeptExperiment(options: {
   };
   const commitMessage = `${options.description}\n\nResult: ${JSON.stringify(resultData)}`;
 
-  const repoRootResult = runGitCommand(options.cwd, ["rev-parse", "--show-toplevel"]);
+  const repoRootResult = await runGitCommand(options.runCommandWithTimeout, options.cwd, [
+    "rev-parse",
+    "--show-toplevel",
+  ]);
   if (repoRootResult.code !== 0 || repoRootResult.stdout.trim().length === 0) {
     return {
       attempted: true,
@@ -61,7 +73,7 @@ export function commitKeptExperiment(options: {
 
   const repoRoot = repoRootResult.stdout.trim();
 
-  const addResult = runGitCommand(repoRoot, ["add", "-A"]);
+  const addResult = await runGitCommand(options.runCommandWithTimeout, repoRoot, ["add", "-A"]);
   if (addResult.code !== 0) {
     return {
       attempted: true,
@@ -72,7 +84,11 @@ export function commitKeptExperiment(options: {
     };
   }
 
-  const diffResult = runGitCommand(repoRoot, ["diff", "--cached", "--quiet"]);
+  const diffResult = await runGitCommand(options.runCommandWithTimeout, repoRoot, [
+    "diff",
+    "--cached",
+    "--quiet",
+  ]);
   if (diffResult.code === 0) {
     return {
       attempted: true,
@@ -92,7 +108,11 @@ export function commitKeptExperiment(options: {
     };
   }
 
-  const commitResult = runGitCommand(repoRoot, ["commit", "-m", commitMessage]);
+  const commitResult = await runGitCommand(options.runCommandWithTimeout, repoRoot, [
+    "commit",
+    "-m",
+    commitMessage,
+  ]);
   if (commitResult.code !== 0) {
     return {
       attempted: true,
@@ -103,7 +123,11 @@ export function commitKeptExperiment(options: {
     };
   }
 
-  const revParseResult = runGitCommand(repoRoot, ["rev-parse", "--short=7", "HEAD"]);
+  const revParseResult = await runGitCommand(options.runCommandWithTimeout, repoRoot, [
+    "rev-parse",
+    "--short=7",
+    "HEAD",
+  ]);
   const actualCommit =
     revParseResult.code === 0 && revParseResult.stdout.trim().length >= 7
       ? revParseResult.stdout.trim().slice(0, 7)
@@ -130,3 +154,16 @@ function truncateOutput(output: string): string {
 function formatExit(code: number | null): string {
   return code === null ? "" : ` (exit ${code})`;
 }
+
+function describeTermination(termination: "exit" | "timeout" | "no-output-timeout" | "signal"): string {
+  switch (termination) {
+    case "timeout":
+      return "command timed out";
+    case "no-output-timeout":
+      return "command timed out waiting for output";
+    case "signal":
+      return "command terminated by signal";
+    default:
+      return "";
+  }
+}

package/extensions/openclaw-autoresearch/src/tools/log-experiment.ts

@@ -78,7 +78,8 @@ export function createLogExperimentTool(api: OpenClawPluginApi) {
       };
 
       if (params.status === "keep") {
-        const gitResult = commitKeptExperiment({
+        const gitResult = await commitKeptExperiment({
+          runCommandWithTimeout: api.runtime.system.runCommandWithTimeout,
           cwd: cwd,
           description: params.description,
           metricName: state.metricName,

package/extensions/openclaw-autoresearch/src/tools/run-experiment.ts

@@ -34,6 +34,7 @@ export function createRunExperimentTool(api: OpenClawPluginApi) {
       let details;
       try {
         details = await executeExperimentCommand({
+          runCommandWithTimeout: api.runtime.system.runCommandWithTimeout,
           command: params.command,
           cwd,
           timeoutSeconds: params.timeout_seconds,

package/openclaw.plugin.json

@@ -5,7 +5,7 @@
   "skills": [
     "./skills"
   ],
-  "version": "1.0.0",
+  "version": "1.0.2",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gianfrancopiana/openclaw-autoresearch",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Faithful OpenClaw port of pi-autoresearch.",
   "type": "module",
   "main": "./index.ts",
@@ -22,6 +22,7 @@
     "skills/",
     "docs/",
     "README.md",
+    "RELEASING.md",
     "LICENSE"
   ],
   "license": "MIT",
@@ -48,6 +49,7 @@
   "publishConfig": {
     "access": "public"
   },
+  "openclawRuntime": ">=2026.3.13",
   "openclaw": {
     "extensions": [
       "./index.ts"