@ahyi/restart-continuity 0.3.1

package/README.md

@@ -0,0 +1,91 @@
+# Restart Continuity Plugin
+
+OpenClaw plugin for **gateway restart continuity**:
+
+- runs resumable startup checks when the plugin service starts
+- can health-check and replay selected cron jobs
+- writes a structured continuity state file
+- writes a human-readable daily memory log
+- can hand off a one-shot startup receipt during agent bootstrap
+
+## Install
+
+### Local path
+
+```bash
+openclaw --profile <profile> plugins install /path/to/restart-continuity-plugin
+openclaw --profile <profile> plugins enable restart-continuity
+```
+
+### npm registry
+
+```bash
+openclaw --profile <profile> plugins install @ahyi/restart-continuity@0.3.1
+openclaw --profile <profile> plugins enable restart-continuity
+```
+
+## What it does
+
+This plugin is designed to replace scattered hook-based restart continuity setups with one installable extension.
+
+On plugin service start it can:
+
+1. initialize its runtime marker/state files
+2. run configured startup resumers
+3. write `memory/restart-continuity-state.json`
+4. append a summary to `memory/YYYY-MM-DD.md`
+5. stage a one-time startup receipt for bootstrap delivery
+
+## Example config
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "restart-continuity": {
+        "enabled": true,
+        "config": {
+          "profile": "mh",
+          "workspaceDir": "/root/.openclaw/workspace-mh",
+          "logToDailyMemory": true,
+          "notifyOnBootstrap": true,
+          "resumers": [
+            {
+              "id": "nightly-learnings",
+              "kind": "cron-healthcheck",
+              "name": "mh-nightly-learnings-check",
+              "jobId": "38a8b8cb-c25a-4bc2-a8a1-d252f9d933ec"
+            },
+            {
+              "id": "weekly-self-improve",
+              "kind": "cron-healthcheck",
+              "name": "mh-weekly-self-improve",
+              "jobId": "6e912522-0591-4307-a155-a6ece496be9c"
+            }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+## Uninstall
+
+```bash
+openclaw --profile <profile> plugins uninstall restart-continuity
+```
+
+OpenClaw removes the plugin config entry and install record. If you want a fully clean teardown, also delete plugin runtime artifacts such as:
+
+- `memory/restart-continuity-state.json`
+- `memory/restart-continuity-installed.json`
+- `memory/restart-continuity-receipt.json`
+
+## Publish
+
+```bash
+npm publish --access public
+```
+
+If scoped publishing is used, make sure the npm account/org owns the scope.

package/index.ts

@@ -0,0 +1,313 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const OPENCLAW_BIN = process.env.OPENCLAW_BIN || "openclaw";
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function normalizeString(value, fallback = "") {
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+
+function getWorkspaceDir(api) {
+  const pluginConfig = api.pluginConfig || {};
+  const explicit = normalizeString(pluginConfig.workspaceDir, "");
+  if (explicit) return explicit;
+  return normalizeString(api.config?.workspace?.dir, process.cwd());
+}
+
+function getProfile(api) {
+  const pluginConfig = api.pluginConfig || {};
+  return normalizeString(pluginConfig.profile, "mh");
+}
+
+function resolvePath(workspaceDir, filePath, fallbackRelative) {
+  const raw = normalizeString(filePath, fallbackRelative);
+  if (path.isAbsolute(raw)) return raw;
+  return path.join(workspaceDir, raw);
+}
+
+async function readJsonSafe(filePath, fallback = null) {
+  try {
+    return JSON.parse(await fs.readFile(filePath, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+async function ensureDir(filePath) {
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+}
+
+async function writeJson(filePath, data) {
+  await ensureDir(filePath);
+  await fs.writeFile(filePath, JSON.stringify(data, null, 2), "utf8");
+}
+
+async function appendText(filePath, text) {
+  await ensureDir(filePath);
+  await fs.appendFile(filePath, text, "utf8");
+}
+
+async function fileExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function runOpenclaw(profile, args, timeoutMs = 180000) {
+  const finalArgs = profile ? ["--profile", profile, ...args] : args;
+  const { stdout } = await execFileAsync(OPENCLAW_BIN, finalArgs, {
+    timeout: timeoutMs,
+    maxBuffer: 1024 * 1024,
+  });
+  return String(stdout || "").trim();
+}
+
+function parseCronRunsJson(raw) {
+  try {
+    const obj = JSON.parse(raw);
+    if (Array.isArray(obj?.entries) && obj.entries.length > 0) return obj.entries[0];
+    if (Array.isArray(obj) && obj.length > 0) return obj[0];
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function buildReceipt(summary) {
+  return `启动自检完成：检查 ${summary.checked} 个任务，健康 ${summary.healthy.length}，续跑 ${summary.resumed.length}，跳过 ${summary.skipped.length}，错误 ${summary.errors.length}。`;
+}
+
+function buildDailyLog(summary) {
+  const lines = [
+    `\n## Restart continuity check (${summary.timestampLocal || summary.timestamp})`,
+    "",
+    `- Checked jobs: ${summary.checked}`,
+    `- Already healthy: ${summary.healthy.length ? summary.healthy.join(", ") : "none"}`,
+    `- Resumed jobs: ${summary.resumed.length ? summary.resumed.join(", ") : "none"}`,
+    `- Skipped jobs: ${summary.skipped.length ? summary.skipped.join(", ") : "none"}`,
+    `- Errors: ${summary.errors.length ? summary.errors.join(" | ") : "none"}`,
+    `- Outcome: ${summary.errors.length ? (summary.resumed.length ? "partial" : "error") : (summary.resumed.length ? "resumed" : "no-op")}`,
+    "",
+  ];
+  return lines.join("\n");
+}
+
+function getDatePartsForShanghai(date = new Date()) {
+  const rendered = new Intl.DateTimeFormat("en-CA", {
+    timeZone: "Asia/Shanghai",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false,
+  }).formatToParts(date);
+  const map = Object.fromEntries(rendered.filter((p) => p.type !== "literal").map((p) => [p.type, p.value]));
+  return {
+    date: `${map.year}-${map.month}-${map.day}`,
+    local: `${map.year}-${map.month}-${map.day} ${map.hour}:${map.minute}:${map.second} Asia/Shanghai`,
+  };
+}
+
+async function runCronHealthcheck(profile, resumer) {
+  const successStatuses = Array.isArray(resumer.successStatuses) && resumer.successStatuses.length
+    ? resumer.successStatuses.map(String)
+    : ["ok"];
+  const runTimeoutMs = Number.isInteger(resumer.runTimeoutMs) ? resumer.runTimeoutMs : 120000;
+
+  const runsRaw = await runOpenclaw(profile, ["cron", "runs", "--id", String(resumer.jobId), "--limit", "1"], 120000);
+  const latest = parseCronRunsJson(runsRaw);
+  const latestStatus = latest && typeof latest.status === "string" ? latest.status : null;
+
+  if (latestStatus && successStatuses.includes(latestStatus)) {
+    return { status: "healthy", detail: `${resumer.name || resumer.id}`, latestStatus };
+  }
+
+  if (resumer.autoResume === false) {
+    return { status: "skipped", detail: `${resumer.name || resumer.id} (latest=${latestStatus || "none"})`, latestStatus };
+  }
+
+  const runRaw = await runOpenclaw(profile, ["cron", "run", String(resumer.jobId), "--expect-final", "--timeout", String(runTimeoutMs)], Math.max(runTimeoutMs + 20000, 30000));
+  const normalized = /\bok\b/i.test(runRaw) ? "ok" : "ran";
+  return { status: "resumed", detail: `${resumer.name || resumer.id} => ${normalized}`, latestStatus };
+}
+
+async function ensureConfigInitialized(api) {
+  const workspaceDir = getWorkspaceDir(api);
+  const pluginConfig = api.pluginConfig || {};
+  const stateFile = resolvePath(workspaceDir, pluginConfig.stateFile, "memory/restart-continuity-state.json");
+  const defaultsFile = resolvePath(workspaceDir, pluginConfig.defaultsFile, "plugins/restart-continuity.defaults.json");
+  const markerFile = resolvePath(workspaceDir, pluginConfig.markerFile, "memory/restart-continuity-installed.json");
+
+  if (await fileExists(markerFile)) return;
+
+  const defaults = await readJsonSafe(defaultsFile, null);
+  await writeJson(markerFile, {
+    installedAt: nowIso(),
+    source: "restart-continuity",
+    workspaceDir,
+    defaultsApplied: Boolean(defaults),
+  });
+
+  if (!(await fileExists(stateFile))) {
+    await writeJson(stateFile, {
+      version: 1,
+      initializedAt: nowIso(),
+      status: "initialized",
+      source: "restart-continuity",
+      defaultsApplied: Boolean(defaults),
+    });
+  }
+
+  api.logger.info?.(`[restart-continuity] initialized (${defaults ? "defaults detected" : "no defaults file"})`);
+}
+
+async function runStartupCheck(api) {
+  const pluginConfig = api.pluginConfig || {};
+  const profile = getProfile(api);
+  const workspaceDir = getWorkspaceDir(api);
+  const stateFile = resolvePath(workspaceDir, pluginConfig.stateFile, "memory/restart-continuity-state.json");
+  const receiptFile = resolvePath(workspaceDir, pluginConfig.receiptFile, "memory/restart-continuity-receipt.json");
+  const logToDailyMemory = pluginConfig.logToDailyMemory !== false;
+  const notifyOnBootstrap = pluginConfig.notifyOnBootstrap !== false;
+  const { date, local } = getDatePartsForShanghai(new Date());
+  const resumers = Array.isArray(pluginConfig.resumers) ? pluginConfig.resumers : [];
+
+  const summary = {
+    version: 1,
+    timestamp: nowIso(),
+    timestampLocal: local,
+    checked: 0,
+    healthy: [],
+    resumed: [],
+    skipped: [],
+    errors: [],
+    results: [],
+  };
+
+  for (const resumer of resumers) {
+    if (!resumer || typeof resumer !== "object") continue;
+    if (resumer.enabled === false) {
+      summary.skipped.push(`${resumer.name || resumer.id || "unknown"} (disabled)`);
+      continue;
+    }
+    summary.checked += 1;
+    try {
+      if (resumer.kind === "cron-healthcheck") {
+        const result = await runCronHealthcheck(profile, resumer);
+        summary.results.push({ id: resumer.id, kind: resumer.kind, ...result });
+        if (result.status === "healthy") summary.healthy.push(result.detail);
+        else if (result.status === "resumed") summary.resumed.push(result.detail);
+        else if (result.status === "skipped") summary.skipped.push(result.detail);
+        else summary.errors.push(`${resumer.name || resumer.id}: unknown status`);
+      } else {
+        summary.errors.push(`${resumer.name || resumer.id}: unsupported kind ${String(resumer.kind)}`);
+      }
+    } catch (error) {
+      const message = error && error.message ? error.message : String(error);
+      summary.errors.push(`${resumer.name || resumer.id}: ${message}`);
+      summary.results.push({ id: resumer.id, kind: resumer.kind, status: "error", error: message });
+    }
+  }
+
+  summary.receipt = buildReceipt(summary);
+  await writeJson(stateFile, summary);
+
+  if (notifyOnBootstrap) {
+    await writeJson(receiptFile, {
+      createdAt: summary.timestamp,
+      source: "restart-continuity",
+      receipt: summary.receipt,
+      summary,
+    });
+  }
+
+  if (logToDailyMemory) {
+    const dailyPath = path.join(workspaceDir, "memory", `${date}.md`);
+    await appendText(dailyPath, buildDailyLog(summary));
+  }
+
+  api.logger.info?.(`[restart-continuity] ${summary.receipt}`);
+}
+
+const plugin = {
+  id: "restart-continuity",
+  name: "Restart Continuity",
+  description: "Gateway restart continuity plugin with resumable startup checks and receipt handoff.",
+  configSchema: {
+    parse(value) {
+      return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+    },
+    uiHints: {
+      profile: { label: "OpenClaw Profile" },
+      workspaceDir: { label: "Workspace Directory" },
+      stateFile: { label: "State File" },
+      receiptFile: { label: "Receipt File" },
+      defaultsFile: { label: "Defaults File" },
+      markerFile: { label: "Install Marker File" },
+      logToDailyMemory: { label: "Append summary to daily memory" },
+      notifyOnBootstrap: { label: "Inject startup receipt into next bootstrap reply" },
+      resumers: { label: "Resumable task definitions" },
+    },
+  },
+  register(api) {
+    api.registerService({
+      id: "restart-continuity-service",
+      start: async () => {
+        try {
+          await ensureConfigInitialized(api);
+          await runStartupCheck(api);
+        } catch (err) {
+          api.logger.warn?.(`[restart-continuity] service start failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      },
+      stop: async () => {},
+    });
+
+    api.registerHook(
+      "agent:bootstrap",
+      async (event) => {
+        const pluginConfig = api.pluginConfig || {};
+        if (pluginConfig.notifyOnBootstrap === false) return;
+        const ctx = event && event.context ? event.context : {};
+        const bootstrapFiles = Array.isArray(ctx.bootstrapFiles) ? ctx.bootstrapFiles : null;
+        if (!bootstrapFiles) return;
+
+        const workspaceDir = getWorkspaceDir(api);
+        const receiptFile = resolvePath(workspaceDir, pluginConfig.receiptFile, "memory/restart-continuity-receipt.json");
+        const pending = await readJsonSafe(receiptFile, null);
+        if (!pending || !pending.receipt) return;
+
+        const content = [
+          "## Restart Continuity Receipt",
+          "",
+          pending.receipt,
+          "",
+          "Instruction: In your next reply to the user, include this startup receipt concisely (1-2 lines) before normal content. Do this once only.",
+        ].join("\n");
+
+        bootstrapFiles.push({ path: "RESTART_CONTINUITY_RECEIPT.md", content, virtual: true });
+        try {
+          await fs.unlink(receiptFile);
+        } catch {}
+      },
+      {
+        name: "restart-continuity.agent-bootstrap",
+        description: "Injects the pending restart continuity receipt into the next bootstrap reply.",
+      },
+    );
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,54 @@
+{
+  "id": "restart-continuity",
+  "name": "Restart Continuity",
+  "description": "Gateway restart continuity plugin with resumable startup checks and receipt handoff.",
+  "version": "0.3.0",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "profile": { "type": "string", "default": "mh" },
+      "workspaceDir": { "type": "string", "default": "" },
+      "stateFile": { "type": "string", "default": "memory/restart-continuity-state.json" },
+      "receiptFile": { "type": "string", "default": "memory/restart-continuity-receipt.json" },
+      "defaultsFile": { "type": "string", "default": "plugins/restart-continuity.defaults.json" },
+      "markerFile": { "type": "string", "default": "memory/restart-continuity-installed.json" },
+      "logToDailyMemory": { "type": "boolean", "default": true },
+      "notifyOnBootstrap": { "type": "boolean", "default": true },
+      "resumers": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "id": { "type": "string" },
+            "kind": { "type": "string", "enum": ["cron-healthcheck"] },
+            "name": { "type": "string" },
+            "enabled": { "type": "boolean", "default": true },
+            "autoResume": { "type": "boolean", "default": true },
+            "jobId": { "type": "string" },
+            "successStatuses": {
+              "type": "array",
+              "items": { "type": "string" },
+              "default": ["ok"]
+            },
+            "runTimeoutMs": { "type": "integer", "minimum": 1000, "default": 120000 }
+          },
+          "required": ["id", "kind", "jobId"]
+        },
+        "default": []
+      }
+    }
+  },
+  "uiHints": {
+    "profile": { "label": "OpenClaw Profile" },
+    "workspaceDir": { "label": "Workspace Directory" },
+    "stateFile": { "label": "State File" },
+    "receiptFile": { "label": "Receipt File" },
+    "defaultsFile": { "label": "Defaults File" },
+    "markerFile": { "label": "Install Marker File" },
+    "logToDailyMemory": { "label": "Append summary to daily memory" },
+    "notifyOnBootstrap": { "label": "Inject startup receipt into next bootstrap reply" },
+    "resumers": { "label": "Resumable task definitions" }
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@ahyi/restart-continuity",
+  "version": "0.3.1",
+  "description": "OpenClaw restart continuity plugin with resumable startup checks and receipt handoff",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "restart",
+    "continuity",
+    "gateway"
+  ],
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}