From e5ca72151eccc2819c15aff2ae55c07718368c80 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=B0=81=E5=9C=A8=E5=90=B5=E7=9D=80=E5=90=83=E7=B3=96?=
Date: Tue, 18 Aug 2026 11:30:05 +0800
Subject: [PATCH] Squashed 'apps/MemOS-Cloud-OpenClaw-Plugin/' changes from
ff2eeb60..e4b4d8b2
e4b4d8b2 Merge pull request #157 from MemTensor/docs-sync/openclaw-cloud-auto-draft-release
28eb5f81 ci: automate cloud plugin draft releases
bf3f9b32 Merge pull request #156 from MemTensor/fix/npm-publish-propagation
df4634d3 ci: validate release fixes before merge
0da6e0a9 ci: harden npm release propagation verification
a3176616 Merge pull request #155 from EF1874/test
2ff7ec75 0.1.20
09714e85 Merge pull request #153 from MemTensor/docs-sync/openclaw-cloud-main-source-release
d33d77fb ci: publish reviewed main versions without action PRs
066f330d Merge pull request #152 from EF1874/test
50ae8cc5 Merge pull request #149 from MemTensor/docs-sync/openclaw-cloud-release-quality
1b027080 ci: surface cloud workflow contract failures
31a17497 ci: isolate read-only release dry runs
8ebc5f02 ci: declare reusable publish secret
e941685b ci: minimize dry-run workflow privileges
6a8de049 ci: align prerelease and stable release channels
41201c0a ci: normalize cloud release evidence refs
8517603d ci: close cloud release failure recovery gaps
58d9efa3 ci: preserve reusable workflow token permissions
7a8cb8fd ci: pin cloud release recovery to npm source
56170ea5 0.1.20-beta.0
557c7269 Merge branch 'main' into test
4d993bcd ci: add auditable cloud release quality gates
066db592 feat: implement deduplication for agent_end snapshots and enhance API call timeout handling
8aee50e2 ci: require recovery mode for missing release metadata
ca0f2357 ci: suppress tag fetch warnings when local tags exist
b06dcf7d ci: avoid tag fetch warnings in originless tests
74d25dd5 ci: validate manual cloud release note categories
98549947 ci: cover publish confirmation guard dry runs
7c9830f4 ci: require confirmation for real cloud releases
34e0f7b2 ci: request candidate self-checks for cloud release notes
0dde13cc ci: harden cloud plugin release previews
fd4bad4c Merge pull request #148 from MemTensor/docs-sync/openclaw-cloud-plugin-semver-previous-tag
c20bf70c fix: compare release tags with semver precedence
becc6f18 Merge pull request #147 from MemTensor/docs-sync/openclaw-cloud-plugin-release
ef831b5d ci: validate telemetry credentials before packaging
2f43ff8c ci: resolve annotated release tags to commits
252e9608 ci: read release tag evidence from commits
7f29b992 ci: add cloud plugin release dry-run automation
d0f2cea7 ci: add OpenClaw cloud plugin release workflow
18cb8c7f Merge pull request #140 from MemTensor/test
3b978092 Merge pull request #135 from EF1874/test
0c2cd2a1 0.1.19
c4ab3104 0.1.19-beta.0
d053b0a2 feat: enhance OpenClaw system prompt detection and handling
e1e7fb0f 0.1.18
ce0a9e16 Merge pull request #132 from Hun-ger/dev_gyh_260617
5152641c feat: add config UI update check
9b9e4ab2 Merge pull request #131 from MemTensor/test
2af0cb2a Merge pull request #129 from EF1874/test
3b0e068e 0.1.17
f7fd95e2 0.1.17-beta.0
70fb1840 feat: update MEMOS_SOURCE to append platform-specific suffixes and add corresponding tests
31d5f6a0 Merge branch 'test' of https://github.com/MemTensor/MemOS-Cloud-OpenClaw-Plugin into test
8b18998d Merge pull request #127 from EF1874/test
e43380d8 Merge pull request #123 from EF1874/test
ec9764d3 0.1.16
0d74ab93 0.1.16-beta.1
ed52b9c1 feat: extend system command detection to include 'clear' command and add internal prompt patterns for session management
00edb855 0.1.16-beta.0
9c773370 feat: enhance memory section handling by adding tool memory support and simplifying filtering logic
f7c1edb9 feat: refactor system event detection logic into dedicated functions for clarity and reuse
eb2bddc8 feat: add function to strip leading system notes from text input
bf25eb78 feat: implement system event detection in recall and agent end hooks to skip processing for heartbeat and command events
869217d7 Merge pull request #122 from MemTensor/test
306841f2 feat: update recall hook registration to use before_prompt_build for newer OpenClaw hosts and add tests for version compatibility
7e8304a7 Merge pull request #120 from EF1874/test
a63116fc 0.1.15
5d2bb28e 0.1.15-beta.0
b4af645e feat: add activation hooks to plugin configurations and improve hook policy handling in index.js
083b6e4b Merge pull request #119 from MemTensor/test
3b5ddaa4 Merge pull request #118 from EF1874/test
e931499a 0.1.14
1a86dc0d 0.1.14-beta.0
d0b88342 feat: add version detection and comparison utilities for host CLI
f7d19029 refactor: enhance configuration UI and improve session handling logic
d982aa0f chore: remove HOOK.md file and clean up package.json by eliminating unused hooks
03fcc33c Merge pull request #115 from MemTensor/test
1e77054b 0.1.13
19e8eb38 0.1.13-beta.1
b32b493a Merge pull request #113 from Hun-ger/fix_cloud_plugin_filter
23a48675 fix:fix filter params
de07588e 0.1.13-beta.0
4451c8a5 Merge pull request #111 from Hun-ger/fix_cloud_plugin_filter
4c84c6c3 fix typos
9f663e50 Merge pull request #110 from Hun-ger/fix_cloud_plugin_filter
92e66d30 feat: Add shared support knowledgebase for multi-agent reuse
git-subtree-dir: apps/MemOS-Cloud-OpenClaw-Plugin
git-subtree-split: e4b4d8b2ad3c50449a1b75f04eee985ebdb324a9
---
.github/release-notes/README.md | 29 +
.../draft-cloud-plugin-release-notes.mjs | 2140 +++++++++++++++++
.../draft-cloud-plugin-release-notes.test.mjs | 1547 ++++++++++++
.github/scripts/resolve-auto-release.mjs | 281 +++
.github/scripts/resolve-auto-release.test.mjs | 175 ++
.github/scripts/retry.sh | 101 +
.github/scripts/retry.test.mjs | 81 +
.../validate-github-release-inventory.mjs | 183 ++
...validate-github-release-inventory.test.mjs | 381 +++
.../scripts/validate-release-confirmation.mjs | 147 ++
.../validate-release-confirmation.test.mjs | 124 +
.../validate-release-source-version.mjs | 102 +
.../validate-release-source-version.test.mjs | 119 +
.github/scripts/wait-for-npm-release.mjs | 240 ++
.github/scripts/wait-for-npm-release.test.mjs | 188 ++
.github/workflows/historical-dry-run.yml | 54 +
.github/workflows/post-merge-dry-run.yml | 101 +
.github/workflows/pre-merge-dry-run.yml | 132 +
.github/workflows/release-dry-run.yml | 344 +++
.github/workflows/release.yml | 1235 ++++++++++
.github/workflows/workflow-contract-lint.yml | 81 +
.gitignore | 1 +
HOOK.md | 22 -
README.md | 4 +-
README_ZH.md | 4 +-
clawdbot.plugin.json | 7 +-
docs/release-owner-runbook.md | 130 +
index.js | 489 +++-
lib/arms-reporter.js | 43 +-
lib/check-update.js | 93 +-
lib/config-ui-server.js | 1693 +++++++------
lib/config-ui/app.css | 102 +
lib/config-ui/app.js | 168 +-
lib/config-ui/index.html | 1 +
lib/memos-cloud-api.js | 93 +-
lib/semver.js | 91 +
moltbot.plugin.json | 7 +-
openclaw.plugin.json | 7 +-
package.json | 21 +-
scripts/generate-telemetry-credentials.cjs | 53 +
test/add-dedup.test.mjs | 599 +++++
test/check-update-version.test.mjs | 12 +
test/direct-session-user-id.test.mjs | 31 +
test/query-strip.test.mjs | 73 +
test/recall-hook-registration.test.mjs | 56 +
45 files changed, 10730 insertions(+), 855 deletions(-)
create mode 100644 .github/release-notes/README.md
create mode 100644 .github/scripts/draft-cloud-plugin-release-notes.mjs
create mode 100644 .github/scripts/draft-cloud-plugin-release-notes.test.mjs
create mode 100644 .github/scripts/resolve-auto-release.mjs
create mode 100644 .github/scripts/resolve-auto-release.test.mjs
create mode 100755 .github/scripts/retry.sh
create mode 100644 .github/scripts/retry.test.mjs
create mode 100644 .github/scripts/validate-github-release-inventory.mjs
create mode 100644 .github/scripts/validate-github-release-inventory.test.mjs
create mode 100644 .github/scripts/validate-release-confirmation.mjs
create mode 100644 .github/scripts/validate-release-confirmation.test.mjs
create mode 100644 .github/scripts/validate-release-source-version.mjs
create mode 100644 .github/scripts/validate-release-source-version.test.mjs
create mode 100644 .github/scripts/wait-for-npm-release.mjs
create mode 100644 .github/scripts/wait-for-npm-release.test.mjs
create mode 100644 .github/workflows/historical-dry-run.yml
create mode 100644 .github/workflows/post-merge-dry-run.yml
create mode 100644 .github/workflows/pre-merge-dry-run.yml
create mode 100644 .github/workflows/release-dry-run.yml
create mode 100644 .github/workflows/release.yml
create mode 100644 .github/workflows/workflow-contract-lint.yml
delete mode 100644 HOOK.md
create mode 100644 docs/release-owner-runbook.md
create mode 100644 lib/semver.js
create mode 100644 scripts/generate-telemetry-credentials.cjs
create mode 100644 test/add-dedup.test.mjs
create mode 100644 test/check-update-version.test.mjs
create mode 100644 test/recall-hook-registration.test.mjs
diff --git a/.github/release-notes/README.md b/.github/release-notes/README.md
new file mode 100644
index 000000000..c8302bc9a
--- /dev/null
+++ b/.github/release-notes/README.md
@@ -0,0 +1,29 @@
+# Reviewed OpenClaw cloud plugin Release Notes
+
+This directory is optional. A version-bump pull request may add
+`.github/release-notes/v.md` when release owners want to provide the
+reviewed GitHub Release body themselves. For example:
+
+```text
+.github/release-notes/v0.1.21.md
+```
+
+The version in the filename must match all four committed version files. No
+special branch name is required. The file must use the same evidence-backed
+contract as the former `release_notes` workflow input:
+
+- public `## Changelog` Markdown;
+- one hidden `doc-agent-release-notes-json` block containing bilingual items
+ and real `source_refs`;
+- one exact `` marker.
+
+The release workflow validates the file. Invalid manual notes fail closed and
+cannot publish npm, a tag, or a Draft Release.
+
+The automatic workflow reads this file directly from the immutable merged
+commit. It does not copy the Markdown through cross-job outputs and does not
+create a version-update pull request.
+
+When this file is absent, the workflow collects immutable git evidence and asks
+the configured 106 Doc Agent draft endpoint to generate and repair the same
+contract. Do not commit internal URLs, tokens, prompts, or unredacted logs here.
diff --git a/.github/scripts/draft-cloud-plugin-release-notes.mjs b/.github/scripts/draft-cloud-plugin-release-notes.mjs
new file mode 100644
index 000000000..30d9286ff
--- /dev/null
+++ b/.github/scripts/draft-cloud-plugin-release-notes.mjs
@@ -0,0 +1,2140 @@
+#!/usr/bin/env node
+import { execFileSync } from "node:child_process";
+import { mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import { pathToFileURL } from "node:url";
+import { cleanVersion, compareSemver, parseSemver } from "../../lib/semver.js";
+
+export { cleanVersion, compareSemver, parseSemver };
+
+export const PRODUCT_ID = "openclaw-cloud-plugin";
+export const PRODUCT_TITLE = {
+ zh: "OpenClaw 云插件",
+ en: "OpenClaw Cloud Plugin",
+};
+export const RELEASE_NOTE_GUIDANCE = {
+ category_policy: {
+ Added:
+ "Use for newly exposed user-facing capabilities, configuration entries, lifecycle hooks, agent integrations, or memory workflow modes.",
+ Improved:
+ "Use for recall/add-memory quality, prompt sanitization, session or user-id resolution, telemetry hardening, packaging, compatibility, or reliability improvements when the evidence is not primarily a broken-behavior fix.",
+ Fixed:
+ "Use for concrete broken behavior, regressions, auth or endpoint handling bugs, duplicate prompt injection, failed retries, or configuration that existed but did not take effect.",
+ },
+ quality_policy: [
+ "Prefer Added / Improved / Fixed sections when the evidence supports all three; omit a section only when evidence is insufficient.",
+ "Keep bullets short, product-facing, and evidence-backed; do not mention internal file names unless they are the feature name users recognize.",
+ "Do not collapse newly added capability and a bug fix in the same subsystem into one item when both are separately evidenced.",
+ "Do not describe release automation, tests, or packaging as a user-facing plugin capability unless the evidence changes the published plugin behavior.",
+ ],
+ translation_policy: [
+ "Treat text_cn as the canonical release-note wording first, then translate text_cn into text_en.",
+ "Do not independently invent English facts beyond the Chinese canonical bullet and its source_refs.",
+ "Keep category and source_refs identical between Chinese and English outputs.",
+ "text_cn must contain Chinese text; text_en must not contain Chinese/CJK characters.",
+ ],
+};
+
+const REPOSITORY = "MemTensor/MemOS-Cloud-OpenClaw-Plugin";
+const CURRENT_TAG_PREFIX = "v";
+const RELEASE_NOTES_MARKER = "doc-agent-release-notes-json";
+const RELEASE_CATEGORY_ORDER = ["Added", "Improved", "Fixed"];
+const MAX_DRAFT_REPAIR_ATTEMPTS = 3;
+const MAX_RELEASE_ITEMS = 12;
+const MAX_TEXT_CN_CHARS = 180;
+const MAX_TEXT_EN_CHARS = 220;
+export const RELEASE_NOTE_LIMITS = Object.freeze({
+ max_items: MAX_RELEASE_ITEMS,
+ max_text_cn_characters: MAX_TEXT_CN_CHARS,
+ max_text_en_characters: MAX_TEXT_EN_CHARS,
+});
+export const RELEASE_FAULT_CASES = Object.freeze([
+ "none",
+ "mixed_language",
+ "missing_source_refs",
+ "missing_important_commit",
+ "invalid_source_ref",
+ "thirteen_items",
+ "too_long",
+ "manual_notes_missing_payload",
+]);
+export const RELEASE_NOTE_QUALITY_REQUEST = {
+ schema: "memos.plugin.release_notes.quality_request.v1",
+ candidate_count: 3,
+ selection_policy: [
+ "Generate multiple candidate release-note drafts when the draft service supports candidate self-evaluation.",
+ "Score candidates against evidence coverage, source_ref validity, bilingual language separation, product-facing clarity, and docs-preview readability.",
+ "Return only the best candidate in release_items/release_notes_markdown; include candidate scoring metadata only in debug fields when available.",
+ ],
+ repair_policy: {
+ max_repair_attempts: MAX_DRAFT_REPAIR_ATTEMPTS,
+ use_validation_report: true,
+ fail_closed_after_exhaustion: true,
+ },
+};
+const RELEASE_TO_DOC_CATEGORY = {
+ Added: "New Features",
+ Improved: "Improvements",
+ Fixed: "Bug Fixes",
+};
+const CJK_RE = /[\u3040-\u30ff\u3400-\u9fff\uf900-\ufaff]/;
+
+function fail(message) {
+ throw new Error(String(message));
+}
+
+function warn(message) {
+ console.error(`::warning::${message}`);
+}
+
+function git(args, options = {}) {
+ return execFileSync("git", args, {
+ cwd: process.cwd(),
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "pipe"],
+ ...options,
+ }).trim();
+}
+
+export function displayVersion(raw) {
+ const value = cleanVersion(raw);
+ return value ? `v${value}` : "";
+}
+
+export function versionFromTag(tag) {
+ const value = String(tag || "").trim();
+ if (!value.startsWith(CURRENT_TAG_PREFIX)) return "";
+ return cleanVersion(value.slice(CURRENT_TAG_PREFIX.length));
+}
+
+function gitShowJson(ref, path) {
+ try {
+ return JSON.parse(git(["show", `${ref}:${path}`]));
+ } catch {
+ return {};
+ }
+}
+
+function readJsonFile(path) {
+ try {
+ return JSON.parse(readFileSync(path, "utf8"));
+ } catch {
+ return {};
+ }
+}
+
+function tagInfo(ref) {
+ const text = git(["show", "--no-patch", "--format=%H%n%ci%n%s", commitRef(ref)]);
+ const [sha = "", date = "", subject = ""] = text.split("\n");
+ return { tag: ref, sha, date, subject };
+}
+
+function commitRef(ref) {
+ return `${ref}^{commit}`;
+}
+
+function refInfo(ref, tagLabel) {
+ const info = tagInfo(ref);
+ return { ...info, tag: tagLabel || ref, ref };
+}
+
+function refExists(ref) {
+ try {
+ git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+export function resolveCurrentRef(
+ currentTag,
+ { requestedRef = process.env.RELEASE_EVIDENCE_REF || "", refExistsImpl = refExists } = {},
+) {
+ const explicit = String(requestedRef || "").trim();
+ if (explicit) {
+ if (!refExistsImpl(explicit)) {
+ fail(`RELEASE_EVIDENCE_REF does not exist or is not a commit: ${explicit}`);
+ }
+ return explicit;
+ }
+ if (currentTag && refExistsImpl(currentTag)) return currentTag;
+ return "HEAD";
+}
+
+function localProductTags() {
+ return git(["tag", "--list", "v*"])
+ .split("\n")
+ .map((tag) => tag.trim())
+ .filter(Boolean)
+ .map((tag) => ({ tag, version: versionFromTag(tag) }))
+ .filter((item) => item.version && parseSemver(item.version));
+}
+
+function listProductTags() {
+ const existingTags = localProductTags();
+ try {
+ const remotes = git(["remote"]).split("\n").map((item) => item.trim()).filter(Boolean);
+ if (remotes.includes("origin")) {
+ git(["fetch", "--tags", "--force", "origin"], { stdio: ["ignore", "ignore", "ignore"] });
+ }
+ } catch {
+ if (existingTags.length === 0) {
+ warn("Failed to fetch tags from origin; using locally available tags.");
+ }
+ }
+
+ return localProductTags();
+}
+
+export function findPreviousTag(targetVersion, currentTag) {
+ const target = parseSemver(targetVersion);
+ const stableTarget = Boolean(target && target.prerelease.length === 0);
+ const candidates = listProductTags()
+ .filter((item) => item.tag !== currentTag)
+ .filter((item) => compareSemver(item.version, targetVersion) < 0)
+ // Prereleases never create a formal Docs entry. A stable release therefore
+ // has to summarize everything since the previous stable release instead of
+ // starting after the latest beta/rc and silently omitting those changes.
+ .filter((item) => !stableTarget || parseSemver(item.version)?.prerelease.length === 0)
+ .sort((a, b) => compareSemver(b.version, a.version));
+ return candidates[0]?.tag || "";
+}
+
+function parseCommits(previousTag, currentRef) {
+ const text = git(["log", "--format=%H%x09%h%x09%s", "--no-merges", `${previousTag}..${currentRef}`]);
+ return text
+ .split("\n")
+ .filter(Boolean)
+ .map((line) => {
+ const [sha = "", shortSha = "", subject = ""] = line.split("\t");
+ return { sha, short_sha: shortSha, subject };
+ });
+}
+
+function parseChangedFiles(previousTag, currentRef) {
+ const text = git(["diff", "--name-status", `${previousTag}..${currentRef}`]);
+ return text
+ .split("\n")
+ .filter(Boolean)
+ .map((line) => {
+ const parts = line.split("\t");
+ const item = { status: parts[0], path: parts[parts.length - 1] };
+ if (parts.length === 3) item.old_path = parts[1];
+ return item;
+ });
+}
+
+function packageChanges(previousTag, currentRef) {
+ const before = gitShowJson(previousTag, "package.json");
+ const after = currentRef === "HEAD" ? readJsonFile("package.json") : gitShowJson(currentRef, "package.json");
+ return ["name", "version"]
+ .filter((field) => before[field] !== after[field])
+ .map((field) => ({ field, before: before[field], after: after[field] }));
+}
+
+function extractPullRequests(commits, repo = process.env.GITHUB_REPOSITORY || REPOSITORY) {
+ const seen = new Set();
+ for (const commit of commits) {
+ for (const match of String(commit.subject || "").matchAll(/#(\d+)/g)) {
+ seen.add(match[1]);
+ }
+ }
+ return [...seen].map((number) => ({
+ number,
+ url: `https://github.com/${repo}/pull/${number}`,
+ }));
+}
+
+function refsForGuidance(commit) {
+ const refs = [];
+ if (commit.short_sha) refs.push(commit.short_sha);
+ for (const match of String(commit.subject || "").matchAll(/#(\d+)/g)) {
+ const value = `#${match[1]}`;
+ if (!refs.includes(value)) refs.push(value);
+ }
+ return refs;
+}
+
+function isReleaseNoiseSubject(subject) {
+ const value = String(subject || "");
+ const lower = value.toLowerCase();
+ return (
+ lower.startsWith("release:") ||
+ /^v?\d+\.\d+\.\d+(?:-[0-9a-z.-]+)?$/i.test(value.trim()) ||
+ /^chore(\([^)]+\))?:\s*(release|version|bump)\b/i.test(value) ||
+ /^(ci|build)(\([^)]+\))?:/i.test(value) ||
+ /^test(\([^)]+\))?:/i.test(value) ||
+ /^docs(\([^)]+\))?:/i.test(value) ||
+ /\b(release (tag|notes?|preview|workflow|metadata)|publish confirmation|semver[^:]*tag|tag[^:]*semver|npm publish)\b/i.test(
+ value,
+ )
+ );
+}
+
+function categoryHintForSubject(subject) {
+ const value = String(subject || "");
+ if (isReleaseNoiseSubject(value)) {
+ return null;
+ }
+ if (/^(feat|feature|add)(\([^)]+\))?:|^add\s+/i.test(value)) {
+ return {
+ category: "Added",
+ reason: "new user-facing cloud plugin capability, configuration, or lifecycle support",
+ };
+ }
+ if (/^(perf|performance|refactor|improve|enhance)(\([^)]+\))?:/i.test(value)) {
+ return {
+ category: "Improved",
+ reason: "performance, maintainability, compatibility, or reliability improvement",
+ };
+ }
+ if (
+ /recall filter|prompt|sanitize|query strip|session|user[-_ ]?id|hook|registration|telemetry|rum|pack|publish|sync-version/i.test(
+ value,
+ ) &&
+ !/^(fix|hotfix|bugfix)(\([^)]+\))?:|^fix\s+#\d+/i.test(value)
+ ) {
+ return {
+ category: "Improved",
+ reason: "cloud plugin integration, prompt, packaging, or telemetry robustness improvement",
+ };
+ }
+ if (/^(fix|hotfix|bugfix)(\([^)]+\))?:|^fix\s+#\d+/i.test(value)) {
+ return {
+ category: "Fixed",
+ reason: "specific cloud plugin bug fix",
+ };
+ }
+ return null;
+}
+
+export function categoryHintsForCommits(commits) {
+ return commits
+ .map((commit) => {
+ const hint = categoryHintForSubject(commit.subject);
+ const sourceRefs = refsForGuidance(commit);
+ if (!hint || sourceRefs.length === 0) return null;
+ return {
+ ...hint,
+ source_refs: sourceRefs,
+ subject: commit.subject,
+ };
+ })
+ .filter(Boolean);
+}
+
+export function releaseNoteGuidanceForCommits(commits) {
+ return {
+ ...RELEASE_NOTE_GUIDANCE,
+ source_ref_category_hints: categoryHintsForCommits(commits),
+ source_ref_hint_policy:
+ "Treat source_ref_category_hints as advisory classification hints grounded in evidence. " +
+ "Use them to cover important feat/fix/perf/refactor commits without inventing product facts.",
+ };
+}
+
+export function collectEvidence({ targetVersion, currentTag, previousTag, currentRef = "HEAD" }) {
+ const commits = parseCommits(previousTag, currentRef);
+ const changedFiles = parseChangedFiles(previousTag, currentRef);
+ const diffRange = `${previousTag}..${currentRef}`;
+ const repo = process.env.GITHUB_REPOSITORY || REPOSITORY;
+ const importantDiff = git(["diff", "--unified=2", diffRange]).slice(0, 24000);
+
+ return {
+ product_id: PRODUCT_ID,
+ product_title: PRODUCT_TITLE,
+ release_note_quality_request: RELEASE_NOTE_QUALITY_REQUEST,
+ release_note_guidance: releaseNoteGuidanceForCommits(commits),
+ repo,
+ previous_tag: previousTag,
+ current_tag: currentTag,
+ current_ref: currentRef,
+ diff_range: diffRange,
+ target_version: displayVersion(targetVersion),
+ git_ref: git(["rev-parse", "--short=12", commitRef(currentRef)]),
+ previous: tagInfo(previousTag),
+ current: refInfo(currentRef, currentTag),
+ commits,
+ pull_requests: extractPullRequests(commits, repo),
+ changed_files: changedFiles,
+ diff_stat: git(["diff", "--stat", diffRange]),
+ important_diff: {
+ "openclaw-cloud-plugin/**": importantDiff,
+ },
+ package_changes: packageChanges(previousTag, currentRef),
+ test_changes: changedFiles.filter((item) => item.path.startsWith("test/")),
+ docs_changes: changedFiles.filter((item) => /(^|\/)(README|docs)/i.test(item.path)),
+ };
+}
+
+export function evidenceForInspection(evidence) {
+ const guidance = evidence?.release_note_guidance || {};
+ const {
+ release_note_guidance: _releaseNoteGuidance,
+ release_note_quality_request: _releaseNoteQualityRequest,
+ important_diff: _importantDiff,
+ ...publicEvidence
+ } = evidence || {};
+ return {
+ ...publicEvidence,
+ release_note_guidance: {
+ source_ref_category_hints: Array.isArray(guidance.source_ref_category_hints)
+ ? guidance.source_ref_category_hints
+ : [],
+ },
+ redactions: {
+ important_diff: "omitted from public workflow artifacts; sent only to the configured draft service",
+ release_note_prompt_guidance: "omitted from public workflow artifacts",
+ release_note_quality_request: "omitted from public workflow artifacts; sent only to the configured draft service",
+ },
+ };
+}
+
+export function draftForInspection(draft) {
+ return {
+ ok: Boolean(draft?.ok),
+ needs_review: Boolean(draft?.needs_review),
+ confidence: draft?.confidence || "",
+ release_items: Array.isArray(draft?.release_items) ? draft.release_items : [],
+ docs_categories: draft?.docs_categories || { cn: {}, en: {} },
+ coverage: {
+ needs_review: Boolean(draft?.coverage?.needs_review),
+ required_count: Number(draft?.coverage?.required_count || 0),
+ covered_required_count: Number(draft?.coverage?.covered_required_count || 0),
+ missing_required_count: Number(draft?.coverage?.missing_required_count || 0),
+ covered_refs: Array.isArray(draft?.coverage?.covered_refs) ? draft.coverage.covered_refs : [],
+ missing_required: Array.isArray(draft?.coverage?.missing_required) ? draft.coverage.missing_required : [],
+ invalid_item_refs: Array.isArray(draft?.coverage?.invalid_item_refs) ? draft.coverage.invalid_item_refs : [],
+ },
+ warnings: Array.isArray(draft?.warnings) ? draft.warnings : [],
+ language_issues: Array.isArray(draft?.language_issues) ? draft.language_issues : [],
+ postprocess: draft?.postprocess || {},
+ validation_report: draft?.validation_report || {},
+ validation_attempt_count: Number(draft?.validation_attempt_count || 0),
+ repair_attempt_count: Number(draft?.repair_attempt_count || 0),
+ repair_attempts: Array.isArray(draft?.repair_attempts) ? draft.repair_attempts : [],
+ redactions: {
+ server_debug_fields: "omitted from public workflow artifacts",
+ model_and_prompt_details: "omitted from public workflow artifacts",
+ },
+ };
+}
+
+function appendOutput(name, value) {
+ const outputPath = process.env.GITHUB_OUTPUT;
+ if (!outputPath) return;
+ writeFileSync(outputPath, `${name}<<__DOC_AGENT_EOF__\n${value}\n__DOC_AGENT_EOF__\n`, {
+ flag: "a",
+ });
+}
+
+export function ensureSourceHint(notes) {
+ const hint = ``;
+ const sourceIds = [
+ ...String(notes || "").matchAll(
+ //g,
+ ),
+ ].map((match) => match[1]);
+ if (sourceIds.length === 0) return `${notes.trim()}\n\n${hint}\n`;
+ if (sourceIds.length !== 1 || sourceIds[0] !== PRODUCT_ID) {
+ fail(
+ `Release notes must contain exactly one Doc Agent source id ${PRODUCT_ID}; found ${sourceIds.join(", ") || "none"}.`,
+ );
+ }
+ return notes;
+}
+
+function normalizeReleaseCategory(value) {
+ const text = String(value || "").trim();
+ return RELEASE_CATEGORY_ORDER.includes(text) ? text : "";
+}
+
+function normalizeSourceRef(value) {
+ const text = String(value || "").trim().replace(/^[`[(\s]+|[`)\],.;\s]+$/g, "");
+ if (/^#\d+$/.test(text)) return text;
+ if (/^[a-fA-F0-9]{7,40}$/.test(text)) return text.toLowerCase();
+ if (/^\d{2,}$/.test(text)) return `#${text}`;
+ return "";
+}
+
+function normalizeSourceRefs(raw) {
+ const values = Array.isArray(raw) ? raw : String(raw || "").match(/#\d+|[a-fA-F0-9]{7,40}/g) || [];
+ const refs = [];
+ for (const value of values) {
+ const ref = normalizeSourceRef(value);
+ if (ref && !refs.includes(ref)) refs.push(ref);
+ }
+ return refs;
+}
+
+function refsForCommit(commit) {
+ const refs = [];
+ for (const ref of [commit?.short_sha, commit?.sha]) {
+ const normalized = normalizeSourceRef(ref);
+ if (normalized && !refs.includes(normalized)) refs.push(normalized);
+ }
+ for (const match of String(commit?.subject || "").matchAll(/#(\d+)/g)) {
+ const ref = `#${match[1]}`;
+ if (!refs.includes(ref)) refs.push(ref);
+ }
+ return refs;
+}
+
+function normalizeReleaseItem(raw) {
+ if (!raw || typeof raw !== "object") return null;
+ const category = normalizeReleaseCategory(raw.category);
+ const textCn = String(raw.text_cn || "").trim().replace(/^-+\s*/, "");
+ const textEn = String(raw.text_en || "").trim().replace(/^-+\s*/, "");
+ const sourceRefs = normalizeSourceRefs(raw.source_refs);
+ if (!category || !textCn || !textEn || sourceRefs.length === 0) return null;
+ return {
+ category,
+ text_cn: textCn,
+ text_en: textEn,
+ source_refs: sourceRefs,
+ };
+}
+
+function buildSourceRefIndex(evidence) {
+ const refToGroup = new Map();
+ const groups = new Map();
+ const knownRefs = new Set();
+ const excludedRefs = new Set();
+
+ for (const commit of evidence?.commits || []) {
+ const commitRefs = refsForCommit(commit);
+ const groupKey = normalizeSourceRef(commit?.short_sha) || commitRefs[0] || "";
+ for (const ref of commitRefs) {
+ knownRefs.add(ref);
+ if (groupKey) refToGroup.set(ref, groupKey);
+ if (isReleaseNoiseSubject(commit?.subject)) excludedRefs.add(ref);
+ }
+ }
+
+ for (const hint of evidence?.release_note_guidance?.source_ref_category_hints || []) {
+ const refs = normalizeSourceRefs(hint.source_refs);
+ const category = normalizeReleaseCategory(hint.category);
+ if (refs.length === 0 || !category) continue;
+ const groupKey = refs[0];
+ for (const ref of refs) {
+ knownRefs.add(ref);
+ refToGroup.set(ref, groupKey);
+ }
+ groups.set(groupKey, {
+ key: groupKey,
+ category,
+ refs,
+ subject: String(hint.subject || ""),
+ reason: String(hint.reason || ""),
+ });
+ }
+
+ return { refToGroup, groups, knownRefs, excludedRefs };
+}
+
+function groupKeyForRef(ref, refToGroup) {
+ return refToGroup.get(ref) || ref;
+}
+
+function groupKeysForItem(item, refToGroup) {
+ const keys = [];
+ for (const ref of item.source_refs || []) {
+ const key = groupKeyForRef(ref, refToGroup);
+ if (!keys.includes(key)) keys.push(key);
+ }
+ return keys;
+}
+
+function subjectsForItem(item, index) {
+ return groupKeysForItem(item, index.refToGroup)
+ .map((key) => index.groups.get(key)?.subject || "")
+ .filter(Boolean)
+ .join(" ");
+}
+
+function evidenceTextForItem(item, index) {
+ return `${subjectsForItem(item, index)}\n${item.text_cn || ""}\n${item.text_en || ""}`;
+}
+
+function knownReleaseItemsForItem(item, index, { allowSplit = true } = {}) {
+ if (allowSplit && item.source_refs.length > 1) {
+ const splitItems = item.source_refs.flatMap((ref) =>
+ knownReleaseItemsForItem({ ...item, source_refs: [ref] }, index, { allowSplit: false }),
+ );
+ const changedByEvidence = splitItems.some(
+ (split) =>
+ split.category !== item.category ||
+ split.text_cn !== item.text_cn ||
+ split.text_en !== item.text_en,
+ );
+ if (changedByEvidence) return dedupeReleaseItems(splitItems);
+ }
+
+ const subjectBlob = subjectsForItem(item, index).toLowerCase();
+ const blob = evidenceTextForItem(item, index).toLowerCase();
+ const refs = [...item.source_refs];
+ const rewrite = (category, textCn, textEn) => ({
+ ...item,
+ category,
+ text_cn: textCn,
+ text_en: textEn,
+ source_refs: refs,
+ });
+
+ const semverPattern = /semver|prerelease|previous tag|compare release tags|beta\.10|beta\.20|update checker|check-update/;
+ const configUpdatePattern = /config ui update check|update check|version status|host-specific update|restart command|copy.*restart/;
+ const memorySourcePattern = /memos_source|memory source|platform|windows|macos|linux|darwin/;
+ const hookPattern = /activation hooks|capability declaration|hook policy|before_prompt_build|recall hook|add memory hook|hook registration/;
+ const recallFilterPattern = /recall filter|payload sanit|query strip|prompt sanit|memory pollution/;
+ const toolMemoryPattern = /tool memory|tool_memories|assistant\.tool_calls|toolresult/;
+ const memoryFilteringPattern = /buildmemorysections|memory section handling|filtering logic|relevance-threshold|relevance threshold/;
+ const systemNotePattern = /system note|leading system notes|interruption notes/;
+ const systemEventSkipPattern = /implement system event detection|skip processing for heartbeat|heartbeat and command events|heartbeat polls|system commands/;
+ const systemEventRefactorPattern = /refactor system event detection|extend system command detection|system-command detection|internal prompt patterns/;
+ const telemetryPattern = /telemetry credentials|memos_arms|arms|rum|observability|generate telemetry credentials/;
+ const systemPromptPattern =
+ /system prompt detection and handling|scheduled task|scheduled reminder|background command|system event|isforcedsystemmessage|system prompt/;
+
+ if (/recall hook registration.*before_prompt_build|before_prompt_build.*newer openclaw|version compatibility/.test(subjectBlob)) {
+ return [
+ rewrite(
+ "Added",
+ "**Recall Hook 兼容新版 OpenClaw**:当宿主版本支持阶段化 Hook 时,召回逻辑自动迁移至 `before_prompt_build`,旧版宿主继续兼容 `before_agent_start`。",
+ "**Recall Hook compatibility for modern OpenClaw hosts**: Moves recall logic to `before_prompt_build` on hosts that support phased hooks while keeping `before_agent_start` compatibility for legacy hosts.",
+ ),
+ ];
+ }
+
+ if (systemEventSkipPattern.test(subjectBlob)) {
+ return [
+ rewrite(
+ "Added",
+ "**系统事件自动跳过**:召回与写入阶段自动识别并跳过心跳探测、系统命令等系统事件,保持记忆数据纯净。",
+ "**Automatic system-event skipping**: Detects and skips heartbeat polls, system commands, and other system events during recall and write phases to keep memory records clean.",
+ ),
+ ];
+ }
+
+ if (toolMemoryPattern.test(subjectBlob)) {
+ const items = [
+ rewrite(
+ "Added",
+ "**工具记忆全链路支持**:召回阶段注入 ``,写入阶段支持 `assistant.tool_calls` 与 `toolResult` 消息转换,统一写入 MemOS 标准消息结构。",
+ "**End-to-end Tool Memory support**: Injects `` during recall and converts `assistant.tool_calls` plus `toolResult` messages into the standard MemOS message structure during write.",
+ ),
+ ];
+ if (memoryFilteringPattern.test(subjectBlob)) {
+ items.push(
+ rewrite(
+ "Improved",
+ "**记忆过滤逻辑精简**:整合记忆片段构建中的重复过滤判断,降低无关内容进入上下文的概率。",
+ "**Memory filtering cleanup**: Consolidates duplicated filtering logic while building memory sections to reduce irrelevant context injection.",
+ ),
+ );
+ }
+ return items;
+ }
+
+ if (systemNotePattern.test(subjectBlob)) {
+ return [
+ rewrite(
+ "Added",
+ "**System Note 前缀自动剥离**:自动剔除上轮 Agent 中断提示词,提升召回查询与入库数据准确性。",
+ "**System Note prefix stripping**: Removes previous-run interruption notes to improve recall queries and stored-memory accuracy.",
+ ),
+ ];
+ }
+
+ if (/extend system command detection|include 'clear' command|internal prompt patterns/.test(subjectBlob)) {
+ return [
+ rewrite(
+ "Improved",
+ "**内部提示识别增强**:扩展 `clear` 命令和内部提示模式识别,减少系统命令类内容进入记忆流程。",
+ "**Internal prompt detection**: Extends `clear` command and internal prompt pattern detection to keep system-command content out of the memory flow.",
+ ),
+ ];
+ }
+
+ if (systemEventRefactorPattern.test(subjectBlob)) {
+ return [
+ rewrite(
+ "Improved",
+ "**系统事件检测重构**:提取心跳、系统命令和内部提示识别逻辑,并降低正常用户消息误判概率。",
+ "**System-event detection refactor**: Extracts heartbeat, system-command, and internal-prompt detection helpers to reduce false positives on normal user messages.",
+ ),
+ ];
+ }
+
+ const subjectFirstRules = [
+ [semverPattern, () => [
+ rewrite(
+ "Fixed",
+ "**版本比较边界修复**:使用标准 SemVer precedence 选择上一版本并检测更新,避免 beta.10、beta.20 等预发布版本被错误排序。",
+ "**Version comparison boundaries**: Uses SemVer precedence for previous-tag selection and update checks so beta.10, beta.20, and similar prereleases sort correctly.",
+ ),
+ ]],
+ [configUpdatePattern, () => [
+ rewrite(
+ "Improved",
+ "**配置页新增更新检查**:可查看版本状态,并复制对应宿主的更新重启命令。",
+ "**Update checks in settings**: Shows version status and lets users copy host-specific update or restart commands.",
+ ),
+ ]],
+ [memorySourcePattern, () => [
+ rewrite(
+ "Added",
+ "**跨平台记忆来源识别**:自动区分 Windows、macOS、Linux 的记忆数据。",
+ "**Platform-aware memory source labeling**: Distinguishes Windows, macOS, and Linux memory data automatically.",
+ ),
+ ]],
+ ];
+
+ for (const [pattern, buildItems] of subjectFirstRules) {
+ if (pattern.test(subjectBlob)) return buildItems();
+ }
+
+ if (hookPattern.test(subjectBlob)) {
+ if (/before_prompt_build|hook registration|registration/.test(subjectBlob)) {
+ return [
+ rewrite(
+ "Fixed",
+ "**Hook 注册兼容性修复**:在支持的 OpenClaw 宿主上正确注册回忆 hook,避免提示构建阶段缺失记忆召回。",
+ "**Hook registration compatibility**: Registers recall hooks correctly on supported OpenClaw hosts so memory recall is available during prompt construction.",
+ ),
+ ];
+ }
+ return [
+ rewrite(
+ "Added",
+ "**插件 Hook 能力声明**:补充插件激活与记忆相关 hook 声明,让宿主能够按权限策略启用云端记忆能力。",
+ "**Plugin hook capability declarations**: Adds activation and memory hook declarations so hosts can enable cloud memory through the permission policy.",
+ ),
+ ];
+ }
+
+ if (recallFilterPattern.test(subjectBlob)) {
+ return [
+ rewrite(
+ "Improved",
+ "**召回过滤与提示清洗优化**:增强召回请求和提示内容清洗,降低系统消息或无关参数进入记忆流程的概率。",
+ "**Recall filtering and prompt sanitization**: Improves recall-request and prompt cleanup to reduce system-message or irrelevant-parameter leakage into memory flows.",
+ ),
+ ];
+ }
+
+ if (telemetryPattern.test(subjectBlob)) {
+ return [
+ rewrite(
+ "Improved",
+ "**遥测凭据打包校验**:发布前校验遥测凭据生成状态,避免半配置密钥导致观测能力缺失或包内容不完整。",
+ "**Telemetry credential packaging**: Validates telemetry credential generation before release to avoid partial secret configuration and incomplete observability packaging.",
+ ),
+ ];
+ }
+
+ if (systemPromptPattern.test(subjectBlob) || systemPromptPattern.test(blob)) {
+ const items = [];
+ if (
+ /system prompt detection and handling|scheduled task|scheduled reminder|background command|system event|isforcedsystemmessage/.test(
+ blob,
+ )
+ ) {
+ items.push(
+ rewrite(
+ "Improved",
+ "**系统事件过滤增强**:自动跳过定时任务、计划提醒和后台命令结果,减少记忆污染。",
+ "**System-event filtering**: Skips scheduled tasks, reminders, and background command results to keep memory cleaner.",
+ ),
+ );
+ }
+ if (/system prompt detection and handling|system prompt|single-line|flattened|false positive|prompt detection/.test(blob)) {
+ items.push(
+ rewrite(
+ "Improved",
+ "**系统提示识别优化**:兼容单行压缩内容并降低普通消息误判概率。",
+ "**System prompt detection**: Supports flattened single-line prompts and reduces false positives on regular messages.",
+ ),
+ );
+ }
+ if (items.length > 0) return items;
+ }
+
+ if (semverPattern.test(blob)) {
+ return [
+ rewrite(
+ "Fixed",
+ "**版本比较边界修复**:使用标准 SemVer precedence 选择上一版本并检测更新,避免 beta.10、beta.20 等预发布版本被错误排序。",
+ "**Version comparison boundaries**: Uses SemVer precedence for previous-tag selection and update checks so beta.10, beta.20, and similar prereleases sort correctly.",
+ ),
+ ];
+ }
+
+ if (configUpdatePattern.test(blob)) {
+ return [
+ rewrite(
+ "Improved",
+ "**配置页新增更新检查**:可查看版本状态,并复制对应宿主的更新重启命令。",
+ "**Update checks in settings**: Shows version status and lets users copy host-specific update or restart commands.",
+ ),
+ ];
+ }
+
+ if (memorySourcePattern.test(blob)) {
+ return [
+ rewrite(
+ "Added",
+ "**跨平台记忆来源识别**:自动区分 Windows、macOS、Linux 的记忆数据。",
+ "**Platform-aware memory source labeling**: Distinguishes Windows, macOS, and Linux memory data automatically.",
+ ),
+ ];
+ }
+
+ if (hookPattern.test(blob)) {
+ if (/before_prompt_build|hook registration|registration/.test(blob)) {
+ return [
+ rewrite(
+ "Fixed",
+ "**Hook 注册兼容性修复**:在支持的 OpenClaw 宿主上正确注册回忆 hook,避免提示构建阶段缺失记忆召回。",
+ "**Hook registration compatibility**: Registers recall hooks correctly on supported OpenClaw hosts so memory recall is available during prompt construction.",
+ ),
+ ];
+ }
+ return [
+ rewrite(
+ "Added",
+ "**插件 Hook 能力声明**:补充插件激活与记忆相关 hook 声明,让宿主能够按权限策略启用云端记忆能力。",
+ "**Plugin hook capability declarations**: Adds activation and memory hook declarations so hosts can enable cloud memory through the permission policy.",
+ ),
+ ];
+ }
+
+ if (recallFilterPattern.test(blob)) {
+ return [
+ rewrite(
+ "Improved",
+ "**召回过滤与提示清洗优化**:增强召回请求和提示内容清洗,降低系统消息或无关参数进入记忆流程的概率。",
+ "**Recall filtering and prompt sanitization**: Improves recall-request and prompt cleanup to reduce system-message or irrelevant-parameter leakage into memory flows.",
+ ),
+ ];
+ }
+
+ if (telemetryPattern.test(blob)) {
+ return [
+ rewrite(
+ "Improved",
+ "**遥测凭据打包校验**:发布前校验遥测凭据生成状态,避免半配置密钥导致观测能力缺失或包内容不完整。",
+ "**Telemetry credential packaging**: Validates telemetry credential generation before release to avoid partial secret configuration and incomplete observability packaging.",
+ ),
+ ];
+ }
+
+ return [item];
+}
+
+function expandKnownReleaseItems(items, index) {
+ let expandedKnownItems = 0;
+ const expanded = [];
+ for (const item of items) {
+ const knownItems = knownReleaseItemsForItem(item, index);
+ if (knownItems.length !== 1 || knownItems[0] !== item) {
+ expandedKnownItems += Math.max(1, knownItems.length);
+ }
+ expanded.push(...knownItems);
+ }
+ return {
+ items: dedupeReleaseItems(expanded),
+ expandedKnownItems,
+ };
+}
+
+function bestHintCategoryForItem(item, index) {
+ const categories = [];
+ for (const key of groupKeysForItem(item, index.refToGroup)) {
+ const category = index.groups.get(key)?.category;
+ if (category && !categories.includes(category)) categories.push(category);
+ }
+ if (categories.length === 1) return categories[0];
+ return "";
+}
+
+function scoreOwnerCandidate(item, group, sourceGroupCount, order) {
+ let score = 0;
+ if (item.category === group.category) score += 100;
+ if (sourceGroupCount === 1) score += 20;
+ score -= sourceGroupCount;
+ score -= order / 1000;
+ return score;
+}
+
+function dedupeSourceRefsByBestCategory(items, index) {
+ const candidatesByGroup = new Map();
+ for (const [order, item] of items.entries()) {
+ for (const groupKey of groupKeysForItem(item, index.refToGroup)) {
+ const group = index.groups.get(groupKey);
+ if (!group) continue;
+ const sourceGroupCount = groupKeysForItem(item, index.refToGroup).length;
+ const candidates = candidatesByGroup.get(groupKey) || [];
+ candidates.push({ item, order, sourceGroupCount });
+ candidatesByGroup.set(groupKey, candidates);
+ }
+ }
+
+ const ownerByGroup = new Map();
+ for (const [groupKey, candidates] of candidatesByGroup.entries()) {
+ const group = index.groups.get(groupKey);
+ if (!group) continue;
+ const sorted = [...candidates].sort((a, b) => {
+ const scoreDelta =
+ scoreOwnerCandidate(b.item, group, b.sourceGroupCount, b.order) -
+ scoreOwnerCandidate(a.item, group, a.sourceGroupCount, a.order);
+ return scoreDelta || a.order - b.order;
+ });
+ ownerByGroup.set(groupKey, sorted[0].item);
+ }
+
+ let removedDuplicateRefs = 0;
+ let droppedItems = 0;
+ const filtered = [];
+ for (const item of items) {
+ const refs = [];
+ for (const ref of item.source_refs) {
+ const groupKey = groupKeyForRef(ref, index.refToGroup);
+ const owner = ownerByGroup.get(groupKey);
+ if (!owner || owner === item) {
+ const canonicalRef =
+ /^[a-f0-9]{40}$/i.test(ref) && /^[a-f0-9]{7,12}$/i.test(groupKey)
+ ? groupKey
+ : ref;
+ if (!refs.includes(canonicalRef)) {
+ refs.push(canonicalRef);
+ } else {
+ removedDuplicateRefs += 1;
+ }
+ } else {
+ removedDuplicateRefs += 1;
+ }
+ }
+ if (refs.length === 0) {
+ droppedItems += 1;
+ continue;
+ }
+ filtered.push({ ...item, source_refs: refs });
+ }
+ return { items: filtered, removedDuplicateRefs, droppedItems };
+}
+
+function removeReleaseNoiseRefs(items, index) {
+ let removedNoiseRefs = 0;
+ let droppedNoiseItems = 0;
+ const filtered = [];
+ for (const item of items) {
+ const refs = item.source_refs.filter((ref) => {
+ if (!index.excludedRefs.has(ref)) return true;
+ removedNoiseRefs += 1;
+ return false;
+ });
+ if (refs.length === 0) {
+ droppedNoiseItems += 1;
+ continue;
+ }
+ filtered.push({ ...item, source_refs: refs });
+ }
+ return { items: filtered, removedNoiseRefs, droppedNoiseItems };
+}
+
+function dedupeReleaseItems(items) {
+ const byKey = new Map();
+ for (const item of items) {
+ const key = `${item.category}\n${item.text_cn}\n${item.text_en}`;
+ const existing = byKey.get(key);
+ if (!existing) {
+ byKey.set(key, { ...item, source_refs: [...item.source_refs] });
+ continue;
+ }
+ for (const ref of item.source_refs) {
+ if (!existing.source_refs.includes(ref)) existing.source_refs.push(ref);
+ }
+ }
+ return [...byKey.values()];
+}
+
+function categoriesFromReleaseItems(items) {
+ const releaseCategories = {};
+ const docsCategories = { cn: {}, en: {} };
+ for (const category of RELEASE_CATEGORY_ORDER) {
+ const categoryItems = items.filter((item) => item.category === category);
+ if (categoryItems.length === 0) continue;
+ releaseCategories[category] = categoryItems.map((item) => item.text_cn);
+ const docCategory = RELEASE_TO_DOC_CATEGORY[category];
+ docsCategories.cn[docCategory] = categoryItems.map((item) => item.text_cn);
+ docsCategories.en[docCategory] = categoryItems.map((item) => item.text_en);
+ }
+ return { releaseCategories, docsCategories };
+}
+
+function coverageFromReleaseItems(evidence, draft, items, index) {
+ const coveredRefs = [];
+ const coveredGroups = new Set();
+ const invalidItemRefs = [];
+ for (const item of items) {
+ for (const ref of item.source_refs || []) {
+ if (!coveredRefs.includes(ref)) coveredRefs.push(ref);
+ const groupKey = groupKeyForRef(ref, index.refToGroup);
+ if (index.groups.has(groupKey)) coveredGroups.add(groupKey);
+ if (index.knownRefs.size > 0 && !index.knownRefs.has(ref)) {
+ invalidItemRefs.push({
+ ref,
+ text_cn: item.text_cn,
+ category: item.category,
+ });
+ }
+ }
+ }
+
+ const required = [...index.groups.values()];
+ const missingRequired = required
+ .filter((group) => !coveredGroups.has(group.key))
+ .map((group) => ({
+ short_sha: group.refs.find((ref) => /^[a-f0-9]{7,40}$/.test(ref)) || "",
+ subject: group.subject,
+ refs: group.refs,
+ reason: group.reason || "important cloud plugin release source",
+ }));
+ const previousCoverage = draft.coverage || {};
+ const requiredCount = required.length || Number(previousCoverage.required_count || 0);
+ const missingRequiredCount = required.length
+ ? missingRequired.length
+ : Number(previousCoverage.missing_required_count || 0);
+ const coveredRequiredCount = required.length
+ ? required.length - missingRequired.length
+ : Number(previousCoverage.covered_required_count || 0);
+ const needsReview = missingRequiredCount > 0 || invalidItemRefs.length > 0 || items.length === 0;
+
+ return {
+ ...previousCoverage,
+ needs_review: needsReview,
+ required_count: requiredCount,
+ covered_required_count: coveredRequiredCount,
+ missing_required_count: missingRequiredCount,
+ missing_required: missingRequired,
+ invalid_item_refs: invalidItemRefs,
+ covered_refs: coveredRefs.sort(),
+ policy:
+ previousCoverage.policy ||
+ "important feat/fix/perf/refactor commits must be referenced by at least one bullet source_ref",
+ };
+}
+
+function languageIssuesFromReleaseItems(items) {
+ const issues = [];
+ for (const [index, item] of items.entries()) {
+ if (!CJK_RE.test(item.text_cn || "")) {
+ issues.push({
+ index,
+ category: item.category,
+ field: "text_cn",
+ current_text: item.text_cn || "",
+ reason: "Chinese release-note text must contain CJK characters.",
+ });
+ }
+ if (CJK_RE.test(item.text_en || "")) {
+ issues.push({
+ index,
+ category: item.category,
+ field: "text_en",
+ current_text: item.text_en || "",
+ reason: "English release-note text must not contain Chinese/CJK characters.",
+ });
+ }
+ }
+ return issues;
+}
+
+function readabilityIssuesFromReleaseItems(items) {
+ const issues = [];
+ if (items.length > MAX_RELEASE_ITEMS) {
+ issues.push({
+ field: "release_items",
+ item_count: items.length,
+ max_item_count: MAX_RELEASE_ITEMS,
+ reason: "Plugin changelog output must be grouped into concise product-facing bullets.",
+ });
+ }
+ for (const [index, item] of items.entries()) {
+ if (item.text_cn && item.text_cn.length > MAX_TEXT_CN_CHARS) {
+ issues.push({
+ index,
+ category: item.category,
+ field: "text_cn",
+ current_text: item.text_cn,
+ current_length: item.text_cn.length,
+ max_length: MAX_TEXT_CN_CHARS,
+ reason: "Chinese release-note text is too long for the Plugin tab.",
+ });
+ }
+ if (item.text_en && item.text_en.length > MAX_TEXT_EN_CHARS) {
+ issues.push({
+ index,
+ category: item.category,
+ field: "text_en",
+ current_text: item.text_en,
+ current_length: item.text_en.length,
+ max_length: MAX_TEXT_EN_CHARS,
+ reason: "English release-note text is too long for the Plugin tab.",
+ });
+ }
+ }
+ return issues;
+}
+
+function summarizeCoverageForValidation(coverage) {
+ const value = coverage || {};
+ return {
+ needs_review: Boolean(value.needs_review),
+ required_count: Number(value.required_count || 0),
+ covered_required_count: Number(value.covered_required_count || 0),
+ missing_required_count: Number(value.missing_required_count || 0),
+ missing_required: Array.isArray(value.missing_required) ? value.missing_required : [],
+ invalid_item_refs: Array.isArray(value.invalid_item_refs) ? value.invalid_item_refs : [],
+ };
+}
+
+function validationReportFromPostprocessedDraft(draft) {
+ const coverage = summarizeCoverageForValidation(draft?.coverage);
+ const releaseItems = Array.isArray(draft?.release_items) ? draft.release_items : [];
+ const languageIssues = languageIssuesFromReleaseItems(releaseItems);
+ const readabilityIssues = readabilityIssuesFromReleaseItems(releaseItems);
+ const issues = [];
+ for (const [index, item] of releaseItems.entries()) {
+ const category = normalizeReleaseCategory(item?.category);
+ const textCn = String(item?.text_cn || "").trim();
+ const textEn = String(item?.text_en || "").trim();
+ const sourceRefs = normalizeSourceRefs(item?.source_refs);
+ if (!category || !textCn || !textEn) {
+ issues.push({
+ kind: "invalid_release_item",
+ index,
+ reason: "release item requires category, text_cn, text_en, and source_refs",
+ });
+ } else if (sourceRefs.length === 0) {
+ issues.push({
+ kind: "missing_source_refs",
+ index,
+ category,
+ reason: "release item must cite at least one real source_ref",
+ });
+ }
+ }
+ for (const issue of languageIssues) {
+ issues.push({
+ kind: "language",
+ index: issue.index,
+ category: issue.category,
+ field: issue.field,
+ current_text: issue.current_text || "",
+ reason: issue.reason,
+ });
+ }
+ for (const issue of readabilityIssues) {
+ issues.push({
+ kind: "readability",
+ index: issue.index,
+ category: issue.category,
+ field: issue.field,
+ current_text: issue.current_text || "",
+ current_length: issue.current_length,
+ max_length: issue.max_length,
+ item_count: issue.item_count,
+ max_item_count: issue.max_item_count,
+ reason: issue.reason,
+ });
+ }
+ for (const item of coverage.missing_required) {
+ issues.push({
+ kind: "missing_required_source",
+ refs: Array.isArray(item.refs) ? item.refs : [],
+ short_sha: item.short_sha || "",
+ subject: item.subject || "",
+ reason: item.reason || "important cloud plugin release source",
+ });
+ }
+ for (const item of coverage.invalid_item_refs) {
+ issues.push({
+ kind: "invalid_source_ref",
+ ref: item.ref || "",
+ category: item.category || "",
+ text_cn: item.text_cn || "",
+ reason: "release note cites a source_ref that is not present in evidence",
+ });
+ }
+ if (!Array.isArray(draft?.release_items) || draft.release_items.length === 0) {
+ issues.push({
+ kind: "empty_release_items",
+ reason: "release_items must contain at least one evidence-backed item",
+ });
+ }
+
+ const repairableKinds = new Set([
+ "language",
+ "readability",
+ "missing_source_refs",
+ "missing_required_source",
+ "invalid_source_ref",
+ ]);
+ const repairable =
+ issues.length > 0 &&
+ issues.every((issue) => repairableKinds.has(issue.kind)) &&
+ Array.isArray(draft?.release_items) &&
+ draft.release_items.length > 0;
+
+ return {
+ ok: Boolean(draft?.ok) && !draft?.needs_review && issues.length === 0,
+ needs_review: Boolean(draft?.needs_review),
+ repairable,
+ item_count: Array.isArray(draft?.release_items) ? draft.release_items.length : 0,
+ limits: RELEASE_NOTE_LIMITS,
+ issue_count: issues.length,
+ language_issue_count: languageIssues.length,
+ structure_issue_count: issues.filter((issue) =>
+ ["empty_release_items", "invalid_release_item", "missing_source_refs"].includes(issue.kind),
+ ).length,
+ readability_issue_count: readabilityIssues.length,
+ invalid_item_ref_count: coverage.invalid_item_refs.length,
+ missing_required_count: coverage.missing_required_count,
+ issues,
+ coverage,
+ postprocess: draft?.postprocess || {},
+ };
+}
+
+function repairContextFromValidation({ draft, validationReport, repairAttempt, maxRepairAttempts }) {
+ return {
+ schema: "memos.plugin.release_notes.repair.v1",
+ repair_attempt: repairAttempt,
+ max_repair_attempts: maxRepairAttempts,
+ validation_report: validationReport,
+ previous_release_items: (draft.release_items || []).map((item, index) => ({
+ index,
+ category: item.category,
+ text_cn: item.text_cn,
+ text_en: item.text_en,
+ source_refs: item.source_refs,
+ })),
+ instructions: [
+ "Repair only the issues listed in validation_report. Do not rewrite already valid release-note facts.",
+ "For language issues, edit only the affected text_cn/text_en field: text_cn must contain Chinese, text_en must contain no Chinese/CJK characters.",
+ "Treat text_cn as the canonical wording first; text_en must be a faithful translation of text_cn, not an independently invented summary.",
+ "Keep existing valid category and source_refs unchanged. Do not add source_refs that are not present in the evidence.",
+ "For missing_source_refs issues, attach one or more semantically matching refs from the evidence.",
+ "For missing_required_source issues, add a concise product-facing item or attach the listed refs to a semantically matching existing item, using only the listed evidence.",
+ "For invalid_source_ref issues, replace fabricated refs with matching refs from the evidence; never invent a SHA or PR number.",
+ "For readability issues, group fragmented items and shorten only the flagged text while preserving facts and valid source_refs.",
+ "When several valid repairs are possible, privately compare alternatives and return the candidate with the best evidence coverage, bilingual quality, and docs-preview readability.",
+ "Return the same release_items schema with category, text_cn, text_en, and source_refs.",
+ ],
+ };
+}
+
+function validationAttemptRecord({ stage, repairAttempt, draft, validationReport }) {
+ return {
+ stage,
+ repair_attempt: repairAttempt,
+ ok: validationReport.ok,
+ needs_review: validationReport.needs_review,
+ repairable: validationReport.repairable,
+ issue_count: validationReport.issue_count,
+ language_issue_count: validationReport.language_issue_count,
+ readability_issue_count: validationReport.readability_issue_count,
+ missing_required_count: validationReport.missing_required_count,
+ invalid_item_ref_count: validationReport.invalid_item_ref_count,
+ coverage: validationReport.coverage,
+ issues: validationReport.issues,
+ postprocess: draft.postprocess || {},
+ };
+}
+
+function cloneReleaseItems(draft) {
+ return (Array.isArray(draft?.release_items) ? draft.release_items : []).map((item) => ({
+ ...item,
+ source_refs: Array.isArray(item?.source_refs) ? [...item.source_refs] : [],
+ }));
+}
+
+function injectRawFaultCase(draft, evidence, faultCase) {
+ const items = cloneReleaseItems(draft);
+ if (items.length === 0) return draft;
+
+ if (faultCase === "missing_source_refs") {
+ items[0].source_refs = [];
+ } else if (faultCase === "invalid_source_ref") {
+ items[0].source_refs = ["deadbeef"];
+ } else if (faultCase === "missing_important_commit") {
+ const refsToRemove = new Set(
+ evidence?.release_note_guidance?.source_ref_category_hints?.[0]?.source_refs || [],
+ );
+ for (const item of items) {
+ item.source_refs = item.source_refs.filter((ref) => !refsToRemove.has(ref));
+ }
+ } else {
+ return draft;
+ }
+ return { ...draft, release_items: items };
+}
+
+function injectPostprocessedFaultCase(draft, faultCase) {
+ const items = cloneReleaseItems(draft);
+ if (items.length === 0) return draft;
+
+ if (faultCase === "mixed_language") {
+ items[0].text_en = `${items[0].text_en} 中文残留`;
+ } else if (faultCase === "thirteen_items") {
+ const seed = items[0];
+ while (items.length < RELEASE_NOTE_LIMITS.max_items + 1) {
+ const number = items.length + 1;
+ items.push({
+ ...seed,
+ text_cn: `${seed.text_cn}(故障注入条目 ${number})`,
+ text_en: `${seed.text_en} (fault-injection item ${number})`,
+ source_refs: [...seed.source_refs],
+ });
+ }
+ } else if (faultCase === "too_long") {
+ items[0].text_cn =
+ `${items[0].text_cn}${"长".repeat(RELEASE_NOTE_LIMITS.max_text_cn_characters)}`;
+ items[0].text_en =
+ `${items[0].text_en} ${"long ".repeat(RELEASE_NOTE_LIMITS.max_text_en_characters)}`;
+ } else {
+ return draft;
+ }
+ return { ...draft, release_items: items };
+}
+
+export function injectReleaseFaultCase(draft, evidence, faultCase, { phase = "raw" } = {}) {
+ const value = String(faultCase || "none").trim() || "none";
+ if (!RELEASE_FAULT_CASES.includes(value)) {
+ fail(`Unknown release fault case: ${value}`);
+ }
+ if (value === "none" || value === "manual_notes_missing_payload") return draft;
+ return phase === "postprocess"
+ ? injectPostprocessedFaultCase(draft, value)
+ : injectRawFaultCase(draft, evidence, value);
+}
+
+export async function requestValidatedDraft(
+ evidence,
+ {
+ requestImpl = requestDraft,
+ maxRepairAttempts = MAX_DRAFT_REPAIR_ATTEMPTS,
+ faultCase = process.env.RELEASE_FAULT_CASE || "none",
+ } = {},
+) {
+ let rawDraft = await requestImpl(evidence);
+ const attempts = [];
+ let finalDraft = null;
+
+ for (let repairAttempt = 0; repairAttempt <= maxRepairAttempts; repairAttempt += 1) {
+ const stage = repairAttempt === 0 ? "draft" : "repair";
+ const injectedRaw =
+ repairAttempt === 0
+ ? injectReleaseFaultCase(rawDraft, evidence, faultCase, { phase: "raw" })
+ : rawDraft;
+ let postprocessed = postprocessDraftFromEvidence(injectedRaw, evidence);
+ if (repairAttempt === 0) {
+ postprocessed = injectReleaseFaultCase(postprocessed, evidence, faultCase, {
+ phase: "postprocess",
+ });
+ }
+ const validationReport = validationReportFromPostprocessedDraft(postprocessed);
+ attempts.push(validationAttemptRecord({ stage, repairAttempt, draft: postprocessed, validationReport }));
+
+ finalDraft = {
+ ...postprocessed,
+ validation_report: validationReport,
+ repair_attempts: attempts,
+ validation_attempt_count: attempts.length,
+ repair_attempt_count: Math.max(0, attempts.length - 1),
+ };
+
+ if (validationReport.ok) {
+ return finalDraft;
+ }
+ if (!validationReport.repairable || repairAttempt >= maxRepairAttempts) {
+ return finalDraft;
+ }
+
+ const stageLabel =
+ repairAttempt === 0 ? "initial draft validation" : `repair validation attempt ${repairAttempt}`;
+ warn(
+ `Release notes validation failed after ${stageLabel}; requesting draft repair ` +
+ `${repairAttempt + 1}/${maxRepairAttempts}: ${validationReport.issues
+ .map((issue) => issue.kind)
+ .join(", ")}`,
+ );
+ rawDraft = await requestImpl({
+ ...evidence,
+ release_notes_repair_context: repairContextFromValidation({
+ draft: finalDraft,
+ validationReport,
+ repairAttempt: repairAttempt + 1,
+ maxRepairAttempts,
+ }),
+ });
+ }
+
+ return finalDraft;
+}
+
+export function qualityReportFromDraft(
+ draft,
+ { targetVersion = "", previousTag = "", currentTag = "", currentRef = "", faultCase = "none" } = {},
+) {
+ const validationReport =
+ draft?.validation_report || validationReportFromPostprocessedDraft(draft || {});
+ return {
+ schema: "memos.plugin.release_notes.quality_report.v1",
+ product_id: PRODUCT_ID,
+ repo: REPOSITORY,
+ target_version: displayVersion(targetVersion),
+ previous_tag: previousTag,
+ current_tag: currentTag,
+ current_ref: currentRef,
+ fault_case: faultCase || "none",
+ ok: Boolean(validationReport.ok),
+ needs_review: Boolean(validationReport.needs_review),
+ limits: RELEASE_NOTE_LIMITS,
+ item_count: Number(validationReport.item_count || draft?.release_items?.length || 0),
+ issue_count: Number(validationReport.issue_count || 0),
+ language_issue_count: Number(validationReport.language_issue_count || 0),
+ structure_issue_count: Number(validationReport.structure_issue_count || 0),
+ readability_issue_count: Number(validationReport.readability_issue_count || 0),
+ invalid_item_ref_count: Number(validationReport.invalid_item_ref_count || 0),
+ missing_required_count: Number(validationReport.missing_required_count || 0),
+ coverage: validationReport.coverage || summarizeCoverageForValidation(draft?.coverage),
+ issues: Array.isArray(validationReport.issues) ? validationReport.issues : [],
+ validation_attempt_count: Number(draft?.validation_attempt_count || 0),
+ repair_attempt_count: Number(draft?.repair_attempt_count || 0),
+ attempts: Array.isArray(draft?.repair_attempts) ? draft.repair_attempts : [],
+ };
+}
+
+function embeddedReleaseNotesPayload(items, coverage) {
+ return {
+ schema: "memos.plugin.release_notes.v1",
+ items: items.map((item) => ({
+ category: item.category,
+ text_cn: item.text_cn,
+ text_en: item.text_en,
+ source_refs: item.source_refs,
+ })),
+ coverage: {
+ needs_review: Boolean(coverage.needs_review),
+ required_count: Number(coverage.required_count || 0),
+ covered_required_count: Number(coverage.covered_required_count || 0),
+ missing_required_count: Number(coverage.missing_required_count || 0),
+ },
+ };
+}
+
+function markdownFromReleaseItems(items, coverage) {
+ const lines = ["## Changelog"];
+ for (const category of RELEASE_CATEGORY_ORDER) {
+ const categoryItems = items.filter((item) => item.category === category);
+ if (categoryItems.length === 0) continue;
+ lines.push("");
+ lines.push(`### ${category}`);
+ for (const item of categoryItems) {
+ lines.push(`- ${item.text_cn}`);
+ }
+ }
+ lines.push("");
+ lines.push(`");
+ return `${lines.join("\n").trim()}\n`;
+}
+
+export function postprocessDraftFromEvidence(draft, evidence) {
+ const inputItems = Array.isArray(draft?.release_items)
+ ? draft.release_items.map(normalizeReleaseItem).filter(Boolean)
+ : [];
+ if (inputItems.length === 0) return draft;
+
+ const index = buildSourceRefIndex(evidence);
+ const noiseFiltered = removeReleaseNoiseRefs(inputItems, index);
+ let reclassifiedItems = 0;
+ let items = noiseFiltered.items.map((item) => {
+ const hintedCategory = bestHintCategoryForItem(item, index);
+ const category = hintedCategory || item.category;
+ if (category !== item.category) reclassifiedItems += 1;
+ return { ...item, category };
+ });
+
+ const deduped = dedupeSourceRefsByBestCategory(items, index);
+ items = dedupeReleaseItems(
+ deduped.items.map((item) => {
+ const hintedCategory = bestHintCategoryForItem(item, index);
+ const category = hintedCategory || item.category;
+ if (category !== item.category) reclassifiedItems += 1;
+ return { ...item, category };
+ }),
+ );
+ const expanded = expandKnownReleaseItems(items, index);
+ items = expanded.items;
+
+ const coverage = coverageFromReleaseItems(evidence, draft, items, index);
+ const languageIssues = languageIssuesFromReleaseItems(items);
+ const readabilityIssues = readabilityIssuesFromReleaseItems(items);
+ if (languageIssues.length > 0 || readabilityIssues.length > 0) {
+ coverage.needs_review = true;
+ }
+ const { releaseCategories, docsCategories } = categoriesFromReleaseItems(items);
+ const postprocess = {
+ applied: true,
+ removed_duplicate_source_refs: deduped.removedDuplicateRefs,
+ dropped_empty_source_items: deduped.droppedItems,
+ removed_release_noise_refs: noiseFiltered.removedNoiseRefs,
+ dropped_release_noise_items: noiseFiltered.droppedNoiseItems,
+ reclassified_items: reclassifiedItems,
+ expanded_known_items: expanded.expandedKnownItems,
+ final_item_count: items.length,
+ };
+ const warnings = Array.isArray(draft.warnings) ? [...draft.warnings] : [];
+ if (
+ postprocess.removed_duplicate_source_refs > 0 ||
+ postprocess.dropped_empty_source_items > 0 ||
+ postprocess.removed_release_noise_refs > 0 ||
+ postprocess.dropped_release_noise_items > 0 ||
+ postprocess.reclassified_items > 0 ||
+ postprocess.expanded_known_items > 0
+ ) {
+ warnings.push("release notes were postprocessed to dedupe source_refs, apply evidence category hints, and normalize known cloud plugin topics");
+ }
+ if (languageIssues.length > 0) {
+ warnings.push("release notes language validation failed; manual review is required");
+ }
+ if (readabilityIssues.length > 0) {
+ warnings.push("release notes readability validation failed; the Plugin tab draft must be repaired before publishing");
+ }
+
+ const result = {
+ ...draft,
+ ok: Boolean(items.length) && !coverage.needs_review,
+ needs_review: Boolean(coverage.needs_review),
+ release_items: items,
+ release_categories: releaseCategories,
+ docs_categories: docsCategories,
+ coverage,
+ warnings,
+ language_issues: languageIssues,
+ readability_issues: readabilityIssues,
+ postprocess,
+ release_notes_markdown: markdownFromReleaseItems(items, coverage),
+ };
+ return {
+ ...result,
+ validation_report: validationReportFromPostprocessedDraft(result),
+ };
+}
+
+function previewDateFromPublishedAt(value) {
+ const text = String(value || "").trim();
+ if (!text) return "";
+ const date = new Date(text);
+ if (Number.isNaN(date.getTime())) return "";
+ return date.toISOString().slice(0, 10);
+}
+
+export function docsPreviewFromDraft(draft, { targetVersion, publishedAt = "" } = {}) {
+ const version = displayVersion(targetVersion || draft?.target_version || "");
+ const date = previewDateFromPublishedAt(publishedAt);
+ const docsCategories = draft?.docs_categories || { cn: {}, en: {} };
+ const buildEntry = (locale) => ({
+ name: version,
+ date,
+ products: {
+ plugin: Object.fromEntries(
+ Object.entries(docsCategories[locale] || {}).map(([category, items]) => [
+ category,
+ [
+ {
+ type: locale === "cn" ? PRODUCT_TITLE.zh : PRODUCT_TITLE.en,
+ changedInfo: items,
+ },
+ ],
+ ]),
+ ),
+ },
+ });
+ return {
+ schema: "memos.plugin.docs_preview.v1",
+ product_id: PRODUCT_ID,
+ repo: REPOSITORY,
+ version,
+ date,
+ date_source: publishedAt ? "provided published_at" : "GitHub Release published_at at publish time",
+ docs_files: {
+ cn: "content/cn/plugin-changelog.yml",
+ en: "content/en/plugin-changelog.yml",
+ },
+ entries: {
+ cn: buildEntry("cn"),
+ en: buildEntry("en"),
+ },
+ };
+}
+
+export function markdownFromDocsPreview(preview) {
+ const lines = [
+ "# MemOS-Docs Plugin Changelog Preview",
+ "",
+ `- product_id: ${preview.product_id}`,
+ `- version: ${preview.version}`,
+ `- date: ${preview.date}`,
+ `- zh file: ${preview.docs_files.cn}`,
+ `- en file: ${preview.docs_files.en}`,
+ ];
+ for (const [locale, title] of [
+ ["cn", "中文预览"],
+ ["en", "English Preview"],
+ ]) {
+ lines.push("");
+ lines.push(`## ${title}`);
+ const plugin = preview.entries[locale]?.products?.plugin || {};
+ const categories = Object.keys(plugin);
+ if (categories.length === 0) {
+ lines.push("");
+ lines.push("- No plugin changelog items would be rendered.");
+ continue;
+ }
+ for (const category of categories) {
+ lines.push("");
+ lines.push(`### ${category}`);
+ for (const group of plugin[category] || []) {
+ lines.push("");
+ lines.push(`- type: ${group.type}`);
+ for (const item of group.changedInfo || []) {
+ lines.push(` - ${item}`);
+ }
+ }
+ }
+ }
+ return `${lines.join("\n").trim()}\n`;
+}
+
+function releaseNotesPayloadFromMarkdown(text) {
+ const match = text.match(//);
+ if (!match) {
+ fail("Manual release notes must include the doc-agent-release-notes-json evidence block.");
+ }
+ try {
+ return JSON.parse(match[1]);
+ } catch {
+ fail("Manual release notes contain invalid doc-agent-release-notes-json.");
+ }
+}
+
+function draftFromReleaseNotesMarkdown(notes) {
+ const payload = releaseNotesPayloadFromMarkdown(notes);
+ const items = Array.isArray(payload?.items) ? payload.items.map(normalizeReleaseItem).filter(Boolean) : [];
+ const coverage = payload?.coverage || {};
+ const { releaseCategories, docsCategories } = categoriesFromReleaseItems(items);
+ return {
+ ok: items.length > 0 && coverage.needs_review === false,
+ needs_review: coverage.needs_review !== false,
+ confidence: "manual",
+ release_items: items,
+ release_categories: releaseCategories,
+ docs_categories: docsCategories,
+ coverage,
+ warnings: [],
+ language_issues: languageIssuesFromReleaseItems(items),
+ postprocess: {
+ applied: false,
+ source: "manual_release_notes",
+ final_item_count: items.length,
+ },
+ release_notes_markdown: notes,
+ };
+}
+
+export function validateManualNotes(notes) {
+ const text = String(notes || "").trim();
+ if (!/^## Changelog\s*$/m.test(text)) {
+ fail("Manual release notes must contain a '## Changelog' heading.");
+ }
+ const payload = releaseNotesPayloadFromMarkdown(text);
+ if (!Array.isArray(payload?.items) || payload.items.length === 0) {
+ fail("Manual release notes evidence block must contain non-empty items.");
+ }
+ if (payload?.coverage?.needs_review !== false) {
+ fail("Manual release notes evidence coverage must explicitly set needs_review=false.");
+ }
+ const normalizedItems = payload.items.map(normalizeReleaseItem);
+ if (normalizedItems.some((item) => !item)) {
+ fail("Every manual release-note item must include category, text_cn, text_en, and valid source_refs.");
+ }
+ for (const item of normalizedItems) {
+ if (!item?.text_cn || !item?.text_en || !Array.isArray(item?.source_refs) || item.source_refs.length === 0) {
+ fail("Every manual release-note item must include text_cn, text_en, and source_refs.");
+ }
+ if (!CJK_RE.test(String(item.text_cn || ""))) {
+ fail("Every manual release-note item text_cn must contain Chinese text.");
+ }
+ if (CJK_RE.test(String(item.text_en || ""))) {
+ fail("Every manual release-note item text_en must not contain Chinese/CJK characters.");
+ }
+ }
+ if (readabilityIssuesFromReleaseItems(normalizedItems).length > 0) {
+ fail("Manual release-note items must stay concise enough for the Plugin tab preview.");
+ }
+ return text;
+}
+
+function isRetryableStatus(status) {
+ return status === 408 || status === 425 || status === 429 || status >= 500;
+}
+
+function hasStructuredDraftItems(payload) {
+ return Array.isArray(payload?.release_items) && payload.release_items.map(normalizeReleaseItem).some(Boolean);
+}
+
+function cleanError(value) {
+ return String(value || "")
+ .replace(/Bearer\s+\S+/gi, "Bearer ***")
+ .replace(/sk-[A-Za-z0-9_-]+/g, "sk-***")
+ .replace(/\bgithub_pat_[A-Za-z0-9_]+\b/g, "github_pat_***")
+ .replace(/\bgh[pousr]_[A-Za-z0-9_]+\b/g, "gh_***")
+ .replace(/\bnpm_[A-Za-z0-9_]+\b/g, "npm_***")
+ .replace(/(_authToken\s*[=:]\s*)\S+/gi, "$1***")
+ .replace(/https?:\/\/[^\s"'<>]+/gi, "https://***")
+ .replace(/\b\d{1,3}(?:\.\d{1,3}){3}(?::\d+)?\b/g, "***")
+ .replace(/\s+/g, " ")
+ .slice(0, 600);
+}
+
+function requiredUrlFromEnv(name) {
+ const value = String(process.env[name] || "").trim();
+ if (!value) {
+ fail(`${name} secret is required when release_notes input is empty.`);
+ }
+ try {
+ const parsed = new URL(value);
+ if (!/^https?:$/.test(parsed.protocol)) fail(`${name} must be an HTTP(S) URL.`);
+ } catch {
+ fail(`${name} must be an HTTP(S) URL.`);
+ }
+ return value;
+}
+
+function optionalUrlFromEnv(name) {
+ const value = String(process.env[name] || "").trim();
+ if (!value) return "";
+ try {
+ const parsed = new URL(value);
+ if (!/^https?:$/.test(parsed.protocol)) fail(`${name} must be an HTTP(S) URL.`);
+ } catch {
+ fail(`${name} must be an HTTP(S) URL.`);
+ }
+ return value;
+}
+
+export async function reportFailure({ evidence, attempts, finalError, phase = "release-notes", fetchImpl = fetch }) {
+ if (attempts.length < 3) return { skipped: true, reason: "fewer than three attempts" };
+ const token = process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN || "";
+ if (!token.trim()) return { skipped: true, reason: "missing configured token" };
+ const url = optionalUrlFromEnv("DOC_AGENT_RELEASE_FAILURE_URL");
+ if (!url) return { skipped: true, reason: "missing configured failure URL" };
+ const response = await fetchImpl(url, {
+ method: "POST",
+ headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+ body: JSON.stringify({
+ product_id: PRODUCT_ID,
+ repository: evidence.repo,
+ version: evidence.target_version,
+ phase,
+ run_id: process.env.GITHUB_RUN_ID || `${evidence.current_tag}-cloud`,
+ run_url: process.env.GITHUB_RUN_ID
+ ? `https://github.com/${evidence.repo}/actions/runs/${process.env.GITHUB_RUN_ID}`
+ : "",
+ attempts: attempts.slice(0, 3).map((item, index) => ({
+ attempt: index + 1,
+ error_code: item.error_code || "DRAFT_FAILED",
+ message: cleanError(item.message),
+ retryable: Boolean(item.retryable),
+ })),
+ final_error: cleanError(finalError),
+ }),
+ });
+ if (!response.ok) {
+ throw new Error(`Failure-report endpoint returned HTTP ${response.status}`);
+ }
+ return response.json();
+}
+
+async function reportFailureBestEffort(args) {
+ try {
+ return await reportFailure(args);
+ } catch (error) {
+ const reason = cleanError(error?.message || error);
+ warn(`Failed to report the exhausted release workflow error: ${reason}`);
+ return { skipped: true, reason };
+ }
+}
+
+export function validationFailureAttempts(draft) {
+ return (Array.isArray(draft?.repair_attempts) ? draft.repair_attempts : [])
+ .filter((attempt) => attempt?.stage === "repair" && !attempt?.ok)
+ .slice(-MAX_DRAFT_REPAIR_ATTEMPTS)
+ .map((attempt) => {
+ const kinds = [
+ ...new Set(
+ (Array.isArray(attempt?.issues) ? attempt.issues : [])
+ .map((issue) => String(issue?.kind || "").trim())
+ .filter(Boolean),
+ ),
+ ];
+ return {
+ error_code: "RELEASE_NOTES_VALIDATION",
+ message: JSON.stringify({
+ repair_attempt: attempt.repair_attempt,
+ issue_kinds: kinds,
+ issues: attempt.issues || [],
+ }),
+ retryable: false,
+ };
+ });
+}
+
+export async function reportValidationFailureIfExhausted(
+ { draft, evidence },
+ { fetchImpl = fetch } = {},
+) {
+ const attempts = validationFailureAttempts(draft);
+ if (attempts.length < MAX_DRAFT_REPAIR_ATTEMPTS) {
+ return { skipped: true, reason: "validation repair attempts not exhausted" };
+ }
+ return reportFailureBestEffort({
+ evidence,
+ attempts,
+ finalError: JSON.stringify(draft?.validation_report || draft?.coverage || {}),
+ phase: "release-notes-validation",
+ fetchImpl,
+ });
+}
+
+export async function reportExternalFailureFromEnv({ fetchImpl = fetch } = {}) {
+ const phase = String(process.env.RELEASE_FAILURE_PHASE || "").trim();
+ const attemptDir = String(process.env.RELEASE_FAILURE_ATTEMPT_DIR || "").trim();
+ if (!phase || !attemptDir) fail("RELEASE_FAILURE_PHASE and RELEASE_FAILURE_ATTEMPT_DIR are required.");
+ let logNames = [];
+ try {
+ logNames = readdirSync(attemptDir)
+ .filter((name) => /^\d+\.log$/.test(name))
+ .sort((left, right) => Number.parseInt(left, 10) - Number.parseInt(right, 10))
+ .slice(0, 20);
+ } catch {}
+ if (logNames.length === 0) logNames = ["1.log"];
+ const attempts = logNames.map((name) => {
+ let message = "attempt log is unavailable";
+ try { message = readFileSync(join(attemptDir, name), "utf8"); } catch {}
+ return { error_code: phase.toUpperCase().replace(/[^A-Z0-9]+/g, "_"), message: cleanError(message), retryable: true };
+ });
+ return reportFailure({
+ evidence: {
+ repo: process.env.GITHUB_REPOSITORY || REPOSITORY,
+ target_version: displayVersion(process.env.RELEASE_VERSION),
+ current_tag: process.env.RELEASE_TAG || `${CURRENT_TAG_PREFIX}${cleanVersion(process.env.RELEASE_VERSION)}`,
+ },
+ attempts,
+ finalError: attempts.at(-1).message,
+ phase,
+ fetchImpl,
+ });
+}
+
+export async function requestDraft(
+ evidence,
+ { fetchImpl = fetch, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) } = {},
+) {
+ const url = requiredUrlFromEnv("DOC_AGENT_RELEASE_NOTES_DRAFT_URL");
+ const token = process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN || "";
+ if (!token.trim()) {
+ fail("DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN secret is required when release_notes input is empty.");
+ }
+
+ const attempts = [];
+ for (let attempt = 1; attempt <= 3; attempt += 1) {
+ try {
+ const response = await fetchImpl(url, {
+ method: "POST",
+ headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+ body: JSON.stringify({
+ ...evidence,
+ workflow_retry_context: {
+ attempt,
+ previous_errors: attempts.map((item) => item.message),
+ },
+ }),
+ });
+ const text = await response.text();
+ let payload = {};
+ try {
+ payload = text ? JSON.parse(text) : {};
+ } catch {
+ throw Object.assign(new Error(`non-JSON response: HTTP ${response.status}`), {
+ retryable: isRetryableStatus(response.status),
+ errorCode: `HTTP_${response.status}`,
+ });
+ }
+ if (!response.ok) {
+ throw Object.assign(
+ new Error(`HTTP ${response.status} ${JSON.stringify(payload).slice(0, 400)}`),
+ { retryable: isRetryableStatus(response.status), errorCode: `HTTP_${response.status}` },
+ );
+ }
+ if (!payload.ok || payload.needs_review) {
+ const serverAttempts = Array.isArray(payload.attempts) ? payload.attempts : [];
+ const coverage = payload.coverage ? JSON.stringify(payload.coverage) : "";
+ const warnings = Array.isArray(payload.warnings) ? payload.warnings.join("; ") : "";
+ const message = `Release notes draft needs review. ${coverage} ${warnings}`.trim();
+ if (hasStructuredDraftItems(payload)) {
+ warn(
+ `${message} Continuing with local validation and repair because the draft service returned structured release_items.`,
+ );
+ return payload;
+ }
+ if (serverAttempts.length >= 3) {
+ await reportFailureBestEffort({
+ evidence,
+ attempts: serverAttempts.map((item) => ({
+ error_code: "DRAFT_VALIDATION",
+ message: item.error || message,
+ retryable: false,
+ })),
+ finalError: message,
+ fetchImpl,
+ });
+ }
+ fail(message);
+ }
+ if (!String(payload.release_notes_markdown || "").trim() && !hasStructuredDraftItems(payload)) {
+ fail("Release-notes draft service returned an empty release_notes_markdown.");
+ }
+ return payload;
+ } catch (error) {
+ const entry = {
+ error_code: error?.errorCode || "DRAFT_REQUEST",
+ message: cleanError(error?.message || error),
+ retryable: Boolean(error?.retryable),
+ };
+ attempts.push(entry);
+ if (!entry.retryable || attempt === 3) {
+ if (attempts.length === 3) {
+ await reportFailureBestEffort({ evidence, attempts, finalError: entry.message, fetchImpl });
+ }
+ fail(`Release-notes draft request failed on attempt ${attempt}: ${entry.message}`);
+ }
+ warn(`Release-notes draft attempt ${attempt} failed; retrying: ${entry.message}`);
+ await sleep(250 * 2 ** (attempt - 1));
+ }
+ }
+ fail("Release-notes draft failed after three attempts.");
+}
+
+export async function main() {
+ const targetVersion = cleanVersion(process.env.RELEASE_VERSION);
+ if (!targetVersion) fail("RELEASE_VERSION is required.");
+
+ const currentTag = process.env.RELEASE_TAG || `${CURRENT_TAG_PREFIX}${targetVersion}`;
+ const faultCase = String(process.env.RELEASE_FAULT_CASE || "none").trim() || "none";
+ if (!RELEASE_FAULT_CASES.includes(faultCase)) {
+ fail(`Unknown release fault case: ${faultCase}`);
+ }
+ const notesPath =
+ process.env.RELEASE_NOTES_FILE ||
+ join(tmpdir(), `openclaw-cloud-plugin-${targetVersion}-release-notes.md`);
+ mkdirSync(dirname(notesPath), { recursive: true });
+
+ const previousTag = findPreviousTag(targetVersion, currentTag);
+ if (!previousTag) {
+ fail(`Cannot find a previous cloud plugin tag before ${currentTag}.`);
+ }
+
+ const currentRef = resolveCurrentRef(currentTag);
+ const evidence = collectEvidence({ targetVersion, currentTag, previousTag, currentRef });
+ const evidencePath = join(tmpdir(), `openclaw-cloud-plugin-${targetVersion}-evidence.json`);
+ writeFileSync(evidencePath, JSON.stringify(evidenceForInspection(evidence), null, 2), "utf8");
+
+ const draftPath = join(tmpdir(), `openclaw-cloud-plugin-${targetVersion}-release-notes-draft.json`);
+ const docsPreviewPath = join(tmpdir(), `openclaw-cloud-plugin-${targetVersion}-docs-preview.json`);
+ const docsPreviewMarkdownPath = join(tmpdir(), `openclaw-cloud-plugin-${targetVersion}-docs-preview.md`);
+ const qualityReportPath = join(tmpdir(), `openclaw-cloud-plugin-${targetVersion}-quality-report.json`);
+
+ const suppliedManualNotesFile = String(
+ process.env.MANUAL_RELEASE_NOTES_FILE || "",
+ ).trim();
+ const suppliedManualNotesInput = String(
+ process.env.MANUAL_RELEASE_NOTES || "",
+ ).trim();
+ if (suppliedManualNotesFile && suppliedManualNotesInput) {
+ fail(
+ "Provide reviewed Release Notes through either MANUAL_RELEASE_NOTES_FILE or MANUAL_RELEASE_NOTES, not both.",
+ );
+ }
+ let suppliedManualNotes = suppliedManualNotesInput;
+ if (suppliedManualNotesFile) {
+ try {
+ suppliedManualNotes = readFileSync(suppliedManualNotesFile, "utf8").trim();
+ } catch (error) {
+ fail(
+ `Cannot read reviewed Release Notes file ${suppliedManualNotesFile}: ${cleanError(error?.message || error)}`,
+ );
+ }
+ if (!suppliedManualNotes) {
+ fail(`Reviewed Release Notes file ${suppliedManualNotesFile} is empty.`);
+ }
+ }
+ const manualNotes =
+ faultCase === "manual_notes_missing_payload"
+ ? "## Changelog\n\n### Added\n- Intentionally missing the hidden evidence payload."
+ : suppliedManualNotes;
+ let draftUsed = true;
+ let draft;
+
+ if (manualNotes) {
+ draftUsed = false;
+ try {
+ const validManualNotes = ensureSourceHint(validateManualNotes(manualNotes));
+ const postprocessed = postprocessDraftFromEvidence(
+ draftFromReleaseNotesMarkdown(validManualNotes),
+ evidence,
+ );
+ const validationReport = validationReportFromPostprocessedDraft(postprocessed);
+ draft = {
+ ...postprocessed,
+ validation_report: validationReport,
+ validation_attempt_count: 1,
+ repair_attempt_count: 0,
+ repair_attempts: [
+ validationAttemptRecord({
+ stage: "manual",
+ repairAttempt: 0,
+ draft: postprocessed,
+ validationReport,
+ }),
+ ],
+ };
+ } catch (error) {
+ const reason = cleanError(error?.message || error);
+ const validationReport = {
+ ok: false,
+ needs_review: true,
+ repairable: false,
+ issue_count: 1,
+ language_issue_count: 0,
+ structure_issue_count: 1,
+ readability_issue_count: 0,
+ invalid_item_ref_count: 0,
+ missing_required_count: 0,
+ item_count: 0,
+ limits: RELEASE_NOTE_LIMITS,
+ issues: [
+ {
+ kind:
+ faultCase === "manual_notes_missing_payload"
+ ? "manual_notes_missing_payload"
+ : "manual_notes_invalid",
+ reason,
+ },
+ ],
+ coverage: summarizeCoverageForValidation({ needs_review: true }),
+ postprocess: { applied: false, source: "manual_release_notes" },
+ };
+ draft = {
+ ok: false,
+ needs_review: true,
+ confidence: "manual",
+ release_items: [],
+ docs_categories: { cn: {}, en: {} },
+ coverage: validationReport.coverage,
+ warnings: [reason],
+ validation_report: validationReport,
+ validation_attempt_count: 1,
+ repair_attempt_count: 0,
+ repair_attempts: [
+ {
+ stage: "manual",
+ repair_attempt: 0,
+ ok: false,
+ needs_review: true,
+ repairable: false,
+ issue_count: 1,
+ issues: validationReport.issues,
+ },
+ ],
+ release_notes_markdown: manualNotes,
+ };
+ }
+ } else {
+ draft = await requestValidatedDraft(evidence, { faultCase });
+ }
+
+ const docsPreview = docsPreviewFromDraft(draft, { targetVersion });
+ const qualityReport = qualityReportFromDraft(draft, {
+ targetVersion,
+ previousTag,
+ currentTag,
+ currentRef,
+ faultCase,
+ });
+ writeFileSync(draftPath, JSON.stringify(draftForInspection(draft), null, 2), "utf8");
+ writeFileSync(docsPreviewPath, JSON.stringify(docsPreview, null, 2), "utf8");
+ writeFileSync(docsPreviewMarkdownPath, markdownFromDocsPreview(docsPreview), "utf8");
+ writeFileSync(qualityReportPath, JSON.stringify(qualityReport, null, 2), "utf8");
+ if (String(draft.release_notes_markdown || "").trim()) {
+ writeFileSync(notesPath, ensureSourceHint(draft.release_notes_markdown), "utf8");
+ }
+
+ appendOutput("release_notes_file", notesPath);
+ appendOutput("evidence_file", evidencePath);
+ appendOutput("draft_file", draftPath);
+ appendOutput("docs_preview_file", docsPreviewPath);
+ appendOutput("docs_preview_markdown_file", docsPreviewMarkdownPath);
+ appendOutput("quality_report_file", qualityReportPath);
+ appendOutput("draft_used", String(draftUsed));
+ appendOutput("previous_tag", previousTag);
+ appendOutput("current_tag", currentTag);
+ appendOutput("current_ref", currentRef);
+ appendOutput("draft_confidence", String(draft.confidence || ""));
+ appendOutput("missing_required_count", String(draft.coverage?.missing_required_count ?? ""));
+ appendOutput("validation_attempt_count", String(draft.validation_attempt_count ?? ""));
+ appendOutput("repair_attempt_count", String(draft.repair_attempt_count ?? ""));
+ appendOutput("fault_case", faultCase);
+
+ console.log(`${draftUsed ? "Drafted" : "Validated manual"} release notes: ${notesPath}`);
+ console.log(`Previous tag: ${previousTag}`);
+ console.log(`Current tag: ${currentTag}`);
+ console.log(`Current evidence ref: ${currentRef}`);
+ console.log(`Fault case: ${faultCase}`);
+ console.log(`Coverage: ${JSON.stringify(draft.coverage || {})}`);
+ console.log(`Validation attempts: ${draft.validation_attempt_count ?? ""}`);
+ console.log(`Repair attempts: ${draft.repair_attempt_count ?? ""}`);
+
+ if (!draft.ok || draft.needs_review) {
+ if (draftUsed) {
+ await reportValidationFailureIfExhausted({ draft, evidence });
+ }
+ fail(`Postprocessed release notes require review: ${JSON.stringify(draft.validation_report || draft.coverage || {})}`);
+ }
+}
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+ const run = process.env.RELEASE_FAILURE_PHASE ? reportExternalFailureFromEnv : main;
+ run().catch((error) => {
+ console.error(`::error::${cleanError(error?.message || String(error))}`);
+ process.exitCode = 1;
+ });
+}
diff --git a/.github/scripts/draft-cloud-plugin-release-notes.test.mjs b/.github/scripts/draft-cloud-plugin-release-notes.test.mjs
new file mode 100644
index 000000000..7bf8dc23c
--- /dev/null
+++ b/.github/scripts/draft-cloud-plugin-release-notes.test.mjs
@@ -0,0 +1,1547 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import {
+ cleanVersion,
+ categoryHintsForCommits,
+ compareSemver,
+ docsPreviewFromDraft,
+ draftForInspection,
+ evidenceForInspection,
+ ensureSourceHint,
+ findPreviousTag,
+ injectReleaseFaultCase,
+ main,
+ markdownFromDocsPreview,
+ postprocessDraftFromEvidence,
+ PRODUCT_ID,
+ qualityReportFromDraft,
+ RELEASE_FAULT_CASES,
+ RELEASE_NOTE_GUIDANCE,
+ RELEASE_NOTE_LIMITS,
+ RELEASE_NOTE_QUALITY_REQUEST,
+ reportExternalFailureFromEnv,
+ reportValidationFailureIfExhausted,
+ requestDraft,
+ requestValidatedDraft,
+ resolveCurrentRef,
+ validationFailureAttempts,
+ validateManualNotes,
+ versionFromTag,
+} from "./draft-cloud-plugin-release-notes.mjs";
+
+const evidence = {
+ repo: "MemTensor/MemOS-Cloud-OpenClaw-Plugin",
+ current_tag: "v0.1.19",
+ target_version: "v0.1.19",
+};
+
+function runGit(cwd, args) {
+ return execFileSync("git", args, {
+ cwd,
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "pipe"],
+ }).trim();
+}
+
+function response(status, body) {
+ return {
+ status,
+ ok: status >= 200 && status < 300,
+ async text() {
+ return JSON.stringify(body);
+ },
+ async json() {
+ return body;
+ },
+ };
+}
+
+test("normalizes cloud plugin versions and tags", () => {
+ assert.equal(cleanVersion("v0.1.19"), "0.1.19");
+ assert.equal(versionFromTag("v0.1.19"), "0.1.19");
+ assert.equal(versionFromTag("openclaw-cloud-plugin-v0.1.19"), "");
+});
+
+test("compares SemVer prerelease identifiers numerically and ignores build metadata", () => {
+ assert.equal(compareSemver("1.0.0-beta.10", "1.0.0-beta.9") > 0, true);
+ assert.equal(compareSemver("1.0.0-beta.20", "1.0.0-beta.19") > 0, true);
+ assert.equal(compareSemver("1.0.0-beta.1", "1.0.0-beta.alpha") < 0, true);
+ assert.equal(compareSemver("1.0.0", "1.0.0-rc.1") > 0, true);
+ assert.equal(compareSemver("1.0.0+build.2", "1.0.0+build.1"), 0);
+ assert.equal(compareSemver("1.0.0-beta.1+build.2", "1.0.0-beta.1+build.1"), 0);
+});
+
+test("finds previous tags using SemVer precedence for prerelease numbers", () => {
+ const previousCwd = process.cwd();
+ const dir = mkdtempSync(join(tmpdir(), "openclaw-cloud-tags-"));
+
+ try {
+ runGit(dir, ["init"]);
+ runGit(dir, ["config", "user.email", "test@example.invalid"]);
+ runGit(dir, ["config", "user.name", "Test User"]);
+ writeFileSync(join(dir, "README.md"), "tags\n");
+ runGit(dir, ["add", "README.md"]);
+ runGit(dir, ["commit", "-m", "seed"]);
+ runGit(dir, ["tag", "v1.0.0"]);
+ runGit(dir, ["tag", "v1.0.1+build.1"]);
+ runGit(dir, ["tag", "v1.0.1-beta.1"]);
+ for (let i = 1; i <= 19; i++) {
+ runGit(dir, ["tag", `v1.0.0-beta.${i}`]);
+ }
+
+ process.chdir(dir);
+ assert.equal(findPreviousTag("1.0.0-beta.10", "v1.0.0-beta.10"), "v1.0.0-beta.9");
+ assert.equal(findPreviousTag("1.0.0-beta.11", "v1.0.0-beta.11"), "v1.0.0-beta.10");
+ assert.equal(findPreviousTag("1.0.0-beta.20", "v1.0.0-beta.20"), "v1.0.0-beta.19");
+ // Prereleases are preview-only in the Docs pipeline, so a stable release
+ // must include the full delta from the previous stable tag.
+ assert.equal(findPreviousTag("1.0.1+build.2", "v1.0.1+build.2"), "v1.0.0");
+ } finally {
+ process.chdir(previousCwd);
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("uses an existing release tag as the evidence endpoint", () => {
+ const exists = (ref) => ref === "v0.1.19" || ref === "manual-ref";
+ assert.equal(resolveCurrentRef("v0.1.19", { requestedRef: "", refExistsImpl: exists }), "v0.1.19");
+ assert.equal(resolveCurrentRef("v0.1.20", { requestedRef: "", refExistsImpl: exists }), "HEAD");
+ assert.equal(resolveCurrentRef("v0.1.20", { requestedRef: "manual-ref", refExistsImpl: exists }), "manual-ref");
+ assert.throws(
+ () => resolveCurrentRef("v0.1.20", { requestedRef: "missing-ref", refExistsImpl: exists }),
+ /RELEASE_EVIDENCE_REF does not exist/,
+ );
+});
+
+test("documents cloud release-note guidance", () => {
+ assert.match(RELEASE_NOTE_GUIDANCE.category_policy.Added, /lifecycle hooks/);
+ assert.match(RELEASE_NOTE_GUIDANCE.category_policy.Improved, /prompt sanitization/);
+ assert.match(RELEASE_NOTE_GUIDANCE.category_policy.Fixed, /duplicate prompt injection/);
+ assert.ok(
+ RELEASE_NOTE_GUIDANCE.translation_policy.some((item) =>
+ item.includes("Treat text_cn as the canonical release-note wording first"),
+ ),
+ );
+ assert.equal(RELEASE_NOTE_QUALITY_REQUEST.candidate_count, 3);
+ assert.equal(RELEASE_NOTE_QUALITY_REQUEST.repair_policy.max_repair_attempts, 3);
+ assert.ok(
+ RELEASE_NOTE_QUALITY_REQUEST.selection_policy.some((item) =>
+ item.includes("Score candidates against evidence coverage"),
+ ),
+ );
+});
+
+test("adds source-ref category hints from cloud plugin commit subjects", () => {
+ const hints = categoryHintsForCommits([
+ {
+ short_sha: "9deb941e",
+ subject: "feat: add direct-session user id support (#135)",
+ },
+ {
+ short_sha: "59c14746",
+ subject: "refactor: improve recall filter payload sanitization",
+ },
+ {
+ short_sha: "de03ab29",
+ subject: "fix: register before_prompt_build hook on supported OpenClaw hosts (#140)",
+ },
+ {
+ short_sha: "c739e9f2",
+ subject: "docs: update README",
+ },
+ {
+ short_sha: "98549947",
+ subject: "ci: cover publish confirmation guard dry runs",
+ },
+ {
+ short_sha: "c20bf70a",
+ subject: "fix: compare release tags with semver precedence",
+ },
+ ]);
+
+ assert.deepEqual(
+ hints.map((hint) => hint.category),
+ ["Added", "Improved", "Fixed"],
+ );
+ assert.deepEqual(hints[0].source_refs, ["9deb941e", "#135"]);
+ assert.deepEqual(hints[2].source_refs, ["de03ab29", "#140"]);
+});
+
+test("redacts full diff and prompt guidance from inspection evidence", () => {
+ const inspection = evidenceForInspection({
+ ...evidence,
+ release_note_guidance: {
+ category_policy: { Added: "private prompt details" },
+ quality_policy: ["private quality prompt"],
+ translation_policy: ["private translation prompt"],
+ source_ref_category_hints: [{ category: "Added", source_refs: ["abc1234"] }],
+ },
+ important_diff: {
+ "openclaw-cloud-plugin/**": "diff --git a/private.js b/private.js",
+ },
+ });
+
+ assert.equal("important_diff" in inspection, false);
+ assert.equal(inspection.release_note_guidance.category_policy, undefined);
+ assert.deepEqual(inspection.release_note_guidance.source_ref_category_hints, [
+ { category: "Added", source_refs: ["abc1234"] },
+ ]);
+ assert.match(inspection.redactions.important_diff, /omitted/);
+});
+
+test("redacts server debug fields from inspection draft", () => {
+ const inspection = draftForInspection({
+ ok: true,
+ needs_review: false,
+ confidence: "high",
+ release_items: [
+ { category: "Added", text_cn: "新增云插件配置", text_en: "Added cloud plugin configuration", source_refs: ["abc1234"] },
+ ],
+ coverage: { needs_review: false, required_count: 1, covered_required_count: 1, covered_refs: ["abc1234"] },
+ model: "private-model",
+ prompt: "private prompt",
+ debug: { trace: "private debug" },
+ });
+
+ assert.equal(inspection.model, undefined);
+ assert.equal(inspection.prompt, undefined);
+ assert.equal(inspection.debug, undefined);
+ assert.deepEqual(inspection.release_items[0].source_refs, ["abc1234"]);
+});
+
+test("postprocesses duplicate source refs into the best evidence category", () => {
+ const processed = postprocessDraftFromEvidence(
+ {
+ ok: true,
+ needs_review: false,
+ release_items: [
+ {
+ category: "Fixed",
+ text_cn: "**召回过滤修复**:解决召回过滤 payload 处理问题。",
+ text_en: "**Recall Filter Fix**: Fixed recall filter payload handling.",
+ source_refs: ["59c14746"],
+ },
+ {
+ category: "Improved",
+ text_cn: "**召回过滤优化**:增强召回过滤 payload 清洗稳定性。",
+ text_en: "**Recall Filter Improvement**: Improved recall filter payload sanitization.",
+ source_refs: ["59c14746"],
+ },
+ ],
+ coverage: { required_count: 1, covered_required_count: 1, missing_required_count: 0 },
+ warnings: [],
+ },
+ {
+ commits: [
+ {
+ sha: "59c1474600000000000000000000000000000000",
+ short_sha: "59c14746",
+ subject: "refactor: improve recall filter payload sanitization",
+ },
+ ],
+ release_note_guidance: {
+ source_ref_category_hints: [
+ {
+ category: "Improved",
+ source_refs: ["59c14746"],
+ subject: "refactor: improve recall filter payload sanitization",
+ },
+ ],
+ },
+ },
+ );
+
+ assert.equal(processed.ok, true);
+ assert.equal(processed.release_items.length, 1);
+ assert.equal(processed.release_items[0].category, "Improved");
+ assert.match(processed.release_notes_markdown, /doc-agent-release-notes-json/);
+});
+
+test("normalizes full and short SHA aliases while preserving a real PR ref", () => {
+ const processed = postprocessDraftFromEvidence(
+ {
+ ok: true,
+ needs_review: false,
+ release_items: [
+ {
+ category: "Added",
+ text_cn: "**插件健康看板**:新增云插件健康状态展示。",
+ text_en: "**Plugin health dashboard**: Adds cloud plugin health status visibility.",
+ source_refs: [
+ "abc1234",
+ `abc1234${"0".repeat(33)}`,
+ "#3001",
+ ],
+ },
+ ],
+ coverage: { needs_review: false },
+ warnings: [],
+ },
+ {
+ commits: [
+ {
+ sha: `abc1234${"0".repeat(33)}`,
+ short_sha: "abc1234",
+ subject: "feat: add plugin health dashboard (#3001)",
+ },
+ ],
+ release_note_guidance: {
+ source_ref_category_hints: [
+ {
+ category: "Added",
+ source_refs: ["abc1234", "#3001"],
+ subject: "feat: add plugin health dashboard (#3001)",
+ },
+ ],
+ },
+ },
+ );
+
+ assert.equal(processed.ok, true);
+ assert.deepEqual(processed.release_items[0].source_refs, ["abc1234", "#3001"]);
+ assert.equal(processed.postprocess.removed_duplicate_source_refs, 1);
+});
+
+test("rewrites known system prompt handling evidence into docs-ready cloud plugin bullets", () => {
+ const processed = postprocessDraftFromEvidence(
+ {
+ ok: true,
+ needs_review: false,
+ release_items: [
+ {
+ category: "Added",
+ text_cn: "**增强系统提示检测**:提升了 OpenClaw 系统提示的检测和处理能力。",
+ text_en: "**Enhanced System Prompt Detection**: Improved detection and handling of OpenClaw system prompts.",
+ source_refs: ["d053b0a"],
+ },
+ ],
+ coverage: { required_count: 1, covered_required_count: 1, missing_required_count: 0 },
+ warnings: [],
+ },
+ {
+ important_diff: {
+ "openclaw-cloud-plugin/**":
+ "isForcedSystemMessage scheduled task scheduled reminder background command system prompt false positive single-line flattened",
+ },
+ commits: [
+ {
+ sha: "d053b0a000000000000000000000000000000000",
+ short_sha: "d053b0a",
+ subject: "feat: enhance OpenClaw system prompt detection and handling",
+ },
+ ],
+ release_note_guidance: {
+ source_ref_category_hints: [
+ {
+ category: "Added",
+ source_refs: ["d053b0a"],
+ subject: "feat: enhance OpenClaw system prompt detection and handling",
+ },
+ ],
+ },
+ },
+ );
+
+ assert.equal(processed.ok, true);
+ assert.equal(processed.release_items.length, 2);
+ assert.deepEqual(
+ processed.release_items.map((item) => item.category),
+ ["Improved", "Improved"],
+ );
+ assert.match(processed.release_items[0].text_cn, /系统事件过滤增强/);
+ assert.match(processed.release_items[1].text_cn, /系统提示识别优化/);
+ assert.equal(processed.coverage.missing_required_count, 0);
+ assert.deepEqual(processed.docs_categories.cn.Improvements, [
+ "**系统事件过滤增强**:自动跳过定时任务、计划提醒和后台命令结果,减少记忆污染。",
+ "**系统提示识别优化**:兼容单行压缩内容并降低普通消息误判概率。",
+ ]);
+});
+
+test("uses evidence subjects ahead of off-topic draft text for known cloud plugin topics", () => {
+ const processed = postprocessDraftFromEvidence(
+ {
+ ok: true,
+ needs_review: false,
+ release_items: [
+ {
+ category: "Added",
+ text_cn: "**增强系统提示检测**:提升了 OpenClaw 系统提示的检测和处理能力。",
+ text_en: "**Enhanced System Prompt Detection**: Improved detection and handling of OpenClaw system prompts.",
+ source_refs: ["5152641"],
+ },
+ ],
+ coverage: { required_count: 1, covered_required_count: 1, missing_required_count: 0 },
+ warnings: [],
+ },
+ {
+ commits: [
+ {
+ sha: "5152641c4b564857f23f46b1ea81f9319ef3fd4a",
+ short_sha: "5152641",
+ subject: "feat: add config UI update check",
+ },
+ ],
+ release_note_guidance: {
+ source_ref_category_hints: [
+ {
+ category: "Added",
+ source_refs: ["5152641"],
+ subject: "feat: add config UI update check",
+ },
+ ],
+ },
+ },
+ );
+
+ assert.equal(processed.ok, true);
+ assert.equal(processed.release_items.length, 1);
+ assert.match(processed.release_items[0].text_cn, /配置页新增更新检查/);
+ assert.match(processed.release_items[0].text_en, /Update checks in settings/);
+ assert.deepEqual(processed.release_items[0].source_refs, ["5152641"]);
+ assert.deepEqual(processed.docs_categories.cn.Improvements, [
+ "**配置页新增更新检查**:可查看版本状态,并复制对应宿主的更新重启命令。",
+ ]);
+});
+
+test("keeps historical product topics while removing release-automation and version noise refs", () => {
+ const commits = [
+ {
+ sha: "70fb1840fdd73a7a04e5f946148cc94b916dad77",
+ short_sha: "70fb184",
+ subject: "feat: update MEMOS_SOURCE to append platform-specific suffixes and add corresponding tests",
+ },
+ {
+ sha: "5152641c4b564857f23f46b1ea81f9319ef3fd4a",
+ short_sha: "5152641",
+ subject: "feat: add config UI update check",
+ },
+ {
+ sha: "d053b0a2764daa923bbeeeb699c949ef0112a437",
+ short_sha: "d053b0a",
+ subject: "feat: enhance OpenClaw system prompt detection and handling",
+ },
+ {
+ sha: "0dde13c000000000000000000000000000000000",
+ short_sha: "0dde13c",
+ subject: "ci: harden cloud plugin release previews",
+ },
+ {
+ sha: "0c2cd2a1a51f6cbfc744a51462ba54ad8ed3f22a",
+ short_sha: "0c2cd2a",
+ subject: "0.1.19",
+ },
+ ];
+ const processed = postprocessDraftFromEvidence(
+ {
+ ok: true,
+ needs_review: false,
+ release_items: [
+ {
+ category: "Added",
+ text_cn: "**云插件更新**:汇总跨平台来源、配置页更新检查和系统提示处理。",
+ text_en:
+ "**Cloud plugin updates**: Summarizes platform-aware sources, settings update checks, and system prompt handling.",
+ source_refs: commits.map((commit) => commit.short_sha),
+ },
+ ],
+ coverage: { needs_review: false },
+ warnings: [],
+ },
+ {
+ commits,
+ release_note_guidance: {
+ source_ref_category_hints: categoryHintsForCommits(commits),
+ },
+ },
+ );
+
+ assert.equal(processed.ok, true);
+ assert.equal(processed.coverage.missing_required_count, 0);
+ assert.equal(processed.postprocess.removed_release_noise_refs, 2);
+ assert.ok(
+ processed.release_items.every(
+ (item) => !item.source_refs.includes("0dde13c") && !item.source_refs.includes("0c2cd2a"),
+ ),
+ );
+ assert.match(processed.release_notes_markdown, /跨平台记忆来源识别/);
+ assert.match(processed.release_notes_markdown, /配置页新增更新检查/);
+ assert.match(processed.release_notes_markdown, /系统事件过滤增强/);
+ assert.match(processed.release_notes_markdown, /系统提示识别优化/);
+ assert.doesNotMatch(processed.release_notes_markdown, /发布预览|release previews|0dde13c|0c2cd2a/);
+});
+
+test("fails closed when a draft contains only release-automation evidence", () => {
+ const processed = postprocessDraftFromEvidence(
+ {
+ ok: true,
+ needs_review: false,
+ release_items: [
+ {
+ category: "Improved",
+ text_cn: "**发布流程优化**:增强发布预览与重试。",
+ text_en: "**Release workflow improvements**: Improves release previews and retries.",
+ source_refs: ["0dde13c"],
+ },
+ ],
+ coverage: { needs_review: false },
+ warnings: [],
+ },
+ {
+ commits: [
+ {
+ sha: "0dde13c000000000000000000000000000000000",
+ short_sha: "0dde13c",
+ subject: "ci: harden cloud plugin release previews",
+ },
+ ],
+ release_note_guidance: { source_ref_category_hints: [] },
+ },
+ );
+
+ assert.equal(processed.ok, false);
+ assert.equal(processed.needs_review, true);
+ assert.deepEqual(processed.release_items, []);
+ assert.equal(processed.postprocess.dropped_release_noise_items, 1);
+ assert.ok(processed.validation_report.issues.some((issue) => issue.kind === "empty_release_items"));
+});
+
+test("splits collapsed multi-ref historical drafts into docs-ready cloud plugin topics", () => {
+ const commits = [
+ {
+ sha: "306841f000000000000000000000000000000000",
+ short_sha: "306841f",
+ subject:
+ "feat: update recall hook registration to use before_prompt_build for newer OpenClaw hosts and add tests for version compatibility",
+ },
+ {
+ sha: "bf25eb70000000000000000000000000000000000",
+ short_sha: "bf25eb7",
+ subject:
+ "feat: implement system event detection in recall and agent end hooks to skip processing for heartbeat and command events",
+ },
+ {
+ sha: "eb2bddc000000000000000000000000000000000",
+ short_sha: "eb2bddc",
+ subject: "feat: add function to strip leading system notes from text input",
+ },
+ {
+ sha: "f7c1edb000000000000000000000000000000000",
+ short_sha: "f7c1edb",
+ subject: "feat: refactor system event detection logic into dedicated functions for clarity and reuse",
+ },
+ {
+ sha: "9c773370000000000000000000000000000000000",
+ short_sha: "9c77337",
+ subject: "feat: enhance memory section handling by adding tool memory support and simplifying filtering logic",
+ },
+ {
+ sha: "ed52b9c000000000000000000000000000000000",
+ short_sha: "ed52b9c",
+ subject:
+ "feat: extend system command detection to include 'clear' command and add internal prompt patterns for session management",
+ },
+ ];
+ const processed = postprocessDraftFromEvidence(
+ {
+ ok: true,
+ needs_review: false,
+ release_items: [
+ {
+ category: "Added",
+ text_cn: "**Hook 与记忆能力增强**:优化云插件 hook、系统事件、工具记忆和提示处理。",
+ text_en: "**Hook and memory improvements**: Improves cloud plugin hooks, system events, tool memory, and prompt handling.",
+ source_refs: ["306841f", "bf25eb7", "eb2bddc", "f7c1edb", "9c77337", "ed52b9c"],
+ },
+ ],
+ coverage: { required_count: 6, covered_required_count: 6, missing_required_count: 0 },
+ warnings: [],
+ },
+ {
+ commits,
+ release_note_guidance: {
+ source_ref_category_hints: commits.map((commit) => ({
+ category: commit.short_sha === "f7c1edb" || commit.short_sha === "ed52b9c" ? "Improved" : "Added",
+ source_refs: [commit.short_sha],
+ subject: commit.subject,
+ })),
+ },
+ },
+ );
+
+ assert.equal(processed.ok, true);
+ assert.equal(processed.coverage.missing_required_count, 0);
+ assert.equal(processed.release_items.length, 7);
+ assert.deepEqual(
+ processed.release_items.map((item) => item.source_refs[0]),
+ ["306841f", "bf25eb7", "eb2bddc", "f7c1edb", "9c77337", "9c77337", "ed52b9c"],
+ );
+ assert.match(processed.release_notes_markdown, /Recall Hook 兼容新版 OpenClaw/);
+ assert.match(processed.release_notes_markdown, /系统事件自动跳过/);
+ assert.match(processed.release_notes_markdown, /System Note 前缀自动剥离/);
+ assert.match(processed.release_notes_markdown, /系统事件检测重构/);
+ assert.match(processed.release_notes_markdown, /工具记忆全链路支持/);
+ assert.match(processed.release_notes_markdown, /记忆过滤逻辑精简/);
+ assert.match(processed.release_notes_markdown, /内部提示识别增强/);
+});
+
+test("generates bilingual MemOS-Docs preview from postprocessed release items", () => {
+ const draft = {
+ docs_categories: {
+ cn: {
+ Improvements: [
+ "**系统事件过滤增强**:自动跳过定时任务、计划提醒和后台命令结果,减少记忆污染。",
+ ],
+ },
+ en: {
+ Improvements: [
+ "**System-event filtering**: Skips scheduled tasks, reminders, and background command results to keep memory cleaner.",
+ ],
+ },
+ },
+ };
+ const preview = docsPreviewFromDraft(draft, {
+ targetVersion: "0.1.20",
+ publishedAt: "2026-07-23T08:00:00Z",
+ });
+ const markdown = markdownFromDocsPreview(preview);
+
+ assert.equal(preview.version, "v0.1.20");
+ assert.equal(preview.date, "2026-07-23");
+ assert.equal(preview.docs_files.cn, "content/cn/plugin-changelog.yml");
+ assert.equal(preview.entries.cn.products.plugin.Improvements[0].type, "OpenClaw 云插件");
+ assert.equal(preview.entries.en.products.plugin.Improvements[0].type, "OpenClaw Cloud Plugin");
+ assert.match(markdown, /中文预览/);
+ assert.match(markdown, /System-event filtering/);
+});
+
+test("postprocess fails closed when English and Chinese text cross languages", () => {
+ const processed = postprocessDraftFromEvidence(
+ {
+ ok: true,
+ needs_review: false,
+ release_items: [
+ {
+ category: "Added",
+ text_cn: "Plugin health dashboard",
+ text_en: "插件健康看板",
+ source_refs: ["abc1234", "#3001"],
+ },
+ ],
+ coverage: { required_count: 1, covered_required_count: 1, missing_required_count: 0 },
+ warnings: [],
+ },
+ {
+ commits: [
+ {
+ sha: "abc12340000000000000000000000000000000",
+ short_sha: "abc1234",
+ subject: "feat: add plugin health dashboard (#3001)",
+ },
+ ],
+ release_note_guidance: {
+ source_ref_category_hints: [
+ {
+ category: "Added",
+ source_refs: ["abc1234", "#3001"],
+ subject: "feat: add plugin health dashboard (#3001)",
+ },
+ ],
+ },
+ },
+ );
+
+ assert.equal(processed.ok, false);
+ assert.equal(processed.needs_review, true);
+ assert.equal(processed.language_issues.length, 2);
+});
+
+test("postprocess fails closed when cloud plugin docs output is too noisy", () => {
+ const commits = Array.from({ length: 13 }, (_item, index) => {
+ const short = `abc${String(index).padStart(4, "0")}`;
+ return {
+ sha: `${short}${"0".repeat(33)}`,
+ short_sha: short,
+ subject: `feat: improve cloud memory recall quality ${index + 1} (#${3001 + index})`,
+ };
+ });
+ const noisyItems = Array.from({ length: 13 }, (_item, index) => ({
+ category: "Improved",
+ text_cn: `**云插件优化 ${index + 1}**:优化发布说明展示效果。`,
+ text_en: `**Cloud plugin improvement ${index + 1}**: Refined release-note presentation.`,
+ source_refs: [commits[index].short_sha, `#${3001 + index}`],
+ }));
+ const processed = postprocessDraftFromEvidence(
+ {
+ ok: true,
+ needs_review: false,
+ release_items: noisyItems,
+ coverage: { required_count: 1, covered_required_count: 1, missing_required_count: 0 },
+ warnings: [],
+ },
+ {
+ commits,
+ release_note_guidance: {
+ source_ref_category_hints: commits.map((commit, index) => ({
+ category: "Improved",
+ source_refs: [commit.short_sha, `#${3001 + index}`],
+ subject: commit.subject,
+ })),
+ },
+ },
+ );
+
+ assert.equal(processed.ok, false);
+ assert.equal(processed.needs_review, true);
+ assert.ok(processed.readability_issues.some((issue) => issue.field === "release_items"));
+ assert.equal(processed.validation_report.readability_issue_count, 1);
+});
+
+test("postprocess fails closed when cloud plugin docs bullets are too long", () => {
+ const processed = postprocessDraftFromEvidence(
+ {
+ ok: true,
+ needs_review: false,
+ release_items: [
+ {
+ category: "Improved",
+ text_cn: `**系统事件过滤增强**:${"用于发布说明质量验证的重复中文描述。".repeat(12)}`,
+ text_en: `**System-event filtering**: ${"This repeated English detail is intentionally too verbose for a changelog bullet. ".repeat(6)}`,
+ source_refs: ["abc1234", "#3001"],
+ },
+ ],
+ coverage: { required_count: 1, covered_required_count: 1, missing_required_count: 0 },
+ warnings: [],
+ },
+ {
+ commits: [
+ {
+ sha: "abc12340000000000000000000000000000000",
+ short_sha: "abc1234",
+ subject: "feat: improve cloud memory recall quality (#3001)",
+ },
+ ],
+ release_note_guidance: {
+ source_ref_category_hints: [
+ {
+ category: "Improved",
+ source_refs: ["abc1234", "#3001"],
+ subject: "feat: improve cloud memory recall quality (#3001)",
+ },
+ ],
+ },
+ },
+ );
+
+ assert.equal(processed.ok, false);
+ assert.equal(processed.needs_review, true);
+ assert.ok(processed.readability_issues.some((issue) => issue.field === "text_cn"));
+ assert.ok(processed.readability_issues.some((issue) => issue.field === "text_en"));
+ assert.ok(processed.validation_report.repairable);
+});
+
+test("repairs postprocessed language validation issues with exact context", async () => {
+ const repairEvidence = {
+ commits: [
+ {
+ sha: "abc12340000000000000000000000000000000",
+ short_sha: "abc1234",
+ subject: "feat: add plugin health dashboard (#3001)",
+ },
+ ],
+ release_note_guidance: {
+ source_ref_category_hints: [
+ {
+ category: "Added",
+ source_refs: ["abc1234", "#3001"],
+ subject: "feat: add plugin health dashboard (#3001)",
+ },
+ ],
+ },
+ };
+ const requests = [];
+ const requestImpl = async (payload) => {
+ requests.push(payload);
+ if (requests.length === 1) {
+ return {
+ ok: true,
+ needs_review: false,
+ release_items: [
+ {
+ category: "Added",
+ text_cn: "Plugin health dashboard",
+ text_en: "插件健康看板",
+ source_refs: ["abc1234", "#3001"],
+ },
+ ],
+ coverage: { required_count: 1, covered_required_count: 1, missing_required_count: 0 },
+ warnings: [],
+ };
+ }
+ return {
+ ok: true,
+ needs_review: false,
+ release_items: [
+ {
+ category: "Added",
+ text_cn: "**插件健康看板**:新增云插件健康状态展示。",
+ text_en: "**Plugin Health Dashboard**: Added cloud plugin health status visibility.",
+ source_refs: ["abc1234", "#3001"],
+ },
+ ],
+ coverage: { required_count: 1, covered_required_count: 1, missing_required_count: 0 },
+ warnings: [],
+ };
+ };
+
+ const result = await requestValidatedDraft(repairEvidence, { requestImpl });
+
+ assert.equal(result.ok, true);
+ assert.equal(result.needs_review, false);
+ assert.equal(result.repair_attempt_count, 1);
+ assert.equal(result.validation_attempt_count, 2);
+ assert.equal(requests.length, 2);
+ assert.equal(requests[1].release_notes_repair_context.validation_report.language_issue_count, 2);
+ assert.match(result.release_notes_markdown, /插件健康看板/);
+});
+
+test("stops release-note repair after two validation repair attempts", async () => {
+ const repairEvidence = {
+ commits: [
+ {
+ sha: "abc12340000000000000000000000000000000",
+ short_sha: "abc1234",
+ subject: "feat: add plugin health dashboard (#3001)",
+ },
+ ],
+ release_note_guidance: {
+ source_ref_category_hints: [
+ {
+ category: "Added",
+ source_refs: ["abc1234", "#3001"],
+ subject: "feat: add plugin health dashboard (#3001)",
+ },
+ ],
+ },
+ };
+ const crossedDraft = {
+ ok: true,
+ needs_review: false,
+ release_items: [
+ {
+ category: "Added",
+ text_cn: "Plugin health dashboard",
+ text_en: "插件健康看板",
+ source_refs: ["abc1234", "#3001"],
+ },
+ ],
+ coverage: { required_count: 1, covered_required_count: 1, missing_required_count: 0 },
+ warnings: [],
+ };
+ const requests = [];
+ const result = await requestValidatedDraft(repairEvidence, {
+ requestImpl: async (payload) => {
+ requests.push(payload);
+ return crossedDraft;
+ },
+ maxRepairAttempts: 2,
+ });
+
+ assert.equal(result.ok, false);
+ assert.equal(result.needs_review, true);
+ assert.equal(result.repair_attempt_count, 2);
+ assert.equal(result.validation_attempt_count, 3);
+ assert.equal(requests.length, 3);
+});
+
+test("defaults to three validation repair attempts before failing closed", async () => {
+ const repairEvidence = {
+ commits: [
+ {
+ sha: "abc12340000000000000000000000000000000",
+ short_sha: "abc1234",
+ subject: "feat: add plugin health dashboard (#3001)",
+ },
+ ],
+ release_note_guidance: {
+ source_ref_category_hints: [
+ {
+ category: "Added",
+ source_refs: ["abc1234", "#3001"],
+ subject: "feat: add plugin health dashboard (#3001)",
+ },
+ ],
+ },
+ };
+ const crossedDraft = {
+ ok: true,
+ needs_review: false,
+ release_items: [
+ {
+ category: "Added",
+ text_cn: "Plugin health dashboard",
+ text_en: "插件健康看板",
+ source_refs: ["abc1234", "#3001"],
+ },
+ ],
+ coverage: { required_count: 1, covered_required_count: 1, missing_required_count: 0 },
+ warnings: [],
+ };
+ const requests = [];
+ const result = await requestValidatedDraft(repairEvidence, {
+ requestImpl: async (payload) => {
+ requests.push(payload);
+ return crossedDraft;
+ },
+ });
+
+ assert.equal(result.ok, false);
+ assert.equal(result.needs_review, true);
+ assert.equal(result.repair_attempt_count, 3);
+ assert.equal(result.validation_attempt_count, 4);
+ assert.equal(requests.length, 4);
+ assert.equal(requests[3].release_notes_repair_context.max_repair_attempts, 3);
+});
+
+test("reports the three semantic repair failures after validation exhaustion", async () => {
+ const previous = { ...process.env };
+ try {
+ process.env.DOC_AGENT_RELEASE_FAILURE_URL = "https://example.invalid/failure";
+ process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN = "test-token";
+ const draft = {
+ ok: false,
+ needs_review: true,
+ validation_report: {
+ ok: false,
+ needs_review: true,
+ issues: [{ kind: "language", field: "text_en" }],
+ },
+ repair_attempts: [
+ { stage: "draft", repair_attempt: 0, ok: false, issues: [{ kind: "language" }] },
+ { stage: "repair", repair_attempt: 1, ok: false, issues: [{ kind: "language" }] },
+ { stage: "repair", repair_attempt: 2, ok: false, issues: [{ kind: "language" }] },
+ { stage: "repair", repair_attempt: 3, ok: false, issues: [{ kind: "language" }] },
+ ],
+ };
+ assert.deepEqual(
+ validationFailureAttempts(draft).map((attempt) => JSON.parse(attempt.message).repair_attempt),
+ [1, 2, 3],
+ );
+
+ let report;
+ const result = await reportValidationFailureIfExhausted(
+ { draft, evidence },
+ {
+ fetchImpl: async (_url, options) => {
+ report = JSON.parse(options.body);
+ return response(200, { ok: true, sent: true });
+ },
+ },
+ );
+ assert.equal(result.ok, true);
+ assert.equal(report.phase, "release-notes-validation");
+ assert.deepEqual(report.attempts.map((attempt) => attempt.attempt), [1, 2, 3]);
+ assert.ok(report.attempts.every((attempt) => attempt.error_code === "RELEASE_NOTES_VALIDATION"));
+ assert.match(report.final_error, /language/);
+ } finally {
+ process.env = previous;
+ }
+});
+
+test("does not report semantic validation before all three repairs are exhausted", async () => {
+ let called = false;
+ const result = await reportValidationFailureIfExhausted(
+ {
+ evidence,
+ draft: {
+ repair_attempts: [
+ { stage: "repair", repair_attempt: 1, ok: false, issues: [{ kind: "language" }] },
+ { stage: "repair", repair_attempt: 2, ok: false, issues: [{ kind: "language" }] },
+ ],
+ },
+ },
+ {
+ fetchImpl: async () => {
+ called = true;
+ return response(200, { ok: true });
+ },
+ },
+ );
+ assert.equal(result.skipped, true);
+ assert.equal(called, false);
+});
+
+test("fault injection covers every required cloud-plugin degradation sample", () => {
+ assert.deepEqual(RELEASE_FAULT_CASES, [
+ "none",
+ "mixed_language",
+ "missing_source_refs",
+ "missing_important_commit",
+ "invalid_source_ref",
+ "thirteen_items",
+ "too_long",
+ "manual_notes_missing_payload",
+ ]);
+ const draft = {
+ release_items: [
+ {
+ category: "Added",
+ text_cn: "新增云插件发布能力。",
+ text_en: "Adds cloud plugin release support.",
+ source_refs: ["abc1234"],
+ },
+ ],
+ };
+ const releaseEvidence = {
+ release_note_guidance: {
+ source_ref_category_hints: [{ source_refs: ["abc1234"] }],
+ },
+ };
+
+ assert.deepEqual(
+ injectReleaseFaultCase(draft, releaseEvidence, "missing_source_refs")
+ .release_items[0].source_refs,
+ [],
+ );
+ assert.match(
+ injectReleaseFaultCase(draft, releaseEvidence, "mixed_language", {
+ phase: "postprocess",
+ }).release_items[0].text_en,
+ /中文/,
+ );
+ assert.equal(
+ injectReleaseFaultCase(draft, releaseEvidence, "thirteen_items", {
+ phase: "postprocess",
+ }).release_items.length,
+ 13,
+ );
+});
+
+test("fault injection enters one repair and then accepts a clean draft", async () => {
+ const releaseEvidence = {
+ commits: [
+ {
+ sha: "abc12340000000000000000000000000000000",
+ short_sha: "abc1234",
+ subject: "feat: improve cloud plugin release audit",
+ },
+ ],
+ release_note_guidance: {
+ source_ref_category_hints: [
+ {
+ category: "Added",
+ source_refs: ["abc1234"],
+ subject: "feat: improve cloud plugin release audit",
+ },
+ ],
+ },
+ };
+ const cleanDraft = {
+ ok: true,
+ needs_review: false,
+ release_items: [
+ {
+ category: "Added",
+ text_cn: "**发布审计**:新增云插件发布质量检查。",
+ text_en: "**Release audit**: Adds cloud plugin release quality checks.",
+ source_refs: ["abc1234"],
+ },
+ ],
+ coverage: { required_count: 1, covered_required_count: 1, missing_required_count: 0 },
+ warnings: [],
+ };
+
+ for (const faultCase of [
+ "mixed_language",
+ "missing_source_refs",
+ "missing_important_commit",
+ "invalid_source_ref",
+ "thirteen_items",
+ "too_long",
+ ]) {
+ let requests = 0;
+ const result = await requestValidatedDraft(releaseEvidence, {
+ faultCase,
+ requestImpl: async () => {
+ requests += 1;
+ return cleanDraft;
+ },
+ });
+ assert.equal(result.ok, true, faultCase);
+ assert.equal(result.repair_attempt_count, 1, faultCase);
+ assert.equal(requests, 2, faultCase);
+ assert.ok(result.repair_attempts[0].issues.length > 0, faultCase);
+ }
+});
+
+test("quality report exposes audit limits, attempts, and production source identity", () => {
+ const report = qualityReportFromDraft(
+ {
+ ok: false,
+ needs_review: true,
+ release_items: [],
+ coverage: { needs_review: true, missing_required_count: 1 },
+ validation_attempt_count: 1,
+ repair_attempt_count: 0,
+ repair_attempts: [{ stage: "draft", repair_attempt: 0, ok: false }],
+ },
+ {
+ targetVersion: "0.1.20",
+ previousTag: "v0.1.19",
+ currentTag: "v0.1.20",
+ currentRef: "HEAD",
+ faultCase: "missing_source_refs",
+ },
+ );
+
+ assert.equal(PRODUCT_ID, "openclaw-cloud-plugin");
+ assert.equal(report.product_id, PRODUCT_ID);
+ assert.equal(report.limits.max_items, 12);
+ assert.equal(report.fault_case, "missing_source_refs");
+ assert.equal(report.ok, false);
+ assert.equal(report.validation_attempt_count, 1);
+ assert.ok(report.issues.some((issue) => issue.kind === "empty_release_items"));
+});
+
+test("manual notes require bilingual evidence refs and passed coverage", () => {
+ const valid = `## Changelog
+
+### Added
+- cloud memory
+
+`;
+ assert.equal(validateManualNotes(valid), valid);
+ assert.match(ensureSourceHint(valid), /source-id=openclaw-cloud-plugin/);
+ assert.throws(
+ () =>
+ ensureSourceHint(
+ `${valid}\n`,
+ ),
+ /exactly one Doc Agent source id openclaw-cloud-plugin/,
+ );
+ assert.throws(
+ () =>
+ ensureSourceHint(
+ `${valid}\n`,
+ ),
+ /exactly one Doc Agent source id openclaw-cloud-plugin/,
+ );
+ assert.throws(() => validateManualNotes("## Changelog\n- unsupported"), /evidence block/);
+ assert.throws(
+ () =>
+ validateManualNotes(`## Changelog
+
+### Added
+- cloud memory
+
+`),
+ /category, text_cn, text_en, and valid source_refs/,
+ );
+ assert.throws(
+ () =>
+ validateManualNotes(`## Changelog
+
+### Added
+- cloud memory
+
+`),
+ /text_cn must contain Chinese/,
+ );
+});
+
+test("manual cloud release notes cannot bypass docs readability validation", () => {
+ assert.throws(
+ () =>
+ validateManualNotes(`## Changelog
+
+### Improved
+- noisy cloud release note
+
+`),
+ /concise enough/,
+ );
+});
+
+test("manual release notes also produce docs preview outputs", async () => {
+ const directory = mkdtempSync(join(tmpdir(), "cloud-plugin-manual-preview-"));
+ const previous = { ...process.env };
+ try {
+ const outputPath = join(directory, "github-output.txt");
+ const notesPath = join(directory, "release-notes.md");
+ const reviewedNotesPath = join(directory, "v0.1.19.md");
+ const sourceRef = runGit(process.cwd(), ["rev-parse", "--short", "d053b0a"]);
+ writeFileSync(reviewedNotesPath, `## Changelog
+
+### Improved
+- **系统提示识别优化**:兼容单行压缩内容并降低普通消息误判概率。
+
+`, "utf8");
+ Object.assign(process.env, {
+ RELEASE_VERSION: "0.1.19",
+ RELEASE_TAG: "v0.1.19",
+ RELEASE_EVIDENCE_REF: "v0.1.19",
+ RELEASE_NOTES_FILE: notesPath,
+ MANUAL_RELEASE_NOTES_FILE: reviewedNotesPath,
+ GITHUB_OUTPUT: outputPath,
+ });
+
+ await main();
+
+ const output = readFileSync(outputPath, "utf8");
+ const match = output.match(/docs_preview_markdown_file<<__DOC_AGENT_EOF__\n([\s\S]*?)\n__DOC_AGENT_EOF__/);
+ assert.ok(match, "docs preview markdown output should be written");
+ const preview = readFileSync(match[1], "utf8");
+ assert.match(preview, /MemOS-Docs Plugin Changelog Preview/);
+ assert.match(preview, /OpenClaw 云插件/);
+ assert.match(preview, /System prompt detection/);
+ assert.match(readFileSync(notesPath, "utf8"), /doc-agent: source-id=openclaw-cloud-plugin/);
+ const qualityMatch = output.match(
+ /quality_report_file<<__DOC_AGENT_EOF__\n([\s\S]*?)\n__DOC_AGENT_EOF__/,
+ );
+ assert.ok(qualityMatch, "quality report output should be written");
+ const quality = JSON.parse(readFileSync(qualityMatch[1], "utf8"));
+ assert.equal(quality.ok, true);
+ assert.equal(quality.validation_attempt_count, 1);
+ } finally {
+ process.env = previous;
+ rmSync(directory, { recursive: true, force: true });
+ }
+});
+
+test("manual release notes fail closed when source_refs are absent from real evidence", async () => {
+ const directory = mkdtempSync(join(tmpdir(), "cloud-plugin-manual-invalid-ref-"));
+ const previous = { ...process.env };
+ try {
+ const outputPath = join(directory, "github-output.txt");
+ Object.assign(process.env, {
+ RELEASE_VERSION: "0.1.20",
+ RELEASE_NOTES_FILE: join(directory, "release-notes.md"),
+ MANUAL_RELEASE_NOTES: `## Changelog
+
+### Improved
+- invalid evidence reference
+
+`,
+ GITHUB_OUTPUT: outputPath,
+ });
+
+ await assert.rejects(main(), /Postprocessed release notes require review/);
+
+ const output = readFileSync(outputPath, "utf8");
+ const qualityMatch = output.match(
+ /quality_report_file<<__DOC_AGENT_EOF__\n([\s\S]*?)\n__DOC_AGENT_EOF__/,
+ );
+ assert.ok(qualityMatch, "failed manual notes should still write a quality report");
+ const quality = JSON.parse(readFileSync(qualityMatch[1], "utf8"));
+ assert.equal(quality.ok, false);
+ assert.equal(quality.invalid_item_ref_count, 1);
+ assert.ok(quality.issues.some((issue) => issue.kind === "invalid_source_ref"));
+ } finally {
+ process.env = previous;
+ rmSync(directory, { recursive: true, force: true });
+ }
+});
+
+test("reports three external-operation attempt logs with a sanitized phase", async () => {
+ const directory = mkdtempSync(join(tmpdir(), "cloud-plugin-release-failure-"));
+ const previous = { ...process.env };
+ try {
+ for (const attempt of [1, 2, 3]) writeFileSync(join(directory, `${attempt}.log`), `npm failure ${attempt}`);
+ Object.assign(process.env, {
+ RELEASE_FAILURE_PHASE: "npm-publish",
+ RELEASE_FAILURE_ATTEMPT_DIR: directory,
+ RELEASE_VERSION: "0.1.19",
+ RELEASE_TAG: "v0.1.19",
+ DOC_AGENT_RELEASE_FAILURE_URL: "https://example.invalid/failure",
+ DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN: "test-token",
+ });
+ let report;
+ await reportExternalFailureFromEnv({
+ fetchImpl: async (_url, options) => {
+ report = JSON.parse(options.body);
+ return response(200, { ok: true });
+ },
+ });
+ assert.equal(report.phase, "npm-publish");
+ assert.deepEqual(report.attempts.map((item) => item.message), ["npm failure 1", "npm failure 2", "npm failure 3"]);
+ } finally {
+ process.env = previous;
+ rmSync(directory, { recursive: true, force: true });
+ }
+});
+
+test("reports the real bounded logs in numeric order without inventing missing attempts", async () => {
+ const directory = mkdtempSync(join(tmpdir(), "cloud-plugin-visibility-failure-"));
+ const previous = { ...process.env };
+ try {
+ writeFileSync(join(directory, "1.log"), "first visibility check");
+ writeFileSync(join(directory, "10.log"), "tenth visibility check");
+ writeFileSync(join(directory, "2.log"), "second visibility check");
+ Object.assign(process.env, {
+ RELEASE_FAILURE_PHASE: "npm-publish-verification",
+ RELEASE_FAILURE_ATTEMPT_DIR: directory,
+ RELEASE_VERSION: "0.1.20",
+ RELEASE_TAG: "v0.1.20",
+ DOC_AGENT_RELEASE_FAILURE_URL: "https://example.invalid/failure",
+ DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN: "test-token",
+ });
+ let report;
+ await reportExternalFailureFromEnv({
+ fetchImpl: async (_url, options) => {
+ report = JSON.parse(options.body);
+ return response(200, { ok: true });
+ },
+ });
+ assert.deepEqual(report.attempts.map((item) => item.message), [
+ "first visibility check",
+ "second visibility check",
+ "tenth visibility check",
+ ]);
+ assert.equal(report.final_error, "tenth visibility check");
+ } finally {
+ process.env = previous;
+ rmSync(directory, { recursive: true, force: true });
+ }
+});
+
+test("retries transient draft failures and passes prior error context", async () => {
+ const previous = { ...process.env };
+ try {
+ process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_URL = "https://example.invalid/draft";
+ process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN = "test-token";
+ const requests = [];
+ const fetchImpl = async (_url, options) => {
+ requests.push(JSON.parse(options.body));
+ if (requests.length < 3) return response(503, { detail: "busy" });
+ return response(200, {
+ ok: true,
+ needs_review: false,
+ release_notes_markdown: "## Changelog\n\n### Added\n- ok",
+ });
+ };
+ const result = await requestDraft(evidence, { fetchImpl, sleep: async () => {} });
+ assert.equal(result.ok, true);
+ assert.equal(requests.length, 3);
+ assert.equal(requests[1].workflow_retry_context.previous_errors.length, 1);
+ assert.equal(requests[2].workflow_retry_context.previous_errors.length, 2);
+ } finally {
+ process.env = previous;
+ }
+});
+
+test("passes release-note quality request to the draft service", async () => {
+ const previous = { ...process.env };
+ try {
+ process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_URL = "https://example.invalid/draft";
+ process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN = "test-token";
+ let requestBody;
+ const result = await requestDraft(
+ {
+ ...evidence,
+ release_note_quality_request: RELEASE_NOTE_QUALITY_REQUEST,
+ },
+ {
+ fetchImpl: async (_url, options) => {
+ requestBody = JSON.parse(options.body);
+ return response(200, {
+ ok: true,
+ needs_review: false,
+ release_notes_markdown: "## Changelog\n\n### Improved\n- ok",
+ });
+ },
+ sleep: async () => {},
+ },
+ );
+ assert.equal(result.ok, true);
+ assert.equal(requestBody.release_note_quality_request.candidate_count, 3);
+ assert.equal(requestBody.release_note_quality_request.repair_policy.max_repair_attempts, 3);
+ assert.match(requestBody.release_note_quality_request.selection_policy.join("\n"), /docs-preview readability/);
+ } finally {
+ process.env = previous;
+ }
+});
+
+test("keeps structured needs-review drafts for local validation instead of failing immediately", async () => {
+ const previous = { ...process.env };
+ try {
+ process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_URL = "https://example.invalid/draft";
+ process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN = "test-token";
+ const result = await requestDraft(evidence, {
+ fetchImpl: async () =>
+ response(200, {
+ ok: false,
+ needs_review: true,
+ warnings: ["English output contains CJK text"],
+ release_items: [
+ {
+ category: "Improved",
+ text_cn: "**系统事件过滤增强**:自动跳过后台命令结果。",
+ text_en: "**System-event Filtering**:自动跳过后台命令结果。",
+ source_refs: ["abc1234"],
+ },
+ ],
+ coverage: { needs_review: true, required_count: 1, covered_required_count: 1, missing_required_count: 0 },
+ }),
+ sleep: async () => {},
+ });
+ assert.equal(result.needs_review, true);
+ assert.equal(result.release_items.length, 1);
+ } finally {
+ process.env = previous;
+ }
+});
+
+test("repairs mixed-language structured drafts by sending validation context back to the drafter", async () => {
+ const requests = [];
+ const result = await requestValidatedDraft(evidence, {
+ requestImpl: async (requestEvidence) => {
+ requests.push(requestEvidence);
+ if (requests.length === 1) {
+ return {
+ ok: false,
+ needs_review: true,
+ release_items: [
+ {
+ category: "Improved",
+ text_cn: "**系统事件过滤增强**:自动跳过后台命令结果。",
+ text_en: "**System-event Filtering**:自动跳过后台命令结果。",
+ source_refs: ["abc1234"],
+ },
+ ],
+ coverage: { needs_review: true, required_count: 0, covered_required_count: 0, missing_required_count: 0 },
+ };
+ }
+ assert.equal(requestEvidence.release_notes_repair_context.validation_report.language_issue_count, 1);
+ return {
+ ok: true,
+ needs_review: false,
+ release_items: [
+ {
+ category: "Improved",
+ text_cn: "**系统事件过滤增强**:自动跳过后台命令结果。",
+ text_en: "**System-event Filtering**: Skips background command results automatically.",
+ source_refs: ["abc1234"],
+ },
+ ],
+ coverage: { needs_review: false, required_count: 0, covered_required_count: 0, missing_required_count: 0 },
+ };
+ },
+ });
+ assert.equal(result.ok, true);
+ assert.equal(result.needs_review, false);
+ assert.equal(result.validation_attempt_count, 2);
+ assert.equal(result.repair_attempt_count, 1);
+ assert.match(result.release_notes_markdown, /Skips scheduled tasks, reminders, and background command results/);
+});
+
+test("reports once after three transient failures", async () => {
+ const previous = { ...process.env };
+ try {
+ process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_URL = "https://example.invalid/draft";
+ process.env.DOC_AGENT_RELEASE_FAILURE_URL = "https://example.invalid/failure";
+ process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN = "test-token";
+ const calls = [];
+ const fetchImpl = async (url, options) => {
+ calls.push({ url, body: JSON.parse(options.body) });
+ if (url.includes("/failure")) return response(200, { ok: true, sent: true });
+ return response(503, { detail: "busy" });
+ };
+ await assert.rejects(requestDraft(evidence, { fetchImpl, sleep: async () => {} }), /attempt 3/);
+ const reports = calls.filter((call) => call.url.includes("/failure"));
+ assert.equal(reports.length, 1);
+ assert.deepEqual(reports[0].body.attempts.map((item) => item.attempt), [1, 2, 3]);
+ assert.equal(reports[0].body.repository, "MemTensor/MemOS-Cloud-OpenClaw-Plugin");
+ } finally {
+ process.env = previous;
+ }
+});
+
+test("keeps the original draft failure when the failure-report endpoint is unavailable", async () => {
+ const previous = { ...process.env };
+ try {
+ process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_URL = "https://example.invalid/draft";
+ process.env.DOC_AGENT_RELEASE_FAILURE_URL = "https://example.invalid/failure";
+ process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN = "test-token";
+ let draftCalls = 0;
+ let reportCalls = 0;
+ const fetchImpl = async (url) => {
+ if (url.includes("/failure")) {
+ reportCalls += 1;
+ return response(503, { detail: "failure sink unavailable" });
+ }
+ draftCalls += 1;
+ return response(503, { detail: "draft service busy" });
+ };
+ await assert.rejects(
+ requestDraft(evidence, { fetchImpl, sleep: async () => {} }),
+ /Release-notes draft request failed on attempt 3: HTTP 503/,
+ );
+ assert.equal(draftCalls, 3);
+ assert.equal(reportCalls, 1);
+ } finally {
+ process.env = previous;
+ }
+});
+
+test("requires configured draft URL instead of using a public fallback", async () => {
+ const previous = { ...process.env };
+ try {
+ delete process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_URL;
+ process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN = "test-token";
+ await assert.rejects(
+ requestDraft(evidence, { fetchImpl: async () => response(200, { ok: true }), sleep: async () => {} }),
+ /DOC_AGENT_RELEASE_NOTES_DRAFT_URL secret is required/,
+ );
+ } finally {
+ process.env = previous;
+ }
+});
+
+test("sanitizes configured URLs and IPs before failure reporting", async () => {
+ const previous = { ...process.env };
+ try {
+ process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_URL = "https://example.invalid/draft";
+ process.env.DOC_AGENT_RELEASE_FAILURE_URL = "https://example.invalid/failure";
+ process.env.DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN = "test-token";
+ const calls = [];
+ const fetchImpl = async (url, options) => {
+ calls.push({ url, body: JSON.parse(options.body) });
+ if (url.includes("/failure")) return response(200, { ok: true, sent: true });
+ throw Object.assign(
+ new Error(
+ "connect ECONNREFUSED https://example.invalid/redacted-path 127.0.0.1:4318 " +
+ "with Bearer test-token github_pat_privatevalue ghp_privatevalue npm_privatevalue " +
+ "//registry.npmjs.org/:_authToken=privatevalue",
+ ),
+ { retryable: true },
+ );
+ };
+ await assert.rejects(requestDraft(evidence, { fetchImpl, sleep: async () => {} }), /attempt 3/);
+ const report = calls.find((call) => call.url.includes("/failure"))?.body;
+ assert.ok(report);
+ assert.doesNotMatch(
+ JSON.stringify(report),
+ /example\.invalid|redacted-path|127\.0\.0\.1|test-token|privatevalue/,
+ );
+ assert.match(JSON.stringify(report), /https:\/\/\*\*\*/);
+ assert.match(JSON.stringify(report), /github_pat_\*\*\*|gh_\*\*\*|npm_\*\*\*|_authToken=\*\*\*/);
+ } finally {
+ process.env = previous;
+ }
+});
diff --git a/.github/scripts/resolve-auto-release.mjs b/.github/scripts/resolve-auto-release.mjs
new file mode 100644
index 000000000..2273c53ab
--- /dev/null
+++ b/.github/scripts/resolve-auto-release.mjs
@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+
+import { execFileSync } from "node:child_process";
+import { appendFileSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { compareSemver, parseSemver } from "../../lib/semver.js";
+
+export const VERSION_FILES = [
+ "package.json",
+ "openclaw.plugin.json",
+ "moltbot.plugin.json",
+ "clawdbot.plugin.json",
+];
+
+function clean(value) {
+ return String(value ?? "").trim();
+}
+
+function exactSha(value) {
+ return /^[0-9a-fA-F]{40}$/.test(clean(value));
+}
+
+export function npmDistTagForVersion(version) {
+ const parsed = parseSemver(version);
+ if (!parsed) throw new Error(`version must be valid SemVer; got '${clean(version)}'`);
+ if (parsed.prerelease.length === 0) return "latest";
+ const identifier = String(parsed.prerelease[0] || "").toLowerCase();
+ return ["alpha", "beta", "next"].includes(identifier) ? identifier : "next";
+}
+
+export function versionsFromFiles(root = process.cwd()) {
+ return Object.fromEntries(
+ VERSION_FILES.map((file) => {
+ const payload = JSON.parse(readFileSync(join(root, file), "utf8"));
+ return [file, clean(payload.version)];
+ }),
+ );
+}
+
+export function versionsFromGitRef(ref, root = process.cwd()) {
+ const sourceRef = clean(ref);
+ if (!sourceRef) throw new Error("a git ref is required to read previous versions");
+ return Object.fromEntries(
+ VERSION_FILES.map((file) => {
+ const raw = execFileSync("git", ["show", `${sourceRef}:${file}`], {
+ cwd: root,
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+ return [file, clean(JSON.parse(raw).version)];
+ }),
+ );
+}
+
+function changedVersionFiles(previousVersions, currentVersions) {
+ return VERSION_FILES.filter(
+ (file) => clean(previousVersions?.[file]) !== clean(currentVersions?.[file]),
+ );
+}
+
+function commonVersion(versions, label) {
+ const values = VERSION_FILES.map((file) => clean(versions?.[file]));
+ const missing = VERSION_FILES.filter((_, index) => !values[index]);
+ if (missing.length > 0) {
+ return {
+ ok: false,
+ reason: `${label} is missing version values in ${missing.join(", ")}`,
+ };
+ }
+ const unique = [...new Set(values)];
+ if (unique.length !== 1) {
+ return {
+ ok: false,
+ reason: `${label} has inconsistent versions: ${VERSION_FILES.map((file) => `${file}=${clean(versions?.[file]) || "missing"}`).join(", ")}`,
+ };
+ }
+ return { ok: true, version: unique[0] };
+}
+
+export function inspectVersionTransition({ previousVersions, currentVersions }) {
+ const changedFiles = changedVersionFiles(previousVersions, currentVersions);
+ if (changedFiles.length === 0) {
+ return {
+ ok: true,
+ eligible: false,
+ reason: "the merge did not change any release version value",
+ changed_version_files: [],
+ };
+ }
+
+ const previous = commonVersion(previousVersions, "the pre-merge main source");
+ if (!previous.ok) return { ...previous, eligible: false, changed_version_files: changedFiles };
+ if (changedFiles.length !== VERSION_FILES.length) {
+ const unchanged = VERSION_FILES.filter((file) => !changedFiles.includes(file));
+ return {
+ ok: false,
+ eligible: false,
+ reason: `a release version changed, but all four version files were not updated; unchanged: ${unchanged.join(", ")}`,
+ previous_version: previous.version,
+ version: "",
+ changed_version_files: changedFiles,
+ };
+ }
+ const current = commonVersion(currentVersions, "the merged main source");
+ if (!current.ok) return { ...current, eligible: false, changed_version_files: changedFiles };
+ if (!parseSemver(previous.version) || !parseSemver(current.version)) {
+ return {
+ ok: false,
+ eligible: false,
+ reason: `release versions must be strict SemVer; got ${previous.version} -> ${current.version}`,
+ previous_version: previous.version,
+ version: current.version,
+ changed_version_files: changedFiles,
+ };
+ }
+ if (previous.version.includes("+") || current.version.includes("+")) {
+ return {
+ ok: false,
+ eligible: false,
+ reason: "automatic releases reject SemVer build metadata because npm precedence and immutable v-tags would become ambiguous",
+ previous_version: previous.version,
+ version: current.version,
+ changed_version_files: changedFiles,
+ };
+ }
+ if (compareSemver(current.version, previous.version) <= 0) {
+ return {
+ ok: false,
+ eligible: false,
+ reason: `release version must increase by SemVer precedence; got ${previous.version} -> ${current.version}`,
+ previous_version: previous.version,
+ version: current.version,
+ changed_version_files: changedFiles,
+ };
+ }
+
+ return {
+ ok: true,
+ eligible: true,
+ reason: `all four committed versions increased from ${previous.version} to ${current.version}`,
+ previous_version: previous.version,
+ version: current.version,
+ npm_dist_tag: npmDistTagForVersion(current.version),
+ github_release_prerelease: parseSemver(current.version).prerelease.length > 0,
+ release_notes_path: `.github/release-notes/v${current.version}.md`,
+ changed_version_files: changedFiles,
+ };
+}
+
+export function inspectPullRequestEvent({
+ eventName,
+ merged,
+ baseRef,
+ headRepo,
+ repository,
+ mergeSha,
+ baseSha,
+}) {
+ if (eventName !== "pull_request") {
+ return { ok: true, inspect: false, reason: "manual workflow dispatch" };
+ }
+ if (clean(merged).toLowerCase() !== "true") {
+ return { ok: true, inspect: false, reason: "pull request closed without merge" };
+ }
+ if (baseRef !== "main") {
+ return { ok: true, inspect: false, reason: `pull request targets ${baseRef || "an unknown branch"}, not main` };
+ }
+ if (headRepo !== repository) {
+ return { ok: true, inspect: false, reason: "fork pull requests cannot authorize an automatic release" };
+ }
+ if (!exactSha(mergeSha) || !exactSha(baseSha)) {
+ return {
+ ok: false,
+ inspect: false,
+ reason: "merged PR must provide exact 40-character base and merge commit SHAs",
+ };
+ }
+ return { ok: true, inspect: true, reason: "same-repository PR merged into main" };
+}
+
+export function validateAutoRelease({
+ eventName,
+ merged,
+ baseRef,
+ headRepo,
+ repository,
+ mergeSha,
+ baseSha,
+ previousVersions,
+ currentVersions,
+}) {
+ const event = inspectPullRequestEvent({
+ eventName,
+ merged,
+ baseRef,
+ headRepo,
+ repository,
+ mergeSha,
+ baseSha,
+ });
+ if (!event.ok || !event.inspect) return { ...event, eligible: false };
+ const transition = inspectVersionTransition({ previousVersions, currentVersions });
+ return {
+ ...transition,
+ inspect: true,
+ target_sha: clean(mergeSha),
+ base_sha: clean(baseSha),
+ };
+}
+
+function writeOutputs(result, outputFile) {
+ if (!outputFile) return;
+ appendFileSync(
+ outputFile,
+ [
+ `eligible=${result.eligible === true}`,
+ `reason=${clean(result.reason).replaceAll("\n", " ")}`,
+ `previous_version=${result.previous_version || ""}`,
+ `version=${result.version || ""}`,
+ `npm_dist_tag=${result.npm_dist_tag || ""}`,
+ `github_release_prerelease=${result.github_release_prerelease === true}`,
+ `target_sha=${result.target_sha || ""}`,
+ `base_sha=${result.base_sha || ""}`,
+ `release_notes_path=${result.release_notes_path || ""}`,
+ "",
+ ].join("\n"),
+ "utf8",
+ );
+}
+
+export function main(env = process.env) {
+ const event = inspectPullRequestEvent({
+ eventName: env.EVENT_NAME,
+ merged: env.PR_MERGED,
+ baseRef: env.PR_BASE_REF,
+ headRepo: env.PR_HEAD_REPO,
+ repository: env.GITHUB_REPOSITORY,
+ mergeSha: env.PR_MERGE_SHA,
+ baseSha: env.PR_BASE_SHA,
+ });
+ if (!event.ok || !event.inspect) {
+ const result = { ...event, eligible: false };
+ writeOutputs(result, env.GITHUB_OUTPUT);
+ if (!result.ok) throw new Error(result.reason);
+ console.log(`Automatic release skipped: ${result.reason}`);
+ return result;
+ }
+ const root = env.GITHUB_WORKSPACE || process.cwd();
+ const currentVersions = versionsFromGitRef(env.PR_MERGE_SHA, root);
+ const previousVersions = versionsFromGitRef(env.PR_BASE_SHA, root);
+ const result = validateAutoRelease({
+ eventName: env.EVENT_NAME,
+ merged: env.PR_MERGED,
+ baseRef: env.PR_BASE_REF,
+ headRepo: env.PR_HEAD_REPO,
+ repository: env.GITHUB_REPOSITORY,
+ mergeSha: env.PR_MERGE_SHA,
+ baseSha: env.PR_BASE_SHA,
+ previousVersions,
+ currentVersions,
+ });
+ writeOutputs(result, env.GITHUB_OUTPUT);
+ if (!result.ok) throw new Error(result.reason);
+ console.log(
+ result.eligible
+ ? `Automatic release accepted: ${result.previous_version} -> ${result.version}, npm tag=${result.npm_dist_tag}, target=${result.target_sha}`
+ : `Automatic release skipped: ${result.reason}`,
+ );
+ return result;
+}
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+ try {
+ main();
+ } catch (error) {
+ console.error(`::error::${error?.message || String(error)}`);
+ process.exitCode = 1;
+ }
+}
diff --git a/.github/scripts/resolve-auto-release.test.mjs b/.github/scripts/resolve-auto-release.test.mjs
new file mode 100644
index 000000000..ff0b0ba5e
--- /dev/null
+++ b/.github/scripts/resolve-auto-release.test.mjs
@@ -0,0 +1,175 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import test from "node:test";
+
+import {
+ VERSION_FILES,
+ inspectPullRequestEvent,
+ inspectVersionTransition,
+ npmDistTagForVersion,
+ validateAutoRelease,
+ versionsFromGitRef,
+} from "./resolve-auto-release.mjs";
+
+const MERGE_SHA = "a".repeat(40);
+const BASE_SHA = "b".repeat(40);
+const REPO = "MemTensor/MemOS-Cloud-OpenClaw-Plugin";
+
+function versions(version) {
+ return Object.fromEntries(VERSION_FILES.map((file) => [file, version]));
+}
+
+function valid(overrides = {}) {
+ return {
+ eventName: "pull_request",
+ merged: "true",
+ baseRef: "main",
+ headRepo: REPO,
+ repository: REPO,
+ mergeSha: MERGE_SHA,
+ baseSha: BASE_SHA,
+ previousVersions: versions("0.1.20"),
+ currentVersions: versions("0.1.21"),
+ ...overrides,
+ };
+}
+
+test("accepts a four-file stable version increase without relying on the branch name", () => {
+ const result = validateAutoRelease(valid());
+ assert.equal(result.ok, true);
+ assert.equal(result.eligible, true);
+ assert.equal(result.previous_version, "0.1.20");
+ assert.equal(result.version, "0.1.21");
+ assert.equal(result.npm_dist_tag, "latest");
+ assert.equal(result.github_release_prerelease, false);
+ assert.equal(result.target_sha, MERGE_SHA);
+ assert.equal(result.release_notes_path, ".github/release-notes/v0.1.21.md");
+});
+
+test("derives beta, alpha, next, and fallback prerelease npm channels", () => {
+ assert.equal(npmDistTagForVersion("0.1.21-beta.1"), "beta");
+ assert.equal(npmDistTagForVersion("0.1.21-alpha.2"), "alpha");
+ assert.equal(npmDistTagForVersion("0.1.21-next.3"), "next");
+ assert.equal(npmDistTagForVersion("0.1.21-rc.1"), "next");
+
+ const beta = validateAutoRelease(
+ valid({ currentVersions: versions("0.1.21-beta.0") }),
+ );
+ assert.equal(beta.ok, true);
+ assert.equal(beta.eligible, true);
+ assert.equal(beta.npm_dist_tag, "beta");
+ assert.equal(beta.github_release_prerelease, true);
+});
+
+test("skips ordinary merges whose four version values are unchanged", () => {
+ const result = validateAutoRelease(
+ valid({ currentVersions: versions("0.1.20") }),
+ );
+ assert.equal(result.ok, true);
+ assert.equal(result.eligible, false);
+ assert.match(result.reason, /did not change/);
+});
+
+test("fails closed when only some version files change", () => {
+ const current = versions("0.1.20");
+ current["package.json"] = "0.1.21";
+ const result = inspectVersionTransition({
+ previousVersions: versions("0.1.20"),
+ currentVersions: current,
+ });
+ assert.equal(result.ok, false);
+ assert.match(result.reason, /all four version files were not updated/);
+});
+
+test("fails closed when the merged versions disagree", () => {
+ const current = versions("0.1.21");
+ current["moltbot.plugin.json"] = "0.1.22";
+ const result = validateAutoRelease(valid({ currentVersions: current }));
+ assert.equal(result.ok, false);
+ assert.match(result.reason, /inconsistent versions/);
+});
+
+test("rejects downgrades, equal precedence, and build metadata", () => {
+ for (const [previous, current, pattern] of [
+ ["0.1.21", "0.1.20", /must increase/],
+ ["0.1.21", "0.1.21-beta.1", /must increase/],
+ ["0.1.21+build.1", "0.1.21+build.2", /build metadata/],
+ ]) {
+ const result = inspectVersionTransition({
+ previousVersions: versions(previous),
+ currentVersions: versions(current),
+ });
+ assert.equal(result.ok, false);
+ assert.match(result.reason, pattern);
+ }
+});
+
+test("accepts beta increments and beta-to-stable promotion", () => {
+ for (const [previous, current] of [
+ ["0.1.21-beta.0", "0.1.21-beta.1"],
+ ["0.1.21-beta.1", "0.1.21"],
+ ]) {
+ const result = inspectVersionTransition({
+ previousVersions: versions(previous),
+ currentVersions: versions(current),
+ });
+ assert.equal(result.ok, true);
+ assert.equal(result.eligible, true);
+ }
+});
+
+test("ignores unmerged, fork, and non-main pull requests", () => {
+ for (const input of [
+ valid({ merged: "false" }),
+ valid({ headRepo: "someone/fork" }),
+ valid({ baseRef: "test" }),
+ ]) {
+ const result = inspectPullRequestEvent(input);
+ assert.equal(result.ok, true);
+ assert.equal(result.inspect, false);
+ }
+});
+
+test("requires immutable base and merge SHAs for eligible merged PRs", () => {
+ for (const input of [
+ valid({ mergeSha: "abc123" }),
+ valid({ baseSha: "abc123" }),
+ ]) {
+ const result = validateAutoRelease(input);
+ assert.equal(result.ok, false);
+ assert.match(result.reason, /40-character/);
+ }
+});
+
+test("replays historical beta, stable, and ordinary main merges from immutable refs", () => {
+ for (const [mergeSha, expected] of [
+ ["066f330d00c710ee3e618312c145f58c51c0d84c", { eligible: true, version: "0.1.20-beta.0", tag: "beta" }],
+ ["a317661691bda94054d3d35f8c226e8bfe0018f7", { eligible: true, version: "0.1.20", tag: "latest" }],
+ ["bf3f9b32003c58368521b3f11cdb2bef707f3b13", { eligible: false }],
+ ]) {
+ let baseSha;
+ try {
+ baseSha = String(
+ execFileSync("git", ["rev-parse", `${mergeSha}^1`], {
+ encoding: "utf8",
+ }),
+ ).trim();
+ } catch {
+ return;
+ }
+ const result = validateAutoRelease({
+ ...valid({
+ mergeSha,
+ baseSha,
+ previousVersions: versionsFromGitRef(baseSha),
+ currentVersions: versionsFromGitRef(mergeSha),
+ }),
+ });
+ assert.equal(result.ok, true);
+ assert.equal(result.eligible, expected.eligible);
+ if (expected.eligible) {
+ assert.equal(result.version, expected.version);
+ assert.equal(result.npm_dist_tag, expected.tag);
+ }
+ }
+});
diff --git a/.github/scripts/retry.sh b/.github/scripts/retry.sh
new file mode 100755
index 000000000..233b7fe24
--- /dev/null
+++ b/.github/scripts/retry.sh
@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+attempts="${RETRY_ATTEMPTS:-3}"
+delay="${RETRY_DELAY_SECONDS:-5}"
+max_delay="${RETRY_MAX_DELAY_SECONDS:-60}"
+attempt_dir="${RETRY_ATTEMPT_DIR:-}"
+label="command"
+
+while [ "$#" -gt 0 ]; do
+ case "$1" in
+ --attempts)
+ attempts="$2"
+ shift 2
+ ;;
+ --delay)
+ delay="$2"
+ shift 2
+ ;;
+ --max-delay)
+ max_delay="$2"
+ shift 2
+ ;;
+ --label)
+ label="$2"
+ shift 2
+ ;;
+ --)
+ shift
+ break
+ ;;
+ *)
+ break
+ ;;
+ esac
+done
+
+if [ "$#" -eq 0 ]; then
+ echo "::error::retry.sh requires a command to run." >&2
+ exit 2
+fi
+
+if ! [[ "${attempts}" =~ ^[1-9][0-9]*$ ]]; then
+ echo "::error::Invalid retry attempts: ${attempts}" >&2
+ exit 2
+fi
+
+if ! [[ "${delay}" =~ ^[0-9]+$ ]]; then
+ echo "::error::Invalid retry delay: ${delay}" >&2
+ exit 2
+fi
+
+if ! [[ "${max_delay}" =~ ^[0-9]+$ ]]; then
+ echo "::error::Invalid retry max delay: ${max_delay}" >&2
+ exit 2
+fi
+
+if [ -n "${attempt_dir}" ]; then
+ mkdir -p "${attempt_dir}"
+fi
+
+for attempt in $(seq 1 "${attempts}"); do
+ echo "::group::${label} attempt ${attempt}/${attempts}" >&2
+ set +e
+ if [ -n "${attempt_dir}" ]; then
+ "$@" >"${attempt_dir}/${attempt}.log" 2>&1
+ status=$?
+ sed -n '1,160p' "${attempt_dir}/${attempt}.log"
+ else
+ "$@"
+ status=$?
+ fi
+ set -e
+ echo "::endgroup::" >&2
+
+ if [ "${status}" -eq 0 ]; then
+ exit 0
+ fi
+
+ if [ "${attempt}" -eq "${attempts}" ]; then
+ echo "::error::${label} failed after ${attempts} attempts with exit code ${status}." >&2
+ exit "${status}"
+ fi
+
+ base_sleep=$((delay * (2 ** (attempt - 1))))
+ if [ "${base_sleep}" -gt "${max_delay}" ]; then
+ base_sleep="${max_delay}"
+ fi
+
+ jitter=0
+ if [ "${base_sleep}" -gt 0 ]; then
+ jitter=$((RANDOM % (base_sleep + 1)))
+ fi
+ sleep_seconds=$((base_sleep + jitter))
+ if [ "${sleep_seconds}" -gt "${max_delay}" ]; then
+ sleep_seconds="${max_delay}"
+ fi
+
+ echo "::warning::${label} failed with exit code ${status}; retrying in ${sleep_seconds}s." >&2
+ sleep "${sleep_seconds}"
+done
diff --git a/.github/scripts/retry.test.mjs b/.github/scripts/retry.test.mjs
new file mode 100644
index 000000000..032cc5020
--- /dev/null
+++ b/.github/scripts/retry.test.mjs
@@ -0,0 +1,81 @@
+import assert from "node:assert/strict";
+import { execFileSync, spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+
+const script = join(dirname(fileURLToPath(import.meta.url)), "retry.sh");
+
+test("captures one bounded log per retry attempt", () => {
+ const directory = mkdtempSync(join(tmpdir(), "cloud-plugin-retry-"));
+ const attemptDirectory = join(directory, "attempts");
+ const counter = join(directory, "counter");
+ try {
+ execFileSync(
+ "bash",
+ [
+ script,
+ "--attempts",
+ "3",
+ "--delay",
+ "0",
+ "--max-delay",
+ "0",
+ "--label",
+ "captured retry",
+ "--",
+ "bash",
+ "-c",
+ 'count=0; [ ! -f "$1" ] || count="$(tr -d \'[:space:]\' <"$1")"; count=$((count + 1)); printf \'%s\\n\' "$count" >"$1"; printf \'attempt %s\\n\' "$count"; [ "$count" -ge 3 ]',
+ "retry-attempt",
+ counter,
+ ],
+ {
+ env: { ...process.env, RETRY_ATTEMPT_DIR: attemptDirectory },
+ stdio: ["ignore", "pipe", "pipe"],
+ },
+ );
+ assert.equal(readFileSync(counter, "utf8").trim(), "3");
+ assert.equal(readFileSync(join(attemptDirectory, "1.log"), "utf8").trim(), "attempt 1");
+ assert.equal(readFileSync(join(attemptDirectory, "2.log"), "utf8").trim(), "attempt 2");
+ assert.equal(readFileSync(join(attemptDirectory, "3.log"), "utf8").trim(), "attempt 3");
+ } finally {
+ rmSync(directory, { recursive: true, force: true });
+ }
+});
+
+test("preserves the final command exit code while retaining exhausted-attempt logs", () => {
+ const directory = mkdtempSync(join(tmpdir(), "cloud-plugin-retry-failure-"));
+ try {
+ const result = spawnSync(
+ "bash",
+ [
+ script,
+ "--attempts",
+ "3",
+ "--delay",
+ "0",
+ "--max-delay",
+ "0",
+ "--label",
+ "failed retry",
+ "--",
+ "bash",
+ "-c",
+ 'printf "retry failed\\n"; exit 7',
+ ],
+ {
+ env: { ...process.env, RETRY_ATTEMPT_DIR: directory },
+ encoding: "utf8",
+ },
+ );
+ assert.equal(result.status, 7);
+ for (const attempt of [1, 2, 3]) {
+ assert.equal(readFileSync(join(directory, `${attempt}.log`), "utf8").trim(), "retry failed");
+ }
+ } finally {
+ rmSync(directory, { recursive: true, force: true });
+ }
+});
diff --git a/.github/scripts/validate-github-release-inventory.mjs b/.github/scripts/validate-github-release-inventory.mjs
new file mode 100644
index 000000000..051b97b59
--- /dev/null
+++ b/.github/scripts/validate-github-release-inventory.mjs
@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+export const DOC_AGENT_SOURCE_ID = "openclaw-cloud-plugin";
+
+function releasePages(value) {
+ if (!Array.isArray(value)) return [];
+ if (value.every((item) => Array.isArray(item))) return value;
+ return [value];
+}
+
+export function flattenReleasePages(value) {
+ return releasePages(value)
+ .flat()
+ .filter((item) => item && typeof item === "object");
+}
+
+export function docAgentSourceIds(body) {
+ return [
+ ...String(body || "").matchAll(
+ //g,
+ ),
+ ].map((match) => match[1]);
+}
+
+function releaseSummary(release) {
+ return {
+ id: Number(release?.id || 0),
+ tag_name: String(release?.tag_name || ""),
+ draft: Boolean(release?.draft),
+ prerelease: Boolean(release?.prerelease),
+ target_commitish: String(release?.target_commitish || ""),
+ created_at: String(release?.created_at || ""),
+ };
+}
+
+export function inspectReleaseInventory({
+ pages,
+ tag,
+ expectedDraft,
+ expectedPrerelease,
+ expectedTargetCommitish,
+ requiredSourceId = DOC_AGENT_SOURCE_ID,
+ requireExisting = false,
+ allowPublishedForDraftRerun = false,
+} = {}) {
+ const releaseTag = String(tag || "").trim();
+ const matches = flattenReleasePages(pages).filter(
+ (release) => String(release?.tag_name || "").trim() === releaseTag,
+ );
+ const summaries = matches.map(releaseSummary);
+ const errors = [];
+
+ if (!releaseTag) {
+ errors.push("release tag is required");
+ }
+ if (matches.length === 0) {
+ if (requireExisting) {
+ errors.push(`GitHub Release ${releaseTag} was not visible after creation`);
+ }
+ return {
+ ok: errors.length === 0,
+ state: "absent",
+ tag: releaseTag,
+ count: 0,
+ releases: [],
+ errors,
+ };
+ }
+ if (matches.length > 1) {
+ errors.push(
+ `found ${matches.length} GitHub Releases for ${releaseTag}; refusing ambiguous release metadata`,
+ );
+ return {
+ ok: false,
+ state: "ambiguous",
+ tag: releaseTag,
+ count: matches.length,
+ releases: summaries,
+ errors,
+ };
+ }
+
+ const release = matches[0];
+ if (
+ typeof expectedDraft === "boolean" &&
+ Boolean(release.draft) !== expectedDraft &&
+ !(expectedDraft && allowPublishedForDraftRerun && !release.draft)
+ ) {
+ errors.push(
+ `GitHub Release ${releaseTag} draft=${Boolean(release.draft)}, expected ${expectedDraft}`,
+ );
+ }
+ if (
+ typeof expectedPrerelease === "boolean" &&
+ Boolean(release.prerelease) !== expectedPrerelease
+ ) {
+ errors.push(
+ `GitHub Release ${releaseTag} prerelease=${Boolean(release.prerelease)}, expected ${expectedPrerelease}`,
+ );
+ }
+ const expectedTarget = String(expectedTargetCommitish || "").trim();
+ if (
+ expectedTarget &&
+ String(release.target_commitish || "").trim() !== expectedTarget
+ ) {
+ errors.push(
+ `GitHub Release ${releaseTag} targets ${String(release.target_commitish || "")}, expected ${expectedTarget}`,
+ );
+ }
+
+ const expectedSourceId = String(requiredSourceId || "").trim();
+ const sourceIds = docAgentSourceIds(release.body);
+ if (
+ expectedSourceId &&
+ (sourceIds.length !== 1 || sourceIds[0] !== expectedSourceId)
+ ) {
+ errors.push(
+ `GitHub Release ${releaseTag} must contain exactly one Doc Agent source id ${expectedSourceId}; found ${sourceIds.join(", ") || "none"}`,
+ );
+ }
+
+ return {
+ ok: errors.length === 0,
+ state: "existing",
+ tag: releaseTag,
+ count: 1,
+ releases: summaries,
+ errors,
+ };
+}
+
+function required(name) {
+ const value = String(process.env[name] || "").trim();
+ if (!value) throw new Error(`${name} is required`);
+ return value;
+}
+
+function parseBoolean(name) {
+ const value = required(name);
+ if (!["true", "false"].includes(value)) {
+ throw new Error(`${name} must be true or false`);
+ }
+ return value === "true";
+}
+
+export function main() {
+ const pages = JSON.parse(
+ readFileSync(required("RELEASE_INVENTORY_FILE"), "utf8"),
+ );
+ const report = inspectReleaseInventory({
+ pages,
+ tag: required("RELEASE_TAG"),
+ expectedDraft: parseBoolean("EXPECTED_RELEASE_DRAFT"),
+ expectedPrerelease: parseBoolean("EXPECTED_RELEASE_PRERELEASE"),
+ expectedTargetCommitish: String(
+ process.env.EXPECTED_RELEASE_TARGET || "",
+ ).trim(),
+ requiredSourceId:
+ String(process.env.REQUIRED_DOC_AGENT_SOURCE_ID || "").trim() ||
+ DOC_AGENT_SOURCE_ID,
+ requireExisting:
+ String(process.env.REQUIRE_EXISTING_RELEASE || "false").trim() === "true",
+ allowPublishedForDraftRerun:
+ String(process.env.ALLOW_PUBLISHED_FOR_DRAFT_RERUN || "false").trim() === "true",
+ });
+ process.stdout.write(`${JSON.stringify(report)}\n`);
+ if (!report.ok) process.exitCode = 1;
+}
+
+const isDirectRun =
+ process.argv[1] &&
+ import.meta.url === pathToFileURL(process.argv[1]).href;
+
+if (isDirectRun) {
+ try {
+ main();
+ } catch (error) {
+ console.error(String(error?.message || error));
+ process.exitCode = 1;
+ }
+}
diff --git a/.github/scripts/validate-github-release-inventory.test.mjs b/.github/scripts/validate-github-release-inventory.test.mjs
new file mode 100644
index 000000000..5a50178b2
--- /dev/null
+++ b/.github/scripts/validate-github-release-inventory.test.mjs
@@ -0,0 +1,381 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+import {
+ DOC_AGENT_SOURCE_ID,
+ docAgentSourceIds,
+ inspectReleaseInventory,
+} from "./validate-github-release-inventory.mjs";
+
+function release(overrides = {}) {
+ return {
+ id: 149,
+ tag_name: "v0.1.20",
+ draft: false,
+ prerelease: false,
+ target_commitish: "abc123",
+ body: `## Changelog\n\n`,
+ created_at: "2026-07-27T00:00:00Z",
+ ...overrides,
+ };
+}
+
+test("extracts exact Doc Agent source ids", () => {
+ assert.deepEqual(
+ docAgentSourceIds(
+ "\n",
+ ),
+ ["openclaw-cloud-plugin", "other"],
+ );
+});
+
+test("accepts an absent release unless post-create verification requires it", () => {
+ const absent = inspectReleaseInventory({
+ pages: [[]],
+ tag: "v0.1.20",
+ expectedDraft: false,
+ expectedPrerelease: false,
+ });
+ assert.equal(absent.ok, true);
+ assert.equal(absent.state, "absent");
+
+ const required = inspectReleaseInventory({
+ pages: [[]],
+ tag: "v0.1.20",
+ expectedDraft: false,
+ expectedPrerelease: false,
+ requireExisting: true,
+ });
+ assert.equal(required.ok, false);
+ assert.match(required.errors[0], /not visible/);
+});
+
+test("fails closed on duplicate releases including drafts", () => {
+ const report = inspectReleaseInventory({
+ pages: [[release(), release({ id: 150, draft: true })]],
+ tag: "v0.1.20",
+ expectedDraft: false,
+ expectedPrerelease: false,
+ });
+ assert.equal(report.ok, false);
+ assert.equal(report.state, "ambiguous");
+ assert.match(report.errors[0], /2 GitHub Releases/);
+});
+
+test("verifies target, release flags, and the exact production source id", () => {
+ const valid = inspectReleaseInventory({
+ pages: [[release()]],
+ tag: "v0.1.20",
+ expectedDraft: false,
+ expectedPrerelease: false,
+ expectedTargetCommitish: "abc123",
+ });
+ assert.equal(valid.ok, true);
+
+ const invalid = inspectReleaseInventory({
+ pages: [[
+ release({
+ draft: true,
+ prerelease: true,
+ target_commitish: "wrong",
+ body:
+ "\n" +
+ "",
+ }),
+ ]],
+ tag: "v0.1.20",
+ expectedDraft: false,
+ expectedPrerelease: false,
+ expectedTargetCommitish: "abc123",
+ });
+ assert.equal(invalid.ok, false);
+ assert.equal(invalid.errors.length, 4);
+ assert.ok(invalid.errors.some((error) => /draft=true/.test(error)));
+ assert.ok(invalid.errors.some((error) => /prerelease=true/.test(error)));
+ assert.ok(invalid.errors.some((error) => /targets wrong/.test(error)));
+ assert.ok(invalid.errors.some((error) => /exactly one Doc Agent source id/.test(error)));
+});
+
+test("accepts an already published matching release as an idempotent automatic Draft rerun", () => {
+ const report = inspectReleaseInventory({
+ pages: [[release({ draft: false })]],
+ tag: "v0.1.20",
+ expectedDraft: true,
+ expectedPrerelease: false,
+ expectedTargetCommitish: "abc123",
+ allowPublishedForDraftRerun: true,
+ });
+ assert.equal(report.ok, true);
+ assert.equal(report.state, "existing");
+});
+
+test("release workflow publishes committed main versions and pins recovery to npm gitHead", () => {
+ const workflow = readFileSync(
+ new URL("../workflows/release.yml", import.meta.url),
+ "utf8",
+ );
+ assert.match(workflow, /npm_release_git_head\(\)/);
+ assert.match(
+ workflow,
+ /RELEASE_EVIDENCE_REF: \$\{\{ steps\.release_source\.outputs\.evidence_ref \}\}/,
+ );
+ assert.match(
+ workflow,
+ /release evidence is pinned to npm gitHead/,
+ );
+ assert.match(
+ workflow,
+ /missing GitHub metadata will target npm gitHead \$\{release_commit_sha\}/,
+ );
+ assert.match(
+ workflow,
+ /git tag -a "\$\{release_tag\}" "\$\{RELEASE_COMMIT_SHA\}"/,
+ );
+ assert.match(workflow, /Validate committed release source version/);
+ assert.match(workflow, /validate-release-source-version\.mjs/);
+ assert.match(
+ workflow,
+ /Publishing the already-reviewed \$\{DEFAULT_BRANCH\} commit \$\{release_commit_sha\}/,
+ );
+ assert.match(workflow, /is no longer the head of \$\{DEFAULT_BRANCH\}/);
+ assert.match(
+ workflow,
+ /Normal real releases require git_ref to be the exact 40-character source_commit approved in the dry-run/,
+ );
+ assert.match(
+ workflow,
+ /Recovery requires \$\{PACKAGE_NAME\}@\$\{RELEASE_VERSION\} to already exist on npm/,
+ );
+ assert.match(workflow, /release-source\.json/);
+ assert.match(
+ workflow,
+ /EXPECTED_RELEASE_PRERELEASE: \$\{\{ steps\.release_policy\.outputs\.github_release_prerelease \}\}/,
+ );
+ assert.match(workflow, /release_flags\+=\(--prerelease\)/);
+ assert.ok(
+ workflow.indexOf("Validate committed release source version") <
+ workflow.indexOf('npm publish --access public --tag "${NPM_DIST_TAG}"'),
+ "the committed source version gate must run before npm publish",
+ );
+ assert.match(
+ workflow,
+ /--target "\$\{RELEASE_COMMIT_SHA\}"/,
+ );
+ assert.match(workflow, /gh api --paginate --slurp/);
+ assert.match(workflow, /wait-for-npm-release\.mjs/);
+ assert.match(workflow, /NPM_VISIBILITY_TIMEOUT_SECONDS: "150"/);
+ assert.match(workflow, /NPM_VISIBILITY_INTERVAL_SECONDS: "10"/);
+ assert.match(
+ workflow,
+ /version, gitHead, and dist-tag were not all visible within \$\{NPM_VISIBILITY_TIMEOUT_SECONDS\}s/,
+ );
+ assert.match(workflow, /GITHUB_RELEASE_VISIBILITY_ATTEMPTS: "12"/);
+ assert.match(workflow, /GITHUB_RELEASE_VISIBILITY_INTERVAL_SECONDS: "10"/);
+ assert.match(workflow, /EXPECTED_RELEASE_DRAFT="\$\{CREATE_DRAFT_RELEASE\}"/);
+ assert.match(workflow, /ALLOW_PUBLISHED_FOR_DRAFT_RERUN="\$\{CREATE_DRAFT_RELEASE\}"/);
+ assert.match(
+ workflow,
+ /Refusing to issue a second create request/,
+ );
+ assert.match(
+ workflow,
+ /Verified resume mode enabled; npm version exists, so publish is skipped/,
+ );
+ assert.match(
+ workflow,
+ /this automatic release is locked to merged commit \$\{AUTOMATIC_RELEASE_TARGET\}/,
+ );
+ assert.match(workflow, /report_exhausted_failure "github-release-create"/);
+ assert.match(workflow, /report_exhausted_failure "github-release-verification"/);
+ assert.match(workflow, /report_exhausted_failure "github-release-tag-push"/);
+ assert.doesNotMatch(
+ workflow,
+ /npm version "\$\{RELEASE_VERSION\}".*--no-git-tag-version/,
+ );
+ assert.doesNotMatch(workflow, /npm run sync-version/);
+ assert.doesNotMatch(workflow, /pull-requests: write/);
+ assert.doesNotMatch(workflow, /gh pr create/);
+ assert.doesNotMatch(workflow, /release_branch/);
+ assert.doesNotMatch(workflow, /create_version_pr/);
+ assert.doesNotMatch(workflow, /gh release view/);
+ assert.match(
+ workflow,
+ /CREATE_DRAFT_RELEASE: \$\{\{ github\.event_name == 'pull_request' \|\| inputs\.recover_existing_npm_release == true \}\}/,
+ );
+});
+
+test("real publishes are version-transition-gated and reusable callers are immutable dry runs", () => {
+ const releaseWorkflow = readFileSync(
+ new URL("../workflows/release.yml", import.meta.url),
+ "utf8",
+ );
+ assert.match(
+ releaseWorkflow,
+ /Real releases must be dispatched from the protected default branch/,
+ );
+ assert.match(releaseWorkflow, /pull_request:\s*\n\s*types: \[closed\]/);
+ assert.match(releaseWorkflow, /resolve-auto-release\.mjs/);
+ assert.match(releaseWorkflow, /PR_BASE_SHA: \$\{\{ github\.event\.pull_request\.base\.sha \}\}/);
+ assert.doesNotMatch(releaseWorkflow, /\^release\/v/);
+ assert.match(releaseWorkflow, /--draft/);
+ assert.match(
+ releaseWorkflow,
+ /npm \$\{RELEASE_VERSION\} and tag \$\{release_tag\} were verified before the Draft was created/,
+ );
+ assert.ok(
+ releaseWorkflow.indexOf('npm publish --access public --tag "${NPM_DIST_TAG}"') <
+ releaseWorkflow.indexOf("release_flags+=(--draft)"),
+ "npm must be published and verified before the human-reviewed Draft is created",
+ );
+
+ for (const name of [
+ "pre-merge-dry-run.yml",
+ "post-merge-dry-run.yml",
+ "historical-dry-run.yml",
+ ]) {
+ const workflow = readFileSync(
+ new URL(`../workflows/${name}`, import.meta.url),
+ "utf8",
+ );
+ assert.match(workflow, /dry_run: true/);
+ assert.doesNotMatch(workflow, /dry_run: false/);
+ if (name !== "historical-dry-run.yml") {
+ assert.match(workflow, /wait-for-npm-release\.mjs/);
+ assert.match(workflow, /wait-for-npm-release\.test\.mjs/);
+ }
+ }
+
+ const contractLintWorkflow = readFileSync(
+ new URL("../workflows/workflow-contract-lint.yml", import.meta.url),
+ "utf8",
+ );
+ const preMergeWorkflow = readFileSync(
+ new URL("../workflows/pre-merge-dry-run.yml", import.meta.url),
+ "utf8",
+ );
+ assert.match(preMergeWorkflow, /- "fix\/\*\*"/);
+ assert.match(contractLintWorkflow, /- "fix\/\*\*"/);
+ assert.match(preMergeWorkflow, /pull_request:/);
+ assert.match(preMergeWorkflow, /Validate proposed four-file version transition/);
+ assert.match(preMergeWorkflow, /ref: \$\{\{ github\.sha \}\}/);
+ assert.doesNotMatch(contractLintWorkflow, /- "release\/v\*\*"/);
+ assert.doesNotMatch(preMergeWorkflow, /- "release\/v\*\*"/);
+ assert.match(contractLintWorkflow, /resolve-auto-release\.test\.mjs/);
+ assert.match(contractLintWorkflow, /wait-for-npm-release\.test\.mjs/);
+ assert.match(releaseWorkflow, /^permissions:\s*\n\s*contents: read/m);
+ assert.match(releaseWorkflow, /publish:\s*\n[\s\S]*?permissions:\s*\n\s*contents: write/);
+});
+
+test("dry-run callers use least privilege and do not inherit all repository secrets", () => {
+ const releaseWorkflow = readFileSync(
+ new URL("../workflows/release.yml", import.meta.url),
+ "utf8",
+ );
+ const dryRunWorkflow = readFileSync(
+ new URL("../workflows/release-dry-run.yml", import.meta.url),
+ "utf8",
+ );
+ assert.doesNotMatch(releaseWorkflow, /workflow_call:/);
+ assert.match(releaseWorkflow, /NODE_AUTH_TOKEN: \$\{\{ secrets\.NPM_TOKEN \}\}/);
+ assert.match(
+ releaseWorkflow,
+ /persist-credentials: \$\{\{ github\.event_name == 'pull_request' \|\| inputs\.dry_run != true \}\}/,
+ );
+ assert.match(dryRunWorkflow, /workflow_call:/);
+ assert.match(dryRunWorkflow, /permissions:\s*\n\s*contents: read/);
+ assert.match(dryRunWorkflow, /persist-credentials: false/);
+ assert.doesNotMatch(dryRunWorkflow, /NPM_TOKEN/);
+ assert.doesNotMatch(dryRunWorkflow, /npm publish/);
+ assert.doesNotMatch(dryRunWorkflow, /gh release/);
+ assert.doesNotMatch(dryRunWorkflow, /contents: write/);
+ assert.doesNotMatch(dryRunWorkflow, /pull-requests: write/);
+
+ const preMerge = readFileSync(
+ new URL("../workflows/pre-merge-dry-run.yml", import.meta.url),
+ "utf8",
+ );
+ assert.match(preMerge, /permissions:\s*\n\s*contents: read/);
+ assert.match(preMerge, /uses: \.\/\.github\/workflows\/release-dry-run\.yml/);
+ assert.match(preMerge, /release_notes: \|/);
+ assert.match(preMerge, /doc-agent-release-notes-json/);
+ assert.doesNotMatch(preMerge, /\$\{\{\s*secrets\./);
+ assert.doesNotMatch(preMerge, /secrets: inherit/);
+ assert.doesNotMatch(preMerge, /contents: write/);
+ assert.doesNotMatch(preMerge, /pull-requests: write/);
+
+ for (const name of [
+ "post-merge-dry-run.yml",
+ "historical-dry-run.yml",
+ ]) {
+ const workflow = readFileSync(
+ new URL(`../workflows/${name}`, import.meta.url),
+ "utf8",
+ );
+ assert.match(workflow, /permissions:\s*\n(?:\s*#[^\n]*\n)*\s*contents: read/);
+ assert.match(workflow, /uses: \.\/\.github\/workflows\/release-dry-run\.yml/);
+ assert.doesNotMatch(workflow, /secrets: inherit/);
+ assert.doesNotMatch(workflow, /NPM_TOKEN/);
+ assert.doesNotMatch(workflow, /contents: write/);
+ assert.doesNotMatch(workflow, /pull-requests: write/);
+ }
+
+ const postMerge = readFileSync(
+ new URL("../workflows/post-merge-dry-run.yml", import.meta.url),
+ "utf8",
+ );
+ assert.match(postMerge, /version: \$\{\{ needs\.release_source\.outputs\.version \}\}/);
+ assert.match(
+ postMerge,
+ /expected_current_ref: \$\{\{ needs\.release_source\.outputs\.source_sha \}\}/,
+ );
+ assert.match(postMerge, /enforce_source_version: true/);
+ assert.doesNotMatch(postMerge, /version: "0\.1\.19"/);
+
+ const preMergeDryRun = readFileSync(
+ new URL("../workflows/pre-merge-dry-run.yml", import.meta.url),
+ "utf8",
+ );
+ assert.match(preMergeDryRun, /enforce_source_version: false/);
+
+ const historical = readFileSync(
+ new URL("../workflows/historical-dry-run.yml", import.meta.url),
+ "utf8",
+ );
+ assert.match(historical, /enforce_source_version: false/);
+ assert.match(historical, /github\.event\.repository\.default_branch/);
+ for (const [version, previousTag] of [
+ ["0.1.15", "v0.1.14"],
+ ["0.1.16", "v0.1.15"],
+ ["0.1.17", "v0.1.16"],
+ ["0.1.18", "v0.1.17"],
+ ["0.1.19", "v0.1.18"],
+ ]) {
+ assert.match(
+ historical,
+ new RegExp(
+ `version: "${version.replaceAll(".", "\\.")}"\\s+expected_previous_tag: "${previousTag.replaceAll(".", "\\.")}"\\s+expected_current_ref: "v${version.replaceAll(".", "\\.")}"`,
+ ),
+ );
+ }
+
+ const contractLint = readFileSync(
+ new URL("../workflows/workflow-contract-lint.yml", import.meta.url),
+ "utf8",
+ );
+ assert.match(contractLint, /permissions:\s*\n\s*contents: read/);
+ assert.match(contractLint, /persist-credentials: false/);
+ assert.match(contractLint, /ACTIONLINT_VERSION: "1\.7\.12"/);
+ assert.match(
+ contractLint,
+ /ACTIONLINT_LINUX_AMD64_SHA256: "8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8"/,
+ );
+ assert.match(
+ contractLint,
+ /node --test \.github\/scripts\/resolve-auto-release\.test\.mjs \.github\/scripts\/validate-github-release-inventory\.test\.mjs \.github\/scripts\/validate-release-confirmation\.test\.mjs \.github\/scripts\/validate-release-source-version\.test\.mjs/,
+ );
+ assert.doesNotMatch(contractLint, /secrets:/);
+ assert.doesNotMatch(contractLint, /contents: write/);
+ assert.doesNotMatch(contractLint, /pull-requests: write/);
+ assert.doesNotMatch(contractLint, /uses: \.\/\.github\/workflows\/release/);
+});
diff --git a/.github/scripts/validate-release-confirmation.mjs b/.github/scripts/validate-release-confirmation.mjs
new file mode 100644
index 000000000..e0b5b1509
--- /dev/null
+++ b/.github/scripts/validate-release-confirmation.mjs
@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+import { appendFileSync } from "node:fs";
+import { cleanVersion, parseSemver } from "../../lib/semver.js";
+
+export function expectedReleaseConfirmation(version) {
+ const versionWithoutPrefix = cleanVersion(version);
+ return `PUBLISH v${versionWithoutPrefix}`;
+}
+
+export function validateReleaseChannel({ version, npmDistTag }) {
+ const parsed = parseSemver(version);
+ const tag = String(npmDistTag || "").trim();
+ if (!parsed) {
+ return {
+ ok: false,
+ reason: `version must be a valid SemVer value; got '${String(version || "").trim()}'.`,
+ };
+ }
+ if (!tag) {
+ return { ok: false, reason: "npm dist-tag is required." };
+ }
+
+ const isPrerelease = parsed.prerelease.length > 0;
+ const prereleaseIdentifier = isPrerelease
+ ? String(parsed.prerelease[0] || "").toLowerCase()
+ : "";
+ const expectedNpmDistTag = isPrerelease
+ ? ["alpha", "beta", "next"].includes(prereleaseIdentifier)
+ ? prereleaseIdentifier
+ : "next"
+ : "latest";
+
+ if (tag !== expectedNpmDistTag) {
+ return {
+ ok: false,
+ reason: isPrerelease
+ ? `prerelease version ${cleanVersion(version)} must use npm dist-tag '${expectedNpmDistTag}'; got '${tag}'.`
+ : `stable version ${cleanVersion(version)} must use npm dist-tag 'latest'; got '${tag}'.`,
+ };
+ }
+
+ return {
+ ok: true,
+ release_channel: isPrerelease ? "prerelease" : "stable",
+ prerelease_identifier: prereleaseIdentifier,
+ expected_npm_dist_tag: expectedNpmDistTag,
+ github_release_prerelease: isPrerelease,
+ docs_sync_expected: !isPrerelease,
+ reason: isPrerelease
+ ? `prerelease version will publish on npm '${tag}', use a GitHub Prerelease, and skip formal Docs sync.`
+ : "stable version will publish on npm 'latest'; formal Docs sync starts only after its GitHub Release is published.",
+ };
+}
+
+export function validateReleaseConfirmation({
+ version,
+ dryRun,
+ confirmation,
+ automaticRelease = false,
+}) {
+ const isDryRun = String(dryRun ?? "true").trim().toLowerCase() === "true";
+ const expected = expectedReleaseConfirmation(version);
+
+ if (isDryRun) {
+ return {
+ ok: true,
+ expected,
+ reason: "dry_run=true; publish confirmation is not required.",
+ };
+ }
+
+ if (String(automaticRelease).trim().toLowerCase() === "true") {
+ return {
+ ok: true,
+ expected,
+ reason:
+ "trusted four-file version increase on merged main accepted; the reviewed version PR is the publish authorization and the GitHub Release will remain Draft for human review.",
+ };
+ }
+
+ if (String(confirmation || "").trim() === expected) {
+ return {
+ ok: true,
+ expected,
+ reason: "publish confirmation accepted.",
+ };
+ }
+
+ return {
+ ok: false,
+ expected,
+ reason:
+ "dry_run=false would perform release side effects; " +
+ `publish_confirmation must exactly equal '${expected}'.`,
+ };
+}
+
+export function main(env = process.env) {
+ const channel = validateReleaseChannel({
+ version: env.RELEASE_VERSION,
+ npmDistTag: env.NPM_DIST_TAG,
+ });
+ if (!channel.ok) {
+ throw new Error(channel.reason);
+ }
+
+ const result = validateReleaseConfirmation({
+ version: env.RELEASE_VERSION,
+ dryRun: env.DRY_RUN,
+ confirmation: env.PUBLISH_CONFIRMATION,
+ automaticRelease: env.AUTOMATIC_RELEASE,
+ });
+
+ if (!result.ok) {
+ throw new Error(result.reason);
+ }
+
+ console.log(channel.reason);
+ console.log(result.reason);
+ if (result.expected) {
+ console.log(`Expected confirmation: ${result.expected}`);
+ }
+ if (env.GITHUB_OUTPUT) {
+ appendFileSync(
+ env.GITHUB_OUTPUT,
+ [
+ `release_channel=${channel.release_channel}`,
+ `prerelease_identifier=${channel.prerelease_identifier}`,
+ `npm_dist_tag=${channel.expected_npm_dist_tag}`,
+ `github_release_prerelease=${channel.github_release_prerelease}`,
+ `docs_sync_expected=${channel.docs_sync_expected}`,
+ "",
+ ].join("\n"),
+ "utf8",
+ );
+ }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+ try {
+ main();
+ } catch (error) {
+ console.error(`::error::${error?.message || String(error)}`);
+ process.exitCode = 1;
+ }
+}
diff --git a/.github/scripts/validate-release-confirmation.test.mjs b/.github/scripts/validate-release-confirmation.test.mjs
new file mode 100644
index 000000000..b1fbe5991
--- /dev/null
+++ b/.github/scripts/validate-release-confirmation.test.mjs
@@ -0,0 +1,124 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import {
+ expectedReleaseConfirmation,
+ main,
+ validateReleaseChannel,
+ validateReleaseConfirmation,
+} from "./validate-release-confirmation.mjs";
+
+test("builds the exact publish confirmation phrase from a version", () => {
+ assert.equal(expectedReleaseConfirmation("0.1.20"), "PUBLISH v0.1.20");
+ assert.equal(expectedReleaseConfirmation("v0.1.20-beta.1"), "PUBLISH v0.1.20-beta.1");
+});
+
+test("does not require publish confirmation for dry runs", () => {
+ assert.equal(
+ validateReleaseConfirmation({
+ version: "0.1.20",
+ dryRun: "true",
+ confirmation: "",
+ }).ok,
+ true,
+ );
+});
+
+test("requires stable versions to use latest and prereleases to use a preview channel", () => {
+ const stable = validateReleaseChannel({ version: "0.1.20", npmDistTag: "latest" });
+ assert.equal(stable.ok, true);
+ assert.equal(stable.release_channel, "stable");
+ assert.equal(stable.github_release_prerelease, false);
+ assert.equal(stable.docs_sync_expected, true);
+
+ const beta = validateReleaseChannel({ version: "0.1.20-beta.1", npmDistTag: "beta" });
+ assert.equal(beta.ok, true);
+ assert.equal(beta.release_channel, "prerelease");
+ assert.equal(beta.prerelease_identifier, "beta");
+ assert.equal(beta.expected_npm_dist_tag, "beta");
+ assert.equal(beta.github_release_prerelease, true);
+ assert.equal(beta.docs_sync_expected, false);
+
+ const releaseCandidate = validateReleaseChannel({
+ version: "0.1.20-rc.1",
+ npmDistTag: "next",
+ });
+ assert.equal(releaseCandidate.ok, true);
+ assert.equal(releaseCandidate.expected_npm_dist_tag, "next");
+
+ const prereleaseOnLatest = validateReleaseChannel({
+ version: "0.1.20-beta.1",
+ npmDistTag: "latest",
+ });
+ assert.equal(prereleaseOnLatest.ok, false);
+ assert.match(prereleaseOnLatest.reason, /must use npm dist-tag 'beta'/);
+
+ const betaOnAlpha = validateReleaseChannel({
+ version: "0.1.20-beta.1",
+ npmDistTag: "alpha",
+ });
+ assert.equal(betaOnAlpha.ok, false);
+ assert.match(betaOnAlpha.reason, /must use npm dist-tag 'beta'/);
+
+ const stableOnBeta = validateReleaseChannel({ version: "0.1.20", npmDistTag: "beta" });
+ assert.equal(stableOnBeta.ok, false);
+ assert.match(stableOnBeta.reason, /must use npm dist-tag 'latest'/);
+});
+
+test("requires exact publish confirmation before a real release", () => {
+ assert.equal(
+ validateReleaseConfirmation({
+ version: "0.1.20",
+ dryRun: "false",
+ confirmation: "",
+ }).ok,
+ false,
+ );
+ assert.equal(
+ validateReleaseConfirmation({
+ version: "0.1.20",
+ dryRun: "false",
+ confirmation: "PUBLISH 0.1.20",
+ }).ok,
+ false,
+ );
+ assert.equal(
+ validateReleaseConfirmation({
+ version: "0.1.20",
+ dryRun: "false",
+ confirmation: "PUBLISH v0.1.20",
+ }).ok,
+ true,
+ );
+});
+
+test("uses a reviewed merged version PR as the confirmation for an automatic Draft release", () => {
+ const result = validateReleaseConfirmation({
+ version: "0.1.21",
+ dryRun: "false",
+ confirmation: "",
+ automaticRelease: "true",
+ });
+ assert.equal(result.ok, true);
+ assert.match(result.reason, /four-file version increase/);
+});
+
+test("exports deterministic beta and Docs routing metadata for workflows", () => {
+ const output = join(mkdtempSync(join(tmpdir(), "openclaw-release-policy-")), "output");
+ main({
+ RELEASE_VERSION: "0.1.20-beta.1",
+ NPM_DIST_TAG: "beta",
+ DRY_RUN: "true",
+ PUBLISH_CONFIRMATION: "",
+ GITHUB_OUTPUT: output,
+ });
+ const values = readFileSync(output, "utf8");
+ assert.match(values, /^release_channel=prerelease$/m);
+ assert.match(values, /^prerelease_identifier=beta$/m);
+ assert.match(values, /^npm_dist_tag=beta$/m);
+ assert.match(values, /^github_release_prerelease=true$/m);
+ assert.match(values, /^docs_sync_expected=false$/m);
+});
diff --git a/.github/scripts/validate-release-source-version.mjs b/.github/scripts/validate-release-source-version.mjs
new file mode 100644
index 000000000..e00266e5f
--- /dev/null
+++ b/.github/scripts/validate-release-source-version.mjs
@@ -0,0 +1,102 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+export const RELEASE_VERSION_FILES = [
+ "package.json",
+ "openclaw.plugin.json",
+ "moltbot.plugin.json",
+ "clawdbot.plugin.json",
+];
+
+function clean(value) {
+ return String(value ?? "").trim();
+}
+
+function readJsonAtRef(file, sourceRef) {
+ const raw =
+ sourceRef === "WORKTREE"
+ ? readFileSync(file, "utf8")
+ : execFileSync("git", ["show", `${sourceRef}:${file}`], {
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+ return JSON.parse(raw);
+}
+
+export function inspectReleaseSourceVersion({
+ expectedVersion,
+ sourceRef = "HEAD",
+ files = RELEASE_VERSION_FILES,
+} = {}) {
+ const expected = clean(expectedVersion);
+ const ref = clean(sourceRef) || "HEAD";
+ if (!expected) {
+ throw new Error("RELEASE_VERSION is required.");
+ }
+
+ const versions = [];
+ for (const file of files) {
+ try {
+ const value = readJsonAtRef(file, ref);
+ versions.push({
+ file,
+ version: clean(value?.version),
+ ok: clean(value?.version) === expected,
+ error: "",
+ });
+ } catch (error) {
+ versions.push({
+ file,
+ version: "",
+ ok: false,
+ error: clean(error?.message || error),
+ });
+ }
+ }
+
+ const mismatches = versions.filter((entry) => !entry.ok);
+ return {
+ ok: mismatches.length === 0,
+ expected_version: expected,
+ source_ref: ref,
+ versions,
+ mismatches,
+ };
+}
+
+export function formatReleaseSourceVersionError(report) {
+ const lines = [
+ `Release source ${report.source_ref} is not ready for version ${report.expected_version}.`,
+ "The publish workflow only consumes committed versions; it does not modify source files or create a version PR.",
+ ];
+ for (const entry of report.mismatches) {
+ const actual = entry.version || (entry.error ? "unreadable" : "missing");
+ lines.push(`- ${entry.file}: expected ${report.expected_version}, got ${actual}`);
+ }
+ lines.push(
+ "Update all four version files in a normal reviewed PR, merge it to main, then rerun the dry-run.",
+ );
+ return lines.join("\n");
+}
+
+export function run() {
+ const report = inspectReleaseSourceVersion({
+ expectedVersion: process.env.RELEASE_VERSION,
+ sourceRef: process.env.RELEASE_SOURCE_REF || "HEAD",
+ });
+ if (!report.ok) {
+ console.error(`::error::${formatReleaseSourceVersionError(report)}`);
+ process.exitCode = 1;
+ return report;
+ }
+
+ console.log(
+ `Validated ${report.expected_version} in ${RELEASE_VERSION_FILES.length} committed version files at ${report.source_ref}.`,
+ );
+ return report;
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+ run();
+}
diff --git a/.github/scripts/validate-release-source-version.test.mjs b/.github/scripts/validate-release-source-version.test.mjs
new file mode 100644
index 000000000..7f4900c7c
--- /dev/null
+++ b/.github/scripts/validate-release-source-version.test.mjs
@@ -0,0 +1,119 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import {
+ formatReleaseSourceVersionError,
+ inspectReleaseSourceVersion,
+ RELEASE_VERSION_FILES,
+} from "./validate-release-source-version.mjs";
+
+function fixture(versions) {
+ const root = mkdtempSync(join(tmpdir(), "openclaw-release-source-"));
+ for (const file of RELEASE_VERSION_FILES) {
+ writeFileSync(
+ join(root, file),
+ `${JSON.stringify({ version: versions[file] }, null, 2)}\n`,
+ "utf8",
+ );
+ }
+ return root;
+}
+
+function inspectWorktree(root, expectedVersion) {
+ const cwd = process.cwd();
+ process.chdir(root);
+ try {
+ return inspectReleaseSourceVersion({
+ expectedVersion,
+ sourceRef: "WORKTREE",
+ });
+ } finally {
+ process.chdir(cwd);
+ }
+}
+
+function git(root, args) {
+ return execFileSync("git", args, {
+ cwd: root,
+ encoding: "utf8",
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+}
+
+test("accepts a source only when all release version files match", () => {
+ const versions = Object.fromEntries(
+ RELEASE_VERSION_FILES.map((file) => [file, "0.1.20"]),
+ );
+ const report = inspectWorktree(fixture(versions), "0.1.20");
+ assert.equal(report.ok, true);
+ assert.equal(report.mismatches.length, 0);
+});
+
+test("reports every mismatched or missing version before publish", () => {
+ const root = fixture({
+ "package.json": "0.1.20",
+ "openclaw.plugin.json": "0.1.20-beta.0",
+ "moltbot.plugin.json": "",
+ "clawdbot.plugin.json": "0.1.19",
+ });
+ const report = inspectWorktree(root, "0.1.20");
+ assert.equal(report.ok, false);
+ assert.deepEqual(
+ report.mismatches.map((entry) => entry.file),
+ [
+ "openclaw.plugin.json",
+ "moltbot.plugin.json",
+ "clawdbot.plugin.json",
+ ],
+ );
+
+ const message = formatReleaseSourceVersionError(report);
+ assert.match(message, /does not modify source files or create a version PR/);
+ assert.match(message, /openclaw\.plugin\.json: expected 0\.1\.20, got 0\.1\.20-beta\.0/);
+ assert.match(message, /normal reviewed PR/);
+});
+
+test("reads the committed Git ref instead of uncommitted worktree changes", () => {
+ const versions = Object.fromEntries(
+ RELEASE_VERSION_FILES.map((file) => [file, "0.1.20-beta.1"]),
+ );
+ const root = fixture(versions);
+ git(root, ["init"]);
+ git(root, ["add", ...RELEASE_VERSION_FILES]);
+ git(root, [
+ "-c",
+ "user.name=release-test",
+ "-c",
+ "user.email=release-test@example.com",
+ "commit",
+ "-m",
+ "release fixture",
+ ]);
+ writeFileSync(
+ join(root, "package.json"),
+ `${JSON.stringify({ version: "0.1.20" }, null, 2)}\n`,
+ "utf8",
+ );
+
+ const cwd = process.cwd();
+ process.chdir(root);
+ try {
+ const committed = inspectReleaseSourceVersion({
+ expectedVersion: "0.1.20-beta.1",
+ sourceRef: "HEAD",
+ });
+ const worktree = inspectReleaseSourceVersion({
+ expectedVersion: "0.1.20-beta.1",
+ sourceRef: "WORKTREE",
+ });
+ assert.equal(committed.ok, true);
+ assert.equal(worktree.ok, false);
+ assert.equal(worktree.mismatches[0].file, "package.json");
+ } finally {
+ process.chdir(cwd);
+ }
+});
diff --git a/.github/scripts/wait-for-npm-release.mjs b/.github/scripts/wait-for-npm-release.mjs
new file mode 100644
index 000000000..dab99acce
--- /dev/null
+++ b/.github/scripts/wait-for-npm-release.mjs
@@ -0,0 +1,240 @@
+import { pathToFileURL } from "node:url";
+
+const SHA_PATTERN = /^[0-9a-f]{40}$/i;
+
+function clean(value) {
+ return String(value ?? "").trim();
+}
+
+function positiveInteger(value, fallback, name) {
+ const parsed = Number.parseInt(String(value ?? ""), 10);
+ if (!Number.isFinite(parsed) || parsed <= 0) {
+ if (fallback !== undefined) {
+ return fallback;
+ }
+ throw new Error(`${name} must be a positive integer.`);
+ }
+ return parsed;
+}
+
+export function npmPackumentUrl(registryUrl, packageName, cacheBust = Date.now()) {
+ const registry = clean(registryUrl || "https://registry.npmjs.org").replace(/\/+$/, "");
+ const name = clean(packageName);
+ if (!name) {
+ throw new Error("NPM_PACKAGE_NAME is required.");
+ }
+ const encodedName = encodeURIComponent(name).replace(/^%40/i, "@");
+ return `${registry}/${encodedName}?cache-bust=${encodeURIComponent(cacheBust)}`;
+}
+
+export function inspectNpmReleaseVisibility({
+ packument,
+ version,
+ distTag,
+ expectedGitHead,
+} = {}) {
+ const targetVersion = clean(version);
+ const targetDistTag = clean(distTag);
+ const expected = clean(expectedGitHead).toLowerCase();
+ if (!targetVersion) {
+ throw new Error("NPM_RELEASE_VERSION is required.");
+ }
+ if (!targetDistTag) {
+ throw new Error("NPM_DIST_TAG is required.");
+ }
+ if (!SHA_PATTERN.test(expected)) {
+ throw new Error("NPM_EXPECTED_GIT_HEAD must be an exact 40-character commit SHA.");
+ }
+
+ const release = packument?.versions?.[targetVersion];
+ if (!release) {
+ return {
+ ok: false,
+ fatal: false,
+ reason: `version ${targetVersion} is not visible`,
+ };
+ }
+
+ const actualGitHead = clean(release.gitHead).toLowerCase();
+ if (!SHA_PATTERN.test(actualGitHead)) {
+ return {
+ ok: false,
+ fatal: false,
+ reason: `version ${targetVersion} is visible but its 40-character gitHead is not`,
+ };
+ }
+ if (actualGitHead !== expected) {
+ return {
+ ok: false,
+ fatal: true,
+ reason: `version ${targetVersion} records gitHead ${actualGitHead}, expected ${expected}`,
+ };
+ }
+
+ const actualDistTagVersion = clean(packument?.["dist-tags"]?.[targetDistTag]);
+ if (actualDistTagVersion !== targetVersion) {
+ return {
+ ok: false,
+ fatal: false,
+ reason:
+ `dist-tag ${targetDistTag} points to ${actualDistTagVersion || "nothing"}, ` +
+ `expected ${targetVersion}`,
+ };
+ }
+
+ return {
+ ok: true,
+ fatal: false,
+ reason: "visible",
+ version: targetVersion,
+ git_head: actualGitHead,
+ dist_tag: targetDistTag,
+ dist_tag_version: actualDistTagVersion,
+ };
+}
+
+function pending(reason) {
+ return { ok: false, fatal: false, reason };
+}
+
+export async function waitForNpmReleaseVisibility(
+ {
+ packageName,
+ version,
+ distTag,
+ expectedGitHead,
+ registryUrl = "https://registry.npmjs.org",
+ timeoutMs = 150_000,
+ intervalMs = 10_000,
+ requestTimeoutMs = 8_000,
+ } = {},
+ {
+ fetchImpl = globalThis.fetch,
+ sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+ now = () => Date.now(),
+ log = (message) => console.log(message),
+ } = {},
+) {
+ if (typeof fetchImpl !== "function") {
+ throw new Error("A fetch implementation is required.");
+ }
+ const totalTimeoutMs = positiveInteger(timeoutMs, undefined, "timeoutMs");
+ const pollIntervalMs = positiveInteger(intervalMs, undefined, "intervalMs");
+ const singleRequestTimeoutMs = positiveInteger(
+ requestTimeoutMs,
+ undefined,
+ "requestTimeoutMs",
+ );
+ // Validate immutable inputs before starting the bounded wait.
+ inspectNpmReleaseVisibility({
+ packument: {},
+ version,
+ distTag,
+ expectedGitHead,
+ });
+
+ const startedAt = now();
+ const deadline = startedAt + totalTimeoutMs;
+ let attempt = 0;
+ let lastReport = pending("registry has not been queried");
+
+ while (now() < deadline) {
+ attempt += 1;
+ const remainingBeforeRequest = Math.max(1, deadline - now());
+ const controller = new AbortController();
+ const requestTimer = setTimeout(
+ () => controller.abort(),
+ Math.min(singleRequestTimeoutMs, remainingBeforeRequest),
+ );
+ try {
+ const response = await fetchImpl(npmPackumentUrl(registryUrl, packageName, now()), {
+ headers: {
+ // The install-v1 packument intentionally omits gitHead. The release
+ // gate needs the full metadata document to verify immutable source.
+ accept: "application/json",
+ "cache-control": "no-cache, no-store, max-age=0",
+ pragma: "no-cache",
+ },
+ signal: controller.signal,
+ });
+ if (response.status === 404) {
+ lastReport = pending(`registry returned 404 for ${packageName}`);
+ } else if (response.status === 401 || response.status === 403) {
+ lastReport = {
+ ok: false,
+ fatal: true,
+ reason: `registry returned HTTP ${response.status}`,
+ };
+ } else if (!response.ok) {
+ lastReport = pending(`registry returned HTTP ${response.status}`);
+ } else {
+ lastReport = inspectNpmReleaseVisibility({
+ packument: await response.json(),
+ version,
+ distTag,
+ expectedGitHead,
+ });
+ }
+ } catch (error) {
+ const reason = error?.name === "AbortError" ? "registry request timed out" : clean(error?.message || error);
+ lastReport = pending(reason || "registry request failed");
+ } finally {
+ clearTimeout(requestTimer);
+ }
+
+ if (lastReport.ok) {
+ log(
+ `npm release verified after ${attempt} attempt(s): ` +
+ `${packageName}@${version}, gitHead=${lastReport.git_head}, ` +
+ `${distTag}=${lastReport.dist_tag_version}.`,
+ );
+ return { ...lastReport, attempts: attempt, elapsed_ms: now() - startedAt };
+ }
+ if (lastReport.fatal) {
+ const error = new Error(`npm release verification failed: ${lastReport.reason}.`);
+ error.code = "NPM_METADATA_MISMATCH";
+ throw error;
+ }
+
+ const remaining = deadline - now();
+ log(
+ `npm visibility attempt ${attempt} pending: ${lastReport.reason}; ` +
+ `${Math.max(0, Math.ceil(remaining / 1000))}s remain.`,
+ );
+ if (remaining <= 0) {
+ break;
+ }
+ await sleep(Math.min(pollIntervalMs, remaining));
+ }
+
+ throw new Error(
+ `npm release was not fully visible within ${Math.ceil(totalTimeoutMs / 1000)}s: ` +
+ `${lastReport.reason}.`,
+ );
+}
+
+export async function run(env = process.env) {
+ try {
+ const report = await waitForNpmReleaseVisibility({
+ packageName: env.NPM_PACKAGE_NAME,
+ version: env.NPM_RELEASE_VERSION,
+ distTag: env.NPM_DIST_TAG,
+ expectedGitHead: env.NPM_EXPECTED_GIT_HEAD,
+ registryUrl: env.NPM_CONFIG_REGISTRY || "https://registry.npmjs.org",
+ timeoutMs: positiveInteger(env.NPM_VISIBILITY_TIMEOUT_SECONDS, 150, "timeout") * 1000,
+ intervalMs: positiveInteger(env.NPM_VISIBILITY_INTERVAL_SECONDS, 10, "interval") * 1000,
+ requestTimeoutMs:
+ positiveInteger(env.NPM_VISIBILITY_REQUEST_TIMEOUT_SECONDS, 8, "request timeout") * 1000,
+ });
+ console.log(JSON.stringify(report));
+ return report;
+ } catch (error) {
+ console.error(`::error::${clean(error?.message || error)}`);
+ process.exitCode = error?.code === "NPM_METADATA_MISMATCH" ? 2 : 1;
+ return null;
+ }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+ await run();
+}
diff --git a/.github/scripts/wait-for-npm-release.test.mjs b/.github/scripts/wait-for-npm-release.test.mjs
new file mode 100644
index 000000000..b6217baab
--- /dev/null
+++ b/.github/scripts/wait-for-npm-release.test.mjs
@@ -0,0 +1,188 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+ inspectNpmReleaseVisibility,
+ npmPackumentUrl,
+ waitForNpmReleaseVisibility,
+} from "./wait-for-npm-release.mjs";
+
+const sha = "a317661691bda94054d3d35f8c226e8bfe0018f7";
+
+function response(packument, status = 200) {
+ return {
+ ok: status >= 200 && status < 300,
+ status,
+ async json() {
+ return packument;
+ },
+ };
+}
+
+function packument({ version = "0.1.20", gitHead = sha, latest = "0.1.20" } = {}) {
+ return {
+ "dist-tags": { latest },
+ versions: { [version]: { gitHead } },
+ };
+}
+
+test("builds a cache-busted scoped-package registry URL", () => {
+ assert.equal(
+ npmPackumentUrl("https://registry.npmjs.org/", "@memtensor/plugin", 123),
+ "https://registry.npmjs.org/@memtensor%2Fplugin?cache-bust=123",
+ );
+});
+
+test("requests the full packument because install-v1 omits gitHead", async () => {
+ let requestHeaders;
+ const report = await waitForNpmReleaseVisibility(
+ {
+ packageName: "@memtensor/plugin",
+ version: "0.1.20",
+ distTag: "latest",
+ expectedGitHead: sha,
+ timeoutMs: 10_000,
+ intervalMs: 1_000,
+ requestTimeoutMs: 1_000,
+ },
+ {
+ fetchImpl: async (_url, options) => {
+ requestHeaders = options.headers;
+ return response(packument());
+ },
+ log: () => {},
+ },
+ );
+ assert.equal(report.ok, true);
+ assert.equal(requestHeaders.accept, "application/json");
+});
+
+test("requires version, gitHead, and dist-tag to become visible together", () => {
+ assert.match(
+ inspectNpmReleaseVisibility({
+ packument: { versions: {}, "dist-tags": {} },
+ version: "0.1.20",
+ distTag: "latest",
+ expectedGitHead: sha,
+ }).reason,
+ /not visible/,
+ );
+ assert.match(
+ inspectNpmReleaseVisibility({
+ packument: packument({ gitHead: "" }),
+ version: "0.1.20",
+ distTag: "latest",
+ expectedGitHead: sha,
+ }).reason,
+ /gitHead is not/,
+ );
+ assert.match(
+ inspectNpmReleaseVisibility({
+ packument: packument({ latest: "0.1.19" }),
+ version: "0.1.20",
+ distTag: "latest",
+ expectedGitHead: sha,
+ }).reason,
+ /latest points to 0\.1\.19/,
+ );
+ assert.equal(
+ inspectNpmReleaseVisibility({
+ packument: packument(),
+ version: "0.1.20",
+ distTag: "latest",
+ expectedGitHead: sha,
+ }).ok,
+ true,
+ );
+});
+
+test("fails immediately when npm exposes a different immutable gitHead", async () => {
+ let sleeps = 0;
+ await assert.rejects(
+ waitForNpmReleaseVisibility(
+ {
+ packageName: "@memtensor/plugin",
+ version: "0.1.20",
+ distTag: "latest",
+ expectedGitHead: sha,
+ timeoutMs: 150_000,
+ intervalMs: 10_000,
+ requestTimeoutMs: 1_000,
+ },
+ {
+ fetchImpl: async () => response(packument({ gitHead: "b".repeat(40) })),
+ sleep: async () => {
+ sleeps += 1;
+ },
+ log: () => {},
+ },
+ ),
+ /records gitHead .* expected/,
+ );
+ assert.equal(sleeps, 0);
+});
+
+test("waits through delayed version, gitHead, and dist-tag propagation", async () => {
+ let clock = 0;
+ let attempt = 0;
+ const replies = [
+ response({}, 404),
+ response(packument({ gitHead: "" })),
+ response(packument({ latest: "0.1.19" })),
+ response(packument()),
+ ];
+ const report = await waitForNpmReleaseVisibility(
+ {
+ packageName: "@memtensor/plugin",
+ version: "0.1.20",
+ distTag: "latest",
+ expectedGitHead: sha,
+ timeoutMs: 150_000,
+ intervalMs: 10_000,
+ requestTimeoutMs: 1_000,
+ },
+ {
+ fetchImpl: async () => replies[attempt++],
+ sleep: async (milliseconds) => {
+ clock += milliseconds;
+ },
+ now: () => clock,
+ log: () => {},
+ },
+ );
+ assert.equal(report.ok, true);
+ assert.equal(report.attempts, 4);
+ assert.equal(clock, 30_000);
+});
+
+test("uses a hard deadline instead of an unbounded retry loop", async () => {
+ let clock = 0;
+ let attempts = 0;
+ await assert.rejects(
+ waitForNpmReleaseVisibility(
+ {
+ packageName: "@memtensor/plugin",
+ version: "0.1.20",
+ distTag: "latest",
+ expectedGitHead: sha,
+ timeoutMs: 30_000,
+ intervalMs: 10_000,
+ requestTimeoutMs: 1_000,
+ },
+ {
+ fetchImpl: async () => {
+ attempts += 1;
+ return response({}, 404);
+ },
+ sleep: async (milliseconds) => {
+ clock += milliseconds;
+ },
+ now: () => clock,
+ log: () => {},
+ },
+ ),
+ /not fully visible within 30s/,
+ );
+ assert.equal(clock, 30_000);
+ assert.equal(attempts, 3);
+});
diff --git a/.github/workflows/historical-dry-run.yml b/.github/workflows/historical-dry-run.yml
new file mode 100644
index 000000000..3e106c3f6
--- /dev/null
+++ b/.github/workflows/historical-dry-run.yml
@@ -0,0 +1,54 @@
+name: OpenClaw Cloud Plugin — Historical Dry Run
+
+on:
+ workflow_dispatch:
+
+permissions:
+ # Historical integration may use Doc Agent secrets only from the protected
+ # default branch and never receives a write-capable token.
+ contents: read
+
+jobs:
+ historical-dry-run:
+ name: ${{ matrix.expected_previous_tag }}..${{ matrix.expected_current_ref }}
+ if: ${{ github.repository == 'MemTensor/MemOS-Cloud-OpenClaw-Plugin' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
+ permissions:
+ contents: read
+ strategy:
+ fail-fast: false
+ matrix:
+ include:
+ - version: "0.1.15"
+ expected_previous_tag: "v0.1.14"
+ expected_current_ref: "v0.1.15"
+ - version: "0.1.16"
+ expected_previous_tag: "v0.1.15"
+ expected_current_ref: "v0.1.16"
+ - version: "0.1.17"
+ expected_previous_tag: "v0.1.16"
+ expected_current_ref: "v0.1.17"
+ - version: "0.1.18"
+ expected_previous_tag: "v0.1.17"
+ expected_current_ref: "v0.1.18"
+ - version: "0.1.19"
+ expected_previous_tag: "v0.1.18"
+ expected_current_ref: "v0.1.19"
+ uses: ./.github/workflows/release-dry-run.yml
+ with:
+ version: ${{ matrix.version }}
+ tag: "latest"
+ git_ref: ""
+ release_notes: ""
+ dry_run: true
+ recover_existing_npm_release: false
+ enforce_source_version: false
+ artifact_name: openclaw-cloud-plugin-release-inspection-${{ matrix.version }}
+ expected_previous_tag: ${{ matrix.expected_previous_tag }}
+ expected_current_ref: ${{ matrix.expected_current_ref }}
+ secrets:
+ DOC_AGENT_RELEASE_NOTES_DRAFT_URL: ${{ secrets.DOC_AGENT_RELEASE_NOTES_DRAFT_URL }}
+ DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN: ${{ secrets.DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN }}
+ DOC_AGENT_RELEASE_FAILURE_URL: ${{ secrets.DOC_AGENT_RELEASE_FAILURE_URL }}
+ MEMOS_ARMS_ENDPOINT: ${{ secrets.MEMOS_ARMS_ENDPOINT }}
+ MEMOS_ARMS_PID: ${{ secrets.MEMOS_ARMS_PID }}
+ MEMOS_ARMS_ENV: ${{ secrets.MEMOS_ARMS_ENV }}
diff --git a/.github/workflows/post-merge-dry-run.yml b/.github/workflows/post-merge-dry-run.yml
new file mode 100644
index 000000000..5f1c7c862
--- /dev/null
+++ b/.github/workflows/post-merge-dry-run.yml
@@ -0,0 +1,101 @@
+name: OpenClaw Cloud Plugin — Post-Merge Dry Run
+
+on:
+ push:
+ branches:
+ - main
+ paths:
+ - ".github/workflows/release.yml"
+ - ".github/workflows/release-dry-run.yml"
+ - ".github/workflows/historical-dry-run.yml"
+ - ".github/workflows/pre-merge-dry-run.yml"
+ - ".github/workflows/post-merge-dry-run.yml"
+ - ".github/workflows/workflow-contract-lint.yml"
+ - ".github/scripts/draft-cloud-plugin-release-notes.mjs"
+ - ".github/scripts/draft-cloud-plugin-release-notes.test.mjs"
+ - ".github/scripts/validate-github-release-inventory.mjs"
+ - ".github/scripts/validate-github-release-inventory.test.mjs"
+ - ".github/scripts/validate-release-confirmation.mjs"
+ - ".github/scripts/validate-release-confirmation.test.mjs"
+ - ".github/scripts/validate-release-source-version.mjs"
+ - ".github/scripts/validate-release-source-version.test.mjs"
+ - ".github/scripts/wait-for-npm-release.mjs"
+ - ".github/scripts/wait-for-npm-release.test.mjs"
+ - ".github/scripts/retry.sh"
+ - "package.json"
+ - "scripts/generate-telemetry-credentials.cjs"
+ - "lib/**"
+ - "test/*.test.mjs"
+ - ".gitignore"
+
+permissions:
+ # Trusted main integration can call the Doc Agent draft endpoint, while the
+ # reusable inspection workflow keeps the GitHub token read-only.
+ contents: read
+
+jobs:
+ release_source:
+ if: ${{ github.repository == 'MemTensor/MemOS-Cloud-OpenClaw-Plugin' }}
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ outputs:
+ version: ${{ steps.source.outputs.version }}
+ npm_dist_tag: ${{ steps.source.outputs.npm_dist_tag }}
+ source_sha: ${{ steps.source.outputs.source_sha }}
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ persist-credentials: false
+
+ - uses: actions/setup-node@v7
+ with:
+ node-version: 22
+
+ - name: Resolve committed release source
+ id: source
+ shell: bash
+ run: |
+ set -euo pipefail
+ version="$(node -p "require('./package.json').version")"
+ npm_dist_tag="latest"
+ if [[ "${version}" == *-* ]]; then
+ prerelease="${version#*-}"
+ npm_dist_tag="${prerelease%%.*}"
+ case "${npm_dist_tag}" in
+ alpha|beta|next) ;;
+ *) npm_dist_tag="next" ;;
+ esac
+ fi
+ RELEASE_VERSION="${version}" \
+ NPM_DIST_TAG="${npm_dist_tag}" \
+ DRY_RUN=true \
+ PUBLISH_CONFIRMATION="" \
+ node .github/scripts/validate-release-confirmation.mjs
+ {
+ echo "version=${version}"
+ echo "source_sha=$(git rev-parse HEAD)"
+ } >> "${GITHUB_OUTPUT}"
+
+ dry-run:
+ needs: release_source
+ if: ${{ github.repository == 'MemTensor/MemOS-Cloud-OpenClaw-Plugin' }}
+ permissions:
+ contents: read
+ uses: ./.github/workflows/release-dry-run.yml
+ with:
+ version: ${{ needs.release_source.outputs.version }}
+ tag: ${{ needs.release_source.outputs.npm_dist_tag }}
+ git_ref: ${{ needs.release_source.outputs.source_sha }}
+ release_notes: ""
+ dry_run: true
+ recover_existing_npm_release: false
+ enforce_source_version: true
+ expected_current_ref: ${{ needs.release_source.outputs.source_sha }}
+ secrets:
+ DOC_AGENT_RELEASE_NOTES_DRAFT_URL: ${{ secrets.DOC_AGENT_RELEASE_NOTES_DRAFT_URL }}
+ DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN: ${{ secrets.DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN }}
+ DOC_AGENT_RELEASE_FAILURE_URL: ${{ secrets.DOC_AGENT_RELEASE_FAILURE_URL }}
+ MEMOS_ARMS_ENDPOINT: ${{ secrets.MEMOS_ARMS_ENDPOINT }}
+ MEMOS_ARMS_PID: ${{ secrets.MEMOS_ARMS_PID }}
+ MEMOS_ARMS_ENV: ${{ secrets.MEMOS_ARMS_ENV }}
diff --git a/.github/workflows/pre-merge-dry-run.yml b/.github/workflows/pre-merge-dry-run.yml
new file mode 100644
index 000000000..0b1202b13
--- /dev/null
+++ b/.github/workflows/pre-merge-dry-run.yml
@@ -0,0 +1,132 @@
+name: OpenClaw Cloud Plugin — Pre-Merge Dry Run
+
+on:
+ pull_request:
+ types: [opened, synchronize, reopened, ready_for_review]
+ branches:
+ - main
+ push:
+ branches:
+ - "docs-sync/**"
+ - "fix/**"
+ paths:
+ - ".github/workflows/release.yml"
+ - ".github/workflows/release-dry-run.yml"
+ - ".github/workflows/historical-dry-run.yml"
+ - ".github/workflows/pre-merge-dry-run.yml"
+ - ".github/workflows/post-merge-dry-run.yml"
+ - ".github/workflows/workflow-contract-lint.yml"
+ - ".github/scripts/draft-cloud-plugin-release-notes.mjs"
+ - ".github/scripts/draft-cloud-plugin-release-notes.test.mjs"
+ - ".github/scripts/resolve-auto-release.mjs"
+ - ".github/scripts/resolve-auto-release.test.mjs"
+ - ".github/scripts/validate-github-release-inventory.mjs"
+ - ".github/scripts/validate-github-release-inventory.test.mjs"
+ - ".github/scripts/validate-release-confirmation.mjs"
+ - ".github/scripts/validate-release-confirmation.test.mjs"
+ - ".github/scripts/validate-release-source-version.mjs"
+ - ".github/scripts/validate-release-source-version.test.mjs"
+ - ".github/scripts/wait-for-npm-release.mjs"
+ - ".github/scripts/wait-for-npm-release.test.mjs"
+ - ".github/scripts/retry.sh"
+ - "package.json"
+ - "openclaw.plugin.json"
+ - "moltbot.plugin.json"
+ - "clawdbot.plugin.json"
+ - ".github/release-notes/**"
+ - "scripts/generate-telemetry-credentials.cjs"
+ - "lib/**"
+ - "test/*.test.mjs"
+ - ".gitignore"
+
+permissions:
+ # Branch code is validated without repository secrets. The reusable
+ # inspection workflow is read-only and cannot publish or modify GitHub.
+ contents: read
+
+jobs:
+ release-candidate:
+ if: ${{ github.repository == 'MemTensor/MemOS-Cloud-OpenClaw-Plugin' && github.event_name == 'pull_request' }}
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ ref: ${{ github.sha }}
+ fetch-depth: 0
+ persist-credentials: false
+
+ - uses: actions/setup-node@v7
+ with:
+ node-version: 22
+
+ - name: Validate proposed four-file version transition
+ shell: bash
+ env:
+ EVENT_NAME: pull_request
+ PR_MERGED: "true"
+ PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
+ PR_HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+ PR_MERGE_SHA: ${{ github.sha }}
+ PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+ run: node .github/scripts/resolve-auto-release.mjs
+
+ secrets-preflight:
+ if: ${{ github.repository == 'MemTensor/MemOS-Cloud-OpenClaw-Plugin' && github.event_name == 'push' }}
+ runs-on: ubuntu-latest
+ steps:
+ - name: Confirm secretless branch inspection
+ shell: bash
+ run: |
+ set -euo pipefail
+ echo "Pre-merge inspection uses a checked-in evidence-backed fixture."
+ echo "No repository secret is passed to branch-controlled workflow code."
+
+ dry-run:
+ needs: secrets-preflight
+ if: ${{ github.repository == 'MemTensor/MemOS-Cloud-OpenClaw-Plugin' && github.event_name == 'push' }}
+ permissions:
+ contents: read
+ uses: ./.github/workflows/release-dry-run.yml
+ with:
+ version: "0.1.19"
+ tag: "latest"
+ git_ref: ""
+ release_notes: |
+ ## Changelog
+
+ ### Improved
+ - **系统事件过滤增强**:自动跳过定时任务、计划提醒和后台命令结果,减少记忆污染。
+ - **系统提示识别优化**:兼容单行压缩内容并降低普通消息误判概率。
+
+
+
+
+ dry_run: true
+ recover_existing_npm_release: false
+ enforce_source_version: false
diff --git a/.github/workflows/release-dry-run.yml b/.github/workflows/release-dry-run.yml
new file mode 100644
index 000000000..0c5885677
--- /dev/null
+++ b/.github/workflows/release-dry-run.yml
@@ -0,0 +1,344 @@
+name: OpenClaw Cloud Plugin — Reusable Release Dry Run
+
+on:
+ workflow_call:
+ inputs:
+ version:
+ description: "Version to inspect (e.g. 0.1.19 or 0.1.20-beta.1)."
+ required: true
+ type: string
+ tag:
+ description: "npm dist-tag paired with the inspected version."
+ required: false
+ type: string
+ default: "latest"
+ git_ref:
+ description: "Git ref containing the workflow and package code. Leave blank to use the caller ref."
+ required: false
+ type: string
+ default: ""
+ release_notes:
+ description: "Optional evidence-backed Markdown. Leave blank to request a Doc Agent draft."
+ required: false
+ type: string
+ default: ""
+ dry_run:
+ description: "Compatibility guard. Reusable callers may only pass true."
+ required: false
+ type: boolean
+ default: true
+ recover_existing_npm_release:
+ description: "Compatibility guard. Reusable dry runs may only pass false."
+ required: false
+ type: boolean
+ default: false
+ enforce_source_version:
+ description: "Require the committed release source to already contain the requested version. Historical evidence replays may disable this."
+ required: false
+ type: boolean
+ default: true
+ fault_case:
+ description: "Release-note fault injection used by dry-run validation."
+ required: false
+ type: string
+ default: "none"
+ artifact_name:
+ description: "Inspection artifact name."
+ required: false
+ type: string
+ default: "openclaw-cloud-plugin-release-inspection"
+ expected_previous_tag:
+ description: "Optional assertion for a known historical range."
+ required: false
+ type: string
+ default: ""
+ expected_current_ref:
+ description: "Optional immutable evidence ref; defaults to v."
+ required: false
+ type: string
+ default: ""
+ secrets:
+ DOC_AGENT_RELEASE_NOTES_DRAFT_URL:
+ description: "Doc Agent release-note draft endpoint."
+ required: false
+ DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN:
+ description: "Bearer token for the Doc Agent draft endpoint."
+ required: false
+ DOC_AGENT_RELEASE_FAILURE_URL:
+ description: "Optional exhausted-failure reporting endpoint."
+ required: false
+ MEMOS_ARMS_ENDPOINT:
+ description: "Optional telemetry endpoint injected into the inspection package."
+ required: false
+ MEMOS_ARMS_PID:
+ description: "Optional telemetry project identifier."
+ required: false
+ MEMOS_ARMS_ENV:
+ description: "Optional telemetry environment."
+ required: false
+
+permissions:
+ contents: read
+
+jobs:
+ inspect:
+ permissions:
+ contents: read
+ runs-on: ubuntu-latest
+ timeout-minutes: 30
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ ref: ${{ inputs.git_ref || github.ref }}
+ fetch-depth: 0
+ persist-credentials: false
+
+ - uses: actions/setup-node@v7
+ with:
+ node-version: 22
+ registry-url: https://registry.npmjs.org
+
+ - name: Validate immutable dry-run inputs
+ id: release_policy
+ shell: bash
+ env:
+ RELEASE_VERSION: ${{ inputs.version }}
+ NPM_DIST_TAG: ${{ inputs.tag }}
+ DRY_RUN: ${{ inputs.dry_run }}
+ RECOVER_EXISTING_NPM_RELEASE: ${{ inputs.recover_existing_npm_release }}
+ RELEASE_FAULT_CASE: ${{ inputs.fault_case }}
+ MANUAL_RELEASE_NOTES: ${{ inputs.release_notes }}
+ PUBLISH_CONFIRMATION: ""
+ run: |
+ set -euo pipefail
+ if [ "${DRY_RUN}" != "true" ]; then
+ echo "::error::The reusable inspection workflow only accepts dry_run=true."
+ exit 1
+ fi
+ if [ "${RECOVER_EXISTING_NPM_RELEASE}" != "false" ]; then
+ echo "::error::The reusable inspection workflow never performs npm recovery."
+ exit 1
+ fi
+ if [[ "${RELEASE_VERSION}" == [vV]* ]]; then
+ echo "::error::version must not include a leading v."
+ exit 1
+ fi
+ if ! [[ "${RELEASE_VERSION}" =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$ ]]; then
+ echo "::error::version must be a valid SemVer value."
+ exit 1
+ fi
+ if ! [[ "${NPM_DIST_TAG}" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]]; then
+ echo "::error::tag must be a valid npm dist-tag."
+ exit 1
+ fi
+ if [ "${RELEASE_FAULT_CASE}" = "manual_notes_missing_payload" ] && [ -z "${MANUAL_RELEASE_NOTES}" ]; then
+ echo "::error::manual_notes_missing_payload requires a manual release_notes fixture."
+ exit 1
+ fi
+ node .github/scripts/validate-release-confirmation.mjs
+
+ - name: Resolve immutable evidence ref
+ id: release_source
+ shell: bash
+ env:
+ RELEASE_VERSION: ${{ inputs.version }}
+ EXPECTED_CURRENT_REF: ${{ inputs.expected_current_ref }}
+ run: |
+ set -euo pipefail
+ evidence_ref="${EXPECTED_CURRENT_REF:-v${RELEASE_VERSION}}"
+ if ! git rev-parse --verify --quiet "${evidence_ref}^{commit}" >/dev/null; then
+ echo "::error::Evidence ref ${evidence_ref} is not an available commit."
+ exit 1
+ fi
+ {
+ echo "evidence_ref=${evidence_ref}"
+ echo "source_commit=$(git rev-parse "${evidence_ref}^{commit}")"
+ } >> "${GITHUB_OUTPUT}"
+
+ - name: Install dependencies
+ shell: bash
+ run: bash .github/scripts/retry.sh --label "npm install" -- npm install
+
+ - name: Run tests
+ shell: bash
+ run: |
+ set -euo pipefail
+ bash .github/scripts/retry.sh --attempts 2 --label "release workflow script tests" -- node --test .github/scripts/*.test.mjs
+ if compgen -G "test/*.test.mjs" >/dev/null; then
+ bash .github/scripts/retry.sh --attempts 2 --label "plugin tests" -- node --test test/*.test.mjs
+ else
+ echo "No plugin tests found; skipping."
+ fi
+
+ - name: Validate committed release source version
+ if: ${{ inputs.enforce_source_version }}
+ shell: bash
+ env:
+ RELEASE_VERSION: ${{ inputs.version }}
+ RELEASE_SOURCE_REF: ${{ steps.release_source.outputs.evidence_ref }}
+ run: |
+ set -euo pipefail
+ node .github/scripts/validate-release-source-version.mjs
+
+ - name: Generate telemetry credentials
+ shell: bash
+ env:
+ MEMOS_ARMS_ENDPOINT: ${{ secrets.MEMOS_ARMS_ENDPOINT }}
+ MEMOS_ARMS_PID: ${{ secrets.MEMOS_ARMS_PID }}
+ MEMOS_ARMS_ENV: ${{ secrets.MEMOS_ARMS_ENV }}
+ run: bash .github/scripts/retry.sh --label "generate telemetry credentials" -- node scripts/generate-telemetry-credentials.cjs
+
+ - name: Verify package contents
+ if: ${{ inputs.enforce_source_version }}
+ shell: bash
+ run: |
+ set -euo pipefail
+ bash .github/scripts/retry.sh --label "npm pack dry-run" -- bash -euo pipefail -c 'npm pack --dry-run --json > "${RUNNER_TEMP}/openclaw-cloud-plugin-pack.json"'
+
+ - name: Draft and validate GitHub Release notes
+ id: release_notes
+ env:
+ RELEASE_VERSION: ${{ inputs.version }}
+ RELEASE_TAG: v${{ inputs.version }}
+ RELEASE_EVIDENCE_REF: ${{ steps.release_source.outputs.evidence_ref }}
+ MANUAL_RELEASE_NOTES: ${{ inputs.release_notes }}
+ RELEASE_FAULT_CASE: ${{ inputs.fault_case }}
+ DOC_AGENT_RELEASE_NOTES_DRAFT_URL: ${{ secrets.DOC_AGENT_RELEASE_NOTES_DRAFT_URL }}
+ DOC_AGENT_RELEASE_FAILURE_URL: ${{ secrets.DOC_AGENT_RELEASE_FAILURE_URL }}
+ DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN: ${{ secrets.DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN }}
+ run: node .github/scripts/draft-cloud-plugin-release-notes.mjs
+
+ - name: Prepare release inspection artifact
+ if: ${{ always() }}
+ shell: bash
+ env:
+ DRAFT_STEP_OUTCOME: ${{ steps.release_notes.outcome }}
+ RELEASE_VERSION: ${{ inputs.version }}
+ FAULT_CASE: ${{ inputs.fault_case }}
+ RELEASE_NOTES_FILE: ${{ steps.release_notes.outputs.release_notes_file }}
+ EVIDENCE_FILE: ${{ steps.release_notes.outputs.evidence_file }}
+ DRAFT_FILE: ${{ steps.release_notes.outputs.draft_file }}
+ DOCS_PREVIEW_FILE: ${{ steps.release_notes.outputs.docs_preview_file }}
+ DOCS_PREVIEW_MARKDOWN_FILE: ${{ steps.release_notes.outputs.docs_preview_markdown_file }}
+ QUALITY_REPORT_FILE: ${{ steps.release_notes.outputs.quality_report_file }}
+ DRAFT_USED: ${{ steps.release_notes.outputs.draft_used }}
+ PREVIOUS_TAG: ${{ steps.release_notes.outputs.previous_tag }}
+ CURRENT_REF: ${{ steps.release_notes.outputs.current_ref }}
+ SOURCE_COMMIT: ${{ steps.release_source.outputs.source_commit }}
+ RELEASE_CHANNEL: ${{ steps.release_policy.outputs.release_channel }}
+ NPM_DIST_TAG: ${{ steps.release_policy.outputs.npm_dist_tag }}
+ GITHUB_RELEASE_PRERELEASE: ${{ steps.release_policy.outputs.github_release_prerelease }}
+ DOCS_SYNC_EXPECTED: ${{ steps.release_policy.outputs.docs_sync_expected }}
+ VALIDATION_ATTEMPT_COUNT: ${{ steps.release_notes.outputs.validation_attempt_count }}
+ REPAIR_ATTEMPT_COUNT: ${{ steps.release_notes.outputs.repair_attempt_count }}
+ EXPECTED_PREVIOUS_TAG: ${{ inputs.expected_previous_tag }}
+ EXPECTED_CURRENT_REF: ${{ inputs.expected_current_ref }}
+ SOURCE_VERSION_GATE: ${{ inputs.enforce_source_version }}
+ run: |
+ set -euo pipefail
+ inspection_dir="${RUNNER_TEMP}/openclaw-cloud-plugin-release-inspection"
+ mkdir -p "${inspection_dir}"
+
+ copy_if_present() {
+ local source_file="$1"
+ local target_name="$2"
+ if [ -n "${source_file}" ] && [ -s "${source_file}" ]; then
+ cp "${source_file}" "${inspection_dir}/${target_name}"
+ fi
+ }
+ copy_if_present "${RELEASE_NOTES_FILE}" "release-notes.md"
+ copy_if_present "${EVIDENCE_FILE}" "evidence.json"
+ copy_if_present "${DRAFT_FILE}" "release-notes-draft.json"
+ copy_if_present "${DOCS_PREVIEW_FILE}" "docs-preview.json"
+ copy_if_present "${DOCS_PREVIEW_MARKDOWN_FILE}" "docs-preview.md"
+ copy_if_present "${QUALITY_REPORT_FILE}" "quality-report.json"
+ copy_if_present "${RUNNER_TEMP}/openclaw-cloud-plugin-pack.json" "npm-pack.json"
+
+ if [ "${DRAFT_STEP_OUTCOME}" = "success" ] && [ ! -s "${inspection_dir}/release-notes.md" ]; then
+ echo "::error::release-notes.md was not generated."
+ exit 1
+ fi
+ if [ "${DRAFT_STEP_OUTCOME}" = "success" ] && [ ! -s "${inspection_dir}/quality-report.json" ]; then
+ echo "::error::quality-report.json was not generated."
+ exit 1
+ fi
+ if [ "${DRAFT_STEP_OUTCOME}" = "success" ] && [ -n "${EXPECTED_PREVIOUS_TAG}" ] && [ "${PREVIOUS_TAG}" != "${EXPECTED_PREVIOUS_TAG}" ]; then
+ echo "::error::Expected previous_tag=${EXPECTED_PREVIOUS_TAG}, got ${PREVIOUS_TAG:-n/a}."
+ exit 1
+ fi
+ if [ "${DRAFT_STEP_OUTCOME}" = "success" ] && [ -n "${EXPECTED_CURRENT_REF}" ] && [ "${CURRENT_REF}" != "${EXPECTED_CURRENT_REF}" ]; then
+ echo "::error::Expected current_ref=${EXPECTED_CURRENT_REF}, got ${CURRENT_REF:-n/a}."
+ exit 1
+ fi
+ github_release_prerelease_json="${GITHUB_RELEASE_PRERELEASE:-null}"
+ docs_sync_expected_json="${DOCS_SYNC_EXPECTED:-null}"
+ if [[ "${github_release_prerelease_json}" != "true" && "${github_release_prerelease_json}" != "false" ]]; then
+ github_release_prerelease_json=null
+ fi
+ if [[ "${docs_sync_expected_json}" != "true" && "${docs_sync_expected_json}" != "false" ]]; then
+ docs_sync_expected_json=null
+ fi
+ jq -n \
+ --arg version "${RELEASE_VERSION}" \
+ --arg source_commit "${SOURCE_COMMIT}" \
+ --arg evidence_ref "${CURRENT_REF:-}" \
+ --arg release_channel "${RELEASE_CHANNEL}" \
+ --arg npm_dist_tag "${NPM_DIST_TAG}" \
+ --argjson github_release_prerelease "${github_release_prerelease_json}" \
+ --argjson docs_sync_expected "${docs_sync_expected_json}" \
+ '{
+ version: $version,
+ source_commit: $source_commit,
+ evidence_ref: $evidence_ref,
+ release_channel: $release_channel,
+ npm_dist_tag: $npm_dist_tag,
+ github_release_prerelease: $github_release_prerelease,
+ docs_sync_expected: $docs_sync_expected
+ }' \
+ > "${inspection_dir}/release-source.json"
+
+ {
+ echo "# OpenClaw cloud plugin release inspection"
+ echo
+ echo "- draft_step_outcome: ${DRAFT_STEP_OUTCOME}"
+ echo "- version: ${RELEASE_VERSION}"
+ echo "- release_channel: ${RELEASE_CHANNEL}"
+ echo "- npm_dist_tag: ${NPM_DIST_TAG}"
+ echo "- github_release_prerelease: ${GITHUB_RELEASE_PRERELEASE}"
+ echo "- docs_sync_expected: ${DOCS_SYNC_EXPECTED}"
+ echo "- fault_case: ${FAULT_CASE}"
+ echo "- draft_used: ${DRAFT_USED:-unknown}"
+ echo "- previous_tag: ${PREVIOUS_TAG:-n/a}"
+ echo "- current_ref: ${CURRENT_REF:-n/a}"
+ echo "- source_commit: ${SOURCE_COMMIT:-n/a}"
+ echo "- source_version_gate: ${SOURCE_VERSION_GATE}"
+ echo "- validation_attempt_count: ${VALIDATION_ATTEMPT_COUNT:-n/a}"
+ echo "- repair_attempt_count: ${REPAIR_ATTEMPT_COUNT:-n/a}"
+ echo "- token_permissions: contents:read"
+ echo "- repository_credentials_persisted: false"
+ } > "${inspection_dir}/README.md"
+
+ {
+ echo "### OpenClaw cloud plugin release dry run"
+ echo
+ echo "- outcome: \`${DRAFT_STEP_OUTCOME}\`"
+ echo "- version: \`${RELEASE_VERSION}\`"
+ echo "- release_channel: \`${RELEASE_CHANNEL}\`"
+ echo "- npm_dist_tag: \`${NPM_DIST_TAG}\`"
+ echo "- github_release_prerelease: \`${GITHUB_RELEASE_PRERELEASE}\`"
+ echo "- docs_sync_expected: \`${DOCS_SYNC_EXPECTED}\`"
+ echo "- previous_tag: \`${PREVIOUS_TAG:-n/a}\`"
+ echo "- current_ref: \`${CURRENT_REF:-n/a}\`"
+ echo "- source_commit: \`${SOURCE_COMMIT:-n/a}\`"
+ echo "- validation_attempt_count: \`${VALIDATION_ATTEMPT_COUNT:-n/a}\`"
+ echo "- repair_attempt_count: \`${REPAIR_ATTEMPT_COUNT:-n/a}\`"
+ echo "- permissions: \`contents: read\`"
+ } >> "${GITHUB_STEP_SUMMARY}"
+
+ - name: Upload release inspection artifact
+ if: ${{ always() }}
+ uses: actions/upload-artifact@v7
+ with:
+ name: ${{ inputs.artifact_name }}
+ path: ${{ runner.temp }}/openclaw-cloud-plugin-release-inspection
+ if-no-files-found: error
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 000000000..e0542f914
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,1235 @@
+name: OpenClaw Cloud Plugin — Publish & Release
+
+on:
+ pull_request:
+ types: [closed]
+ branches:
+ - main
+ workflow_dispatch:
+ inputs:
+ version:
+ description: "Version to publish (e.g. 0.1.20 or 0.1.20-beta.1)"
+ required: true
+ tag:
+ description: "npm dist-tag (latest for production, beta/next/alpha for testing)"
+ required: true
+ type: choice
+ default: "latest"
+ options:
+ - latest
+ - beta
+ - next
+ - alpha
+ git_ref:
+ description: "Dry-run: leave blank for main. Real publish: exact 40-character source_commit approved in the dry-run."
+ required: false
+ default: ""
+ release_notes:
+ description: "Optional evidence-backed Markdown. Leave blank to draft it from git evidence."
+ required: false
+ default: ""
+ dry_run:
+ description: "Build, validate, and generate inspection artifacts without publishing or changing GitHub."
+ required: true
+ type: boolean
+ default: true
+ publish_confirmation:
+ description: "Required only when dry_run=false. Must exactly equal: PUBLISH v"
+ required: false
+ default: ""
+ recover_existing_npm_release:
+ description: "Backfill missing tag/Release from npm gitHead without republishing. Keep false for normal releases."
+ required: true
+ type: boolean
+ default: false
+ fault_case:
+ description: "Dry-run-only release-note fault injection."
+ required: true
+ type: choice
+ default: "none"
+ options:
+ - none
+ - mixed_language
+ - missing_source_refs
+ - missing_important_commit
+ - invalid_source_ref
+ - thirteen_items
+ - too_long
+ - manual_notes_missing_payload
+
+concurrency:
+ group: openclaw-cloud-plugin-publish
+ cancel-in-progress: false
+
+permissions:
+ contents: read
+
+jobs:
+ classify_auto_release:
+ name: Classify automatic release
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ outputs:
+ eligible: ${{ steps.classify.outputs.eligible }}
+ reason: ${{ steps.classify.outputs.reason }}
+ previous_version: ${{ steps.classify.outputs.previous_version }}
+ version: ${{ steps.classify.outputs.version }}
+ npm_dist_tag: ${{ steps.classify.outputs.npm_dist_tag }}
+ target_sha: ${{ steps.classify.outputs.target_sha }}
+ release_notes_file: ${{ steps.classify.outputs.release_notes_file }}
+ release_notes_source: ${{ steps.classify.outputs.release_notes_source }}
+ steps:
+ - name: Check merged pull request boundary
+ id: gate
+ shell: bash
+ env:
+ EVENT_NAME: ${{ github.event_name }}
+ PR_MERGED: ${{ github.event.pull_request.merged || false }}
+ PR_BASE_REF: ${{ github.event.pull_request.base.ref || '' }}
+ PR_HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name || '' }}
+ REPOSITORY: ${{ github.repository }}
+ run: |
+ set -euo pipefail
+ inspect=false
+ reason="manual workflow dispatch"
+ if [ "${EVENT_NAME}" = "pull_request" ]; then
+ reason="closed pull request is not an eligible same-repository main merge"
+ if [ "${PR_MERGED}" = "true" ] && \
+ [ "${PR_BASE_REF}" = "main" ] && \
+ [ "${PR_HEAD_REPO}" = "${REPOSITORY}" ]; then
+ inspect=true
+ reason="same-repository pull request merged into main; inspect committed versions"
+ fi
+ fi
+ {
+ echo "inspect=${inspect}"
+ echo "reason=${reason}"
+ } >> "${GITHUB_OUTPUT}"
+ {
+ echo "### OpenClaw cloud plugin release trigger"
+ echo
+ echo "- Inspect committed version transition: \`${inspect}\`"
+ echo "- Reason: ${reason}"
+ } >> "${GITHUB_STEP_SUMMARY}"
+
+ - uses: actions/checkout@v7
+ if: ${{ steps.gate.outputs.inspect == 'true' }}
+ with:
+ ref: ${{ github.event.pull_request.merge_commit_sha }}
+ fetch-depth: 0
+ persist-credentials: false
+
+ - uses: actions/setup-node@v7
+ if: ${{ steps.gate.outputs.inspect == 'true' }}
+ with:
+ node-version: 22
+
+ - name: Resolve immutable automatic release
+ if: ${{ steps.gate.outputs.inspect == 'true' }}
+ id: release
+ shell: bash
+ env:
+ EVENT_NAME: ${{ github.event_name }}
+ PR_MERGED: ${{ github.event.pull_request.merged }}
+ PR_BASE_REF: ${{ github.event.pull_request.base.ref }}
+ PR_HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+ PR_MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
+ PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+ run: node .github/scripts/resolve-auto-release.mjs
+
+ - name: Load optional reviewed Release Notes
+ if: ${{ steps.release.outputs.eligible == 'true' }}
+ id: notes
+ shell: bash
+ env:
+ RELEASE_NOTES_PATH: ${{ steps.release.outputs.release_notes_path }}
+ run: |
+ set -euo pipefail
+ if [ -f "${RELEASE_NOTES_PATH}" ]; then
+ {
+ echo "release_notes_source=checked_in"
+ echo "release_notes_file=${RELEASE_NOTES_PATH}"
+ } >> "${GITHUB_OUTPUT}"
+ echo "Using reviewed Release Notes from ${RELEASE_NOTES_PATH}."
+ else
+ echo "release_notes_source=doc_agent" >> "${GITHUB_OUTPUT}"
+ echo "release_notes_file=" >> "${GITHUB_OUTPUT}"
+ echo "${RELEASE_NOTES_PATH} is absent; 106 Doc Agent will draft from immutable git evidence."
+ fi
+
+ - name: Export automatic release inputs
+ if: ${{ steps.gate.outputs.inspect == 'true' }}
+ id: classify
+ shell: bash
+ env:
+ VERSION: ${{ steps.release.outputs.version }}
+ PREVIOUS_VERSION: ${{ steps.release.outputs.previous_version }}
+ NPM_DIST_TAG: ${{ steps.release.outputs.npm_dist_tag }}
+ TARGET_SHA: ${{ steps.release.outputs.target_sha }}
+ ELIGIBLE: ${{ steps.release.outputs.eligible }}
+ RELEASE_REASON: ${{ steps.release.outputs.reason }}
+ RELEASE_NOTES_FILE: ${{ steps.notes.outputs.release_notes_file }}
+ RELEASE_NOTES_SOURCE: ${{ steps.notes.outputs.release_notes_source }}
+ run: |
+ set -euo pipefail
+ {
+ echo "eligible=${ELIGIBLE}"
+ echo "reason=${RELEASE_REASON}"
+ echo "previous_version=${PREVIOUS_VERSION}"
+ echo "version=${VERSION}"
+ echo "npm_dist_tag=${NPM_DIST_TAG}"
+ echo "target_sha=${TARGET_SHA}"
+ echo "release_notes_source=${RELEASE_NOTES_SOURCE}"
+ echo "release_notes_file=${RELEASE_NOTES_FILE}"
+ } >> "${GITHUB_OUTPUT}"
+ {
+ echo
+ echo "- Automatic release: \`${ELIGIBLE}\`"
+ echo "- Version transition: \`${PREVIOUS_VERSION:-unchanged} -> ${VERSION:-unchanged}\`"
+ echo "- Result: ${RELEASE_REASON}"
+ } >> "${GITHUB_STEP_SUMMARY}"
+
+ publish:
+ needs: classify_auto_release
+ if: >-
+ ${{
+ github.event_name == 'workflow_dispatch' ||
+ needs.classify_auto_release.outputs.eligible == 'true'
+ }}
+ runs-on: ubuntu-latest
+ timeout-minutes: 30
+ permissions:
+ contents: write
+ steps:
+ - name: Validate immutable publish ref
+ if: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run != true }}
+ shell: bash
+ env:
+ RELEASE_GIT_REF: ${{ inputs.git_ref }}
+ RECOVER_EXISTING_NPM_RELEASE: ${{ inputs.recover_existing_npm_release }}
+ DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+ run: |
+ set -euo pipefail
+ if [ "${GITHUB_REF}" != "refs/heads/${DEFAULT_BRANCH}" ]; then
+ echo "::error::Real releases must be dispatched with Use workflow from=${DEFAULT_BRANCH}; got ${GITHUB_REF}."
+ exit 1
+ fi
+ if [ "${RECOVER_EXISTING_NPM_RELEASE}" != "true" ] && ! [[ "${RELEASE_GIT_REF}" =~ ^[0-9a-fA-F]{40}$ ]]; then
+ echo "::error::Normal real releases require git_ref to be the exact 40-character source_commit approved in the dry-run."
+ exit 1
+ fi
+ if [ "${RECOVER_EXISTING_NPM_RELEASE}" = "true" ] && [ -n "${RELEASE_GIT_REF//[[:space:]]/}" ] && [ "${RELEASE_GIT_REF}" != "${DEFAULT_BRANCH}" ] && [ "${RELEASE_GIT_REF}" != "refs/heads/${DEFAULT_BRANCH}" ]; then
+ echo "::error::Recovery runs use npm gitHead as the immutable source; leave git_ref blank or set it to ${DEFAULT_BRANCH}."
+ exit 1
+ fi
+
+ - uses: actions/checkout@v7
+ with:
+ ref: >-
+ ${{
+ github.event_name == 'pull_request' && needs.classify_auto_release.outputs.target_sha ||
+ inputs.git_ref || github.ref
+ }}
+ fetch-depth: 0
+ persist-credentials: ${{ github.event_name == 'pull_request' || inputs.dry_run != true }}
+
+ - uses: actions/setup-node@v7
+ with:
+ node-version: 22
+ registry-url: https://registry.npmjs.org
+
+ - name: Validate release inputs
+ id: release_policy
+ shell: bash
+ env:
+ RELEASE_VERSION: ${{ github.event_name == 'pull_request' && needs.classify_auto_release.outputs.version || inputs.version }}
+ NPM_DIST_TAG: ${{ github.event_name == 'pull_request' && needs.classify_auto_release.outputs.npm_dist_tag || inputs.tag }}
+ DRY_RUN: ${{ github.event_name == 'pull_request' && 'false' || inputs.dry_run }}
+ PUBLISH_CONFIRMATION: ${{ github.event_name == 'pull_request' && '' || inputs.publish_confirmation }}
+ RELEASE_FAULT_CASE: ${{ github.event_name == 'pull_request' && 'none' || inputs.fault_case }}
+ RELEASE_GIT_REF: ${{ github.event_name == 'pull_request' && needs.classify_auto_release.outputs.target_sha || inputs.git_ref }}
+ RECOVER_EXISTING_NPM_RELEASE: ${{ github.event_name == 'pull_request' && 'false' || inputs.recover_existing_npm_release }}
+ AUTOMATIC_RELEASE: ${{ github.event_name == 'pull_request' }}
+ DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+ run: |
+ set -euo pipefail
+ if [[ "${RELEASE_VERSION}" == [vV]* ]]; then
+ echo "::error::version must not include a leading v."
+ exit 1
+ fi
+ if ! [[ "${RELEASE_VERSION}" =~ ^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$ ]]; then
+ echo "::error::version must be a SemVer value like 0.1.20, 0.1.20-beta.1, or 0.1.20+build.1."
+ exit 1
+ fi
+ if [ -z "${NPM_DIST_TAG//[[:space:]]/}" ]; then
+ echo "::error::tag is required."
+ exit 1
+ fi
+ if ! [[ "${NPM_DIST_TAG}" =~ ^[A-Za-z0-9][A-Za-z0-9._-]*$ ]]; then
+ echo "::error::tag must be a valid npm dist-tag."
+ exit 1
+ fi
+ if [ "${DRY_RUN}" != "true" ] && [ "${RELEASE_FAULT_CASE}" != "none" ]; then
+ echo "::error::fault_case is only allowed when dry_run=true."
+ exit 1
+ fi
+ if [ "${DRY_RUN}" != "true" ] && [ "${AUTOMATIC_RELEASE}" != "true" ] && [ "${GITHUB_REF}" != "refs/heads/${DEFAULT_BRANCH}" ]; then
+ echo "::error::Real releases must be dispatched from the protected default branch ${DEFAULT_BRANCH}; got ${GITHUB_REF}."
+ exit 1
+ fi
+ if [ "${DRY_RUN}" != "true" ] && [ "${AUTOMATIC_RELEASE}" != "true" ]; then
+ if [ "${RECOVER_EXISTING_NPM_RELEASE}" != "true" ] && ! [[ "${RELEASE_GIT_REF}" =~ ^[0-9a-fA-F]{40}$ ]]; then
+ echo "::error::Normal real releases require git_ref to be the exact 40-character source_commit approved in the dry-run."
+ exit 1
+ fi
+ if [ "${RECOVER_EXISTING_NPM_RELEASE}" = "true" ] && [ -n "${RELEASE_GIT_REF//[[:space:]]/}" ] && [ "${RELEASE_GIT_REF}" != "${DEFAULT_BRANCH}" ] && [ "${RELEASE_GIT_REF}" != "refs/heads/${DEFAULT_BRANCH}" ]; then
+ echo "::error::Recovery runs use npm gitHead as the immutable source and cannot override git_ref away from ${DEFAULT_BRANCH}."
+ exit 1
+ fi
+ fi
+ if [ "${DRY_RUN}" != "true" ] && [ "${RECOVER_EXISTING_NPM_RELEASE}" != "true" ]; then
+ approved_commit="$(git rev-parse "${RELEASE_GIT_REF}^{commit}")"
+ checked_out_commit="$(git rev-parse HEAD)"
+ if [ "${checked_out_commit}" != "${approved_commit}" ]; then
+ echo "::error::Checked-out commit ${checked_out_commit} does not match approved dry-run commit ${approved_commit}."
+ exit 1
+ fi
+ fi
+ node .github/scripts/validate-release-confirmation.mjs
+
+ - name: Resolve immutable release source
+ id: release_source
+ shell: bash
+ env:
+ PACKAGE_NAME: "@memtensor/memos-cloud-openclaw-plugin"
+ RELEASE_VERSION: ${{ github.event_name == 'pull_request' && needs.classify_auto_release.outputs.version || inputs.version }}
+ AUTOMATIC_RELEASE: ${{ github.event_name == 'pull_request' }}
+ AUTOMATIC_RELEASE_TARGET: ${{ needs.classify_auto_release.outputs.target_sha }}
+ run: |
+ set -euo pipefail
+ release_tag="v${RELEASE_VERSION#v}"
+ npm_view_log="${RUNNER_TEMP}/openclaw-cloud-plugin-source-version.log"
+ npm_version_exists() {
+ for attempt in 1 2 3; do
+ set +e
+ npm view "${PACKAGE_NAME}@${RELEASE_VERSION}" version >"${npm_view_log}" 2>&1
+ status=$?
+ set -e
+ if [ "${status}" = 0 ]; then
+ return 0
+ fi
+ if grep -Eiq "E404|404 Not Found|No match found|is not in this registry" "${npm_view_log}"; then
+ return 1
+ fi
+ sed -n '1,120p' "${npm_view_log}" >&2
+ if [ "${attempt}" = 3 ]; then
+ echo "::error::Failed to determine whether ${PACKAGE_NAME}@${RELEASE_VERSION} exists."
+ exit "${status}"
+ fi
+ sleep "$((attempt * 5))"
+ done
+ }
+ npm_release_git_head() {
+ local out="${RUNNER_TEMP}/openclaw-cloud-plugin-source-git-head.log"
+ local git_head
+ for attempt in 1 2 3; do
+ set +e
+ npm view "${PACKAGE_NAME}@${RELEASE_VERSION}" gitHead >"${out}" 2>&1
+ status=$?
+ set -e
+ if [ "${status}" = 0 ]; then
+ git_head="$(tr -d '[:space:]"' <"${out}")"
+ if [[ "${git_head}" =~ ^[0-9a-fA-F]{40}$ ]]; then
+ printf '%s\n' "${git_head}"
+ return 0
+ fi
+ sed -n '1,80p' "${out}" >&2
+ if [ "${attempt}" = 3 ]; then
+ echo "::error::${PACKAGE_NAME}@${RELEASE_VERSION} has no trustworthy 40-character npm gitHead after three attempts." >&2
+ return 1
+ fi
+ sleep "$((attempt * 5))"
+ continue
+ fi
+ sed -n '1,80p' "${out}" >&2
+ if [ "${attempt}" = 3 ]; then
+ echo "::error::Failed to read npm gitHead for ${PACKAGE_NAME}@${RELEASE_VERSION}." >&2
+ return "${status}"
+ fi
+ sleep "$((attempt * 5))"
+ done
+ }
+ validate_release_commit_versions() {
+ local commit_sha="$1"
+ local file
+ local actual
+ for file in package.json openclaw.plugin.json moltbot.plugin.json clawdbot.plugin.json; do
+ actual="$(
+ git show "${commit_sha}:${file}" |
+ node -e 'let value=""; process.stdin.on("data", chunk => value += chunk); process.stdin.on("end", () => process.stdout.write(JSON.parse(value).version || ""));'
+ )"
+ if [ "${actual}" != "${RELEASE_VERSION}" ]; then
+ echo "::error::npm gitHead ${commit_sha} has ${file} version ${actual:-missing}, expected ${RELEASE_VERSION}."
+ exit 1
+ fi
+ done
+ }
+
+ evidence_ref=""
+ npm_git_head=""
+ if npm_version_exists; then
+ npm_git_head="$(npm_release_git_head)"
+ if [ "${AUTOMATIC_RELEASE}" = "true" ] && [ "${npm_git_head}" != "${AUTOMATIC_RELEASE_TARGET}" ]; then
+ echo "::error::npm records gitHead ${npm_git_head} for ${PACKAGE_NAME}@${RELEASE_VERSION}, but this automatic release is locked to merged commit ${AUTOMATIC_RELEASE_TARGET}."
+ exit 1
+ fi
+ if ! git cat-file -e "${npm_git_head}^{commit}" 2>/dev/null; then
+ bash .github/scripts/retry.sh --label "fetch npm gitHead ${npm_git_head}" -- \
+ git fetch --no-tags origin "${npm_git_head}"
+ fi
+ if ! git cat-file -e "${npm_git_head}^{commit}" 2>/dev/null; then
+ echo "::error::npm gitHead ${npm_git_head} is not a commit in ${GITHUB_REPOSITORY}."
+ exit 1
+ fi
+ validate_release_commit_versions "${npm_git_head}"
+
+ if git rev-parse --verify --quiet "${release_tag}^{commit}" >/dev/null; then
+ tag_commit="$(git rev-parse "${release_tag}^{commit}")"
+ if [ "${tag_commit}" != "${npm_git_head}" ]; then
+ echo "::error::Tag ${release_tag} points to ${tag_commit}, but npm records gitHead ${npm_git_head}."
+ exit 1
+ fi
+ evidence_ref="${release_tag}"
+ else
+ evidence_ref="${npm_git_head}"
+ echo "::notice::Tag ${release_tag} is missing; release evidence is pinned to npm gitHead ${npm_git_head}."
+ fi
+ elif git rev-parse --verify --quiet "${release_tag}^{commit}" >/dev/null; then
+ echo "::error::Tag ${release_tag} exists while ${PACKAGE_NAME}@${RELEASE_VERSION} is absent; refusing inconsistent release metadata."
+ exit 1
+ else
+ evidence_ref="HEAD"
+ fi
+
+ {
+ echo "evidence_ref=${evidence_ref}"
+ echo "npm_git_head=${npm_git_head}"
+ echo "source_commit=$(git rev-parse "${evidence_ref}^{commit}")"
+ } >> "${GITHUB_OUTPUT}"
+
+ - name: Install dependencies
+ shell: bash
+ run: bash .github/scripts/retry.sh --label "npm install" -- npm install
+
+ - name: Run tests
+ shell: bash
+ run: |
+ set -euo pipefail
+ bash .github/scripts/retry.sh --attempts 2 --label "release workflow script tests" -- node --test .github/scripts/*.test.mjs
+ if compgen -G "test/*.test.mjs" >/dev/null; then
+ bash .github/scripts/retry.sh --attempts 2 --label "plugin tests" -- node --test test/*.test.mjs
+ else
+ echo "No plugin tests found; skipping."
+ fi
+
+ - name: Validate committed release source version
+ shell: bash
+ env:
+ RELEASE_VERSION: ${{ github.event_name == 'pull_request' && needs.classify_auto_release.outputs.version || inputs.version }}
+ RELEASE_SOURCE_REF: ${{ steps.release_source.outputs.evidence_ref }}
+ run: |
+ set -euo pipefail
+ node .github/scripts/validate-release-source-version.mjs
+
+ - name: Generate telemetry credentials
+ shell: bash
+ env:
+ MEMOS_ARMS_ENDPOINT: ${{ secrets.MEMOS_ARMS_ENDPOINT }}
+ MEMOS_ARMS_PID: ${{ secrets.MEMOS_ARMS_PID }}
+ MEMOS_ARMS_ENV: ${{ secrets.MEMOS_ARMS_ENV }}
+ run: bash .github/scripts/retry.sh --label "generate telemetry credentials" -- node scripts/generate-telemetry-credentials.cjs
+
+ - name: Verify package contents
+ shell: bash
+ run: |
+ set -euo pipefail
+ bash .github/scripts/retry.sh --label "npm pack dry-run" -- bash -euo pipefail -c 'npm pack --dry-run --json > "${RUNNER_TEMP}/openclaw-cloud-plugin-pack.json"'
+
+ - name: Draft GitHub Release notes
+ id: release_notes
+ env:
+ RELEASE_VERSION: ${{ github.event_name == 'pull_request' && needs.classify_auto_release.outputs.version || inputs.version }}
+ RELEASE_TAG: v${{ github.event_name == 'pull_request' && needs.classify_auto_release.outputs.version || inputs.version }}
+ RELEASE_EVIDENCE_REF: ${{ steps.release_source.outputs.evidence_ref }}
+ MANUAL_RELEASE_NOTES: ${{ github.event_name == 'pull_request' && '' || inputs.release_notes }}
+ MANUAL_RELEASE_NOTES_FILE: ${{ github.event_name == 'pull_request' && needs.classify_auto_release.outputs.release_notes_file || '' }}
+ RELEASE_FAULT_CASE: ${{ github.event_name == 'pull_request' && 'none' || inputs.fault_case }}
+ DOC_AGENT_RELEASE_NOTES_DRAFT_URL: ${{ secrets.DOC_AGENT_RELEASE_NOTES_DRAFT_URL }}
+ DOC_AGENT_RELEASE_FAILURE_URL: ${{ secrets.DOC_AGENT_RELEASE_FAILURE_URL }}
+ DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN: ${{ secrets.DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN }}
+ run: node .github/scripts/draft-cloud-plugin-release-notes.mjs
+
+ - name: Prepare release inspection artifact
+ if: ${{ always() }}
+ shell: bash
+ env:
+ DRAFT_STEP_OUTCOME: ${{ steps.release_notes.outcome }}
+ DRY_RUN: ${{ github.event_name == 'pull_request' && 'false' || inputs.dry_run }}
+ RELEASE_VERSION: ${{ github.event_name == 'pull_request' && needs.classify_auto_release.outputs.version || inputs.version }}
+ FAULT_CASE: ${{ github.event_name == 'pull_request' && 'none' || inputs.fault_case }}
+ RELEASE_NOTES_SOURCE: ${{ github.event_name == 'pull_request' && needs.classify_auto_release.outputs.release_notes_source || (inputs.release_notes != '' && 'manual_input' || 'doc_agent') }}
+ RELEASE_NOTES_FILE: ${{ steps.release_notes.outputs.release_notes_file }}
+ EVIDENCE_FILE: ${{ steps.release_notes.outputs.evidence_file }}
+ DRAFT_FILE: ${{ steps.release_notes.outputs.draft_file }}
+ DOCS_PREVIEW_FILE: ${{ steps.release_notes.outputs.docs_preview_file }}
+ DOCS_PREVIEW_MARKDOWN_FILE: ${{ steps.release_notes.outputs.docs_preview_markdown_file }}
+ QUALITY_REPORT_FILE: ${{ steps.release_notes.outputs.quality_report_file }}
+ DRAFT_USED: ${{ steps.release_notes.outputs.draft_used }}
+ PREVIOUS_TAG: ${{ steps.release_notes.outputs.previous_tag }}
+ CURRENT_TAG: ${{ steps.release_notes.outputs.current_tag }}
+ CURRENT_REF: ${{ steps.release_notes.outputs.current_ref }}
+ SOURCE_COMMIT: ${{ steps.release_source.outputs.source_commit }}
+ RELEASE_CHANNEL: ${{ steps.release_policy.outputs.release_channel }}
+ NPM_DIST_TAG: ${{ steps.release_policy.outputs.npm_dist_tag }}
+ GITHUB_RELEASE_PRERELEASE: ${{ steps.release_policy.outputs.github_release_prerelease }}
+ DOCS_SYNC_EXPECTED: ${{ steps.release_policy.outputs.docs_sync_expected }}
+ DRAFT_CONFIDENCE: ${{ steps.release_notes.outputs.draft_confidence }}
+ MISSING_REQUIRED_COUNT: ${{ steps.release_notes.outputs.missing_required_count }}
+ VALIDATION_ATTEMPT_COUNT: ${{ steps.release_notes.outputs.validation_attempt_count }}
+ REPAIR_ATTEMPT_COUNT: ${{ steps.release_notes.outputs.repair_attempt_count }}
+ EXPECTED_PREVIOUS_TAG: ""
+ EXPECTED_CURRENT_REF: ""
+ run: |
+ set -euo pipefail
+ inspection_dir="${RUNNER_TEMP}/openclaw-cloud-plugin-release-inspection"
+ mkdir -p "${inspection_dir}"
+
+ if [ "${DRAFT_STEP_OUTCOME}" = "success" ] && { [ -z "${RELEASE_NOTES_FILE}" ] || [ ! -s "${RELEASE_NOTES_FILE}" ]; }; then
+ echo "::error::Release notes file was not generated."
+ exit 1
+ fi
+
+ if [ "${DRAFT_STEP_OUTCOME}" = "success" ] && [ -n "${EXPECTED_PREVIOUS_TAG:-}" ] && [ "${PREVIOUS_TAG:-}" != "${EXPECTED_PREVIOUS_TAG}" ]; then
+ echo "::error::Expected previous_tag=${EXPECTED_PREVIOUS_TAG}, got ${PREVIOUS_TAG:-n/a}."
+ exit 1
+ fi
+ if [ "${DRAFT_STEP_OUTCOME}" = "success" ] && [ -n "${EXPECTED_CURRENT_REF:-}" ] && [ "${CURRENT_REF:-}" != "${EXPECTED_CURRENT_REF}" ]; then
+ echo "::error::Expected current_ref=${EXPECTED_CURRENT_REF}, got ${CURRENT_REF:-n/a}."
+ exit 1
+ fi
+
+ if [ -n "${RELEASE_NOTES_FILE}" ] && [ -s "${RELEASE_NOTES_FILE}" ]; then
+ cp "${RELEASE_NOTES_FILE}" "${inspection_dir}/release-notes.md"
+ fi
+ if [ -s "${RUNNER_TEMP}/openclaw-cloud-plugin-pack.json" ]; then
+ cp "${RUNNER_TEMP}/openclaw-cloud-plugin-pack.json" "${inspection_dir}/npm-pack.json"
+ fi
+ if [ -n "${EVIDENCE_FILE}" ] && [ -s "${EVIDENCE_FILE}" ]; then
+ cp "${EVIDENCE_FILE}" "${inspection_dir}/evidence.json"
+ fi
+ if [ -n "${DRAFT_FILE}" ] && [ -s "${DRAFT_FILE}" ]; then
+ cp "${DRAFT_FILE}" "${inspection_dir}/release-notes-draft.json"
+ fi
+ if [ -n "${DOCS_PREVIEW_FILE}" ] && [ -s "${DOCS_PREVIEW_FILE}" ]; then
+ cp "${DOCS_PREVIEW_FILE}" "${inspection_dir}/docs-preview.json"
+ fi
+ if [ -n "${DOCS_PREVIEW_MARKDOWN_FILE}" ] && [ -s "${DOCS_PREVIEW_MARKDOWN_FILE}" ]; then
+ cp "${DOCS_PREVIEW_MARKDOWN_FILE}" "${inspection_dir}/docs-preview.md"
+ fi
+ if [ -n "${QUALITY_REPORT_FILE}" ] && [ -s "${QUALITY_REPORT_FILE}" ]; then
+ cp "${QUALITY_REPORT_FILE}" "${inspection_dir}/quality-report.json"
+ fi
+ if [ "${DRAFT_STEP_OUTCOME}" = "success" ] && [ ! -s "${inspection_dir}/quality-report.json" ]; then
+ echo "::error::quality-report.json was not generated."
+ exit 1
+ fi
+ github_release_prerelease_json="${GITHUB_RELEASE_PRERELEASE:-null}"
+ docs_sync_expected_json="${DOCS_SYNC_EXPECTED:-null}"
+ if [[ "${github_release_prerelease_json}" != "true" && "${github_release_prerelease_json}" != "false" ]]; then
+ github_release_prerelease_json=null
+ fi
+ if [[ "${docs_sync_expected_json}" != "true" && "${docs_sync_expected_json}" != "false" ]]; then
+ docs_sync_expected_json=null
+ fi
+ jq -n \
+ --arg version "${RELEASE_VERSION}" \
+ --arg source_commit "${SOURCE_COMMIT}" \
+ --arg evidence_ref "${CURRENT_REF:-}" \
+ --arg release_channel "${RELEASE_CHANNEL}" \
+ --arg npm_dist_tag "${NPM_DIST_TAG}" \
+ --argjson github_release_prerelease "${github_release_prerelease_json}" \
+ --argjson docs_sync_expected "${docs_sync_expected_json}" \
+ '{
+ version: $version,
+ source_commit: $source_commit,
+ evidence_ref: $evidence_ref,
+ release_channel: $release_channel,
+ npm_dist_tag: $npm_dist_tag,
+ github_release_prerelease: $github_release_prerelease,
+ docs_sync_expected: $docs_sync_expected
+ }' \
+ > "${inspection_dir}/release-source.json"
+
+ {
+ echo "# OpenClaw cloud plugin release inspection"
+ echo
+ echo "- draft_step_outcome: ${DRAFT_STEP_OUTCOME}"
+ echo "- dry_run: ${DRY_RUN}"
+ echo "- version: ${RELEASE_VERSION}"
+ echo "- release_channel: ${RELEASE_CHANNEL}"
+ echo "- npm_dist_tag: ${NPM_DIST_TAG}"
+ echo "- github_release_prerelease: ${GITHUB_RELEASE_PRERELEASE}"
+ echo "- docs_sync_expected: ${DOCS_SYNC_EXPECTED}"
+ echo "- fault_case: ${FAULT_CASE}"
+ echo "- release_notes_source: ${RELEASE_NOTES_SOURCE}"
+ echo "- draft_used: ${DRAFT_USED:-unknown}"
+ echo "- previous_tag: ${PREVIOUS_TAG:-n/a}"
+ echo "- current_tag: ${CURRENT_TAG:-n/a}"
+ echo "- current_ref: ${CURRENT_REF:-n/a}"
+ echo "- source_commit: ${SOURCE_COMMIT:-n/a}"
+ echo "- draft_confidence: ${DRAFT_CONFIDENCE:-n/a}"
+ echo "- missing_required_count: ${MISSING_REQUIRED_COUNT:-n/a}"
+ echo "- validation_attempt_count: ${VALIDATION_ATTEMPT_COUNT:-n/a}"
+ echo "- repair_attempt_count: ${REPAIR_ATTEMPT_COUNT:-n/a}"
+ echo
+ echo "Files:"
+ echo
+ if [ -f "${inspection_dir}/release-notes.md" ]; then
+ echo "- release-notes.md"
+ fi
+ if [ -f "${inspection_dir}/npm-pack.json" ]; then
+ echo "- npm-pack.json"
+ fi
+ if [ -f "${inspection_dir}/evidence.json" ]; then
+ echo "- evidence.json (redacted; no full diff or prompt guidance)"
+ fi
+ if [ -f "${inspection_dir}/release-notes-draft.json" ]; then
+ echo "- release-notes-draft.json"
+ fi
+ if [ -f "${inspection_dir}/docs-preview.md" ]; then
+ echo "- docs-preview.md"
+ echo "- docs-preview.json"
+ fi
+ if [ -f "${inspection_dir}/quality-report.json" ]; then
+ echo "- quality-report.json"
+ fi
+ echo "- release-source.json"
+ } > "${inspection_dir}/README.md"
+
+ {
+ echo "### OpenClaw cloud plugin release notes"
+ echo
+ echo "- draft_step_outcome: \`${DRAFT_STEP_OUTCOME}\`"
+ echo "- dry_run: \`${DRY_RUN}\`"
+ echo "- release_channel: \`${RELEASE_CHANNEL}\`"
+ echo "- npm_dist_tag: \`${NPM_DIST_TAG}\`"
+ echo "- github_release_prerelease: \`${GITHUB_RELEASE_PRERELEASE}\`"
+ echo "- docs_sync_expected: \`${DOCS_SYNC_EXPECTED}\`"
+ echo "- fault_case: \`${FAULT_CASE}\`"
+ echo "- release_notes_source: \`${RELEASE_NOTES_SOURCE}\`"
+ echo "- draft_used: \`${DRAFT_USED:-unknown}\`"
+ echo "- previous_tag: \`${PREVIOUS_TAG:-n/a}\`"
+ echo "- current_tag: \`${CURRENT_TAG:-n/a}\`"
+ echo "- current_ref: \`${CURRENT_REF:-n/a}\`"
+ echo "- source_commit: \`${SOURCE_COMMIT:-n/a}\`"
+ echo "- draft_confidence: \`${DRAFT_CONFIDENCE:-n/a}\`"
+ echo "- missing_required_count: \`${MISSING_REQUIRED_COUNT:-n/a}\`"
+ echo "- validation_attempt_count: \`${VALIDATION_ATTEMPT_COUNT:-n/a}\`"
+ echo "- repair_attempt_count: \`${REPAIR_ATTEMPT_COUNT:-n/a}\`"
+ echo
+ echo "Download the workflow artifact \`openclaw-cloud-plugin-release-inspection\` to review release-notes.md, quality-report.json, release-notes-draft.json, and redacted evidence.json."
+ if [ -f "${inspection_dir}/docs-preview.md" ]; then
+ echo
+ echo "### MemOS-Docs preview"
+ echo
+ sed -n '1,120p' "${inspection_dir}/docs-preview.md"
+ fi
+ } >> "${GITHUB_STEP_SUMMARY}"
+
+ - name: Upload release inspection artifact
+ if: ${{ always() }}
+ uses: actions/upload-artifact@v7
+ with:
+ name: openclaw-cloud-plugin-release-inspection
+ path: ${{ runner.temp }}/openclaw-cloud-plugin-release-inspection
+ if-no-files-found: error
+
+ - name: Stop before publish in dry run
+ if: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run == true }}
+ run: |
+ echo "::notice::dry_run=true; skipped npm publish, tag, and GitHub Release."
+
+ - name: Publish to npm
+ id: publish_npm
+ if: ${{ github.event_name == 'pull_request' || inputs.dry_run != true }}
+ env:
+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+ GH_TOKEN: ${{ github.token }}
+ PACKAGE_NAME: "@memtensor/memos-cloud-openclaw-plugin"
+ RELEASE_VERSION: ${{ github.event_name == 'pull_request' && needs.classify_auto_release.outputs.version || inputs.version }}
+ RELEASE_TAG: v${{ github.event_name == 'pull_request' && needs.classify_auto_release.outputs.version || inputs.version }}
+ NPM_DIST_TAG: ${{ github.event_name == 'pull_request' && needs.classify_auto_release.outputs.npm_dist_tag || inputs.tag }}
+ CREATE_DRAFT_RELEASE: ${{ github.event_name == 'pull_request' || inputs.recover_existing_npm_release == true }}
+ EXPECTED_RELEASE_PRERELEASE: ${{ steps.release_policy.outputs.github_release_prerelease }}
+ RECOVER_EXISTING_NPM_RELEASE: ${{ github.event_name == 'pull_request' && 'false' || inputs.recover_existing_npm_release }}
+ AUTOMATIC_RELEASE: ${{ github.event_name == 'pull_request' }}
+ AUTOMATIC_RELEASE_TARGET: ${{ needs.classify_auto_release.outputs.target_sha }}
+ DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
+ DOC_AGENT_RELEASE_FAILURE_URL: ${{ secrets.DOC_AGENT_RELEASE_FAILURE_URL }}
+ DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN: ${{ secrets.DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN }}
+ NPM_VISIBILITY_TIMEOUT_SECONDS: "150"
+ NPM_VISIBILITY_INTERVAL_SECONDS: "10"
+ NPM_VISIBILITY_REQUEST_TIMEOUT_SECONDS: "8"
+ run: |
+ set -euo pipefail
+
+ release_tag="v${RELEASE_VERSION#v}"
+ expected_release_prerelease="${EXPECTED_RELEASE_PRERELEASE}"
+ report_exhausted_failure() {
+ local phase="$1"
+ local attempt_dir="$2"
+ RELEASE_FAILURE_PHASE="${phase}" \
+ RELEASE_FAILURE_ATTEMPT_DIR="${attempt_dir}" \
+ node .github/scripts/draft-cloud-plugin-release-notes.mjs \
+ || echo "::warning::Failed to report exhausted ${phase} attempts."
+ }
+
+ npm_view_log="${RUNNER_TEMP}/openclaw-cloud-plugin-npm-view.log"
+ npm_version_exists() {
+ for attempt in 1 2 3; do
+ set +e
+ npm view "${PACKAGE_NAME}@${RELEASE_VERSION}" version >"${npm_view_log}" 2>&1
+ status=$?
+ set -e
+ if [ "${status}" = 0 ]; then
+ sed -n '1,40p' "${npm_view_log}"
+ return 0
+ fi
+ if grep -Eiq "E404|404 Not Found|No match found|is not in this registry" "${npm_view_log}"; then
+ return 1
+ fi
+ sed -n '1,120p' "${npm_view_log}"
+ if [ "${attempt}" = 3 ]; then
+ echo "::error::npm view failed after three attempts; refusing to guess whether ${PACKAGE_NAME}@${RELEASE_VERSION} exists."
+ exit "${status}"
+ fi
+ sleep "$((attempt * 5))"
+ done
+ }
+ npm_release_git_head() {
+ local out="${RUNNER_TEMP}/openclaw-cloud-plugin-npm-git-head.log"
+ local git_head
+ for attempt in 1 2 3; do
+ set +e
+ npm view "${PACKAGE_NAME}@${RELEASE_VERSION}" gitHead >"${out}" 2>&1
+ status=$?
+ set -e
+ if [ "${status}" = 0 ]; then
+ git_head="$(tr -d '[:space:]"' <"${out}")"
+ if [[ "${git_head}" =~ ^[0-9a-fA-F]{40}$ ]]; then
+ printf '%s\n' "${git_head}"
+ return 0
+ fi
+ sed -n '1,80p' "${out}" >&2
+ if [ "${attempt}" = 3 ]; then
+ echo "::error::${PACKAGE_NAME}@${RELEASE_VERSION} has no trustworthy 40-character npm gitHead after three attempts." >&2
+ return 1
+ fi
+ sleep "$((attempt * 5))"
+ continue
+ fi
+ sed -n '1,80p' "${out}" >&2
+ if [ "${attempt}" = 3 ]; then
+ echo "::error::Failed to read npm gitHead for ${PACKAGE_NAME}@${RELEASE_VERSION} after three attempts." >&2
+ return "${status}"
+ fi
+ sleep "$((attempt * 5))"
+ done
+ }
+ wait_for_npm_release_visibility() {
+ local expected_git_head="$1"
+ NPM_PACKAGE_NAME="${PACKAGE_NAME}" \
+ NPM_RELEASE_VERSION="${RELEASE_VERSION}" \
+ NPM_DIST_TAG="${NPM_DIST_TAG}" \
+ NPM_EXPECTED_GIT_HEAD="${expected_git_head}" \
+ NPM_VISIBILITY_TIMEOUT_SECONDS="${NPM_VISIBILITY_TIMEOUT_SECONDS}" \
+ NPM_VISIBILITY_INTERVAL_SECONDS="${NPM_VISIBILITY_INTERVAL_SECONDS}" \
+ NPM_VISIBILITY_REQUEST_TIMEOUT_SECONDS="${NPM_VISIBILITY_REQUEST_TIMEOUT_SECONDS}" \
+ node .github/scripts/wait-for-npm-release.mjs
+ }
+ ensure_commit_available() {
+ local commit_sha="$1"
+ if git cat-file -e "${commit_sha}^{commit}" 2>/dev/null; then
+ return 0
+ fi
+ bash .github/scripts/retry.sh --label "fetch npm gitHead ${commit_sha}" -- \
+ git fetch --no-tags origin "${commit_sha}"
+ if ! git cat-file -e "${commit_sha}^{commit}" 2>/dev/null; then
+ echo "::error::npm gitHead ${commit_sha} is not a commit in ${GITHUB_REPOSITORY}."
+ exit 1
+ fi
+ }
+ validate_release_commit_versions() {
+ local commit_sha="$1"
+ local file
+ local actual
+ for file in package.json openclaw.plugin.json moltbot.plugin.json clawdbot.plugin.json; do
+ actual="$(
+ git show "${commit_sha}:${file}" |
+ node -e 'let value=""; process.stdin.on("data", chunk => value += chunk); process.stdin.on("end", () => process.stdout.write(JSON.parse(value).version || ""));'
+ )"
+ if [ "${actual}" != "${RELEASE_VERSION}" ]; then
+ echo "::error::npm gitHead ${commit_sha} has ${file} version ${actual:-missing}, expected ${RELEASE_VERSION}."
+ exit 1
+ fi
+ done
+ }
+ remote_tag_exists() {
+ local release_tag="$1"
+ for attempt in 1 2 3; do
+ set +e
+ git ls-remote --exit-code --tags origin "refs/tags/${release_tag}" >/dev/null 2>&1
+ status=$?
+ set -e
+ if [ "${status}" = 0 ]; then
+ return 0
+ fi
+ if [ "${status}" = 2 ]; then
+ return 1
+ fi
+ if [ "${attempt}" = 3 ]; then
+ echo "::error::Failed to check remote tag ${release_tag} after three attempts."
+ exit "${status}"
+ fi
+ sleep "$((attempt * 5))"
+ done
+ }
+ remote_branch_sha() {
+ local branch="$1"
+ local out="${RUNNER_TEMP}/openclaw-cloud-plugin-remote-branch.txt"
+ for attempt in 1 2 3; do
+ set +e
+ git ls-remote --heads origin "${branch}" >"${out}" 2>&1
+ status=$?
+ set -e
+ if [ "${status}" = 0 ]; then
+ awk '{print $1}' "${out}"
+ return 0
+ fi
+ sed -n '1,120p' "${out}" >&2
+ if [ "${attempt}" = 3 ]; then
+ echo "::error::Failed to check remote branch ${branch} after three attempts."
+ exit "${status}"
+ fi
+ sleep "$((attempt * 5))"
+ done
+ }
+ release_inventory_file="${RUNNER_TEMP}/openclaw-cloud-plugin-release-inventory.json"
+ refresh_release_inventory() {
+ local out="${release_inventory_file}.tmp"
+ local err="${release_inventory_file}.err"
+ for attempt in 1 2 3; do
+ set +e
+ gh api --paginate --slurp \
+ "repos/${GITHUB_REPOSITORY}/releases?per_page=100" >"${out}" 2>"${err}"
+ status=$?
+ set -e
+ if [ "${status}" = 0 ]; then
+ mv "${out}" "${release_inventory_file}"
+ return 0
+ fi
+ sed -n '1,120p' "${err}" >&2
+ if [ "${attempt}" = 3 ]; then
+ echo "::error::Failed to enumerate GitHub Releases after three attempts."
+ exit "${status}"
+ fi
+ sleep "$((attempt * 5))"
+ done
+ }
+ inspect_release_inventory() {
+ local expected_target="${1:-}"
+ RELEASE_INVENTORY_FILE="${release_inventory_file}" \
+ RELEASE_TAG="${release_tag}" \
+ EXPECTED_RELEASE_DRAFT="${CREATE_DRAFT_RELEASE}" \
+ EXPECTED_RELEASE_PRERELEASE="${expected_release_prerelease}" \
+ EXPECTED_RELEASE_TARGET="${expected_target}" \
+ REQUIRED_DOC_AGENT_SOURCE_ID=openclaw-cloud-plugin \
+ REQUIRE_EXISTING_RELEASE=false \
+ ALLOW_PUBLISHED_FOR_DRAFT_RERUN="${CREATE_DRAFT_RELEASE}" \
+ node .github/scripts/validate-github-release-inventory.mjs
+ }
+
+ tag_exists=false
+ tag_commit=""
+ if remote_tag_exists "${release_tag}"; then
+ tag_exists=true
+ git fetch --force origin "refs/tags/${release_tag}:refs/tags/${release_tag}"
+ tag_commit="$(git rev-parse "${release_tag}^{commit}")"
+ fi
+
+ refresh_release_inventory
+ set +e
+ release_inventory_report="$(inspect_release_inventory "")"
+ release_inventory_status=$?
+ set -e
+ if [ "${release_inventory_status}" -ne 0 ]; then
+ echo "::error::${release_inventory_report}"
+ exit 1
+ fi
+ release_state="$(printf '%s' "${release_inventory_report}" | jq -r '.state')"
+ release_exists=false
+ if [ "${release_state}" = "existing" ]; then
+ release_exists=true
+ fi
+
+ if npm_version_exists; then
+ release_commit_sha="$(npm_release_git_head)"
+ if [ "${AUTOMATIC_RELEASE}" = "true" ] && [ "${release_commit_sha}" != "${AUTOMATIC_RELEASE_TARGET}" ]; then
+ echo "::error::npm records gitHead ${release_commit_sha} for ${PACKAGE_NAME}@${RELEASE_VERSION}, but this automatic release is locked to merged commit ${AUTOMATIC_RELEASE_TARGET}."
+ exit 1
+ fi
+ ensure_commit_available "${release_commit_sha}"
+ validate_release_commit_versions "${release_commit_sha}"
+
+ if [ "${tag_exists}" = "true" ] && [ "${tag_commit}" != "${release_commit_sha}" ]; then
+ echo "::error::Tag ${release_tag} points to ${tag_commit}, but npm ${PACKAGE_NAME}@${RELEASE_VERSION} records gitHead ${release_commit_sha}."
+ exit 1
+ fi
+ if [ "${tag_exists}" = "true" ] && [ "${release_exists}" = "true" ]; then
+ echo "${PACKAGE_NAME}@${RELEASE_VERSION}, ${release_tag}, and its validated GitHub Release already exist; treating this as an idempotent rerun."
+ elif [ "${RECOVER_EXISTING_NPM_RELEASE}" = "true" ] || [ "${AUTOMATIC_RELEASE}" = "true" ]; then
+ echo "Verified resume mode enabled; npm version exists, so publish is skipped and missing GitHub metadata will target npm gitHead ${release_commit_sha}."
+ else
+ missing=()
+ if [ "${tag_exists}" != "true" ]; then
+ missing+=("${release_tag}")
+ fi
+ if [ "${release_exists}" != "true" ]; then
+ missing+=("GitHub Release ${release_tag}")
+ fi
+ printf -v missing_text "%s, " "${missing[@]}"
+ missing_text="${missing_text%, }"
+ echo "::error::${PACKAGE_NAME}@${RELEASE_VERSION} already exists on npm, but ${missing_text} is missing. Set recover_existing_npm_release=true only for an intentional metadata backfill pinned to npm gitHead."
+ exit 1
+ fi
+ else
+ if [ "${RECOVER_EXISTING_NPM_RELEASE}" = "true" ]; then
+ echo "::error::Recovery requires ${PACKAGE_NAME}@${RELEASE_VERSION} to already exist on npm. Refusing to turn metadata recovery into a first publish."
+ exit 1
+ fi
+ if [ "${tag_exists}" = "true" ] || [ "${release_exists}" = "true" ]; then
+ echo "::error::Refusing to publish ${PACKAGE_NAME}@${RELEASE_VERSION}: GitHub tag/Release metadata already exists while npm does not."
+ exit 1
+ fi
+
+ source_commit_sha="$(git rev-parse HEAD)"
+ remote_default_sha="$(remote_branch_sha "${DEFAULT_BRANCH}")"
+ if [ -z "${remote_default_sha}" ]; then
+ echo "::error::Could not resolve the protected default branch ${DEFAULT_BRANCH}."
+ exit 1
+ fi
+ if [ "${AUTOMATIC_RELEASE}" = "true" ]; then
+ if [ "${source_commit_sha}" != "${AUTOMATIC_RELEASE_TARGET}" ]; then
+ echo "::error::Checked-out source ${source_commit_sha} does not match the merged version PR target ${AUTOMATIC_RELEASE_TARGET}."
+ exit 1
+ fi
+ git fetch --no-tags origin "${DEFAULT_BRANCH}"
+ if ! git merge-base --is-ancestor "${source_commit_sha}" "origin/${DEFAULT_BRANCH}"; then
+ echo "::error::Merged release target ${source_commit_sha} is no longer an ancestor of ${DEFAULT_BRANCH}."
+ exit 1
+ fi
+ elif [ "${remote_default_sha}" != "${source_commit_sha}" ]; then
+ echo "::error::The checked-out release source ${source_commit_sha} is no longer the head of ${DEFAULT_BRANCH} (${remote_default_sha}). Rerun the workflow from the latest main commit."
+ exit 1
+ fi
+ release_commit_sha="${source_commit_sha}"
+ validate_release_commit_versions "${release_commit_sha}"
+ echo "Publishing the already-reviewed ${DEFAULT_BRANCH} commit ${release_commit_sha}; no source files or version PR will be created by Actions."
+
+ attempt_dir="${RUNNER_TEMP}/openclaw-cloud-plugin-npm-publish-attempts"
+ mkdir -p "${attempt_dir}"
+ publish_confirmed=false
+ for attempt in 1 2 3; do
+ set +e
+ npm publish --access public --tag "${NPM_DIST_TAG}" >"${attempt_dir}/${attempt}.log" 2>&1
+ publish_status=$?
+ set -e
+ sed -n '1,160p' "${attempt_dir}/${attempt}.log"
+ set +e
+ wait_for_npm_release_visibility "${release_commit_sha}" 2>&1 |
+ tee -a "${attempt_dir}/${attempt}.log"
+ visibility_status="${PIPESTATUS[0]}"
+ set -e
+ if [ "${visibility_status}" = 0 ]; then
+ publish_confirmed=true
+ elif [ "${visibility_status}" = 2 ]; then
+ report_exhausted_failure "npm-publish-verification" "${attempt_dir}"
+ echo "::error::npm exposed immutable metadata that does not match the reviewed release source; refusing any publish retry."
+ exit 1
+ fi
+ if [ "${publish_confirmed}" = "true" ]; then
+ if [ "${publish_status}" = 0 ]; then
+ echo "npm publish and the bounded registry visibility check both succeeded."
+ else
+ echo "Publish returned an error, but npm now contains the fully verified release; refusing a duplicate publish."
+ fi
+ break
+ fi
+ if [ "${publish_status}" = 0 ]; then
+ report_exhausted_failure "npm-publish-verification" "${attempt_dir}"
+ echo "::error::npm publish returned success, but version, gitHead, and dist-tag were not all visible within ${NPM_VISIBILITY_TIMEOUT_SECONDS}s. Refusing to issue a second publish request."
+ exit 1
+ fi
+ if [ "${attempt}" = 3 ]; then
+ report_exhausted_failure "npm-publish" "${attempt_dir}"
+ echo "::error::npm publish failed after three attempts, and no fully verified release became visible."
+ exit 1
+ fi
+ sleep "$((attempt * 5))"
+ done
+ if [ "${publish_confirmed}" != "true" ]; then
+ echo "::error::npm publish appeared to finish, but ${PACKAGE_NAME}@${RELEASE_VERSION} is still not visible."
+ exit 1
+ fi
+ fi
+
+ echo "release_commit_sha=${release_commit_sha}" >> "${GITHUB_OUTPUT}"
+
+ - name: Create release tag and GitHub Release
+ if: ${{ github.event_name == 'pull_request' || inputs.dry_run != true }}
+ env:
+ GH_TOKEN: ${{ github.token }}
+ RELEASE_VERSION: ${{ github.event_name == 'pull_request' && needs.classify_auto_release.outputs.version || inputs.version }}
+ NPM_DIST_TAG: ${{ github.event_name == 'pull_request' && needs.classify_auto_release.outputs.npm_dist_tag || inputs.tag }}
+ CREATE_DRAFT_RELEASE: ${{ github.event_name == 'pull_request' || inputs.recover_existing_npm_release == true }}
+ EXPECTED_RELEASE_PRERELEASE: ${{ steps.release_policy.outputs.github_release_prerelease }}
+ RELEASE_NOTES_FILE: ${{ steps.release_notes.outputs.release_notes_file }}
+ RELEASE_COMMIT_SHA: ${{ steps.publish_npm.outputs.release_commit_sha }}
+ DOC_AGENT_RELEASE_FAILURE_URL: ${{ secrets.DOC_AGENT_RELEASE_FAILURE_URL }}
+ DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN: ${{ secrets.DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN }}
+ GITHUB_RELEASE_VISIBILITY_ATTEMPTS: "12"
+ GITHUB_RELEASE_VISIBILITY_INTERVAL_SECONDS: "10"
+ run: |
+ set -euo pipefail
+ if [ -z "${RELEASE_NOTES_FILE}" ] || [ ! -s "${RELEASE_NOTES_FILE}" ]; then
+ echo "::error::Release notes file was not generated."
+ exit 1
+ fi
+ if ! [[ "${RELEASE_COMMIT_SHA}" =~ ^[0-9a-fA-F]{40}$ ]]; then
+ echo "::error::Publish step did not provide a trustworthy release commit SHA."
+ exit 1
+ fi
+ if ! git cat-file -e "${RELEASE_COMMIT_SHA}^{commit}" 2>/dev/null; then
+ echo "::error::Release commit ${RELEASE_COMMIT_SHA} is not available locally."
+ exit 1
+ fi
+
+ git config user.name "github-actions[bot]"
+ git config user.email "github-actions[bot]@users.noreply.github.com"
+
+ release_tag="v${RELEASE_VERSION#v}"
+ expected_release_prerelease="${EXPECTED_RELEASE_PRERELEASE}"
+ report_exhausted_failure() {
+ local phase="$1"
+ local attempt_dir="$2"
+ RELEASE_FAILURE_PHASE="${phase}" \
+ RELEASE_FAILURE_ATTEMPT_DIR="${attempt_dir}" \
+ RELEASE_TAG="${release_tag}" \
+ node .github/scripts/draft-cloud-plugin-release-notes.mjs \
+ || echo "::warning::Failed to report exhausted ${phase} attempts."
+ }
+ remote_tag_exists() {
+ local tag="$1"
+ local attempt_dir="${RUNNER_TEMP}/openclaw-cloud-plugin-remote-tag-attempts"
+ mkdir -p "${attempt_dir}"
+ for attempt in 1 2 3; do
+ set +e
+ git ls-remote --exit-code --tags origin "refs/tags/${tag}" >"${attempt_dir}/${attempt}.log" 2>&1
+ status=$?
+ set -e
+ if [ "${status}" = 0 ]; then
+ return 0
+ fi
+ if [ "${status}" = 2 ]; then
+ return 1
+ fi
+ if [ "${attempt}" = 3 ]; then
+ report_exhausted_failure "github-release-tag-lookup" "${attempt_dir}"
+ echo "::error::Failed to check remote tag ${tag} after three attempts."
+ exit "${status}"
+ fi
+ sleep "$((attempt * 5))"
+ done
+ }
+ release_inventory_file="${RUNNER_TEMP}/openclaw-cloud-plugin-release-inventory.json"
+ refresh_release_inventory() {
+ local out="${release_inventory_file}.tmp"
+ local attempt_dir="${RUNNER_TEMP}/openclaw-cloud-plugin-release-inventory-attempts"
+ mkdir -p "${attempt_dir}"
+ for attempt in 1 2 3; do
+ set +e
+ gh api --paginate --slurp \
+ "repos/${GITHUB_REPOSITORY}/releases?per_page=100" >"${out}" 2>"${attempt_dir}/${attempt}.log"
+ status=$?
+ set -e
+ if [ "${status}" = 0 ]; then
+ mv "${out}" "${release_inventory_file}"
+ return 0
+ fi
+ sed -n '1,120p' "${attempt_dir}/${attempt}.log" >&2
+ if [ "${attempt}" = 3 ]; then
+ report_exhausted_failure "github-release-inventory" "${attempt_dir}"
+ echo "::error::Failed to enumerate GitHub Releases after three attempts."
+ exit "${status}"
+ fi
+ sleep "$((attempt * 5))"
+ done
+ }
+ inspect_release_inventory() {
+ local require_existing="$1"
+ RELEASE_INVENTORY_FILE="${release_inventory_file}" \
+ RELEASE_TAG="${release_tag}" \
+ EXPECTED_RELEASE_DRAFT="${CREATE_DRAFT_RELEASE}" \
+ EXPECTED_RELEASE_PRERELEASE="${expected_release_prerelease}" \
+ EXPECTED_RELEASE_TARGET="${RELEASE_COMMIT_SHA}" \
+ REQUIRED_DOC_AGENT_SOURCE_ID=openclaw-cloud-plugin \
+ REQUIRE_EXISTING_RELEASE="${require_existing}" \
+ ALLOW_PUBLISHED_FOR_DRAFT_RERUN="${CREATE_DRAFT_RELEASE}" \
+ node .github/scripts/validate-github-release-inventory.mjs
+ }
+ create_release_if_missing() {
+ local release_flags=()
+ local create_attempt_dir="${RUNNER_TEMP}/openclaw-cloud-plugin-release-create-attempts"
+ local verification_attempt_dir="${RUNNER_TEMP}/openclaw-cloud-plugin-release-verification-attempts"
+ mkdir -p "${create_attempt_dir}" "${verification_attempt_dir}"
+ if [ "${expected_release_prerelease}" = "true" ]; then
+ release_flags+=(--prerelease)
+ echo "Marking GitHub Release ${release_tag} as prerelease because version=${RELEASE_VERSION}, npm_dist_tag=${NPM_DIST_TAG}."
+ fi
+ if [ "${CREATE_DRAFT_RELEASE}" = "true" ]; then
+ release_flags+=(--draft)
+ echo "Creating GitHub Release ${release_tag} as a Draft for human review. Publishing the Draft is the only Docs webhook boundary."
+ fi
+
+ for attempt in 1 2 3; do
+ refresh_release_inventory
+ set +e
+ release_inventory_report="$(inspect_release_inventory false)"
+ release_inventory_status=$?
+ set -e
+ release_inventory_state="$(
+ printf '%s' "${release_inventory_report}" |
+ jq -r '.state // "invalid"'
+ )"
+ if [ "${release_inventory_status}" -eq 0 ] && [ "${release_inventory_state}" = "existing" ]; then
+ echo "GitHub Release ${release_tag} already exists with matching source metadata; leaving it unchanged."
+ return 0
+ fi
+ if [ "${release_inventory_status}" -ne 0 ] || [ "${release_inventory_state}" != "absent" ]; then
+ echo "::error::${release_inventory_report}"
+ exit 1
+ fi
+
+ echo "::group::create GitHub Release attempt ${attempt}/3"
+ set +e
+ gh release create "${release_tag}" \
+ --repo "${GITHUB_REPOSITORY}" \
+ --target "${RELEASE_COMMIT_SHA}" \
+ --title "OpenClaw Cloud Plugin ${release_tag}" \
+ --notes-file "${RELEASE_NOTES_FILE}" \
+ "${release_flags[@]}" >"${create_attempt_dir}/${attempt}.log" 2>&1
+ create_status=$?
+ set -e
+ sed -n '1,160p' "${create_attempt_dir}/${attempt}.log"
+ echo "::endgroup::"
+
+ release_verified=false
+ for poll_attempt in $(seq 1 "${GITHUB_RELEASE_VISIBILITY_ATTEMPTS}"); do
+ refresh_release_inventory
+ set +e
+ release_inventory_report="$(inspect_release_inventory true)"
+ release_inventory_status=$?
+ set -e
+ printf '%s\n' "${release_inventory_report}" >"${verification_attempt_dir}/${poll_attempt}.log"
+ release_inventory_state="$(
+ printf '%s' "${release_inventory_report}" |
+ jq -r '.state // "invalid"'
+ )"
+ if [ "${release_inventory_status}" -eq 0 ]; then
+ if [ "${create_status}" -ne 0 ]; then
+ echo "::notice::GitHub Release ${release_tag} exists with correct metadata after an unsuccessful create response."
+ fi
+ release_verified=true
+ break
+ fi
+ if [ "${release_inventory_state}" != "absent" ]; then
+ echo "::error::${release_inventory_report}"
+ exit 1
+ fi
+ if [ "${poll_attempt}" -lt "${GITHUB_RELEASE_VISIBILITY_ATTEMPTS}" ]; then
+ sleep "${GITHUB_RELEASE_VISIBILITY_INTERVAL_SECONDS}"
+ fi
+ done
+
+ if [ "${release_verified}" = "true" ]; then
+ return 0
+ fi
+ if [ "${create_status}" -eq 0 ]; then
+ report_exhausted_failure "github-release-verification" "${verification_attempt_dir}"
+ echo "::error::GitHub reported a successful Release create, but ${release_tag} could not be verified. Refusing to issue a second create request."
+ exit 1
+ fi
+ if [ "${attempt}" -lt 3 ]; then
+ sleep "$((attempt * 5))"
+ fi
+ done
+
+ report_exhausted_failure "github-release-create" "${create_attempt_dir}"
+ echo "::error::Failed to create and verify GitHub Release ${release_tag} after three attempts."
+ exit 1
+ }
+ refresh_release_inventory
+ set +e
+ release_inventory_report="$(inspect_release_inventory false)"
+ release_inventory_status=$?
+ set -e
+ if [ "${release_inventory_status}" -ne 0 ]; then
+ echo "::error::${release_inventory_report}"
+ exit 1
+ fi
+
+ if remote_tag_exists "${release_tag}"; then
+ git fetch --force origin "refs/tags/${release_tag}:refs/tags/${release_tag}"
+ actual_tag_commit="$(git rev-parse "${release_tag}^{commit}")"
+ if [ "${actual_tag_commit}" != "${RELEASE_COMMIT_SHA}" ]; then
+ echo "::error::Tag ${release_tag} points to ${actual_tag_commit}, expected npm gitHead ${RELEASE_COMMIT_SHA}."
+ exit 1
+ fi
+ echo "Tag ${release_tag} already points to npm gitHead ${RELEASE_COMMIT_SHA}; leaving it unchanged."
+ else
+ if git rev-parse --verify "refs/tags/${release_tag}" >/dev/null 2>&1; then
+ echo "::error::A local-only tag ${release_tag} exists while the remote tag is absent; refusing to overwrite or guess."
+ exit 1
+ fi
+ git tag -a "${release_tag}" "${RELEASE_COMMIT_SHA}" -m "OpenClaw Cloud Plugin ${release_tag}"
+ tag_attempt_dir="${RUNNER_TEMP}/openclaw-cloud-plugin-release-tag-push-attempts"
+ if ! RETRY_ATTEMPT_DIR="${tag_attempt_dir}" \
+ bash .github/scripts/retry.sh --label "push release tag" -- \
+ git push origin "refs/tags/${release_tag}"; then
+ report_exhausted_failure "github-release-tag-push" "${tag_attempt_dir}"
+ exit 1
+ fi
+ fi
+
+ create_release_if_missing
+
+ if [ "${CREATE_DRAFT_RELEASE}" = "true" ]; then
+ {
+ echo "### Draft Release ready for review"
+ echo
+ echo "- npm ${RELEASE_VERSION} and tag ${release_tag} were verified before the Draft was created."
+ echo "- Review the Draft Release body and Docs preview."
+ echo "- Stable release: click Publish only after review; that release.published event triggers 106."
+ echo "- Prerelease: publishing remains a GitHub Prerelease and 106 must skip formal Docs sync."
+ } >> "${GITHUB_STEP_SUMMARY}"
+ fi
diff --git a/.github/workflows/workflow-contract-lint.yml b/.github/workflows/workflow-contract-lint.yml
new file mode 100644
index 000000000..e9a7839cc
--- /dev/null
+++ b/.github/workflows/workflow-contract-lint.yml
@@ -0,0 +1,81 @@
+name: OpenClaw Cloud Plugin — Workflow Contract Lint
+
+on:
+ pull_request:
+ branches:
+ - main
+ paths:
+ - ".github/workflows/**"
+ - ".github/scripts/resolve-auto-release.mjs"
+ - ".github/scripts/resolve-auto-release.test.mjs"
+ - ".github/scripts/validate-github-release-inventory.mjs"
+ - ".github/scripts/validate-github-release-inventory.test.mjs"
+ - ".github/scripts/validate-release-confirmation.mjs"
+ - ".github/scripts/validate-release-confirmation.test.mjs"
+ - ".github/scripts/validate-release-source-version.mjs"
+ - ".github/scripts/validate-release-source-version.test.mjs"
+ - ".github/scripts/wait-for-npm-release.mjs"
+ - ".github/scripts/wait-for-npm-release.test.mjs"
+ push:
+ branches:
+ - main
+ - "docs-sync/**"
+ - "fix/**"
+ paths:
+ - ".github/workflows/**"
+ - ".github/scripts/validate-github-release-inventory.mjs"
+ - ".github/scripts/validate-github-release-inventory.test.mjs"
+ - ".github/scripts/resolve-auto-release.mjs"
+ - ".github/scripts/resolve-auto-release.test.mjs"
+ - ".github/scripts/validate-release-confirmation.mjs"
+ - ".github/scripts/validate-release-confirmation.test.mjs"
+ - ".github/scripts/validate-release-source-version.mjs"
+ - ".github/scripts/validate-release-source-version.test.mjs"
+ - ".github/scripts/wait-for-npm-release.mjs"
+ - ".github/scripts/wait-for-npm-release.test.mjs"
+
+permissions:
+ contents: read
+
+jobs:
+ actionlint:
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ persist-credentials: false
+
+ - name: Install verified actionlint
+ shell: bash
+ env:
+ ACTIONLINT_VERSION: "1.7.12"
+ ACTIONLINT_LINUX_AMD64_SHA256: "8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8"
+ run: |
+ set -euo pipefail
+ archive="${RUNNER_TEMP}/actionlint.tar.gz"
+ binary="${RUNNER_TEMP}/actionlint"
+ url="https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz"
+ curl --fail --location --retry 3 --retry-all-errors \
+ --output "${archive}" "${url}"
+ printf '%s %s\n' "${ACTIONLINT_LINUX_AMD64_SHA256}" "${archive}" |
+ sha256sum --check -
+ tar -xzf "${archive}" -C "${RUNNER_TEMP}" actionlint
+ "${binary}" -version
+ "${binary}" -color
+
+ release-contracts:
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ persist-credentials: false
+
+ - uses: actions/setup-node@v7
+ with:
+ node-version: 22
+
+ - name: Validate reusable workflow boundaries
+ shell: bash
+ run: node --test .github/scripts/resolve-auto-release.test.mjs .github/scripts/validate-github-release-inventory.test.mjs .github/scripts/validate-release-confirmation.test.mjs .github/scripts/validate-release-source-version.test.mjs .github/scripts/wait-for-npm-release.test.mjs
diff --git a/.gitignore b/.gitignore
index 0aa2d3677..9c65f2ab9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,7 @@ node_modules
.env
.env.*
.memos_arms_uid
+telemetry.credentials.json
# NPM
.npmrc
diff --git a/HOOK.md b/HOOK.md
deleted file mode 100644
index 842385824..000000000
--- a/HOOK.md
+++ /dev/null
@@ -1,22 +0,0 @@
----
-name: memos-cloud-openclaw-plugin
-description: "OpenClaw lifecycle plugin for MemOS Cloud (add + recall memory)"
-homepage: https://github.com/MemTensor/MemOS-Cloud-OpenClaw-Plugin
-metadata: {
- "openclaw": {
- "emoji": "🧠",
- "events": ["before_agent_start", "agent_end", "command:new"],
- "requires": {
- "bins": ["node"]
- }
- }
-}
----
-
-# MemOS Cloud OpenClaw Plugin Hooks
-
-This plugin registers the following OpenClaw lifecycle hooks to interact with MemOS Cloud:
-
-- `before_agent_start`: Intercepts the agent startup sequence to recall relevant memories from MemOS Cloud and injects them into the agent's context.
-- `agent_end`: Intercepts the agent termination sequence to capture the completed conversation turn and saves it to MemOS Cloud.
-- `command:new`: Increments a numeric conversation suffix when the `/new` command is issued to keep MemOS contexts distinct.
diff --git a/README.md b/README.md
index 90c45a095..4bdde16b2 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@ Official plugin maintained by MemTensor.
A minimal OpenClaw lifecycle plugin that **recalls** memories from MemOS Cloud before each run and **adds** new messages to MemOS Cloud after each run.
## Features
-- **Recall**: `before_agent_start` → `/search/memory`
+- **Recall**: `before_prompt_build` (`before_agent_start` on older OpenClaw hosts) → `/search/memory`
- **Add**: `agent_end` → `/add/message`
- **Config UI**: starting the gateway also starts a local plugin config page for editing `plugins.entries.memos-cloud-openclaw-plugin.config`
- Uses **Token** auth (`Authorization: Token `)
@@ -164,7 +164,7 @@ In `plugins.entries.memos-cloud-openclaw-plugin.config`:
```
## How it Works
-- **Recall** (`before_agent_start`)
+- **Recall** (`before_prompt_build`; falls back to `before_agent_start` on older OpenClaw hosts)
- Builds a `/search/memory` request using `user_id`, `query` (= prompt + optional prefix), and optional filters.
- Default **global recall**: when `recallGlobal=true`, it does **not** pass `conversation_id`.
- Optional second-pass filtering: if `recallFilterEnabled=true`, candidates are sent to your configured model and only returned `keep` items are injected.
diff --git a/README_ZH.md b/README_ZH.md
index d923831ea..08e6ad134 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -7,7 +7,7 @@
- **添加记忆**:在每轮对话结束后把消息写回 MemOS Cloud
## 功能
-- **Recall**:`before_agent_start` → `/search/memory`
+- **Recall**:`before_prompt_build`(旧版 OpenClaw 回退到 `before_agent_start`)→ `/search/memory`
- **Add**:`agent_end` → `/add/message`
- **Config UI**:启动 gateway 时同时启动本地插件配置页面,用来编辑 `plugins.entries.memos-cloud-openclaw-plugin.config`
- 使用 **Token** 认证(`Authorization: Token `)
@@ -164,7 +164,7 @@ MEMOS_API_KEY=YOUR_TOKEN
```
## 工作原理
-### 1) 召回(before_agent_start)
+### 1) 召回(新版 OpenClaw 使用 `before_prompt_build`;旧版回退到 `before_agent_start`)
- 组装 `/search/memory` 请求
- `user_id`、`query`(= prompt + 可选前缀)
- 默认**全局召回**:`recallGlobal=true` 时不传 `conversation_id`
diff --git a/clawdbot.plugin.json b/clawdbot.plugin.json
index ffe06718d..2633a84fa 100644
--- a/clawdbot.plugin.json
+++ b/clawdbot.plugin.json
@@ -2,9 +2,14 @@
"id": "memos-cloud-openclaw-plugin",
"name": "MemOS Cloud OpenClaw Plugin",
"description": "MemOS Cloud recall + add memory via lifecycle hooks",
- "version": "0.1.12",
+ "version": "0.1.20",
"kind": "lifecycle",
"main": "./index.js",
+ "activation": {
+ "onCapabilities": [
+ "hook"
+ ]
+ },
"configSchema": {
"type": "object",
"properties": {
diff --git a/docs/release-owner-runbook.md b/docs/release-owner-runbook.md
new file mode 100644
index 000000000..5f3d681cd
--- /dev/null
+++ b/docs/release-owner-runbook.md
@@ -0,0 +1,130 @@
+# OpenClaw 云插件自动 Draft Release 发布说明
+
+## 一句话结论
+
+发布人员不需要新建固定名称的 `release/*` 分支,也不需要手工填写 npm tag 或 40 位 commit。
+将四个版本文件在同一个受审 PR 中一致升级并合入 `main` 后,系统会自动判断是 Beta 还是稳定版,
+发布并验证 npm,随后创建 GitHub Draft Release;发布负责人检查 Draft 后再点击 **Publish**。
+
+这套流程不会让 GitHub Actions 新建或批准 PR,因此仓库不需要开启
+**Allow GitHub Actions to create and approve pull requests**。版本修改仍由开发人员通过普通 PR 提交,Actions
+只负责消费已经合入 `main` 的代码、发布 npm、创建 tag 和 Draft Release。
+
+## 发布负责人怎么操作
+
+以稳定版 `0.1.21` 为例:
+
+1. 使用团队现有分支,例如 `test` 或普通版本准备分支,不要求特定名称。
+2. 将下列四个文件的 `version` 全部从当前版本改成 `0.1.21`:
+ - `package.json`
+ - `openclaw.plugin.json`
+ - `moltbot.plugin.json`
+ - `clawdbot.plugin.json`
+3. 可选:添加 `.github/release-notes/v0.1.21.md`。不添加时由 106 根据 Git 证据自动生成。
+4. 提交目标为 `main` 的 PR,确认测试和版本检查通过后由有权限人员合并。
+5. 合并后打开 Actions 中的 **OpenClaw Cloud Plugin — Publish & Release**,确认自动 run 为绿色。
+6. 打开仓库 Releases,检查系统创建的 `v0.1.21` Draft:
+ - 版本和目标 commit 正确;
+ - Release Notes 准确;
+ - 中英文官网预览准确;
+ - npm `0.1.21` 已经通过 `latest` 可见。
+7. 确认无误后点击 **Publish release**。只有这一步会产生稳定版 `release.published` webhook,并让 106 创建 MemOS-Docs PR。
+
+合并前会有一条只读的版本门禁,只比较 PR 合并预览与当前 `main` 的四个版本值,不读取发布 Secrets,
+也不会发布 npm、创建 tag 或 Release。真正副作用只发生在合并后的自动 Workflow。
+
+Beta 示例:将四个文件从旧版本一致升级为 `0.1.21-beta.0`。系统自动选择 npm `beta`,创建
+GitHub Prerelease Draft;Publish 后 106 必须成功跳过正式官网同步。
+
+## 系统怎样判断这是一次发版
+
+系统比较 PR 合入前的 `main` 与合入后的精确 merge commit。只有同时满足以下条件才自动发版:
+
+1. PR 已合入 `main`,并且来自当前仓库而不是 Fork;
+2. 四个版本文件在合入前版本一致;
+3. 四个版本文件在合入后版本一致;
+4. 四个版本值都在本次 PR 中发生升级;
+5. 新版本是严格 SemVer,并且优先级高于旧版本;
+6. npm、GitHub tag 和 Release 状态没有冲突。
+
+如果四个版本值完全没变,这是普通代码合并,自动跳过,不会发布。只改一部分版本文件、四个版本不一致、
+版本倒退或使用 build metadata 时会失败停止,避免产生半正确的包。
+
+允许的升级示例:
+
+```text
+0.1.20 -> 0.1.21-beta.0
+0.1.21-beta.0 -> 0.1.21-beta.1
+0.1.21-beta.1 -> 0.1.21
+```
+
+## Beta 与稳定版的区别
+
+| 合入后的版本 | npm dist-tag | GitHub Draft | Publish 后的 Docs 行为 |
+|---|---|---|---|
+| `0.1.21-beta.0` | `beta` | Prerelease Draft | 106 成功跳过,不创建正式 Docs PR |
+| `0.1.21-alpha.1` | `alpha` | Prerelease Draft | 106 成功跳过,不创建正式 Docs PR |
+| `0.1.21-rc.1` | `next` | Prerelease Draft | 106 成功跳过,不创建正式 Docs PR |
+| `0.1.21` | `latest` | 正常 Draft | 人工 Publish 后由 106 创建 Docs PR |
+
+## 为什么 npm 在 Draft 之前发布
+
+GitHub Draft 一旦被人工 Publish,`release.published` webhook 会立即到达 106。如果这时才异步发布 npm,
+就可能出现官网同步已经开始、npm 却失败或暂时不可见的半发布状态。
+
+因此本仓库选择:
+
+```text
+版本 PR 合入 main
+-> 校验四文件版本与 Release Notes
+-> npm publish + 校验 version/gitHead/dist-tag
+-> 创建不可变 tag 和 Draft Release
+-> 人工 Publish
+-> 稳定版进入 106 Docs PR,预发布版成功跳过
+```
+
+合并版本 PR 表示已经批准代码和 npm 发布;Draft 的人工边界用于最后确认 GitHub Release 和官网文案。
+如果团队要求“人工审批前 npm 也不能发布”,需要改用受保护 GitHub Environment 的审批按钮,不能只依赖原生 Draft。
+
+## Release Notes 规则
+
+### 默认方式:106 自动生成
+
+不创建 `.github/release-notes/v<版本>.md`。Workflow 会基于真实 tag range 和本次 merge commit 调用 106,
+生成中英文内容、真实 `source_refs`、质量报告和 Docs Preview。
+
+稳定版会跳过中间 prerelease tag,以上一个稳定 tag 为 evidence 基线,避免 Beta 已经承载的真实功能在
+`beta -> stable` 时被漏掉。
+
+### 人工方式:随版本 PR 提交
+
+创建 `.github/release-notes/v<版本>.md`。文件必须包含:
+
+- `## Changelog` 公开 Markdown;
+- 隐藏的 `doc-agent-release-notes-json` 双语证据块;
+- 唯一的 ``。
+
+人工文件也必须通过 source ref、覆盖率、双语和长度检查,不能绕过质量门禁。
+
+## 哪些合并不会发布
+
+分支名不决定是否发版。`test`、`feature/*`、`fix/*`、`docs-sync/*` 都可以合入 `main`:
+
+- 四个版本值没有变化:正常跳过发布;
+- 四个版本值全部一致升级:进入自动发布;
+- 只有部分版本变化或版本不一致:检查失败,要求修正。
+
+## 失败怎么处理
+
+- 合并前版本检查失败:继续修改原 PR,四个版本一致且确实升级后再合并。
+- 106 文案生成失败:不会发布 npm、tag 或 Draft;修复 endpoint、证据或人工 notes 后再处理。
+- npm 发布失败且 registry 没有正确版本:不会创建 tag/Draft;根据 Action 错误处理,禁止猜测成功。
+- npm 已成功但同一次自动任务尚未创建 tag/Draft:可先点击 Re-run;系统确认 npm `gitHead` 与原合并 commit 完全相同后,只补缺失元数据,不会重复发布 npm。
+- npm 已成功,但 tag/Draft 未创建:使用现有 Workflow 的显式 Recovery;它从 npm `gitHead` 补齐元数据,不会重复发布 npm,并且仍然只创建 Draft 等待人工 Publish。
+- Draft 文案不通过:不要点 Publish。修订 Draft 时不得删除或损坏隐藏的双语 evidence payload 和 `source-id`。
+- tag 指向、npm `gitHead`、四文件版本任一冲突:必须人工排查,Workflow 不会移动已有 tag。
+
+## 旧的手动入口
+
+**OpenClaw Cloud Plugin — Publish & Release** 的 `Run workflow` 仍保留给历史 Dry-run、故障注入和部分失败 Recovery。
+正常新版本发布直接走“四个版本文件一致升级并合入 `main`”,不再要求发布人员填写旧表单。
diff --git a/index.js b/index.js
index 65be37bee..72f7edb53 100644
--- a/index.js
+++ b/index.js
@@ -1,4 +1,5 @@
#!/usr/bin/env node
+import { createHash } from "node:crypto";
import {
addMessage,
buildConfig,
@@ -6,18 +7,57 @@ import {
extractText,
formatRecallHookResult,
isAgentAllowed,
+ isOpenClawSystemPrompt,
resolveAgentConfig,
searchMemory,
stripOpenClawInjectedPrefix,
} from "./lib/memos-cloud-api.js";
import { reportRumEvent } from "./lib/arms-reporter.js";
import { startUpdateChecker } from "./lib/check-update.js";
-import { closeConfigUiService, ensureConfigUiService, waitForGatewayReady } from "./lib/config-ui-server.js";
+import {
+ closeConfigUiService,
+ compareVersionStrings,
+ detectHostVersion,
+ ensureConfigUiService,
+ ensurePluginHookPolicy,
+ isGatewayRuntimeStartup,
+ waitForGatewayReady,
+} from "./lib/config-ui-server.js";
let lastCaptureTime = 0;
+// ponytail: in-process cache; replace with server idempotency for cross-restart or multi-instance guarantees.
+const recentCaptureKeys = new Set();
+const MAX_CAPTURE_KEYS = 1000;
const conversationCounters = new Map();
const API_KEY_HELP_URL = "https://memos-dashboard.openmem.net/cn/apikeys/";
const ENV_FILE_SEARCH_HINTS = ["~/.openclaw/.env", "~/.moltbot/.env", "~/.clawdbot/.env"];
-const MEMOS_SOURCE = "openclaw";
+const MEMOS_SOURCE = (() => {
+ const platform = process.platform;
+ if (platform === "win32") return "openclaw_win";
+ if (platform === "darwin") return "openclaw_mac";
+ if (platform === "linux") return "openclaw_linux";
+ return "openclaw";
+})();
+
+// Heartbeat prompts are always injected at the very beginning of the user
+// content by the host (OpenClaw). Anchoring at start prevents false positives
+// when a legitimate user message happens to mention these phrases.
+const HEARTBEAT_PROMPT_PATTERN =
+ /^\s*(?:Read HEARTBEAT\.md if it exists\b|\[OpenClaw heartbeat poll\])/i;
+const SYSTEM_COMMAND_PATTERN = /^\/(?:new|reset|clear|stop|status|help|dock_|undock)\b/i;
+const INTERNAL_SYSTEM_PROMPT_PATTERNS = [
+ /^A new session was started via \/new or \/reset\./i,
+ /^Based on this conversation, generate a short 1-2 word filename slug\b[\s\S]*\bReply with ONLY the slug\b/i,
+];
+
+function isHeartbeatPrompt(text) {
+ return typeof text === "string" && HEARTBEAT_PROMPT_PATTERN.test(text);
+}
+
+export function isSystemCommandPrompt(text) {
+ if (typeof text !== "string") return false;
+ const prompt = text.trimStart();
+ return SYSTEM_COMMAND_PATTERN.test(prompt) || INTERNAL_SYSTEM_PROMPT_PATTERNS.some((pattern) => pattern.test(prompt));
+}
function warnMissingApiKey(log, context) {
const heading = "[memos-cloud] Missing MEMOS_API_KEY (Token auth)";
@@ -106,19 +146,29 @@ export function buildSearchPayload(cfg, prompt, ctx) {
let filterObj = cfg.filter ? JSON.parse(JSON.stringify(cfg.filter)) : null;
const agentId = getEffectiveAgentId(cfg, ctx);
+ // Check if the filter is already in the categorized format (filter1)
+ const isCategorized = filterObj && (filterObj.user !== undefined || filterObj.knowledgebase !== undefined || filterObj.public !== undefined);
+ let userFilter = isCategorized ? (filterObj.user || null) : filterObj;
+
if (agentId) {
- if (filterObj) {
- if (Array.isArray(filterObj.and)) {
- filterObj.and.push({ agent_id: agentId });
+ if (userFilter && Object.keys(userFilter).length > 0) {
+ if (Array.isArray(userFilter.and)) {
+ userFilter.and.push({ agent_id: agentId });
} else {
- filterObj = { and: [filterObj, { agent_id: agentId }] };
+ userFilter = { and: [userFilter, { agent_id: agentId }] };
}
} else {
- filterObj = { agent_id: agentId };
+ userFilter = { and: [{ agent_id: agentId }] };
}
}
- if (filterObj) payload.filter = filterObj;
+ if (isCategorized) {
+ if (userFilter && Object.keys(userFilter).length > 0) filterObj.user = userFilter;
+ if (Object.keys(filterObj).length > 0) payload.filter = filterObj;
+ } else if (userFilter && Object.keys(userFilter).length > 0) {
+ // If not categorized, wrap it in 'user' so knowledgebase is not filtered
+ payload.filter = { user: userFilter };
+ }
if (cfg.knowledgebaseIds?.length) payload.knowledgebase_ids = cfg.knowledgebaseIds;
@@ -146,7 +196,7 @@ export function buildAddMessagePayload(cfg, messages, ctx) {
if (cfg.tags?.length) payload.tags = cfg.tags;
const info = {
- source: "openclaw",
+ source: MEMOS_SOURCE,
sessionKey: ctx?.sessionKey,
agentId: ctx?.agentId,
...(cfg.info || {}),
@@ -160,48 +210,285 @@ export function buildAddMessagePayload(cfg, messages, ctx) {
return payload;
}
-function pickLastTurnMessages(messages, cfg) {
- const lastUserIndex = messages
- .map((m, idx) => ({ m, idx }))
- .filter(({ m }) => m?.role === "user")
- .map(({ idx }) => idx)
- .pop();
-
- if (lastUserIndex === undefined) return [];
-
- const slice = messages.slice(lastUserIndex);
- const results = [];
-
- for (const msg of slice) {
- if (!msg || !msg.role) continue;
- if (msg.role === "user") {
- const content = stripOpenClawInjectedPrefix(extractText(msg.content));
- if (content) results.push({ role: "user", content: truncate(content, cfg.maxMessageChars) });
- continue;
+function convertAssistantMessage(msg, cfg) {
+ const contentArr = Array.isArray(msg.content)
+ ? msg.content
+ : msg.content
+ ? [{ type: "text", text: String(msg.content) }]
+ : [];
+
+ const textContent = contentArr
+ .filter((c) => c?.type === "text")
+ .map((c) => c.text || "")
+ .filter(Boolean)
+ .join("\n");
+
+ const toolCallItems = contentArr.filter((c) => c?.type === "toolCall");
+
+ const result = { role: "assistant" };
+
+ if (textContent) {
+ result.content = truncate(textContent, cfg.maxMessageChars);
+ }
+
+ if (cfg.includeToolMemory && toolCallItems.length > 0) {
+ result.tool_calls = toolCallItems.map((tc) => ({
+ id: tc.id,
+ type: "function",
+ function: {
+ name: tc.name,
+ arguments: typeof tc.arguments === "string" ? tc.arguments : JSON.stringify(tc.arguments ?? {}),
+ },
+ }));
+ }
+
+ if (!result.content && !result.tool_calls) return null;
+ return result;
+}
+
+function safeStringify(value) {
+ try {
+ return JSON.stringify(value);
+ } catch {
+ return "";
+ }
+}
+
+// 把单个附件值(URL / data URI / 裸 base64)统一描述成可读 text:
+// - http(s):// / 其它协议 URL:[: ]
+// - data:;base64,...:[ ( base64, ~ chars)]
+// - 其它(视为裸 base64):[ (base64, ~ chars)]
+function describeAttachment(kind, value) {
+ const dataMatch = /^data:([^;,]+)/i.exec(value);
+ if (dataMatch) {
+ return `[${kind} (${dataMatch[1] || kind} base64, ~${value.length} chars)]`;
+ }
+ if (/^[a-z][a-z0-9+.-]*:\/\//i.test(value)) {
+ return `[${kind}: ${value}]`;
+ }
+ return `[${kind} (base64, ~${value.length} chars)]`;
+}
+
+// MemOS 是文本记忆服务,召回路径上图片/文件 block 几乎只有文本价值。
+// 这里把所有 block 一律归一成 [{type:"text", text}],但**保留 URL 文字本身**:
+// - text block:透传文本(按 cfg.maxMessageChars 截头)
+// - URL 形态:输出 "[image: ]" / "[file: ]",URL 作为可检索文字保留
+// - data URI / base64 形态:输出 "[image ( base64, ~ chars)]" 元数据描述,永不 inline base64
+// - 未识别 type:含 url 字段则 "[: ]",否则 JSON.stringify 兜底
+function normalizeToolResultContent(content, cfg) {
+ const blocks = [];
+
+ const pushText = (raw) => {
+ const text = truncate(String(raw ?? ""), cfg.maxMessageChars);
+ if (text) blocks.push({ type: "text", text });
+ };
+
+ // 解析所有协议下的 image 类 block,提取出统一的"附件值"再交给 describeAttachment 描述。
+ // 覆盖:
+ // {type:"image_url", image_url:{url}} / {image_url:""} / 顶层 url (OpenAI 风格)
+ // {type:"image", data, media_type} / {type:"image", source:{data, media_type}} (Claude 风格)
+ // {type:"image", url} (少见)
+ const tryPushImageBlock = (block) => {
+ const claudeData =
+ (block.source && typeof block.source === "object" && block.source.data) || block.data || "";
+ if (claudeData) {
+ const mediaType =
+ (block.source && typeof block.source === "object" && block.source.media_type) ||
+ block.media_type ||
+ block.mimeType ||
+ "image";
+ pushText(describeAttachment("image", `data:${mediaType};base64,${String(claudeData)}`));
+ return true;
+ }
+ const url =
+ (block.image_url && typeof block.image_url === "object" && block.image_url.url) ||
+ (typeof block.image_url === "string" ? block.image_url : "") ||
+ block.url ||
+ "";
+ if (!url) return false;
+ pushText(describeAttachment("image", String(url)));
+ return true;
+ };
+
+ // MemOS schema 标准 file block:{type:"file", file:{file_data}},兼容顶层 file_data。
+ const tryPushFileBlock = (block) => {
+ const fileData =
+ (block.file && typeof block.file === "object" && block.file.file_data) ||
+ block.file_data ||
+ "";
+ if (!fileData) return false;
+ pushText(describeAttachment("file", String(fileData)));
+ return true;
+ };
+
+ const tryPushTypedBlock = (block) => {
+ if (!block || typeof block !== "object") return false;
+ if (block.type === "text") {
+ pushText(block.text);
+ return true;
+ }
+ if (block.type === "image_url" || block.type === "image") return tryPushImageBlock(block);
+ if (block.type === "file") return tryPushFileBlock(block);
+ return false;
+ };
+
+ // 未识别 type:有 url 字段则给可读占位,否则整体 stringify。
+ const fallbackSerialize = (block) => {
+ if (
+ block &&
+ typeof block === "object" &&
+ typeof block.type === "string" &&
+ typeof block.url === "string" &&
+ block.url
+ ) {
+ pushText(`[${block.type}: ${block.url}]`);
+ return;
+ }
+ const serialized = safeStringify(block);
+ if (serialized) pushText(serialized);
+ };
+
+ if (content == null || content === "") return blocks;
+
+ if (typeof content === "string") {
+ pushText(content);
+ return blocks;
+ }
+
+ if (Array.isArray(content)) {
+ for (const block of content) {
+ if (block == null) continue;
+ if (typeof block === "string") {
+ pushText(block);
+ continue;
+ }
+ if (typeof block !== "object") continue;
+ if (tryPushTypedBlock(block)) continue;
+ fallbackSerialize(block);
}
- if (msg.role === "assistant" && cfg.includeAssistant) {
- const content = extractText(msg.content);
- if (content) results.push({ role: "assistant", content: truncate(content, cfg.maxMessageChars) });
+ return blocks;
+ }
+
+ if (typeof content === "object") {
+ if (!tryPushTypedBlock(content)) {
+ fallbackSerialize(content);
}
+ return blocks;
}
- return results;
+ return blocks;
}
-function pickFullSessionMessages(messages, cfg) {
- const results = [];
- for (const msg of messages) {
- if (!msg || !msg.role) continue;
- if (msg.role === "user") {
- const content = stripOpenClawInjectedPrefix(extractText(msg.content));
- if (content) results.push({ role: "user", content: truncate(content, cfg.maxMessageChars) });
+function convertToolResultMessage(msg, cfg) {
+ const toolCallId = msg.toolCallId || msg.tool_call_id;
+ if (!toolCallId) return null;
+ const blocks = normalizeToolResultContent(msg.content, cfg);
+ if (blocks.length === 0) return null;
+ return {
+ role: "tool",
+ tool_call_id: toolCallId,
+ content: blocks,
+ };
+}
+
+// 把 OpenClaw 的单条原始消息转成 MemOS /add/message 接受的形态。
+// 三类 role 分发:user / assistant / toolResult,其它 role(system/...)直接丢弃返 null。
+function convertSessionMessage(msg, cfg) {
+ if (!msg || !msg.role) return null;
+ if (msg.role === "user") {
+ const content = stripOpenClawInjectedPrefix(extractText(msg.content));
+ if (!content) return null;
+ return { role: "user", content: truncate(content, cfg.maxMessageChars) };
+ }
+ if (msg.role === "assistant" && cfg.includeAssistant) {
+ return convertAssistantMessage(msg, cfg);
+ }
+ if (msg.role === "toolResult" && cfg.includeToolMemory) {
+ return convertToolResultMessage(msg, cfg);
+ }
+ return null;
+}
+
+function pickLastTurnMessages(messages, cfg) {
+ let lastUserIndex = -1;
+ for (let i = messages.length - 1; i >= 0; i--) {
+ if (messages[i]?.role === "user") {
+ lastUserIndex = i;
+ break;
}
- if (msg.role === "assistant" && cfg.includeAssistant) {
- const content = extractText(msg.content);
- if (content) results.push({ role: "assistant", content: truncate(content, cfg.maxMessageChars) });
+ }
+ if (lastUserIndex < 0) return [];
+ if (isOpenClawSystemPrompt(extractText(messages[lastUserIndex]?.content || ""))) return [];
+ return messages
+ .slice(lastUserIndex)
+ .map((m) => convertSessionMessage(m, cfg))
+ .filter(Boolean);
+}
+
+function pickFullSessionMessages(messages, cfg) {
+ const out = [];
+ let skipSystemTurn = false;
+ for (const message of messages) {
+ if (message?.role === "user") {
+ skipSystemTurn = isOpenClawSystemPrompt(extractText(message.content || ""));
+ } else if (skipSystemTurn) {
+ continue;
}
+ const converted = convertSessionMessage(message, cfg);
+ if (converted) out.push(converted);
+ }
+ return out;
+}
+
+function reserveCapture(payload, rawMessages, ctx, runId) {
+ const sessionIdentity = ctx?.sessionId || ctx?.sessionKey;
+ const stableMessageIdentities = rawMessages
+ .map(
+ (message) =>
+ message?.idempotencyKey ??
+ message?.id ??
+ message?.messageId ??
+ message?.timestamp,
+ )
+ .filter((identity) => identity !== undefined && identity !== null && identity !== "");
+ const eventIdentity = stableMessageIdentities.length
+ ? ["messages", stableMessageIdentities]
+ : runId;
+ if (!sessionIdentity || eventIdentity === undefined || eventIdentity === null || eventIdentity === "") {
+ return null;
+ }
+
+ let captureSnapshot;
+ try {
+ captureSnapshot = JSON.stringify(payload.messages);
+ } catch {
+ return null;
+ }
+ if (!captureSnapshot) return null;
+
+ const key = createHash("sha256")
+ .update(
+ JSON.stringify([
+ payload.user_id,
+ payload.conversation_id,
+ payload.agent_id,
+ payload.app_id,
+ sessionIdentity,
+ eventIdentity,
+ captureSnapshot,
+ ]),
+ )
+ .digest("hex");
+ if (recentCaptureKeys.delete(key)) {
+ recentCaptureKeys.add(key);
+ return { duplicate: true };
+ }
+
+ recentCaptureKeys.add(key);
+ if (recentCaptureKeys.size > MAX_CAPTURE_KEYS) {
+ recentCaptureKeys.delete(recentCaptureKeys.keys().next().value);
}
- return results;
+ return { duplicate: false, key };
}
function truncate(text, maxLen) {
@@ -428,13 +715,56 @@ export default {
// Start 12-hour background update interval
startUpdateChecker(log);
- void (async () => {
- const ready = await waitForGatewayReady(api.config, log);
- if (!ready || configUiStartupCancelled) return;
- await ensureConfigUiService(log);
- })().catch((error) => {
- log.warn?.(`[memos-cloud] config UI failed to start: ${String(error)}`);
- });
+
+ // Detect the host CLI version once so every hook registration branch can reference it.
+ const hostVersion = detectHostVersion();
+
+ // Side effects below are only meaningful when the host CLI was actually
+ // launched to run the gateway (`openclaw gateway run|start|restart`).
+ // Other entry points (e.g. `plugins install`, `security audit`) also
+ // load this plugin to inspect/register it, but:
+ // - `ensurePluginHookPolicy` writes to `openclaw.json` and would race
+ // against the install command's own commit (ConfigMutationConflictError).
+ // - `waitForGatewayReady` would keep the short-lived event loop alive
+ // for 45s probing a gateway that will never come up, then emit a
+ // misleading "probe timed out" warning before the process exits.
+ // Gate them all in one place so the policy is explicit and discoverable.
+ if (isGatewayRuntimeStartup()) {
+ // `allowConversationAccess` hook policy was introduced in 2026.4.23;
+ // older hosts do not understand the field and don't need it patched in.
+ const HOOK_POLICY_MIN_VERSION = "2026.4.23";
+ const needsHookPolicy =
+ hostVersion === null ||
+ compareVersionStrings(hostVersion, HOOK_POLICY_MIN_VERSION) >= 0;
+
+ void (async () => {
+ const ready = await waitForGatewayReady(api.config, log);
+ if (!ready || configUiStartupCancelled) return;
+
+ // Patch hook policy AFTER gateway is fully ready. Writing the config
+ // file at this point triggers the gateway's built-in config-change
+ // watcher which will auto-restart, making agent_end effective without
+ // requiring the user to manually restart.
+ if (needsHookPolicy) {
+ try {
+ const policyResult = ensurePluginHookPolicy(api.config, log);
+ if (policyResult?.error) {
+ log.warn?.(
+ `[memos-cloud] hook policy check skipped due to error: ${String(policyResult.error?.message ?? policyResult.error)}`,
+ );
+ }
+ } catch (error) {
+ log.warn?.(
+ `[memos-cloud] failed to ensure plugin hook policy: ${String(error?.message ?? error)}`,
+ );
+ }
+ }
+
+ await ensureConfigUiService(log);
+ })().catch((error) => {
+ log.warn?.(`[memos-cloud] config UI failed to start: ${String(error)}`);
+ });
+ }
if (!cfg.envFileStatus?.found) {
const searchPaths = cfg.envFileStatus?.searchPaths?.join(", ") ?? ENV_FILE_SEARCH_HINTS.join(", ");
@@ -468,7 +798,18 @@ export default {
);
}
- api.on("before_agent_start", async (event, ctx) => {
+ const runRecall = async (event, ctx) => {
+ // Skip system events: heartbeat, /new, /reset, and other commands
+ const prompt = event?.prompt || "";
+ const isHeartbeat = isHeartbeatPrompt(prompt);
+ const isSystemCommand = isSystemCommandPrompt(prompt);
+ const isSystemPrompt = isOpenClawSystemPrompt(prompt);
+
+ if (isHeartbeat || isSystemCommand || isSystemPrompt) {
+ log.info?.(`[memos-cloud] recall skipped: system event detected (heartbeat=${isHeartbeat}, command=${isSystemCommand}, systemPrompt=${isSystemPrompt}, prompt="${prompt.substring(0, 50)}...")`);
+ return;
+ }
+
if (!isAgentAllowed(cfg, ctx)) {
log.info?.(`[memos-cloud] recall skipped: agent "${ctx?.agentId}" not in allowedAgents [${cfg.allowedAgents?.join(", ")}]`);
return;
@@ -500,9 +841,39 @@ export default {
} catch (err) {
log.warn?.(`[memos-cloud] recall failed: ${String(err)}`);
}
- });
+ };
+
+ // Recall mutates prompt context only, so the phase-specific replacement for
+ // legacy before_agent_start is before_prompt_build. Do not register both on
+ // new hosts, otherwise the same memory block can be injected twice.
+ const PROMPT_BUILD_HOOK_MIN_VERSION = "2026.5.7";
+ const usesBeforePromptBuild =
+ hostVersion !== null &&
+ compareVersionStrings(hostVersion, PROMPT_BUILD_HOOK_MIN_VERSION) >= 0;
+
+ if (usesBeforePromptBuild) {
+ api.on("before_prompt_build", runRecall);
+ } else {
+ api.on("before_agent_start", runRecall);
+ }
api.on("agent_end", async (event, ctx) => {
+ // Skip system events: heartbeat and commands
+ // Check the last user message to determine if this was a system event
+ const messages = event?.messages || [];
+ const lastUserIndex = messages.findLastIndex((message) => message?.role === "user");
+ const lastUserMsg = messages[lastUserIndex];
+ const lastUserContent = extractText(lastUserMsg?.content || "");
+
+ const isHeartbeat = isHeartbeatPrompt(lastUserContent);
+ const isSystemCommand = isSystemCommandPrompt(lastUserContent);
+ const isSystemPrompt = isOpenClawSystemPrompt(lastUserContent);
+
+ if (isHeartbeat || isSystemCommand || isSystemPrompt) {
+ log.info?.(`[memos-cloud] add skipped: system event detected (heartbeat=${isHeartbeat}, command=${isSystemCommand}, systemPrompt=${isSystemPrompt}, content="${lastUserContent.substring(0, 50)}...")`);
+ return;
+ }
+
if (!isAgentAllowed(cfg, ctx)) {
log.info?.(`[memos-cloud] add skipped: agent "${ctx?.agentId}" not in allowedAgents [${cfg.allowedAgents?.join(", ")}]`);
return;
@@ -519,9 +890,12 @@ export default {
if (agentCfg.throttleMs && now - lastCaptureTime < agentCfg.throttleMs) {
return;
}
- lastCaptureTime = now;
try {
+ const rawCaptureMessages =
+ agentCfg.captureStrategy === "full_session"
+ ? event.messages
+ : event.messages.slice(lastUserIndex);
const messages =
agentCfg.captureStrategy === "full_session"
? pickFullSessionMessages(event.messages, agentCfg)
@@ -530,6 +904,17 @@ export default {
if (!messages.length) return;
const payload = buildAddMessagePayload(agentCfg, messages, ctx);
+ const captureReservation = reserveCapture(
+ payload,
+ rawCaptureMessages,
+ ctx,
+ event.runId ?? ctx?.runId,
+ );
+ if (captureReservation?.duplicate) {
+ log.info?.("[memos-cloud] add skipped: duplicate agent_end snapshot");
+ return;
+ }
+ lastCaptureTime = now;
await addMessage(agentCfg, payload);
} catch (err) {
log.warn?.(`[memos-cloud] add failed: ${String(err)}`);
diff --git a/lib/arms-reporter.js b/lib/arms-reporter.js
index d5421b147..260de9629 100644
--- a/lib/arms-reporter.js
+++ b/lib/arms-reporter.js
@@ -3,12 +3,37 @@ import { readFileSync, writeFileSync } from "node:fs";
import { homedir } from "node:os";
import { join } from "node:path";
-const ARMS_ENDPOINT = "https://proj-xtrace-e218d9316b328f196a3c640cc7ca84-cn-hangzhou.cn-hangzhou.log.aliyuncs.com/rum/web/v2?workspace=default-cms-1026429231103299-cn-hangzhou&service_id=a3u72ukxmr@bed68dd882dd823439015"
-const ARMS_PID = "a3u72ukxmr@c42a249fb14f4d9";
-const ARMS_ENV = "prod";
const ARMS_UID_FILE = new URL("../.memos_arms_uid", import.meta.url);
+const TELEMETRY_CREDENTIALS_FILE = new URL("../telemetry.credentials.json", import.meta.url);
let armsUidCache = "";
+let telemetryCredentialsCache;
+
+function loadTelemetryCredentials(log) {
+ if (telemetryCredentialsCache) return telemetryCredentialsCache;
+ if (process.env.MEMOS_ARMS_ENDPOINT) {
+ telemetryCredentialsCache = {
+ endpoint: String(process.env.MEMOS_ARMS_ENDPOINT || "").trim(),
+ pid: String(process.env.MEMOS_ARMS_PID || "").trim(),
+ env: String(process.env.MEMOS_ARMS_ENV || "prod").trim() || "prod",
+ };
+ } else {
+ try {
+ const parsed = JSON.parse(readFileSync(TELEMETRY_CREDENTIALS_FILE, "utf-8"));
+ telemetryCredentialsCache = {
+ endpoint: String(parsed.endpoint || "").trim(),
+ pid: String(parsed.pid || "").trim(),
+ env: String(parsed.env || "prod").trim() || "prod",
+ };
+ } catch {
+ telemetryCredentialsCache = { endpoint: "", pid: "", env: "prod" };
+ }
+ }
+ if (!telemetryCredentialsCache.endpoint || !telemetryCredentialsCache.pid) {
+ log?.debug?.("[memos-cloud] RUM disabled: telemetry credentials are incomplete.");
+ }
+ return telemetryCredentialsCache;
+}
function readUidFromFile() {
try {
@@ -65,11 +90,11 @@ function loadArmsUid(log) {
return armsUidCache;
}
-function buildPayload(ctx, eventName, payload, log) {
+function buildPayload(ctx, eventName, payload, log, credentials) {
return {
app: {
- id: ARMS_PID,
- env: ARMS_ENV,
+ id: credentials.pid,
+ env: credentials.env,
type: "node",
},
user: { id: loadArmsUid(log) },
@@ -92,14 +117,16 @@ function buildPayload(ctx, eventName, payload, log) {
export async function reportRumEvent(eventName, payload, cfg, ctx, log) {
if (!cfg.rumEnabled) return;
+ const credentials = loadTelemetryCredentials(log);
+ if (!credentials.endpoint || !credentials.pid) return;
const controller = new AbortController();
const timeoutId = setTimeout(
() => controller.abort(),
Number.isFinite(cfg.rumTimeoutMs) ? Math.max(1000, cfg.rumTimeoutMs) : 3000,
);
try {
- const body = buildPayload(ctx, eventName, payload, log);
- const res = await fetch(ARMS_ENDPOINT, {
+ const body = buildPayload(ctx, eventName, payload, log, credentials);
+ const res = await fetch(credentials.endpoint, {
method: "POST",
headers: { "Content-Type": "text/plain" },
body: JSON.stringify(body),
diff --git a/lib/check-update.js b/lib/check-update.js
index 906fdf314..b16f008c7 100644
--- a/lib/check-update.js
+++ b/lib/check-update.js
@@ -3,6 +3,7 @@ import fs from "fs";
import path from "path";
import { fileURLToPath } from "url";
import os from "os";
+import { compareSemver } from "./semver.js";
const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -19,7 +20,7 @@ const ANSI = {
};
-function getPackageVersion() {
+export function getPackageVersion() {
try {
const pkgPath = path.join(__dirname, "..", "package.json");
const pkgData = fs.readFileSync(pkgPath, "utf-8");
@@ -30,7 +31,7 @@ function getPackageVersion() {
}
}
-function getLatestVersion(log) {
+export function getLatestVersion() {
return new Promise((resolve, reject) => {
const req = https.get(
`https://registry.npmjs.org/${PLUGIN_NAME}/latest`,
@@ -68,37 +69,39 @@ function getLatestVersion(log) {
});
}
-function compareVersions(v1, v2) {
- // Split pre-release tags (e.g. 0.1.8-beta.1 -> "0.1.8" and "beta.1")
- const split1 = v1.split("-");
- const split2 = v2.split("-");
- const parts1 = split1[0].split(".").map(Number);
- const parts2 = split2[0].split(".").map(Number);
-
- // Compare major.minor.patch
- for (let i = 0; i < Math.max(parts1.length, parts2.length); i++) {
- const p1 = parts1[i] || 0;
- const p2 = parts2[i] || 0;
- if (p1 > p2) return 1;
- if (p1 < p2) return -1;
+export function compareVersions(v1, v2) {
+ return compareSemver(v1, v2);
+}
+
+function detectCliName() {
+ // Check the full path of the entry script (e.g., .../moltbot/bin/index.js) or the executable
+ const scriptPath = process.argv[1] ? process.argv[1].toLowerCase() : "";
+ const execPath = process.execPath ? process.execPath.toLowerCase() : "";
+
+ if (scriptPath.includes("moltbot") || execPath.includes("moltbot")) return "moltbot";
+ if (scriptPath.includes("clawdbot") || execPath.includes("clawdbot")) return "clawdbot";
+ return "openclaw";
+}
+
+export async function checkForPluginUpdate() {
+ const currentVersion = getPackageVersion();
+ if (!currentVersion) {
+ throw new Error("Could not read current version from package.json");
}
-
- // If base versions are equal, compare pre-release tags.
- // A version WITH a pre-release tag is LOWER than a version WITHOUT one.
- // e.g. 0.1.8-beta is less than 0.1.8. 0.1.8 is the final release.
- const hasPre1 = split1.length > 1;
- const hasPre2 = split2.length > 1;
-
- if (hasPre1 && !hasPre2) return -1; // v1 is a beta, v2 is a full release
- if (!hasPre1 && hasPre2) return 1; // v1 is a full release, v2 is a beta
- if (!hasPre1 && !hasPre2) return 0; // both are full releases and equal
-
- // If both are pre-releases, do a basic string compare on the tag
- // "alpha" < "beta" < "rc"
- if (split1[1] > split2[1]) return 1;
- if (split1[1] < split2[1]) return -1;
-
- return 0;
+
+ const latestVersion = await getLatestVersion();
+ const updateAvailable = compareVersions(latestVersion, currentVersion) > 0;
+ const cliName = detectCliName();
+
+ return {
+ pluginName: PLUGIN_NAME,
+ currentVersion,
+ latestVersion,
+ updateAvailable,
+ cliName,
+ updateCommand: `${cliName} plugins update memos-cloud-openclaw-plugin`,
+ checkedAt: new Date().toISOString(),
+ };
}
export function startUpdateChecker(log) {
@@ -118,39 +121,23 @@ export function startUpdateChecker(log) {
log.warn?.(`${ANSI.RED}[memos-cloud] Failed to write timestamp file: ${e.message}${ANSI.RESET}`);
}
- const currentVersion = getPackageVersion();
- if (!currentVersion) {
- log.warn?.(`${ANSI.RED}[memos-cloud] Could not read current version from package.json${ANSI.RESET}`);
- return;
- }
-
try {
- const latestVersion = await getLatestVersion(log);
+ const updateStatus = await checkForPluginUpdate();
// Normal version check
- if (compareVersions(latestVersion, currentVersion) <= 0) {
+ if (!updateStatus.updateAvailable) {
return;
}
- const cliName = (() => {
- // Check the full path of the entry script (e.g., .../moltbot/bin/index.js) or the executable
- const scriptPath = process.argv[1] ? process.argv[1].toLowerCase() : "";
- const execPath = process.execPath ? process.execPath.toLowerCase() : "";
-
- if (scriptPath.includes("moltbot") || execPath.includes("moltbot")) return "moltbot";
- if (scriptPath.includes("clawdbot") || execPath.includes("clawdbot")) return "clawdbot";
- return "openclaw";
- })();
-
const border = "=".repeat(64);
log.info?.("");
log.info?.(`${ANSI.GREEN}${border}${ANSI.RESET}`);
log.info?.(`${ANSI.YELLOW}🚀 [memos-cloud] NEW VERSION AVAILABLE!${ANSI.RESET}`);
- log.info?.(`${ANSI.CYAN}📦 Current version : ${currentVersion}${ANSI.RESET}`);
- log.info?.(`${ANSI.GREEN}✨ Latest version : ${latestVersion}${ANSI.RESET}`);
+ log.info?.(`${ANSI.CYAN}📦 Current version : ${updateStatus.currentVersion}${ANSI.RESET}`);
+ log.info?.(`${ANSI.GREEN}✨ Latest version : ${updateStatus.latestVersion}${ANSI.RESET}`);
log.info?.(`${ANSI.CYAN}────────────────────────────────────────────────────────────────${ANSI.RESET}`);
log.info?.(`${ANSI.GREEN}Please run the following command to update manually:${ANSI.RESET}`);
- log.info?.(`${ANSI.YELLOW}${cliName} plugins update memos-cloud-openclaw-plugin${ANSI.RESET}`);
+ log.info?.(`${ANSI.YELLOW}${updateStatus.updateCommand}${ANSI.RESET}`);
log.info?.(`${ANSI.GREEN}${border}${ANSI.RESET}`);
log.info?.("");
diff --git a/lib/config-ui-server.js b/lib/config-ui-server.js
index 675237675..dba421413 100644
--- a/lib/config-ui-server.js
+++ b/lib/config-ui-server.js
@@ -1,713 +1,1038 @@
-
+
import { createHash, randomBytes } from "node:crypto";
import { mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { createServer } from "node:http";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
import { Script } from "node:vm";
+import { checkForPluginUpdate, getPackageVersion } from "./check-update.js";
import { getConfigResolution } from "./memos-cloud-api.js";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-const PLUGIN_ID = "memos-cloud-openclaw-plugin";
-const UI_HOST = "127.0.0.1";
-const UI_BASE_PORT = 38463;
-const UI_PORT_ATTEMPTS = 24;
-const GLOBAL_STATE_KEY = "__memosCloudConfigUiState";
-const ASSET_DIR = join(__dirname, "config-ui");
-const ANSI_BOLD = "\x1b[1m";
-const ANSI_CYAN = "\x1b[36m";
-const ANSI_GREEN = "\x1b[32m";
-const ANSI_RESET = "\x1b[0m";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const PLUGIN_ID = "memos-cloud-openclaw-plugin";
+const UI_HOST = "127.0.0.1";
+const UI_BASE_PORT = 38463;
+const UI_PORT_ATTEMPTS = 24;
+const GLOBAL_STATE_KEY = "__memosCloudConfigUiState";
+const ASSET_DIR = join(__dirname, "config-ui");
+const ANSI_BOLD = "\x1b[1m";
+const ANSI_CYAN = "\x1b[36m";
+const ANSI_GREEN = "\x1b[32m";
+const ANSI_YELLOW = "\x1b[33m";
+const ANSI_RESET = "\x1b[0m";
const DEFAULT_GATEWAY_READY_PORT = 18789;
-
-const FIELD_GROUPS = [
- { id: "connection", title: "Connection", description: "MemOS endpoint, authentication, and identity mapping." },
- { id: "session", title: "Session And Recall", description: "Conversation id strategy, recall scope, and injection behavior." },
- { id: "capture", title: "Capture And Storage", description: "What gets written back to MemOS after each agent run." },
- { id: "agent", title: "Agent Isolation", description: "Multi-agent isolation, app metadata, and sharing permissions." },
- { id: "filter", title: "Recall Filter", description: "Optional model-based second-pass filtering before memories are injected." },
- { id: "advanced", title: "Advanced", description: "Timeouts, throttling, and low-level controls." },
-];
-
-const FIELD_DEFINITIONS = [
- { key: "baseUrl", group: "connection", type: "string", label: "MemOS Base URL", description: "Base URL for the MemOS OpenMem API.", placeholder: "https://memos.memtensor.cn/api/openmem/v1" },
- { key: "apiKey", group: "connection", type: "secret", label: "MemOS API Key", description: "Token auth key. Leave inherited to use env files.", placeholder: "mpg-..." },
- { key: "userId", group: "connection", type: "string", label: "User ID", description: "Unique identifier of the user associated with added messages and queried memories.", placeholder: "openclaw-user" },
- { key: "useDirectSessionUserId", group: "connection", type: "boolean", label: "Use Direct Session User ID", description: "Use direct-session user id from session key when available." },
- { key: "conversationId", group: "session", type: "string", label: "Conversation ID Override", description: "Unique identifier of the conversation. Reusing the same value keeps turns in the same context." },
- { key: "conversationIdPrefix", group: "session", type: "string", label: "Conversation Prefix", description: "Prepended to the derived conversation id." },
- { key: "conversationIdSuffix", group: "session", type: "string", label: "Conversation Suffix", description: "Appended to the derived conversation id." },
- { key: "conversationSuffixMode", group: "session", type: "enum", label: "Suffix Mode", description: "Choose whether /new increments a numeric suffix.", options: [{ value: "none", label: "none" }, { value: "counter", label: "counter" }] },
- { key: "resetOnNew", group: "session", type: "boolean", label: "Reset On /new", description: "Requires hooks.internal.enabled when counter suffix mode is used." },
- { key: "queryPrefix", group: "session", type: "textarea", rows: 4, label: "Query Prefix", description: "Extra text prepended to query before retrieval.", placeholder: "important user context preferences decisions " },
- { key: "maxQueryChars", group: "session", type: "integer", label: "Max Query Chars", description: "Limit the query text length before sending recall search.", placeholder: "0" },
- { key: "recallEnabled", group: "session", type: "boolean", label: "Recall Enabled", description: "Enable before_agent_start memory recall." },
- { key: "recallGlobal", group: "session", type: "boolean", label: "Global Recall", description: "When enabled, query is sent without conversation_id, so current-session weighting is not emphasized." },
- { key: "maxItemChars", group: "session", type: "integer", label: "Max Item Chars", description: "Maximum characters kept when injecting each recalled memory item into context.", placeholder: "8000" },
- { key: "memoryLimitNumber", group: "session", type: "integer", label: "Memory Limit", description: "Maximum number of recalled memories. Default is 9, max is 25.", placeholder: "9" },
- { key: "preferenceLimitNumber", group: "session", type: "integer", label: "Preference Limit", description: "Maximum number of recalled preference memories. Default is 9, max is 25.", placeholder: "9" },
- { key: "includePreference", group: "session", type: "boolean", label: "Include Preferences", description: "Whether to enable preference memory recall." },
- { key: "includeToolMemory", group: "session", type: "boolean", label: "Include Tool Memory", description: "Whether to enable tool memory recall." },
- { key: "toolMemoryLimitNumber", group: "session", type: "integer", label: "Tool Memory Limit", description: "Maximum number of tool memories returned. Effective only when tool memory recall is enabled.", placeholder: "6" },
- { key: "relativity", group: "session", type: "number", label: "Relativity Threshold", description: "Recall relevance threshold from 0 to 1. Set to 0 to disable relevance filtering.", placeholder: "0.45", step: "0.01" },
- { key: "filter", group: "session", type: "json", rows: 7, label: "Search Filter (JSON)", description: "Filter conditions used before retrieval. Supports agent_id, app_id, time fields, info fields, and and/or/gte/lte/gt/lt.", placeholder: '{\n "agent_id": "assistant-1"\n}' },
- { key: "knowledgebaseIds", group: "session", type: "stringArray", rows: 4, label: "Knowledge Base IDs", description: "Restrict the knowledgebase scope for this search. Use one ID per line, or all.", placeholder: "kb-001\nkb-002" },
- { key: "addEnabled", group: "capture", type: "boolean", label: "Add Enabled", description: "Enable adding message arrays and writing resulting memories at agent_end." },
- { key: "captureStrategy", group: "capture", type: "enum", label: "Capture Strategy", description: "Choose whether messages contains only the last turn or the full session.", options: [{ value: "last_turn", label: "last_turn" }, { value: "full_session", label: "full_session" }] },
- { key: "maxMessageChars", group: "capture", type: "integer", label: "Max Message Chars", description: "Maximum characters kept per stored message before building the messages array.", placeholder: "20000" },
- { key: "includeAssistant", group: "capture", type: "boolean", label: "Include Assistant", description: "Include assistant replies in the messages array." },
- { key: "tags", group: "capture", type: "stringArray", rows: 4, label: "Tags", description: "Custom tags used to classify added messages. One value per line.", placeholder: "openclaw" },
- { key: "info", group: "capture", type: "json", rows: 7, label: "Info Payload (JSON)", description: "Structured metadata merged into info for filtering, tracing, and source tracking.", placeholder: '{\n "channel": "webchat"\n}' },
- { key: "asyncMode", group: "capture", type: "boolean", label: "Async Mode", description: "Add memories asynchronously in the background to avoid blocking the call chain." },
- { key: "agentId", group: "agent", type: "string", label: "Static Agent ID", description: "Unique identifier of the Agent associated with added messages and retrieved memories." },
- { key: "multiAgentMode", group: "agent", type: "boolean", label: "Multi-Agent Mode", description: "Isolate recall and add payloads by ctx.agentId when available." },
- { key: "allowedAgents", group: "agent", type: "stringArray", rows: 4, label: "Allowed Agents", description: "Only listed agent ids are allowed to recall and add; empty means all agents." },
- { key: "agentOverrides", group: "agent", type: "json", rows: 10, label: "Agent Overrides (JSON)", description: "Per-agent overrides. Key is agent id, value is an object of supported override fields.", placeholder: '{\n "assistant-1": {\n "knowledgebaseIds": ["kb-001"],\n "recallEnabled": true\n }\n}' },
- { key: "appId", group: "agent", type: "string", label: "App ID", description: "Unique identifier of the App associated with added messages and retrieved memories." },
- { key: "allowPublic", group: "agent", type: "boolean", label: "Allow Public", description: "Allow generated memories to be written to the public memory store." },
- { key: "allowKnowledgebaseIds", group: "agent", type: "stringArray", rows: 4, label: "Allowed Knowledge Base IDs", description: "Knowledgebase scope where generated memories are allowed to be written. One ID per line.", placeholder: "kb-public\nkb-team" },
- { key: "recallFilterEnabled", group: "filter", type: "boolean", label: "Recall Filter Enabled", description: "Enable second-pass model filtering for recall candidates." },
- { key: "recallFilterBaseUrl", group: "filter", type: "string", label: "Filter Base URL", description: "OpenAI-compatible endpoint used for recall filtering.", placeholder: "http://127.0.0.1:11434/v1" },
- { key: "recallFilterApiKey", group: "filter", type: "secret", label: "Filter API Key", description: "Optional bearer token for the recall filter model endpoint." },
- { key: "recallFilterModel", group: "filter", type: "string", label: "Filter Model", description: "Model name used by the recall filter endpoint.", placeholder: "qwen2.5:7b" },
- { key: "recallFilterTimeoutMs", group: "filter", type: "integer", label: "Filter Timeout (ms)", description: "Request timeout for the recall filter model.", placeholder: "6000" },
- { key: "recallFilterRetries", group: "filter", type: "integer", label: "Filter Retries", description: "Retry count when the recall filter request fails.", placeholder: "0" },
- { key: "recallFilterCandidateLimit", group: "filter", type: "integer", label: "Candidate Limit", description: "Per-category candidate limit before filtering.", placeholder: "30" },
- { key: "recallFilterMaxItemChars", group: "filter", type: "integer", label: "Filter Max Item Chars", description: "Maximum characters kept per candidate item before filtering.", placeholder: "500" },
- { key: "recallFilterFailOpen", group: "filter", type: "boolean", label: "Fail Open", description: "Fall back to unfiltered recall if the filter model errors." },
- { key: "timeoutMs", group: "advanced", type: "integer", label: "MemOS Timeout (ms)", description: "Timeout used for MemOS API requests.", placeholder: "5000" },
- { key: "retries", group: "advanced", type: "integer", label: "MemOS Retries", description: "Retry count for MemOS API requests.", placeholder: "1" },
- { key: "throttleMs", group: "advanced", type: "integer", label: "Throttle (ms)", description: "Skip add/message when the previous capture happened too recently.", placeholder: "0" },
-];
-
-function getGlobalState() {
- if (!globalThis[GLOBAL_STATE_KEY]) {
- globalThis[GLOBAL_STATE_KEY] = {
- promise: null,
- service: null,
- cleanupInstalled: false,
- restartHookInstalled: false,
- restartTimer: null,
- restartPending: false,
- recyclePromise: null,
- shuttingDown: false,
- child: null,
- };
- }
- return globalThis[GLOBAL_STATE_KEY];
-}
-
-function isPlainObject(value) {
- return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
-function deepClone(value) {
- if (value === undefined) return undefined;
- return JSON.parse(JSON.stringify(value));
-}
-
-function sanitizeStructuredValue(value, depth = 0) {
- if (depth > 16) throw new Error("Config payload is too deeply nested.");
- if (value === null) return null;
- if (typeof value === "string" || typeof value === "boolean") return value;
- if (typeof value === "number") {
- if (!Number.isFinite(value)) throw new Error("Config payload contains a non-finite number.");
- return value;
- }
- if (Array.isArray(value)) return value.map((item) => sanitizeStructuredValue(item, depth + 1));
- if (isPlainObject(value)) {
- const next = {};
- for (const [key, child] of Object.entries(value)) {
- const normalized = sanitizeStructuredValue(child, depth + 1);
- if (normalized !== undefined) next[key] = normalized;
- }
- return next;
- }
- if (value === undefined) return undefined;
- throw new Error("Config payload contains an unsupported value type.");
-}
-
-function sortForHash(value) {
- if (Array.isArray(value)) return value.map((item) => sortForHash(item));
- if (isPlainObject(value)) {
- return Object.keys(value)
- .sort()
- .reduce((acc, key) => {
- acc[key] = sortForHash(value[key]);
- return acc;
- }, {});
- }
- return value;
-}
-
-function createRevision(value) {
- return createHash("sha1").update(JSON.stringify(sortForHash(value))).digest("hex").slice(0, 12);
-}
-
-function detectRuntimeProfile() {
- const scriptPath = String(process.argv[1] || "").toLowerCase();
- const execPath = String(process.execPath || "").toLowerCase();
-
- if (scriptPath.includes("moltbot") || execPath.includes("moltbot")) {
- return { id: "moltbot", displayName: "Moltbot", cliName: "moltbot", configPath: join(homedir(), ".moltbot", "moltbot.json") };
- }
- if (scriptPath.includes("clawdbot") || execPath.includes("clawdbot")) {
- return { id: "clawdbot", displayName: "ClawDBot", cliName: "clawdbot", configPath: join(homedir(), ".clawdbot", "clawdbot.json") };
- }
- return { id: "openclaw", displayName: "OpenClaw", cliName: "openclaw", configPath: join(homedir(), ".openclaw", "openclaw.json") };
-}
-
-function parsePositiveInteger(value, fallback) {
- const parsed = Number(value);
- if (Number.isFinite(parsed) && parsed > 0) return Math.floor(parsed);
- return fallback;
-}
-
-function resolveGatewayReadyProbeTarget(rootConfig = {}) {
- const gateway = isPlainObject(rootConfig?.gateway) ? rootConfig.gateway : {};
- const port = parsePositiveInteger(gateway.port, DEFAULT_GATEWAY_READY_PORT);
- const bind = typeof gateway.bind === "string" ? gateway.bind.trim().toLowerCase() : "";
- const customBindHost = typeof gateway.customBindHost === "string" ? gateway.customBindHost.trim() : "";
- const host = bind === "custom" && customBindHost ? customBindHost : "127.0.0.1";
- return { host, port, url: `http://${host}:${port}/ready` };
-}
-
-export async function waitForGatewayReady(rootConfig = {}, log = console, options = {}) {
- const timeoutMs = parsePositiveInteger(options.timeoutMs, 45000);
- const intervalMs = parsePositiveInteger(options.intervalMs, 300);
- const deadline = Date.now() + timeoutMs;
- const target = resolveGatewayReadyProbeTarget(rootConfig);
-
- while (Date.now() < deadline) {
- try {
- const response = await fetch(target.url, {
- method: "GET",
- cache: "no-store",
- });
- if (response.ok) {
- let body = null;
- try {
- body = await response.json();
- } catch {
- body = null;
- }
- if (!body || body.ready !== false) return true;
- }
- } catch {
- // Ignore probe failures until timeout expires.
- }
-
- await new Promise((resolve) => setTimeout(resolve, intervalMs));
- }
-
- log.warn?.(`[memos-cloud] Gateway readiness probe timed out at ${target.url}; config UI will not start yet.`);
- return false;
-}
-
-function shouldStartConfigUi() {
- const args = process.argv.map((value) => String(value || "").toLowerCase());
- const gatewayIndex = args.lastIndexOf("gateway");
- if (gatewayIndex === -1) return false;
-
- const nextArg = args[gatewayIndex + 1];
- if (!nextArg || nextArg.startsWith("-")) return true;
- return nextArg === "start" || nextArg === "restart";
-}
-
-function stripBom(text) {
- return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
-}
-
-function parseJson5File(text, filePath) {
- const source = stripBom(String(text || "")).trim();
- if (!source) return {};
-
- try {
- const parsed = JSON.parse(source);
- if (!isPlainObject(parsed)) throw new Error("Root config must be an object.");
- return parsed;
- } catch {
- const script = new Script(`(${source}\n)`, { filename: filePath });
- const parsed = script.runInNewContext(Object.create(null), { timeout: 500 });
- if (!isPlainObject(parsed)) throw new Error("Root config must be an object.");
- return parsed;
- }
-}
-
-function hasIncludeDirective(value, depth = 0) {
- if (depth > 8) return false;
- if (Array.isArray(value)) return value.some((item) => hasIncludeDirective(item, depth + 1));
- if (!isPlainObject(value)) return false;
- if (Object.prototype.hasOwnProperty.call(value, "$include")) return true;
- return Object.values(value).some((child) => hasIncludeDirective(child, depth + 1));
-}
-
-function readGatewayConfig(profile) {
- let root = {};
- let fileExists = true;
- let stat = null;
-
- try {
- root = parseJson5File(readFileSync(profile.configPath, "utf8"), profile.configPath);
- stat = statSync(profile.configPath);
- } catch (error) {
- if (error?.code !== "ENOENT") throw error;
- fileExists = false;
- }
-
- const plugins = isPlainObject(root.plugins) ? root.plugins : {};
- const entries = isPlainObject(plugins.entries) ? plugins.entries : {};
- const entry = isPlainObject(entries[PLUGIN_ID]) ? entries[PLUGIN_ID] : null;
- const config = entry && isPlainObject(entry.config) ? deepClone(entry.config) : {};
- const enabled = entry ? entry.enabled !== false : true;
-
- return {
- profile,
- fileExists,
- configPath: profile.configPath,
- entryExists: Boolean(entry),
- enabled,
- config,
- root,
- hasInclude: hasIncludeDirective(root.plugins) || hasIncludeDirective(root),
- revision: createRevision({
- config,
- enabled,
- entryExists: Boolean(entry),
- fileExists,
- mtimeMs: stat?.mtimeMs ?? 0,
- size: stat?.size ?? 0,
- }),
- };
-}
-
-function writeGatewayConfig(profile, payload) {
- const current = readGatewayConfig(profile);
- const nextRoot = isPlainObject(current.root) ? deepClone(current.root) : {};
- if (!isPlainObject(nextRoot.plugins)) nextRoot.plugins = {};
- if (!isPlainObject(nextRoot.plugins.entries)) nextRoot.plugins.entries = {};
-
- const entry = { enabled: payload.enabled !== false };
- const config = sanitizeStructuredValue(payload.config ?? {});
- if (!isPlainObject(config)) throw new Error("Config payload must be an object.");
- if (Object.keys(config).length > 0) entry.config = config;
-
- nextRoot.plugins.entries[PLUGIN_ID] = entry;
-
- mkdirSync(dirname(profile.configPath), { recursive: true });
- writeFileSync(profile.configPath, `${JSON.stringify(nextRoot, null, 2)}\n`, "utf8");
- return readGatewayConfig(profile);
-}
-
-function buildStatePayload(service) {
- const state = readGatewayConfig(service.profile);
- const resolution = getConfigResolution(state.config);
- return {
+const UPDATE_STATUS_CACHE_MS = 30 * 60 * 1000;
+
+// Hook policies that the gateway requires non-bundled plugins to opt into.
+// Without these, the gateway blocks `agent_end` (and other conversation-access
+// hooks) at registration time. Keep this list in sync with the policies the
+// plugin actually relies on so we never drift from runtime behavior.
+const REQUIRED_HOOK_POLICIES = ["allowConversationAccess"];
+
+const FIELD_GROUPS = [
+ { id: "connection", title: "Connection", description: "MemOS endpoint, authentication, and identity mapping." },
+ { id: "session", title: "Session And Recall", description: "Conversation id strategy, recall scope, and injection behavior." },
+ { id: "capture", title: "Capture And Storage", description: "What gets written back to MemOS after each agent run." },
+ { id: "agent", title: "Agent Isolation", description: "Multi-agent isolation, app metadata, and sharing permissions." },
+ { id: "filter", title: "Recall Filter", description: "Optional model-based second-pass filtering before memories are injected." },
+ { id: "advanced", title: "Advanced", description: "Timeouts, throttling, and low-level controls." },
+];
+
+const FIELD_DEFINITIONS = [
+ { key: "baseUrl", group: "connection", type: "string", label: "MemOS Base URL", description: "Base URL for the MemOS OpenMem API.", placeholder: "https://memos.memtensor.cn/api/openmem/v1" },
+ { key: "apiKey", group: "connection", type: "secret", label: "MemOS API Key", description: "Token auth key. Leave inherited to use env files.", placeholder: "mpg-..." },
+ { key: "userId", group: "connection", type: "string", label: "User ID", description: "Unique identifier of the user associated with added messages and queried memories.", placeholder: "openclaw-user" },
+ { key: "useDirectSessionUserId", group: "connection", type: "boolean", label: "Use Direct Session User ID", description: "Use direct-session user id from session key when available." },
+ { key: "conversationId", group: "session", type: "string", label: "Conversation ID Override", description: "Unique identifier of the conversation. Reusing the same value keeps turns in the same context." },
+ { key: "conversationIdPrefix", group: "session", type: "string", label: "Conversation Prefix", description: "Prepended to the derived conversation id." },
+ { key: "conversationIdSuffix", group: "session", type: "string", label: "Conversation Suffix", description: "Appended to the derived conversation id." },
+ { key: "conversationSuffixMode", group: "session", type: "enum", label: "Suffix Mode", description: "Choose whether /new increments a numeric suffix.", options: [{ value: "none", label: "none" }, { value: "counter", label: "counter" }] },
+ { key: "resetOnNew", group: "session", type: "boolean", label: "Reset On /new", description: "Requires hooks.internal.enabled when counter suffix mode is used." },
+ { key: "queryPrefix", group: "session", type: "textarea", rows: 4, label: "Query Prefix", description: "Extra text prepended to query before retrieval.", placeholder: "important user context preferences decisions " },
+ { key: "maxQueryChars", group: "session", type: "integer", label: "Max Query Chars", description: "Limit the query text length before sending recall search.", placeholder: "0" },
+ { key: "recallEnabled", group: "session", type: "boolean", label: "Recall Enabled", description: "Enable before_agent_start memory recall." },
+ { key: "recallGlobal", group: "session", type: "boolean", label: "Global Recall", description: "When enabled, query is sent without conversation_id, so current-session weighting is not emphasized." },
+ { key: "maxItemChars", group: "session", type: "integer", label: "Max Item Chars", description: "Maximum characters kept when injecting each recalled memory item into context.", placeholder: "8000" },
+ { key: "memoryLimitNumber", group: "session", type: "integer", label: "Memory Limit", description: "Maximum number of recalled memories. Default is 9, max is 25.", placeholder: "9" },
+ { key: "preferenceLimitNumber", group: "session", type: "integer", label: "Preference Limit", description: "Maximum number of recalled preference memories. Default is 9, max is 25.", placeholder: "9" },
+ { key: "includePreference", group: "session", type: "boolean", label: "Include Preferences", description: "Whether to enable preference memory recall." },
+ { key: "includeToolMemory", group: "session", type: "boolean", label: "Include Tool Memory", description: "Whether to enable tool memory recall." },
+ { key: "toolMemoryLimitNumber", group: "session", type: "integer", label: "Tool Memory Limit", description: "Maximum number of tool memories returned. Effective only when tool memory recall is enabled.", placeholder: "6" },
+ { key: "relativity", group: "session", type: "number", label: "Relativity Threshold", description: "Recall relevance threshold from 0 to 1. Set to 0 to disable relevance filtering.", placeholder: "0.45", step: "0.01" },
+ { key: "filter", group: "session", type: "json", rows: 7, label: "Search Filter (JSON)", description: "Filter conditions used before retrieval. Supports agent_id, app_id, time fields, info fields, and and/or/gte/lte/gt/lt.", placeholder: '{\n "agent_id": "assistant-1"\n}' },
+ { key: "knowledgebaseIds", group: "session", type: "stringArray", rows: 4, label: "Knowledge Base IDs", description: "Restrict the knowledgebase scope for this search. Use one ID per line, or all.", placeholder: "kb-001\nkb-002" },
+ { key: "addEnabled", group: "capture", type: "boolean", label: "Add Enabled", description: "Enable adding message arrays and writing resulting memories at agent_end." },
+ { key: "captureStrategy", group: "capture", type: "enum", label: "Capture Strategy", description: "Choose whether messages contains only the last turn or the full session.", options: [{ value: "last_turn", label: "last_turn" }, { value: "full_session", label: "full_session" }] },
+ { key: "maxMessageChars", group: "capture", type: "integer", label: "Max Message Chars", description: "Maximum characters kept per stored message before building the messages array.", placeholder: "20000" },
+ { key: "includeAssistant", group: "capture", type: "boolean", label: "Include Assistant", description: "Include assistant replies in the messages array." },
+ { key: "tags", group: "capture", type: "stringArray", rows: 4, label: "Tags", description: "Custom tags used to classify added messages. One value per line.", placeholder: "openclaw" },
+ { key: "info", group: "capture", type: "json", rows: 7, label: "Info Payload (JSON)", description: "Structured metadata merged into info for filtering, tracing, and source tracking.", placeholder: '{\n "channel": "webchat"\n}' },
+ { key: "asyncMode", group: "capture", type: "boolean", label: "Async Mode", description: "Add memories asynchronously in the background to avoid blocking the call chain." },
+ { key: "agentId", group: "agent", type: "string", label: "Static Agent ID", description: "Unique identifier of the Agent associated with added messages and retrieved memories." },
+ { key: "multiAgentMode", group: "agent", type: "boolean", label: "Multi-Agent Mode", description: "Isolate recall and add payloads by ctx.agentId when available." },
+ { key: "allowedAgents", group: "agent", type: "stringArray", rows: 4, label: "Allowed Agents", description: "Only listed agent ids are allowed to recall and add; empty means all agents." },
+ { key: "agentOverrides", group: "agent", type: "json", rows: 10, label: "Agent Overrides (JSON)", description: "Per-agent overrides. Key is agent id, value is an object of supported override fields.", placeholder: '{\n "assistant-1": {\n "knowledgebaseIds": ["kb-001"],\n "recallEnabled": true\n }\n}' },
+ { key: "appId", group: "agent", type: "string", label: "App ID", description: "Unique identifier of the App associated with added messages and retrieved memories." },
+ { key: "allowPublic", group: "agent", type: "boolean", label: "Allow Public", description: "Allow generated memories to be written to the public memory store." },
+ { key: "allowKnowledgebaseIds", group: "agent", type: "stringArray", rows: 4, label: "Allowed Knowledge Base IDs", description: "Knowledgebase scope where generated memories are allowed to be written. One ID per line.", placeholder: "kb-public\nkb-team" },
+ { key: "recallFilterEnabled", group: "filter", type: "boolean", label: "Recall Filter Enabled", description: "Enable second-pass model filtering for recall candidates." },
+ { key: "recallFilterBaseUrl", group: "filter", type: "string", label: "Filter Base URL", description: "OpenAI-compatible endpoint used for recall filtering.", placeholder: "http://127.0.0.1:11434/v1" },
+ { key: "recallFilterApiKey", group: "filter", type: "secret", label: "Filter API Key", description: "Optional bearer token for the recall filter model endpoint." },
+ { key: "recallFilterModel", group: "filter", type: "string", label: "Filter Model", description: "Model name used by the recall filter endpoint.", placeholder: "qwen2.5:7b" },
+ { key: "recallFilterTimeoutMs", group: "filter", type: "integer", label: "Filter Timeout (ms)", description: "Request timeout for the recall filter model.", placeholder: "6000" },
+ { key: "recallFilterRetries", group: "filter", type: "integer", label: "Filter Retries", description: "Retry count when the recall filter request fails.", placeholder: "0" },
+ { key: "recallFilterCandidateLimit", group: "filter", type: "integer", label: "Candidate Limit", description: "Per-category candidate limit before filtering.", placeholder: "30" },
+ { key: "recallFilterMaxItemChars", group: "filter", type: "integer", label: "Filter Max Item Chars", description: "Maximum characters kept per candidate item before filtering.", placeholder: "500" },
+ { key: "recallFilterFailOpen", group: "filter", type: "boolean", label: "Fail Open", description: "Fall back to unfiltered recall if the filter model errors." },
+ { key: "timeoutMs", group: "advanced", type: "integer", label: "MemOS Timeout (ms)", description: "Timeout used for MemOS API requests.", placeholder: "5000" },
+ { key: "retries", group: "advanced", type: "integer", label: "MemOS Retries", description: "Retry count for MemOS API requests.", placeholder: "1" },
+ { key: "throttleMs", group: "advanced", type: "integer", label: "Throttle (ms)", description: "Skip add/message when the previous capture happened too recently.", placeholder: "0" },
+];
+
+function getGlobalState() {
+ if (!globalThis[GLOBAL_STATE_KEY]) {
+ globalThis[GLOBAL_STATE_KEY] = {
+ promise: null,
+ service: null,
+ cleanupInstalled: false,
+ restartHookInstalled: false,
+ restartTimer: null,
+ restartPending: false,
+ recyclePromise: null,
+ shuttingDown: false,
+ child: null,
+ };
+ }
+ return globalThis[GLOBAL_STATE_KEY];
+}
+
+function isPlainObject(value) {
+ return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function deepClone(value) {
+ if (value === undefined) return undefined;
+ return JSON.parse(JSON.stringify(value));
+}
+
+function sanitizeStructuredValue(value, depth = 0) {
+ if (depth > 16) throw new Error("Config payload is too deeply nested.");
+ if (value === null) return null;
+ if (typeof value === "string" || typeof value === "boolean") return value;
+ if (typeof value === "number") {
+ if (!Number.isFinite(value)) throw new Error("Config payload contains a non-finite number.");
+ return value;
+ }
+ if (Array.isArray(value)) return value.map((item) => sanitizeStructuredValue(item, depth + 1));
+ if (isPlainObject(value)) {
+ const next = {};
+ for (const [key, child] of Object.entries(value)) {
+ const normalized = sanitizeStructuredValue(child, depth + 1);
+ if (normalized !== undefined) next[key] = normalized;
+ }
+ return next;
+ }
+ if (value === undefined) return undefined;
+ throw new Error("Config payload contains an unsupported value type.");
+}
+
+function sortForHash(value) {
+ if (Array.isArray(value)) return value.map((item) => sortForHash(item));
+ if (isPlainObject(value)) {
+ return Object.keys(value)
+ .sort()
+ .reduce((acc, key) => {
+ acc[key] = sortForHash(value[key]);
+ return acc;
+ }, {});
+ }
+ return value;
+}
+
+function createRevision(value) {
+ return createHash("sha1").update(JSON.stringify(sortForHash(value))).digest("hex").slice(0, 12);
+}
+
+function detectRuntimeProfile() {
+ const scriptPath = String(process.argv[1] || "").toLowerCase();
+ const execPath = String(process.execPath || "").toLowerCase();
+
+ if (scriptPath.includes("moltbot") || execPath.includes("moltbot")) {
+ return { id: "moltbot", displayName: "Moltbot", cliName: "moltbot", configPath: join(homedir(), ".moltbot", "moltbot.json") };
+ }
+ if (scriptPath.includes("clawdbot") || execPath.includes("clawdbot")) {
+ return { id: "clawdbot", displayName: "ClawDBot", cliName: "clawdbot", configPath: join(homedir(), ".clawdbot", "clawdbot.json") };
+ }
+ return { id: "openclaw", displayName: "OpenClaw", cliName: "openclaw", configPath: join(homedir(), ".openclaw", "openclaw.json") };
+}
+
+/**
+ * Detect the version of the host CLI (openclaw / moltbot / clawdbot).
+ *
+ * Strategy (in order of preference):
+ * 1. Parse `@X.Y.Z` out of `process.argv[1]` — pnpm/npm global installs
+ * always embed the version in the store path
+ * (e.g. `.../openclaw@2026.4.26/node_modules/openclaw/openclaw.mjs`).
+ * 2. Walk up from `process.argv[1]` looking for a `package.json` that has
+ * a `version` field — covers local `node` invocations and bundled builds.
+ * 3. Return `null` if neither succeeds.
+ */
+export function detectHostVersion() {
+ const scriptPath = String(process.argv[1] || "");
+
+ const atMatch = scriptPath.match(/@(\d+\.\d+(?:\.\d+)?)/);
+ if (atMatch) return atMatch[1];
+
+ try {
+ let dir = dirname(scriptPath);
+ for (let i = 0; i < 8; i++) {
+ try {
+ const raw = readFileSync(join(dir, "package.json"), "utf8");
+ const pkg = JSON.parse(raw);
+ if (pkg.version && typeof pkg.version === "string") return pkg.version;
+ } catch {
+ // not found at this level, keep walking
+ }
+ const parent = dirname(dir);
+ if (parent === dir) break;
+ dir = parent;
+ }
+ } catch {
+ // ignore
+ }
+
+ return null;
+}
+
+/**
+ * Compare two CalVer / semver version strings component by component.
+ * Returns -1 when a < b, 0 when equal, 1 when a > b.
+ * Non-numeric components (e.g. pre-release suffixes) are ignored.
+ */
+export function compareVersionStrings(a, b) {
+ const partsA = String(a ?? "").split(".").map(Number);
+ const partsB = String(b ?? "").split(".").map(Number);
+ const len = Math.max(partsA.length, partsB.length);
+ for (let i = 0; i < len; i++) {
+ const na = Number.isFinite(partsA[i]) ? partsA[i] : 0;
+ const nb = Number.isFinite(partsB[i]) ? partsB[i] : 0;
+ if (na < nb) return -1;
+ if (na > nb) return 1;
+ }
+ return 0;
+}
+
+function parsePositiveInteger(value, fallback) {
+ const parsed = Number(value);
+ if (Number.isFinite(parsed) && parsed > 0) return Math.floor(parsed);
+ return fallback;
+}
+
+function resolveGatewayReadyProbeTarget(rootConfig = {}) {
+ const gateway = isPlainObject(rootConfig?.gateway) ? rootConfig.gateway : {};
+ const port = parsePositiveInteger(gateway.port, DEFAULT_GATEWAY_READY_PORT);
+ const bind = typeof gateway.bind === "string" ? gateway.bind.trim().toLowerCase() : "";
+ const customBindHost = typeof gateway.customBindHost === "string" ? gateway.customBindHost.trim() : "";
+ const host = bind === "custom" && customBindHost ? customBindHost : "127.0.0.1";
+ return { host, port, url: `http://${host}:${port}/ready` };
+}
+
+export async function waitForGatewayReady(rootConfig = {}, log = console, options = {}) {
+ const timeoutMs = parsePositiveInteger(options.timeoutMs, 45000);
+ const intervalMs = parsePositiveInteger(options.intervalMs, 300);
+ const deadline = Date.now() + timeoutMs;
+ const target = resolveGatewayReadyProbeTarget(rootConfig);
+
+ while (Date.now() < deadline) {
+ try {
+ const response = await fetch(target.url, {
+ method: "GET",
+ cache: "no-store",
+ });
+ if (response.ok) {
+ let body = null;
+ try {
+ body = await response.json();
+ } catch {
+ body = null;
+ }
+ if (!body || body.ready !== false) return true;
+ }
+ } catch {
+ // Ignore probe failures until timeout expires.
+ }
+
+ await new Promise((resolve) => setTimeout(resolve, intervalMs));
+ }
+
+ log.warn?.(`[memos-cloud] Gateway readiness probe timed out at ${target.url}; config UI will not start yet.`);
+ return false;
+}
+
+// Returns true when the current process was launched by an `openclaw gateway`
+// command that actually starts (or restarts) the long-lived gateway. Other
+// CLI entry points (`plugins install`, `security audit`, `--help`, ...) also
+// load this plugin to inspect/register it, but they perform their own
+// config commits and must not be racing with our hook-policy patcher.
+function isGatewayStartCommand() {
+ const args = process.argv.map((value) => String(value || "").toLowerCase());
+ const gatewayIndex = args.lastIndexOf("gateway");
+ if (gatewayIndex === -1) return false;
+
+ const nextArg = args[gatewayIndex + 1];
+ if (!nextArg || nextArg.startsWith("-")) return true;
+ return nextArg === "start" || nextArg === "restart" || nextArg === "run";
+}
+
+function shouldStartConfigUi() {
+ return isGatewayStartCommand();
+}
+
+export function isGatewayRuntimeStartup() {
+ return isGatewayStartCommand();
+}
+
+function stripBom(text) {
+ return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+function parseJson5File(text, filePath) {
+ const source = stripBom(String(text || "")).trim();
+ if (!source) return {};
+
+ try {
+ const parsed = JSON.parse(source);
+ if (!isPlainObject(parsed)) throw new Error("Root config must be an object.");
+ return parsed;
+ } catch {
+ const script = new Script(`(${source}\n)`, { filename: filePath });
+ const parsed = script.runInNewContext(Object.create(null), { timeout: 500 });
+ if (!isPlainObject(parsed)) throw new Error("Root config must be an object.");
+ return parsed;
+ }
+}
+
+function hasIncludeDirective(value, depth = 0) {
+ if (depth > 8) return false;
+ if (Array.isArray(value)) return value.some((item) => hasIncludeDirective(item, depth + 1));
+ if (!isPlainObject(value)) return false;
+ if (Object.prototype.hasOwnProperty.call(value, "$include")) return true;
+ return Object.values(value).some((child) => hasIncludeDirective(child, depth + 1));
+}
+
+function readGatewayConfig(profile) {
+ let root = {};
+ let fileExists = true;
+ let stat = null;
+
+ try {
+ root = parseJson5File(readFileSync(profile.configPath, "utf8"), profile.configPath);
+ stat = statSync(profile.configPath);
+ } catch (error) {
+ if (error?.code !== "ENOENT") throw error;
+ fileExists = false;
+ }
+
+ const plugins = isPlainObject(root.plugins) ? root.plugins : {};
+ const entries = isPlainObject(plugins.entries) ? plugins.entries : {};
+ const entry = isPlainObject(entries[PLUGIN_ID]) ? entries[PLUGIN_ID] : null;
+ const config = entry && isPlainObject(entry.config) ? deepClone(entry.config) : {};
+ const enabled = entry ? entry.enabled !== false : true;
+
+ return {
+ profile,
+ fileExists,
+ configPath: profile.configPath,
+ entryExists: Boolean(entry),
+ enabled,
+ config,
+ root,
+ hasInclude: hasIncludeDirective(root.plugins) || hasIncludeDirective(root),
+ revision: createRevision({
+ config,
+ enabled,
+ entryExists: Boolean(entry),
+ fileExists,
+ mtimeMs: stat?.mtimeMs ?? 0,
+ size: stat?.size ?? 0,
+ }),
+ };
+}
+
+function writeGatewayConfig(profile, payload) {
+ const current = readGatewayConfig(profile);
+ const nextRoot = isPlainObject(current.root) ? deepClone(current.root) : {};
+ if (!isPlainObject(nextRoot.plugins)) nextRoot.plugins = {};
+ if (!isPlainObject(nextRoot.plugins.entries)) nextRoot.plugins.entries = {};
+
+ // Preserve any entry-level fields the user already set (e.g. `hooks`,
+ // policy opt-ins, future gateway metadata) so that saving from the config
+ // UI never silently drops gateway-required settings such as
+ // `hooks.allowConversationAccess`.
+ const previousEntry = isPlainObject(nextRoot.plugins.entries[PLUGIN_ID])
+ ? nextRoot.plugins.entries[PLUGIN_ID]
+ : {};
+ const entry = { ...previousEntry, enabled: payload.enabled !== false };
+
+ const config = sanitizeStructuredValue(payload.config ?? {});
+ if (!isPlainObject(config)) throw new Error("Config payload must be an object.");
+ if (Object.keys(config).length > 0) {
+ entry.config = config;
+ } else {
+ delete entry.config;
+ }
+
+ nextRoot.plugins.entries[PLUGIN_ID] = entry;
+
+ mkdirSync(dirname(profile.configPath), { recursive: true });
+ writeFileSync(profile.configPath, `${JSON.stringify(nextRoot, null, 2)}\n`, "utf8");
+ return readGatewayConfig(profile);
+}
+
+function getPluginEntry(root) {
+ const plugins = isPlainObject(root?.plugins) ? root.plugins : null;
+ if (!plugins) return null;
+ const entries = isPlainObject(plugins.entries) ? plugins.entries : null;
+ if (!entries) return null;
+ return isPlainObject(entries[PLUGIN_ID]) ? entries[PLUGIN_ID] : null;
+}
+
+function getMissingHookPolicies(root, hookKeys) {
+ const entry = getPluginEntry(root);
+ const hooks = isPlainObject(entry?.hooks) ? entry.hooks : {};
+ return hookKeys.filter((key) => hooks[key] !== true);
+}
+
+/**
+ * Ensure the gateway config grants this plugin the typed-hook policies it
+ * needs. The gateway blocks non-bundled plugins from registering hooks like
+ * `agent_end` unless `plugins.entries..hooks.allowConversationAccess` is
+ * explicitly set to `true`. Users hit this on every fresh install because the
+ * key is not part of any default config template, so we patch it in
+ * automatically on first load.
+ *
+ * Behavior:
+ * - Fast-path: if `rootConfig` already has all required keys, do nothing
+ * silently — no logs, no disk reads.
+ * - Otherwise: read the on-disk config (to preserve unrelated edits made
+ * after the gateway booted), merge in the missing keys, write it back,
+ * and return `{ changed: true }` so the caller can ask the user to
+ * restart the gateway. We only mutate the keys we own.
+ * - If the config uses `$include` directives we cannot safely rewrite the
+ * merged tree, so we just warn and leave the file untouched.
+ *
+ * NOTE: callers are responsible for deciding *when* to invoke this. In
+ * particular it must NOT be called from short-lived CLI commands such as
+ * `plugins install` that perform their own config commits — racing with
+ * them triggers `ConfigMutationConflictError`. See `isGatewayRuntimeStartup`.
+ */
+export function ensurePluginHookPolicy(rootConfig = null, log = console, options = {}) {
+ const hookKeys = Array.isArray(options.hookKeys) && options.hookKeys.length > 0
+ ? options.hookKeys
+ : REQUIRED_HOOK_POLICIES;
+
+ const profile = detectRuntimeProfile();
+
+ if (isPlainObject(rootConfig) && getMissingHookPolicies(rootConfig, hookKeys).length === 0) {
+ return { changed: false, configPath: profile.configPath, profile };
+ }
+
+ let current;
+ try {
+ current = readGatewayConfig(profile);
+ } catch (error) {
+ log.warn?.(
+ `[memos-cloud] failed to read ${profile.configPath} while ensuring plugin hook policy: ${String(error?.message ?? error)}`,
+ );
+ return { changed: false, error, configPath: profile.configPath, profile };
+ }
+
+ if (current.hasInclude) {
+ const missing = getMissingHookPolicies(current.root, hookKeys);
+ if (missing.length > 0) {
+ log.warn?.(
+ `[memos-cloud] gateway config at ${profile.configPath} uses $include directives, ` +
+ `cannot auto-enable required plugin hook policies: ${missing.join(", ")}. ` +
+ `Add plugins.entries.${PLUGIN_ID}.hooks={${missing.map((k) => `${k}:true`).join(", ")}} manually and restart the gateway.`,
+ );
+ }
+ return { changed: false, hasInclude: true, configPath: profile.configPath, profile };
+ }
+
+ const missingKeys = getMissingHookPolicies(current.root, hookKeys);
+ if (missingKeys.length === 0) return { changed: false, configPath: profile.configPath, profile };
+
+ const nextRoot = isPlainObject(current.root) ? deepClone(current.root) : {};
+ if (!isPlainObject(nextRoot.plugins)) nextRoot.plugins = {};
+ if (!isPlainObject(nextRoot.plugins.entries)) nextRoot.plugins.entries = {};
+ if (!isPlainObject(nextRoot.plugins.entries[PLUGIN_ID])) {
+ nextRoot.plugins.entries[PLUGIN_ID] = {};
+ }
+ const entry = nextRoot.plugins.entries[PLUGIN_ID];
+ if (entry.enabled === undefined) entry.enabled = true;
+ if (!isPlainObject(entry.hooks)) entry.hooks = {};
+ for (const key of missingKeys) {
+ entry.hooks[key] = true;
+ }
+
+ try {
+ mkdirSync(dirname(profile.configPath), { recursive: true });
+ writeFileSync(profile.configPath, `${JSON.stringify(nextRoot, null, 2)}\n`, "utf8");
+ } catch (error) {
+ log.warn?.(
+ `[memos-cloud] failed to write ${profile.configPath} to enable required plugin hook policies (${missingKeys.join(", ")}): ${String(error?.message ?? error)}`,
+ );
+ return { changed: false, error, configPath: profile.configPath, profile };
+ }
+
+ // Emit the eye-catching banner directly through stdout so the gateway's
+ // log-line prefix (`[plugins] [memos-cloud] ...`) does not break up the
+ // box drawing. Then also emit a single terse `log.warn` line so any
+ // structured log aggregator / CI capture still gets the event.
+// console.log(renderHookPolicyRestartBanner(profile, missingKeys));
+ log.warn?.(
+ `[memos-cloud] hook policy patched in ${profile.configPath} (added: ${missingKeys.join(", ")}). ` +
+ `Manual gateway restart required: \`${profile.cliName} gateway restart\`.`,
+ );
+
+ return { changed: true, addedKeys: missingKeys, configPath: profile.configPath, profile };
+}
+
+/**
+ * Returns metadata describing how `ensurePluginHookPolicy` would behave for
+ * the current runtime, without writing anything. Useful in tests and for
+ * letting host code surface "we will write to " diagnostics before any
+ * IO actually happens.
+ */
+export function describePluginHookPolicyTarget() {
+ const profile = detectRuntimeProfile();
+ return {
+ runtime: profile.id,
+ configPath: profile.configPath,
+ hookKeys: [...REQUIRED_HOOK_POLICIES],
+ };
+}
+
+function buildStatePayload(service) {
+ const state = readGatewayConfig(service.profile);
+ const resolution = getConfigResolution(state.config);
+ return {
runtime: state.profile.id,
runtimeDisplayName: state.profile.displayName,
+ pluginVersion: getPackageVersion(),
configPath: state.configPath,
- entryExists: state.entryExists,
- fileExists: state.fileExists,
- enabled: state.enabled,
- config: state.config,
- resolvedConfig: resolution.resolved,
- fieldMeta: resolution.fieldMeta,
- revision: state.revision,
- hasInclude: state.hasInclude,
- bootId: service.bootId,
- assetRevision: getAssetRevision(),
- port: service.port,
- url: service.url,
- };
-}
-
-function getCachedStatePayload(service, maxAgeMs = 1200) {
- const now = Date.now();
- if (service.stateCache && now - service.stateCache.createdAt < maxAgeMs) {
- return service.stateCache.payload;
- }
- const payload = buildStatePayload(service);
- service.stateCache = {
- createdAt: now,
- payload,
- };
- return payload;
+ entryExists: state.entryExists,
+ fileExists: state.fileExists,
+ enabled: state.enabled,
+ config: state.config,
+ resolvedConfig: resolution.resolved,
+ fieldMeta: resolution.fieldMeta,
+ revision: state.revision,
+ hasInclude: state.hasInclude,
+ bootId: service.bootId,
+ assetRevision: getAssetRevision(),
+ port: service.port,
+ url: service.url,
+ };
+}
+
+function getCachedStatePayload(service, maxAgeMs = 1200) {
+ const now = Date.now();
+ if (service.stateCache && now - service.stateCache.createdAt < maxAgeMs) {
+ return service.stateCache.payload;
+ }
+ const payload = buildStatePayload(service);
+ service.stateCache = {
+ createdAt: now,
+ payload,
+ };
+ return payload;
+}
+
+function getCachedHeartbeatPayload(service, maxAgeMs = 1200) {
+ const now = Date.now();
+ if (service.heartbeatCache && now - service.heartbeatCache.createdAt < maxAgeMs) {
+ return {
+ ...service.heartbeatCache.payload,
+ timestamp: now,
+ };
+ }
+ const payload = {
+ ok: true,
+ runtime: service.profile.id,
+ bootId: service.bootId,
+ assetRevision: getAssetRevision(),
+ };
+ service.heartbeatCache = {
+ createdAt: now,
+ payload,
+ };
+ return {
+ ...payload,
+ timestamp: now,
+ };
}
-function getCachedHeartbeatPayload(service, maxAgeMs = 1200) {
+async function getCachedUpdateStatusPayload(service, maxAgeMs = UPDATE_STATUS_CACHE_MS, options = {}) {
const now = Date.now();
- if (service.heartbeatCache && now - service.heartbeatCache.createdAt < maxAgeMs) {
+ if (!options.force && service.updateStatusCache && now - service.updateStatusCache.createdAt < maxAgeMs) {
return {
- ...service.heartbeatCache.payload,
- timestamp: now,
+ ...service.updateStatusCache.payload,
+ cached: true,
};
}
- const payload = {
- ok: true,
- runtime: service.profile.id,
- bootId: service.bootId,
- assetRevision: getAssetRevision(),
- };
- service.heartbeatCache = {
- createdAt: now,
- payload,
- };
- return {
- ...payload,
- timestamp: now,
- };
-}
-function loadAssetTemplate(name) {
- return readFileSync(join(ASSET_DIR, name), "utf8");
-}
-
-function getAssetRevision() {
- const files = ["index.html", "app.js", "app.css"];
- const parts = [];
- for (const name of files) {
- try {
- const stat = statSync(join(ASSET_DIR, name));
- parts.push(`${name}:${stat.mtimeMs}:${stat.size}`);
- } catch {
- parts.push(`${name}:missing`);
- }
- }
- return createRevision(parts);
-}
-
-function replaceTokens(template, tokenMap) {
- let output = template;
- for (const [token, value] of Object.entries(tokenMap)) {
- output = output.split(token).join(value);
- }
- return output;
-}
-
-function jsonString(value) {
- return JSON.stringify(value).replace(/ ` [${index + 1}] ${url}`);
- const plainLines = [
- "",
- ...titleArt,
- "",
- heading,
- "",
- "Plugin configuration page is ready.",
- "Open one of the following URLs in your browser:",
- "",
- ...urlLines,
- "",
- "Tip: keep this window open while you finish the setup.",
- "",
- ];
- const contentWidth = plainLines.reduce((max, line) => Math.max(max, line.length), 0);
- const centeredTitleArt = titleArt.map((line) => centerText(line, contentWidth));
- const centeredHeading = centerText(heading, contentWidth);
- const visibleLineWidths = [
- 0,
- ...centeredTitleArt.map(() => contentWidth),
- 0,
- contentWidth,
- contentWidth,
- "Plugin configuration page is ready.".length,
- "Open one of the following URLs in your browser:".length,
- 0,
- ...urlLines.map((line) => line.length),
- 0,
- "Tip: keep this window open while you finish the setup.".length,
- 0,
- ];
- const separator = "-".repeat(contentWidth);
- const coloredLines = [
- "",
- ...centeredTitleArt.map((line) => `${ANSI_BOLD}${ANSI_CYAN}${line}${ANSI_RESET}`),
- "",
- `${ANSI_BOLD}${centeredHeading}${ANSI_RESET}`,
- `${ANSI_GREEN}${separator}${ANSI_RESET}`,
- "Plugin configuration page is ready.",
- "Open one of the following URLs in your browser:",
- "",
- ...urlLines.map((line) => `${ANSI_BOLD}${ANSI_GREEN}${line}${ANSI_RESET}`),
- "",
- "Tip: keep this window open while you finish the setup.",
- "",
- ];
- const horizontalBorder = `+${"=".repeat(contentWidth + 2)}+`;
-
- return `\n${ANSI_GREEN}${horizontalBorder}${ANSI_RESET}\n${coloredLines
- .map((line, index) => padBoxLine(line, visibleLineWidths[index], contentWidth))
- .join("\n")}\n${ANSI_GREEN}${horizontalBorder}${ANSI_RESET}`;
-}
-
-function renderHtml(service) {
- return replaceTokens(loadAssetTemplate("index.html"), {
- "__PLUGIN_ID__": PLUGIN_ID,
- "__APP_JS_URL__": `/app.js?token=${service.token}`,
- });
-}
-
-function renderAppJs(service) {
- return replaceTokens(loadAssetTemplate("app.js"), {
- "__CONFIG_UI_TOKEN__": jsonString(service.token),
- "__FIELD_GROUPS__": jsonString(FIELD_GROUPS),
- "__FIELD_DEFINITIONS__": jsonString(FIELD_DEFINITIONS),
- });
-}
-
- // Legacy restart functions removed for sandbox compliance
-
-function listenOnPort(server, host, port) {
- return new Promise((resolve, reject) => {
- const onError = (error) => {
- cleanup();
- reject(error);
+ try {
+ const status = await checkForPluginUpdate();
+ const payload = {
+ ok: true,
+ ...status,
+ cached: false,
};
- const onListening = () => {
- cleanup();
- resolve(port);
+ service.updateStatusCache = {
+ createdAt: now,
+ payload,
};
- const cleanup = () => {
- server.off("error", onError);
- server.off("listening", onListening);
+ return payload;
+ } catch (error) {
+ return {
+ ok: false,
+ currentVersion: getPackageVersion(),
+ error: String(error?.message || error),
+ checkedAt: new Date().toISOString(),
+ cached: false,
};
- server.once("error", onError);
- server.once("listening", onListening);
- server.listen(port, host);
- });
-}
-
-async function bindWithFallback(server) {
- for (let offset = 0; offset < UI_PORT_ATTEMPTS; offset += 1) {
- const port = UI_BASE_PORT + offset;
- try {
- await listenOnPort(server, UI_HOST, port);
- return port;
- } catch (error) {
- if (error?.code !== "EADDRINUSE") throw error;
- }
}
- throw new Error(`Could not bind config UI after trying ${UI_PORT_ATTEMPTS} ports from ${UI_BASE_PORT}.`);
}
-function readRequestBody(req) {
- return new Promise((resolve, reject) => {
- let body = "";
- req.setEncoding("utf8");
- req.on("data", (chunk) => {
- body += chunk;
- if (body.length > 1024 * 1024) {
- reject(new Error("Request body too large."));
- req.destroy();
- }
- });
- req.on("end", () => resolve(body));
- req.on("error", reject);
- });
-}
-
-function sendJson(res, statusCode, payload) {
- res.writeHead(statusCode, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" });
- res.end(JSON.stringify(payload));
-}
-
-function sendText(res, statusCode, message) {
- res.writeHead(statusCode, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" });
- res.end(message);
-}
-
-function isAuthorized(req, service) {
- return req.headers["x-memos-config-token"] === service.token;
-}
-
-async function createService(log) {
- const profile = detectRuntimeProfile();
- const token = randomBytes(24).toString("hex");
- const bootId = randomBytes(10).toString("hex");
-
- const service = { profile, token, bootId, port: 0, url: "", server: null, stateCache: null, heartbeatCache: null };
-
- const server = createServer(async (req, res) => {
- try {
- const requestUrl = new URL(req.url || "/", `http://${req.headers.host || "127.0.0.1"}`);
-
- if (requestUrl.pathname === "/favicon.ico") {
- res.writeHead(204);
- res.end();
- return;
- }
-
- if (requestUrl.pathname === "/icon.svg") {
- res.writeHead(200, { "Content-Type": "image/svg+xml; charset=utf-8", "Cache-Control": "no-store" });
- res.end(loadAssetTemplate("icon.svg"));
- return;
- }
-
- if (requestUrl.pathname === "/app.css") {
- res.writeHead(200, { "Content-Type": "text/css; charset=utf-8", "Cache-Control": "no-store" });
- res.end(loadAssetTemplate("app.css"));
- return;
- }
-
- if (requestUrl.pathname === "/app.js") {
- if (requestUrl.searchParams.get("token") !== service.token) {
- sendText(res, 403, "Forbidden");
- return;
- }
- res.writeHead(200, { "Content-Type": "application/javascript; charset=utf-8", "Cache-Control": "no-store" });
- res.end(renderAppJs(service));
- return;
- }
-
- if (requestUrl.pathname === "/api/heartbeat" && req.method === "GET") {
- sendJson(res, 200, getCachedHeartbeatPayload(service));
- return;
- }
-
- if (requestUrl.pathname.startsWith("/api/")) {
- if (!isAuthorized(req, service)) {
- sendText(res, 403, "Forbidden");
- return;
- }
-
+function loadAssetTemplate(name) {
+ return readFileSync(join(ASSET_DIR, name), "utf8");
+}
+
+function getAssetRevision() {
+ const files = ["index.html", "app.js", "app.css"];
+ const parts = [];
+ for (const name of files) {
+ try {
+ const stat = statSync(join(ASSET_DIR, name));
+ parts.push(`${name}:${stat.mtimeMs}:${stat.size}`);
+ } catch {
+ parts.push(`${name}:missing`);
+ }
+ }
+ return createRevision(parts);
+}
+
+function replaceTokens(template, tokenMap) {
+ let output = template;
+ for (const [token, value] of Object.entries(tokenMap)) {
+ output = output.split(token).join(value);
+ }
+ return output;
+}
+
+function jsonString(value) {
+ return JSON.stringify(value).replace(/ ` [${index + 1}] ${url}`);
+ const plainLines = [
+ "",
+ ...titleArt,
+ "",
+ heading,
+ "",
+ "Plugin configuration page is ready.",
+ "Open one of the following URLs in your browser:",
+ "",
+ ...urlLines,
+ "",
+ "Tip: keep this window open while you finish the setup.",
+ "",
+ ];
+ const contentWidth = plainLines.reduce((max, line) => Math.max(max, line.length), 0);
+ const centeredTitleArt = titleArt.map((line) => centerText(line, contentWidth));
+ const centeredHeading = centerText(heading, contentWidth);
+ const visibleLineWidths = [
+ 0,
+ ...centeredTitleArt.map(() => contentWidth),
+ 0,
+ contentWidth,
+ contentWidth,
+ "Plugin configuration page is ready.".length,
+ "Open one of the following URLs in your browser:".length,
+ 0,
+ ...urlLines.map((line) => line.length),
+ 0,
+ "Tip: keep this window open while you finish the setup.".length,
+ 0,
+ ];
+ const separator = "-".repeat(contentWidth);
+ const coloredLines = [
+ "",
+ ...centeredTitleArt.map((line) => `${ANSI_BOLD}${ANSI_CYAN}${line}${ANSI_RESET}`),
+ "",
+ `${ANSI_BOLD}${centeredHeading}${ANSI_RESET}`,
+ `${ANSI_GREEN}${separator}${ANSI_RESET}`,
+ "Plugin configuration page is ready.",
+ "Open one of the following URLs in your browser:",
+ "",
+ ...urlLines.map((line) => `${ANSI_BOLD}${ANSI_GREEN}${line}${ANSI_RESET}`),
+ "",
+ "Tip: keep this window open while you finish the setup.",
+ "",
+ ];
+ const horizontalBorder = `+${"=".repeat(contentWidth + 2)}+`;
+
+ return `\n${ANSI_GREEN}${horizontalBorder}${ANSI_RESET}\n${coloredLines
+ .map((line, index) => padBoxLine(line, visibleLineWidths[index], contentWidth))
+ .join("\n")}\n${ANSI_GREEN}${horizontalBorder}${ANSI_RESET}`;
+}
+
+function renderHookPolicyRestartBanner(profile, addedKeys) {
+ const heading = "PLUGIN HOOK POLICY UPDATED";
+ const subheading = "Manual gateway restart required";
+ const command = `${profile.cliName} gateway restart`;
+ const keyLines = addedKeys.map((key) => ` - ${key}`);
+
+ const plainLines = [
+ "",
+ heading,
+ subheading,
+ "",
+ "Patched file:",
+ ` ${profile.configPath}`,
+ "",
+ "Added hook policies:",
+ ...keyLines,
+ "",
+ "To apply the change, restart the gateway:",
+ "",
+ ` $ ${command}`,
+ "",
+ "Without a restart, hooks like `agent_end` will not be registered,",
+ "so memory capture / recall will silently stop working.",
+ "",
+ ];
+
+ const contentWidth = plainLines.reduce((max, line) => Math.max(max, line.length), 0);
+ const centeredHeading = centerText(heading, contentWidth);
+ const centeredSubheading = centerText(subheading, contentWidth);
+ const separator = "-".repeat(contentWidth);
+
+ const coloredLines = plainLines.map((line) => {
+ if (line === heading) return `${ANSI_BOLD}${ANSI_YELLOW}${centeredHeading}${ANSI_RESET}`;
+ if (line === subheading) return `${ANSI_YELLOW}${centeredSubheading}${ANSI_RESET}`;
+ if (line === ` $ ${command}`) return `${ANSI_BOLD}${ANSI_GREEN}${line}${ANSI_RESET}`;
+ if (line === ` ${profile.configPath}`) return `${ANSI_CYAN}${line}${ANSI_RESET}`;
+ if (line.startsWith(" - ")) return `${ANSI_CYAN}${line}${ANSI_RESET}`;
+ return line;
+ });
+
+ const visibleLineWidths = plainLines.map((line, index) => {
+ if (index === 1 || index === 2) return contentWidth;
+ return line.length;
+ });
+
+ // Insert a separator line between the subheading block and the body so
+ // the title visually anchors to the top of the box.
+ const headingBoundaryIndex = 3;
+ coloredLines.splice(headingBoundaryIndex, 0, `${ANSI_YELLOW}${separator}${ANSI_RESET}`);
+ visibleLineWidths.splice(headingBoundaryIndex, 0, contentWidth);
+
+ const padYellowBoxLine = (content, visibleLength) =>
+ `${ANSI_YELLOW}| ${ANSI_RESET}${content}${" ".repeat(Math.max(0, contentWidth - visibleLength))}${ANSI_YELLOW} |${ANSI_RESET}`;
+
+ const horizontalBorder = `${ANSI_YELLOW}+${"=".repeat(contentWidth + 2)}+${ANSI_RESET}`;
+
+ return `\n${horizontalBorder}\n${coloredLines
+ .map((line, index) => padYellowBoxLine(line, visibleLineWidths[index]))
+ .join("\n")}\n${horizontalBorder}\n`;
+}
+
+function renderHtml(service) {
+ return replaceTokens(loadAssetTemplate("index.html"), {
+ "__PLUGIN_ID__": PLUGIN_ID,
+ "__APP_JS_URL__": `/app.js?token=${service.token}`,
+ });
+}
+
+function renderAppJs(service) {
+ return replaceTokens(loadAssetTemplate("app.js"), {
+ "__CONFIG_UI_TOKEN__": jsonString(service.token),
+ "__FIELD_GROUPS__": jsonString(FIELD_GROUPS),
+ "__FIELD_DEFINITIONS__": jsonString(FIELD_DEFINITIONS),
+ });
+}
+
+ // Legacy restart functions removed for sandbox compliance
+
+function listenOnPort(server, host, port) {
+ return new Promise((resolve, reject) => {
+ const onError = (error) => {
+ cleanup();
+ reject(error);
+ };
+ const onListening = () => {
+ cleanup();
+ resolve(port);
+ };
+ const cleanup = () => {
+ server.off("error", onError);
+ server.off("listening", onListening);
+ };
+ server.once("error", onError);
+ server.once("listening", onListening);
+ server.listen(port, host);
+ });
+}
+
+async function bindWithFallback(server) {
+ for (let offset = 0; offset < UI_PORT_ATTEMPTS; offset += 1) {
+ const port = UI_BASE_PORT + offset;
+ try {
+ await listenOnPort(server, UI_HOST, port);
+ return port;
+ } catch (error) {
+ if (error?.code !== "EADDRINUSE") throw error;
+ }
+ }
+ throw new Error(`Could not bind config UI after trying ${UI_PORT_ATTEMPTS} ports from ${UI_BASE_PORT}.`);
+}
+
+function readRequestBody(req) {
+ return new Promise((resolve, reject) => {
+ let body = "";
+ req.setEncoding("utf8");
+ req.on("data", (chunk) => {
+ body += chunk;
+ if (body.length > 1024 * 1024) {
+ reject(new Error("Request body too large."));
+ req.destroy();
+ }
+ });
+ req.on("end", () => resolve(body));
+ req.on("error", reject);
+ });
+}
+
+function sendJson(res, statusCode, payload) {
+ res.writeHead(statusCode, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" });
+ res.end(JSON.stringify(payload));
+}
+
+function sendText(res, statusCode, message) {
+ res.writeHead(statusCode, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" });
+ res.end(message);
+}
+
+function isAuthorized(req, service) {
+ return req.headers["x-memos-config-token"] === service.token;
+}
+
+async function createService(log) {
+ const profile = detectRuntimeProfile();
+ const token = randomBytes(24).toString("hex");
+ const bootId = randomBytes(10).toString("hex");
+
+ const service = {
+ profile,
+ token,
+ bootId,
+ port: 0,
+ url: "",
+ server: null,
+ stateCache: null,
+ heartbeatCache: null,
+ updateStatusCache: null,
+ };
+
+ const server = createServer(async (req, res) => {
+ try {
+ const requestUrl = new URL(req.url || "/", `http://${req.headers.host || "127.0.0.1"}`);
+
+ if (requestUrl.pathname === "/favicon.ico") {
+ res.writeHead(204);
+ res.end();
+ return;
+ }
+
+ if (requestUrl.pathname === "/icon.svg") {
+ res.writeHead(200, { "Content-Type": "image/svg+xml; charset=utf-8", "Cache-Control": "no-store" });
+ res.end(loadAssetTemplate("icon.svg"));
+ return;
+ }
+
+ if (requestUrl.pathname === "/app.css") {
+ res.writeHead(200, { "Content-Type": "text/css; charset=utf-8", "Cache-Control": "no-store" });
+ res.end(loadAssetTemplate("app.css"));
+ return;
+ }
+
+ if (requestUrl.pathname === "/app.js") {
+ if (requestUrl.searchParams.get("token") !== service.token) {
+ sendText(res, 403, "Forbidden");
+ return;
+ }
+ res.writeHead(200, { "Content-Type": "application/javascript; charset=utf-8", "Cache-Control": "no-store" });
+ res.end(renderAppJs(service));
+ return;
+ }
+
+ if (requestUrl.pathname === "/api/heartbeat" && req.method === "GET") {
+ sendJson(res, 200, getCachedHeartbeatPayload(service));
+ return;
+ }
+
+ if (requestUrl.pathname.startsWith("/api/")) {
+ if (!isAuthorized(req, service)) {
+ sendText(res, 403, "Forbidden");
+ return;
+ }
+
if (requestUrl.pathname === "/api/state" && req.method === "GET") {
sendJson(res, 200, getCachedStatePayload(service));
return;
}
- if (requestUrl.pathname === "/api/save" && req.method === "POST") {
- let parsed = {};
- try {
- parsed = JSON.parse((await readRequestBody(req)) || "{}");
- } catch {
- sendText(res, 400, "Invalid JSON payload.");
- return;
- }
- if (!isPlainObject(parsed)) {
- sendText(res, 400, "Invalid JSON payload.");
- return;
- }
- if (typeof parsed.enabled !== "boolean") {
- sendText(res, 400, "Payload.enabled must be a boolean.");
- return;
- }
- if (!isPlainObject(parsed.config)) {
- sendText(res, 400, "Payload.config must be an object.");
- return;
- }
-
- const nextState = writeGatewayConfig(profile, parsed);
- service.stateCache = null;
- service.heartbeatCache = null;
- sendJson(res, 200, { ok: true, state: buildStatePayload({ ...service, profile: nextState.profile }) });
+ if (requestUrl.pathname === "/api/update-status" && req.method === "GET") {
+ sendJson(res, 200, await getCachedUpdateStatusPayload(service, UPDATE_STATUS_CACHE_MS, {
+ force: requestUrl.searchParams.get("force") === "1",
+ }));
return;
}
- // Legacy `/api/restart` has been entirely removed
- sendText(res, 404, "Not found");
- return;
- }
-
- if (requestUrl.pathname !== "/") {
- sendText(res, 404, "Not found");
- return;
- }
-
- res.writeHead(200, {
- "Content-Type": "text/html; charset=utf-8",
- "Cache-Control": "no-store",
- "Content-Security-Policy": "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:;",
- });
- res.end(renderHtml(service));
- } catch (error) {
- sendText(res, 500, `Internal error: ${String(error?.message || error)}`);
- }
- });
-
- service.server = server;
- service.port = await bindWithFallback(server);
- service.url = `http://${UI_HOST}:${service.port}`;
-
- setTimeout(() => {
- console.log(renderConfigAddressBanner(service.port));
- }, 1200);
- return service;
-}
-
-export function ensureConfigUiService(log = console) {
- if (!shouldStartConfigUi()) {
- return Promise.resolve(null);
- }
-
- const globalState = getGlobalState();
- if (globalState.promise) return globalState.promise;
-
- globalState.promise = createService(log)
- .then((service) => {
- globalState.service = service;
- return service;
- })
- .catch((error) => {
- globalState.service = null;
- globalState.promise = null;
- throw error;
- });
-
- return globalState.promise;
-}
-
-export async function closeConfigUiService(options = {}) {
- const globalState = getGlobalState();
-
- if (!globalState.service) {
- globalState.promise = null;
- return;
- }
-
- const { service } = globalState;
- globalState.service = null;
- globalState.promise = null;
-
- if (service?.server) {
- await new Promise((resolve) => {
- try {
- service.server.close(() => resolve());
- } catch {
- resolve();
- }
- });
- }
-}
-
-export async function runConfigUiChildProcess(log = console) {
- // no-op
-}
+ if (requestUrl.pathname === "/api/save" && req.method === "POST") {
+ let parsed = {};
+ try {
+ parsed = JSON.parse((await readRequestBody(req)) || "{}");
+ } catch {
+ sendText(res, 400, "Invalid JSON payload.");
+ return;
+ }
+ if (!isPlainObject(parsed)) {
+ sendText(res, 400, "Invalid JSON payload.");
+ return;
+ }
+ if (typeof parsed.enabled !== "boolean") {
+ sendText(res, 400, "Payload.enabled must be a boolean.");
+ return;
+ }
+ if (!isPlainObject(parsed.config)) {
+ sendText(res, 400, "Payload.config must be an object.");
+ return;
+ }
+
+ const nextState = writeGatewayConfig(profile, parsed);
+ service.stateCache = null;
+ service.heartbeatCache = null;
+ sendJson(res, 200, { ok: true, state: buildStatePayload({ ...service, profile: nextState.profile }) });
+ return;
+ }
+
+ // Legacy `/api/restart` has been entirely removed
+ sendText(res, 404, "Not found");
+ return;
+ }
+
+ if (requestUrl.pathname !== "/") {
+ sendText(res, 404, "Not found");
+ return;
+ }
+
+ res.writeHead(200, {
+ "Content-Type": "text/html; charset=utf-8",
+ "Cache-Control": "no-store",
+ "Content-Security-Policy": "default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:;",
+ });
+ res.end(renderHtml(service));
+ } catch (error) {
+ sendText(res, 500, `Internal error: ${String(error?.message || error)}`);
+ }
+ });
+
+ service.server = server;
+ service.port = await bindWithFallback(server);
+ service.url = `http://${UI_HOST}:${service.port}`;
+
+ setTimeout(() => {
+ console.log(renderConfigAddressBanner(service.port));
+ }, 1200);
+ return service;
+}
+
+export function ensureConfigUiService(log = console) {
+ if (!shouldStartConfigUi()) {
+ return Promise.resolve(null);
+ }
+
+ const globalState = getGlobalState();
+ if (globalState.promise) return globalState.promise;
+
+ globalState.promise = createService(log)
+ .then((service) => {
+ globalState.service = service;
+ return service;
+ })
+ .catch((error) => {
+ globalState.service = null;
+ globalState.promise = null;
+ throw error;
+ });
+
+ return globalState.promise;
+}
+
+export async function closeConfigUiService(options = {}) {
+ const globalState = getGlobalState();
+
+ if (!globalState.service) {
+ globalState.promise = null;
+ return;
+ }
+
+ const { service } = globalState;
+ globalState.service = null;
+ globalState.promise = null;
+
+ if (service?.server) {
+ await new Promise((resolve) => {
+ try {
+ service.server.close(() => resolve());
+ } catch {
+ resolve();
+ }
+ });
+ }
+}
+
+export async function runConfigUiChildProcess(log = console) {
+ // no-op
+}
diff --git a/lib/config-ui/app.css b/lib/config-ui/app.css
index 58ca635a1..f636d37d3 100644
--- a/lib/config-ui/app.css
+++ b/lib/config-ui/app.css
@@ -337,6 +337,99 @@ h1 {
color: var(--warn);
}
+.update-notice {
+ display: none;
+ margin-top: 16px;
+ padding: 14px 16px;
+ border: 1px solid rgba(181, 71, 8, 0.2);
+ border-radius: 18px;
+ background: rgba(181, 71, 8, 0.08);
+ color: var(--warn);
+}
+
+.update-notice.show {
+ display: block;
+}
+
+.update-notice.error {
+ border-color: rgba(180, 35, 24, 0.18);
+ background: rgba(180, 35, 24, 0.08);
+ color: var(--danger);
+}
+
+.update-notice.ok,
+.update-notice.info {
+ border-color: rgba(15, 118, 110, 0.18);
+ background: rgba(15, 118, 110, 0.08);
+ color: var(--accent2);
+}
+
+.update-check-button {
+ appearance: none;
+ min-height: 38px;
+ padding: 8px 14px;
+ border: 1px solid rgba(15, 23, 42, 0.08);
+ background: rgba(255, 255, 255, 0.74);
+ color: var(--strong);
+ font-weight: 700;
+ cursor: pointer;
+ transition: border-color 160ms ease, box-shadow 160ms ease, color 160ms ease, transform 160ms ease;
+}
+
+.update-check-button:hover {
+ border-color: rgba(15, 118, 110, 0.2);
+ color: var(--accent2);
+ transform: translateY(-1px);
+}
+
+.update-check-button:focus {
+ outline: none;
+ border-color: rgba(15, 118, 110, 0.34);
+ box-shadow: 0 0 0 4px rgba(15, 118, 110, 0.12);
+}
+
+.update-check-button:disabled {
+ cursor: wait;
+ opacity: 0.7;
+ transform: none;
+}
+
+.update-copy {
+ display: flex;
+ align-items: flex-start;
+ justify-content: space-between;
+ gap: 14px;
+}
+
+.update-title {
+ margin-bottom: 4px;
+ color: var(--strong);
+ font-weight: 800;
+}
+
+.update-body {
+ font-size: 13px;
+ line-height: 1.55;
+}
+
+.update-command {
+ display: block;
+ margin-top: 12px;
+ padding: 10px 12px;
+ border-radius: 14px;
+ background: rgba(255, 255, 255, 0.72);
+ color: var(--strong);
+ font-family: "Cascadia Code", "Consolas", monospace;
+ font-size: 12px;
+ line-height: 1.45;
+ overflow-x: auto;
+}
+
+.update-copy-button {
+ flex: 0 0 auto;
+ white-space: nowrap;
+}
+
.hero-actions {
display: grid;
gap: 12px;
@@ -609,6 +702,11 @@ h1 {
cursor: pointer;
}
+.inline-btn:disabled {
+ opacity: 0.58;
+ cursor: not-allowed;
+}
+
.error {
color: var(--danger);
font-size: 12px;
@@ -868,6 +966,10 @@ body.nav-collapsed .floating-nav {
padding: 18px;
}
+ .update-copy {
+ display: grid;
+ }
+
.card,
.panel {
padding: 18px;
diff --git a/lib/config-ui/app.js b/lib/config-ui/app.js
index 576bc6431..d5f68fa4c 100644
--- a/lib/config-ui/app.js
+++ b/lib/config-ui/app.js
@@ -6,6 +6,9 @@ const APP = {
const knownKeys = new Set(APP.fieldDefinitions.map((field) => field.key));
let remoteState = null;
+let updateStatus = null;
+let updateStatusChecked = false;
+let updateStatusLoading = false;
let draft = null;
let baselineSnapshot = "";
@@ -41,6 +44,8 @@ const elements = {
languageOptionZh: document.getElementById("languageOptionZh"),
statusRow: document.getElementById("statusRow"),
metaRow: document.getElementById("metaRow"),
+ updateCheckButton: document.getElementById("updateCheckButton") || document.createElement("button"),
+ updateNotice: document.getElementById("updateNotice"),
banner: document.getElementById("banner"),
floatingTools: document.getElementById("floatingTools"),
floatingNavLabel: document.getElementById("floatingNavLabel"),
@@ -128,6 +133,7 @@ const UI_TEXT = {
bannerAuthWaiting: "Config session expired. Waiting for the gateway to finish restarting before retrying...",
bannerAuthFailed: "Config session expired. Refresh this page to reconnect.",
bannerCopied: "The config file path was copied to your clipboard.",
+ bannerUpdateCommandCopied: "The update command was copied to your clipboard.",
bannerClipboardFailed: "Clipboard access failed. Copy the address from your browser bar instead.",
bannerSaved: "The plugin config was saved.",
bannerRestartLaunched: "Restart requested. Refresh this page in a few seconds if it does not recover automatically.",
@@ -135,12 +141,21 @@ const UI_TEXT = {
bannerWaitingBack: "Restart requested. Refresh this page in a few seconds if it does not recover automatically.",
bannerRestartRefreshHint: "Restart requested. Refresh this page in a few seconds if it does not recover automatically.",
pillPlugin: "Plugin",
+ pillVersion: "Version",
pillRuntime: "Runtime",
pillEntry: "Entry",
pillPageUrl: "Page URL",
- pillRevision: "Revision",
+ pillRevision: "Config revision",
pillConfigFile: "Config file",
pillInclude: "Include",
+ checkUpdates: "Check for updates",
+ checkingUpdates: "Checking...",
+ updateTitle: "Plugin update available",
+ updateBody: "Current version {current}; latest version {latest}. Update and restart with:",
+ updateCopyCommand: "Copy Update And Restart Command",
+ upToDateTitle: "Already up to date",
+ upToDateBody: "Current version {current} is the latest version.",
+ updateCheckFailed: "Version check failed: {error}",
pillEntryPresent: "present",
pillEntryMissing: "missing",
pillConfigFound: "found",
@@ -209,6 +224,7 @@ const UI_TEXT = {
bannerAuthWaiting: "配置页会话已过期,正在等待 Gateway 完成重启后再恢复...",
bannerAuthFailed: "配置页会话已过期,请刷新页面后重新连接。",
bannerCopied: "配置文件路径已复制到剪贴板。",
+ bannerUpdateCommandCopied: "更新命令已复制到剪贴板。",
bannerClipboardFailed: "复制失败,请直接从浏览器地址栏复制。",
bannerSaved: "插件配置已保存。",
bannerRestartLaunched: "已请求重启。如果页面没有自动恢复,请过几秒刷新重试。",
@@ -216,12 +232,21 @@ const UI_TEXT = {
bannerWaitingBack: "已请求重启。如果页面没有自动恢复,请过几秒刷新重试。",
bannerRestartRefreshHint: "已请求重启。如果页面没有自动恢复,请过几秒刷新重试。",
pillPlugin: "插件",
+ pillVersion: "版本",
pillRuntime: "运行时",
pillEntry: "配置项",
pillPageUrl: "页面地址",
- pillRevision: "版本标识",
+ pillRevision: "配置标识",
pillConfigFile: "配置文件",
pillInclude: "包含",
+ checkUpdates: "检查更新",
+ checkingUpdates: "检查中...",
+ updateTitle: "插件有新版本",
+ updateBody: "当前版本 {current};最新版本 {latest}。可使用以下命令更新并重启:",
+ updateCopyCommand: "复制更新并重启命令",
+ upToDateTitle: "已是最新版本",
+ upToDateBody: "当前版本 {current} 已经是最新版本。",
+ updateCheckFailed: "版本检查失败:{error}",
pillEntryPresent: "已存在",
pillEntryMissing: "不存在",
pillConfigFound: "已找到",
@@ -307,6 +332,14 @@ function uiText(key) {
return UI_TEXT[lang][key] ?? UI_TEXT.en[key] ?? key;
}
+function formatUiText(key, values) {
+ let text = uiText(key);
+ for (const [name, value] of Object.entries(values || {})) {
+ text = text.split(`{${name}}`).join(String(value ?? ""));
+ }
+ return text;
+}
+
function localizedGroup(group) {
const lang = getCurrentLanguage();
const translated = GROUP_TRANSLATIONS[lang]?.[group.id];
@@ -340,6 +373,10 @@ function applyLanguageUi() {
elements.copyPathButton.setAttribute("aria-label", uiText("copyPath"));
elements.copyPathButton.setAttribute("title", uiText("copyPath"));
elements.saveButton.textContent = uiText("save");
+ elements.updateCheckButton.id = "updateCheckButton";
+ elements.updateCheckButton.type = "button";
+ elements.updateCheckButton.className = "pill update-check-button";
+ updateCheckButtonUi();
elements.reloadButton.textContent = uiText("reload");
elements.overlayTitle.textContent = uiText("overlayTitle");
@@ -350,6 +387,22 @@ function applyLanguageUi() {
elements.languageOptionEn.textContent = "EN";
elements.languageOptionZh.textContent = "中文";
updateLanguageDropdownUi();
+ renderUpdateNotice();
+}
+
+function updateCheckButtonUi() {
+ if (!elements.updateCheckButton) return;
+ const version = remoteState?.pluginVersion || "unknown";
+ const action = updateStatusLoading ? uiText("checkingUpdates") : uiText("checkUpdates");
+ elements.updateCheckButton.innerHTML =
+ "" +
+ escapeHtml(uiText("pillVersion")) +
+ "" +
+ escapeHtml(version + " · " + action) +
+ "";
+ elements.updateCheckButton.setAttribute("aria-label", uiText("pillVersion") + " " + version + ", " + action);
+ elements.updateCheckButton.setAttribute("title", action);
+ elements.updateCheckButton.disabled = updateStatusLoading;
}
function updateFloatingNavToggleUi() {
@@ -722,11 +775,16 @@ function renderStatus() {
elements.statusRow.innerHTML = "";
elements.metaRow.innerHTML = "";
elements.pathBox.textContent = remoteState ? remoteState.configPath : "";
+ if (elements.updateCheckButton && !elements.updateCheckButton.parentElement) {
+ elements.updateCheckButton.remove();
+ }
if (!remoteState) return;
elements.statusRow.appendChild(
createPill(remoteState.enabled ? "ok" : "warn", uiText("pillPlugin"), remoteState.enabled ? uiText("enabled") : uiText("disabled")),
);
+ updateCheckButtonUi();
+ elements.statusRow.appendChild(elements.updateCheckButton);
elements.statusRow.appendChild(createPill("", uiText("pillRuntime"), remoteState.runtimeDisplayName));
elements.statusRow.appendChild(
createPill(remoteState.entryExists ? "" : "warn", uiText("pillEntry"), remoteState.entryExists ? uiText("pillEntryPresent") : uiText("pillEntryMissing")),
@@ -743,6 +801,70 @@ function renderStatus() {
}
}
+function renderUpdateNotice() {
+ if (!elements.updateNotice) return;
+
+ if (updateStatusLoading) {
+ elements.updateNotice.hidden = false;
+ elements.updateNotice.className = "update-notice info show";
+ elements.updateNotice.innerHTML =
+ '' +
+ escapeHtml(uiText("checkingUpdates")) +
+ "
";
+ return;
+ }
+
+ if (!updateStatusChecked || !updateStatus) {
+ elements.updateNotice.hidden = true;
+ elements.updateNotice.className = "update-notice";
+ elements.updateNotice.innerHTML = "";
+ return;
+ }
+
+ elements.updateNotice.hidden = false;
+ elements.updateNotice.className = "update-notice " + (updateStatus.ok === false ? "error show" : updateStatus.updateAvailable ? "show" : "ok show");
+
+ if (updateStatus.updateAvailable) {
+ const command = getUpdateAndRestartCommand(updateStatus);
+ elements.updateNotice.innerHTML =
+ '' +
+ '
' +
+ escapeHtml(uiText("updateTitle")) +
+ '
' +
+ escapeHtml(formatUiText("updateBody", { current: updateStatus.currentVersion, latest: updateStatus.latestVersion })) +
+ '
' +
+ '
" +
+ '' +
+ escapeHtml(command) +
+ "";
+
+ elements.updateNotice.querySelector(".update-copy-button")?.addEventListener("click", () => {
+ void copyUpdateCommand(command);
+ });
+ return;
+ }
+
+ if (updateStatus.ok === false) {
+ elements.updateNotice.innerHTML = escapeHtml(formatUiText("updateCheckFailed", { error: updateStatus.error || "Unknown error" }));
+ return;
+ }
+
+ elements.updateNotice.innerHTML =
+ '' +
+ escapeHtml(uiText("upToDateTitle")) +
+ '
' +
+ escapeHtml(formatUiText("upToDateBody", { current: updateStatus.currentVersion || remoteState?.pluginVersion || "unknown" })) +
+ "
";
+}
+
+function getUpdateAndRestartCommand(status) {
+ const cliName = status?.cliName || "openclaw";
+ const updateCommand = status?.updateCommand || `${cliName} plugins update memos-cloud-openclaw-plugin`;
+ return `${updateCommand} && ${cliName} gateway restart`;
+}
+
function renderEnabledField() {
const field = document.createElement("div");
field.className = "field";
@@ -1096,6 +1218,35 @@ async function checkHeartbeat() {
return response.json();
}
+async function loadUpdateStatus(options = {}) {
+ const manual = options.manual === true;
+ if (manual) {
+ updateStatusChecked = true;
+ updateStatusLoading = true;
+ updateCheckButtonUi();
+ renderUpdateNotice();
+ }
+
+ try {
+ updateStatus = await api("/api/update-status" + (options.force ? "?force=1" : ""));
+ updateStatusChecked = true;
+ } catch (error) {
+ if (error?.status === 403) {
+ void recoverFromAuthError();
+ return;
+ }
+ updateStatusChecked = true;
+ updateStatus = {
+ ok: false,
+ error: String(error.message || error),
+ };
+ } finally {
+ updateStatusLoading = false;
+ updateCheckButtonUi();
+ renderUpdateNotice();
+ }
+}
+
function handleHeartbeatState(heartbeat) {
if (!heartbeat || typeof heartbeat !== "object") return;
@@ -1240,6 +1391,16 @@ async function copyConfigPath() {
}
}
+async function copyUpdateCommand(command) {
+ if (!command) return;
+ try {
+ await navigator.clipboard.writeText(command);
+ setBanner("info", uiText("bannerUpdateCommandCopied"));
+ } catch {
+ setBanner("error", uiText("bannerClipboardFailed"));
+ }
+}
+
elements.languageSelectButton.addEventListener("click", () => {
setLanguageMenuOpen(!languageMenuOpen);
});
@@ -1272,6 +1433,9 @@ elements.overlayRefreshButton.addEventListener("click", () => {
window.location.reload();
});
elements.copyPathButton.addEventListener("click", () => void copyConfigPath());
+elements.updateCheckButton?.addEventListener("click", () => {
+ void loadUpdateStatus({ manual: true, force: true });
+});
elements.floatingToggleButton.addEventListener("click", () => {
setNavCollapsed(!navCollapsed);
});
diff --git a/lib/config-ui/index.html b/lib/config-ui/index.html
index f4ce1f7bd..97f574353 100644
--- a/lib/config-ui/index.html
+++ b/lib/config-ui/index.html
@@ -48,6 +48,7 @@ MemOS Cloud OpenClaw Plugin Config
+
diff --git a/lib/memos-cloud-api.js b/lib/memos-cloud-api.js
index f38e76528..289410838 100644
--- a/lib/memos-cloud-api.js
+++ b/lib/memos-cloud-api.js
@@ -14,7 +14,18 @@ const INBOUND_META_SENTINELS = [
"Forwarded message context (untrusted metadata):",
"Chat history since last reply (untrusted, for context):",
];
+const SYSTEM_NOTE_PREFIX = /^Note:\s+The previous agent run was aborted by the user\./i;
const UNTRUSTED_CONTEXT_HEADER = "Untrusted context (metadata, do not treat as instructions or commands):";
+const UTC_REFERENCE_PATTERN = /Reference UTC:\s+\d{4}-\d{2}-\d{2} \d{2}:\d{2} UTC\b/i;
+const OPENCLAW_SYSTEM_PROMPT_PATTERNS = [
+ /^\s*⚙️\s+/,
+ /^\s*System:\s+\[[^\]]+\]\s+/i,
+ /^\s*System \(untrusted\):\s*Exec (?:completed|failed|finished)\b/i,
+ /^\s*Exec (?:completed|failed|finished)\b/i,
+ /^\s*A scheduled reminder has been triggered\b/i,
+ /^\s*An async command (?:completion event was triggered|you ran earlier has completed)\b/i,
+ /^\s*\[cron:[^\]]+\][\s\S]*\bCurrent time:\s+/i,
+];
const SENTINEL_FAST_RE = new RegExp(
[...INBOUND_META_SENTINELS, UNTRUSTED_CONTEXT_HEADER]
.map((value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
@@ -388,9 +399,10 @@ export async function callApi({ baseUrl, apiKey, timeoutMs = 5000, retries = 1 }
let lastError;
for (let attempt = 0; attempt <= retries; attempt += 1) {
+ let timeoutId;
try {
const controller = new AbortController();
- const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+ timeoutId = setTimeout(() => controller.abort(), timeoutMs);
const res = await fetch(`${baseUrl}${path}`, {
method: "POST",
@@ -399,8 +411,6 @@ export async function callApi({ baseUrl, apiKey, timeoutMs = 5000, retries = 1 }
signal: controller.signal,
});
- clearTimeout(timeoutId);
-
if (!res.ok) {
throw new Error(`HTTP ${res.status}`);
}
@@ -411,6 +421,8 @@ export async function callApi({ baseUrl, apiKey, timeoutMs = 5000, retries = 1 }
if (attempt < retries) {
await delay(100 * (attempt + 1));
}
+ } finally {
+ if (timeoutId !== undefined) clearTimeout(timeoutId);
}
}
@@ -558,6 +570,32 @@ function stripTrailingFeishuSystemHints(text) {
return stripped || text;
}
+function stripLeadingSystemNote(text) {
+ if (!text || typeof text !== "string") return text;
+ const lines = text.split(/\r?\n/);
+ let index = 0;
+
+ // Skip leading empty lines
+ while (index < lines.length && lines[index].trim() === "") {
+ index += 1;
+ }
+
+ if (index >= lines.length) return "";
+
+ // Check if first non-empty line matches system note pattern
+ if (!SYSTEM_NOTE_PREFIX.test(lines[index])) return text;
+
+ // Skip the system note line
+ index += 1;
+
+ // Skip trailing empty lines after the note
+ while (index < lines.length && lines[index].trim() === "") {
+ index += 1;
+ }
+
+ return index === 0 ? text : lines.slice(index).join("\n");
+}
+
function stripLeadingFeishuSenderPrefix(text) {
if (!text || typeof text !== "string") return text;
// Feishu user IDs are typically "ou_
". Strip only if it is the leading line prefix.
@@ -598,15 +636,30 @@ export function sanitizeAddMessagePayload(payload) {
return nextPayload;
}
+export function isOpenClawSystemPrompt(text) {
+ if (!text || typeof text !== "string") return false;
+ const cleanedText = stripFeishuInjectedPrompt(text).trimStart();
+ if (!cleanedText) return false;
+ if (/^\s*\[cron:[^\]]+\]/i.test(cleanedText)) {
+ return UTC_REFERENCE_PATTERN.test(cleanedText);
+ }
+ if (/^\s*System:\s+\[[^\]]+\]\s+[\s\S]*\bA scheduled reminder has been triggered\b/i.test(cleanedText)) {
+ return true;
+ }
+ return OPENCLAW_SYSTEM_PROMPT_PATTERNS.some((pattern) => pattern.test(cleanedText));
+}
+
export function stripOpenClawInjectedPrefix(text) {
if (!text || typeof text !== "string") return "";
const cleanedText = stripFeishuInjectedPrompt(text);
+ if (isOpenClawSystemPrompt(cleanedText)) return "";
const markerIndex = cleanedText.lastIndexOf(USER_QUERY_MARKER);
const withoutRecallPrefix =
markerIndex === -1
? cleanedText
: cleanedText.slice(markerIndex + USER_QUERY_MARKER.length);
- const withoutInboundMetadata = stripLeadingInboundMetadata(withoutRecallPrefix).trimStart();
+ const withoutSystemNote = stripLeadingSystemNote(withoutRecallPrefix).trimStart();
+ const withoutInboundMetadata = stripLeadingInboundMetadata(withoutSystemNote).trimStart();
const withoutMessageIdHints = stripLeadingMessageIdHints(withoutInboundMetadata).trimStart();
const withoutEnvelope = stripLeadingEnvelope(withoutMessageIdHints).trimStart();
const withoutTrailingSystemHints = stripTrailingFeishuSystemHints(withoutEnvelope).trimStart();
@@ -675,13 +728,12 @@ function wrapCodeBlock(lines, options = {}) {
function buildMemorySections(data, options = {}) {
const memoryList = data?.memory_detail_list ?? [];
const preferenceList = data?.preference_detail_list ?? [];
+ const toolMemoryList = data?.tool_memory_detail_list ?? [];
+
+ const threshold = options.relativity ?? 0;
const memoryLines = memoryList
- .filter((item) => {
- const score = item?.relativity ?? 1;
- const threshold = options.relativity ?? 0;
- return score > threshold;
- })
+ .filter((item) => (item?.relativity ?? 1) > threshold)
.map((item) => {
const text = item?.memory_value || item?.memory_key || "";
return formatMemoryLine(item, text, options);
@@ -689,18 +741,22 @@ function buildMemorySections(data, options = {}) {
.filter(Boolean);
const preferenceLines = preferenceList
- .filter((item) => {
- const score = item?.relativity ?? 1;
- const threshold = options.relativity ?? 0;
- return score > threshold;
- })
+ .filter((item) => (item?.relativity ?? 1) > threshold)
.map((item) => {
const text = item?.preference || "";
return formatPreferenceLine(item, text, options);
})
.filter(Boolean);
- return { memoryLines, preferenceLines };
+ const toolMemoryLines = toolMemoryList
+ .filter((item) => (item?.relativity ?? 1) > threshold)
+ .map((item) => {
+ const text = item?.tool_value || "";
+ return formatMemoryLine(item, text, options);
+ })
+ .filter(Boolean);
+
+ return { memoryLines, preferenceLines, toolMemoryLines };
}
const STATIC_RECALL_SYSTEM_PROMPT = [
@@ -752,8 +808,8 @@ const STATIC_RECALL_SYSTEM_PROMPT = [
].join("\n");
function buildMemoryPrependBlock(data, options = {}) {
- const { memoryLines, preferenceLines } = buildMemorySections(data, options);
- const hasContent = memoryLines.length > 0 || preferenceLines.length > 0;
+ const { memoryLines, preferenceLines, toolMemoryLines } = buildMemorySections(data, options);
+ const hasContent = memoryLines.length > 0 || preferenceLines.length > 0 || toolMemoryLines.length > 0;
if (!hasContent) return "";
const memoriesBlock = [
@@ -761,6 +817,9 @@ function buildMemoryPrependBlock(data, options = {}) {
" ",
...memoryLines,
" ",
+ " ",
+ ...toolMemoryLines,
+ " ",
" ",
...preferenceLines,
" ",
diff --git a/lib/semver.js b/lib/semver.js
new file mode 100644
index 000000000..5d650cc08
--- /dev/null
+++ b/lib/semver.js
@@ -0,0 +1,91 @@
+const SEMVER_RE =
+ /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+const CORE_NUMBER_RE = /^(0|[1-9]\d*)$/;
+const NUMERIC_IDENTIFIER_RE = /^\d+$/;
+
+function compareString(a, b) {
+ if (a > b) return 1;
+ if (a < b) return -1;
+ return 0;
+}
+
+function parseIdentifierList(raw, { rejectLeadingZeroNumeric }) {
+ if (!raw) return [];
+
+ const identifiers = raw.split(".");
+ for (const identifier of identifiers) {
+ if (!identifier) return null;
+ if (rejectLeadingZeroNumeric && NUMERIC_IDENTIFIER_RE.test(identifier) && !CORE_NUMBER_RE.test(identifier)) {
+ return null;
+ }
+ }
+ return identifiers;
+}
+
+export function cleanVersion(raw) {
+ const value = String(raw || "").trim();
+ return value.startsWith("v") || value.startsWith("V") ? value.slice(1) : value;
+}
+
+export function parseSemver(version) {
+ const cleaned = cleanVersion(version);
+ const match = cleaned.match(SEMVER_RE);
+ if (!match) return null;
+ if (![match[1], match[2], match[3]].every((part) => CORE_NUMBER_RE.test(part))) return null;
+
+ const prerelease = parseIdentifierList(match[4] || "", { rejectLeadingZeroNumeric: true });
+ const build = parseIdentifierList(match[5] || "", { rejectLeadingZeroNumeric: false });
+ if (!prerelease || !build) return null;
+
+ return {
+ major: Number(match[1]),
+ minor: Number(match[2]),
+ patch: Number(match[3]),
+ prerelease,
+ build,
+ };
+}
+
+function comparePrereleaseIdentifier(a, b) {
+ const aNumeric = NUMERIC_IDENTIFIER_RE.test(a);
+ const bNumeric = NUMERIC_IDENTIFIER_RE.test(b);
+
+ if (aNumeric && bNumeric) {
+ const ai = BigInt(a);
+ const bi = BigInt(b);
+ if (ai > bi) return 1;
+ if (ai < bi) return -1;
+ return 0;
+ }
+ if (aNumeric) return -1;
+ if (bNumeric) return 1;
+ return compareString(a, b);
+}
+
+function comparePrerelease(a, b) {
+ if (a.length === 0 && b.length === 0) return 0;
+ if (a.length === 0) return 1;
+ if (b.length === 0) return -1;
+
+ const len = Math.max(a.length, b.length);
+ for (let i = 0; i < len; i++) {
+ if (a[i] === undefined) return -1;
+ if (b[i] === undefined) return 1;
+ const result = comparePrereleaseIdentifier(a[i], b[i]);
+ if (result !== 0) return result;
+ }
+ return 0;
+}
+
+export function compareSemver(a, b) {
+ const av = parseSemver(a);
+ const bv = parseSemver(b);
+ if (!av || !bv) return compareString(String(a), String(b));
+
+ for (const key of ["major", "minor", "patch"]) {
+ if (av[key] > bv[key]) return 1;
+ if (av[key] < bv[key]) return -1;
+ }
+
+ return comparePrerelease(av.prerelease, bv.prerelease);
+}
diff --git a/moltbot.plugin.json b/moltbot.plugin.json
index ffe06718d..2633a84fa 100644
--- a/moltbot.plugin.json
+++ b/moltbot.plugin.json
@@ -2,9 +2,14 @@
"id": "memos-cloud-openclaw-plugin",
"name": "MemOS Cloud OpenClaw Plugin",
"description": "MemOS Cloud recall + add memory via lifecycle hooks",
- "version": "0.1.12",
+ "version": "0.1.20",
"kind": "lifecycle",
"main": "./index.js",
+ "activation": {
+ "onCapabilities": [
+ "hook"
+ ]
+ },
"configSchema": {
"type": "object",
"properties": {
diff --git a/openclaw.plugin.json b/openclaw.plugin.json
index ffe06718d..2633a84fa 100644
--- a/openclaw.plugin.json
+++ b/openclaw.plugin.json
@@ -2,9 +2,14 @@
"id": "memos-cloud-openclaw-plugin",
"name": "MemOS Cloud OpenClaw Plugin",
"description": "MemOS Cloud recall + add memory via lifecycle hooks",
- "version": "0.1.12",
+ "version": "0.1.20",
"kind": "lifecycle",
"main": "./index.js",
+ "activation": {
+ "onCapabilities": [
+ "hook"
+ ]
+ },
"configSchema": {
"type": "object",
"properties": {
diff --git a/package.json b/package.json
index 498a667fb..6a81433a3 100644
--- a/package.json
+++ b/package.json
@@ -1,8 +1,18 @@
{
"name": "@memtensor/memos-cloud-openclaw-plugin",
- "version": "0.1.12",
+ "version": "0.1.20",
"description": "OpenClaw lifecycle plugin for MemOS Cloud (add + recall memory)",
+ "files": [
+ "index.js",
+ "lib",
+ "openclaw.plugin.json",
+ "moltbot.plugin.json",
+ "clawdbot.plugin.json",
+ "telemetry.credentials.json"
+ ],
"scripts": {
+ "test": "node --test .github/scripts/*.test.mjs test/*.test.mjs",
+ "generate-telemetry-credentials": "node scripts/generate-telemetry-credentials.cjs",
"sync-version": "node scripts/sync-version.js",
"version": "npm run sync-version && git add openclaw.plugin.json moltbot.plugin.json clawdbot.plugin.json",
"publish-beta": "npm publish --tag beta",
@@ -29,25 +39,16 @@
"author": "MemTensor",
"license": "MIT",
"openclaw": {
- "hooks": [
- "./index.js"
- ],
"extensions": [
"./index.js"
]
},
"clawdbot": {
- "hooks": [
- "./index.js"
- ],
"extensions": [
"./index.js"
]
},
"moltbot": {
- "hooks": [
- "./index.js"
- ],
"extensions": [
"./index.js"
]
diff --git a/scripts/generate-telemetry-credentials.cjs b/scripts/generate-telemetry-credentials.cjs
new file mode 100644
index 000000000..d9f451e06
--- /dev/null
+++ b/scripts/generate-telemetry-credentials.cjs
@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * Generate telemetry.credentials.json from environment variables.
+ *
+ * CI calls this before npm packaging so the published artifact can include
+ * telemetry credentials while the git repository stays free of cloud resource
+ * identifiers.
+ *
+ * Required env vars:
+ * MEMOS_ARMS_ENDPOINT - full ARMS RUM endpoint URL
+ * MEMOS_ARMS_PID - ARMS application PID
+ * MEMOS_ARMS_ENV - environment tag (default: "prod")
+ */
+
+const fs = require("node:fs");
+const path = require("node:path");
+
+const endpoint = String(process.env.MEMOS_ARMS_ENDPOINT || "").trim();
+const pid = String(process.env.MEMOS_ARMS_PID || "").trim();
+const env = String(process.env.MEMOS_ARMS_ENV || "prod").trim() || "prod";
+
+if (!endpoint && !pid) {
+ console.warn(
+ "[generate-telemetry-credentials] MEMOS_ARMS_ENDPOINT not set; " +
+ "skipping. RUM telemetry will be disabled in this build.",
+ );
+ process.exit(0);
+}
+
+if (!endpoint || !pid) {
+ console.error(
+ "[generate-telemetry-credentials] MEMOS_ARMS_ENDPOINT and MEMOS_ARMS_PID " +
+ "must be set together. Refusing to write partial telemetry credentials.",
+ );
+ process.exit(1);
+}
+
+let parsedEndpoint;
+try {
+ parsedEndpoint = new URL(endpoint);
+} catch {
+ console.error("[generate-telemetry-credentials] MEMOS_ARMS_ENDPOINT must be a valid URL.");
+ process.exit(1);
+}
+
+if (!["http:", "https:"].includes(parsedEndpoint.protocol)) {
+ console.error("[generate-telemetry-credentials] MEMOS_ARMS_ENDPOINT must use http or https.");
+ process.exit(1);
+}
+
+const out = path.resolve(__dirname, "..", "telemetry.credentials.json");
+fs.writeFileSync(out, JSON.stringify({ endpoint, pid, env }, null, 2) + "\n", "utf-8");
+console.log("[generate-telemetry-credentials] wrote " + out);
diff --git a/test/add-dedup.test.mjs b/test/add-dedup.test.mjs
new file mode 100644
index 000000000..6e730ac15
--- /dev/null
+++ b/test/add-dedup.test.mjs
@@ -0,0 +1,599 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import plugin from "../index.js";
+import { addMessage, buildConfig } from "../lib/memos-cloud-api.js";
+
+const createAgentEndHandler = (sessionKey, sessionId, pluginConfig = {}) => {
+ const hooks = new Map();
+ const logs = [];
+ plugin.register({
+ config: { hooks: { internal: { enabled: false } } },
+ logger: {
+ info: (message) => logs.push(message),
+ warn: (message) => logs.push(message),
+ },
+ pluginConfig: {
+ apiKey: "mpg-test",
+ baseUrl: "http://memos.test",
+ recallEnabled: false,
+ rumEnabled: false,
+ ...pluginConfig,
+ },
+ on: (name, handler) => hooks.set(name, handler),
+ registerHook: () => {},
+ });
+
+ return {
+ handler: hooks.get("agent_end"),
+ ctx: { sessionKey, sessionId },
+ logs,
+ };
+};
+
+const turn = (messages) => ({ success: true, messages });
+
+test("uses a 5 second MemOS API timeout by default", () => {
+ assert.equal(buildConfig({}).timeoutMs, 5_000);
+});
+
+test("add/message uses the configured retry count", async () => {
+ const originalFetch = globalThis.fetch;
+ let attempts = 0;
+ globalThis.fetch = async () => {
+ attempts += 1;
+ throw new Error("network down");
+ };
+
+ try {
+ await assert.rejects(
+ addMessage(
+ {
+ apiKey: "mpg-test",
+ baseUrl: "http://memos.test",
+ timeoutMs: 10,
+ retries: 1,
+ },
+ { messages: [{ role: "user", content: "hello" }] },
+ ),
+ );
+ assert.equal(attempts, 2);
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
+
+test("add/message can disable retries through configuration", async () => {
+ const originalFetch = globalThis.fetch;
+ let attempts = 0;
+ globalThis.fetch = async () => {
+ attempts += 1;
+ throw new Error("network down");
+ };
+
+ try {
+ await assert.rejects(
+ addMessage(
+ {
+ apiKey: "mpg-test",
+ baseUrl: "http://memos.test",
+ timeoutMs: 10,
+ retries: 0,
+ },
+ { messages: [{ role: "user", content: "hello" }] },
+ ),
+ );
+ assert.equal(attempts, 1);
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
+
+test("replayed agent_end writes the same logical turn only once", async () => {
+ const originalFetch = globalThis.fetch;
+ let adds = 0;
+ globalThis.fetch = async (_url, options) => {
+ if (_url.endsWith("/add/message")) adds += 1;
+ return new Response(JSON.stringify({ data: {} }), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+ };
+
+ try {
+ const { handler, ctx, logs } = createAgentEndHandler("agent:main:test:dedup-replay");
+ const event = {
+ ...turn([
+ { role: "user", content: "remember replay test" },
+ { role: "assistant", content: [{ type: "text", text: "noted" }] },
+ ]),
+ runId: "run-dedup-replay",
+ };
+
+ await handler(event, ctx);
+ await handler(event, ctx);
+
+ assert.equal(adds, 1);
+ assert.ok(logs.some((line) => line.includes("duplicate agent_end snapshot")));
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
+
+test("40 redeliveries do not exceed the configured two add attempts", async () => {
+ const originalFetch = globalThis.fetch;
+ let acceptedWrites = 0;
+ globalThis.fetch = async (_url, options) => {
+ acceptedWrites += 1;
+ return new Promise((_resolve, reject) => {
+ options.signal.addEventListener(
+ "abort",
+ () => reject(new DOMException("aborted", "AbortError")),
+ { once: true },
+ );
+ });
+ };
+
+ try {
+ const { handler, ctx } = createAgentEndHandler(
+ "agent:main:test:slow-redelivery",
+ "session-slow-redelivery",
+ { timeoutMs: 10 },
+ );
+ const messages = [
+ { role: "user", content: "remember slow redelivery", timestamp: 1_784_800_000_000 },
+ {
+ role: "assistant",
+ content: [{ type: "text", text: "noted" }],
+ timestamp: 1_784_800_000_100,
+ },
+ ];
+
+ for (let replay = 0; replay < 40; replay += 1) {
+ await handler({ ...turn(messages), runId: `run-redelivery-${replay}` }, ctx);
+ }
+
+ assert.equal(acceptedWrites, 2);
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
+
+test("replayed agent_end without a run id uses stable message ids", async () => {
+ const originalFetch = globalThis.fetch;
+ let adds = 0;
+ globalThis.fetch = async () => {
+ adds += 1;
+ return new Response(JSON.stringify({ data: {} }), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+ };
+
+ try {
+ const { handler, ctx } = createAgentEndHandler("agent:main:test:dedup-message-id");
+ const event = turn([
+ { role: "user", content: "remember replay test", id: "message-user-1" },
+ { role: "assistant", content: [{ type: "text", text: "noted" }] },
+ ]);
+
+ await handler(event, ctx);
+ await handler(event, ctx);
+
+ assert.equal(adds, 1);
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
+
+test("a changed message list is not deduplicated even when the run id is unchanged", async () => {
+ const originalFetch = globalThis.fetch;
+ let adds = 0;
+ globalThis.fetch = async () => {
+ adds += 1;
+ return new Response(JSON.stringify({ data: {} }), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+ };
+
+ try {
+ const { handler, ctx } = createAgentEndHandler("agent:main:test:changed-snapshot");
+ const userMessage = {
+ role: "user",
+ content: "same request",
+ idempotencyKey: "request-123",
+ };
+
+ await handler({
+ ...turn([
+ userMessage,
+ { role: "assistant", content: [{ type: "text", text: "first attempt" }] },
+ ]),
+ runId: "run-changed-snapshot",
+ }, ctx);
+ await handler({
+ ...turn([
+ userMessage,
+ { role: "assistant", content: [{ type: "text", text: "fallback attempt" }] },
+ ]),
+ runId: "run-changed-snapshot",
+ }, ctx);
+
+ assert.equal(adds, 2);
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
+
+test("a timed-out add is not resent beyond configured retries when the turn is replayed", async () => {
+ const originalFetch = globalThis.fetch;
+ let adds = 0;
+ globalThis.fetch = async () => {
+ adds += 1;
+ throw new DOMException("aborted", "AbortError");
+ };
+
+ try {
+ const { handler, ctx, logs } = createAgentEndHandler("agent:main:test:dedup-timeout");
+ const event = {
+ ...turn([
+ { role: "user", content: "remember timeout test" },
+ { role: "assistant", content: [{ type: "text", text: "noted" }] },
+ ]),
+ runId: "run-dedup-timeout",
+ };
+
+ await handler(event, ctx);
+ await handler(event, ctx);
+
+ assert.equal(adds, 2);
+ assert.ok(logs.some((line) => line.includes("add failed")));
+ assert.ok(logs.some((line) => line.includes("duplicate agent_end snapshot")));
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
+
+test("hook redelivery does not reset an exhausted retry budget", async () => {
+ const originalFetch = globalThis.fetch;
+ let attempts = 0;
+ globalThis.fetch = async () => {
+ attempts += 1;
+ throw new Error("connection refused");
+ };
+
+ try {
+ const { handler, ctx } = createAgentEndHandler(
+ "agent:main:test:definite-failure-redelivery",
+ "session-definite-failure-redelivery",
+ { retries: 0 },
+ );
+ const messages = [
+ { role: "user", content: "retry a definite failure", timestamp: 1_784_800_000_200 },
+ {
+ role: "assistant",
+ content: [{ type: "text", text: "noted" }],
+ timestamp: 1_784_800_000_300,
+ },
+ ];
+
+ for (let replay = 0; replay < 5; replay += 1) {
+ await handler({ ...turn(messages), runId: `run-definite-failure-${replay}` }, ctx);
+ }
+
+ assert.equal(attempts, 1);
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
+
+test("the same text in a later turn is still written", async () => {
+ const originalFetch = globalThis.fetch;
+ let adds = 0;
+ globalThis.fetch = async () => {
+ adds += 1;
+ return new Response(JSON.stringify({ data: {} }), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+ };
+
+ try {
+ const { handler, ctx } = createAgentEndHandler("agent:main:test:dedup-new-turn");
+ const first = [
+ { role: "user", content: "same text" },
+ { role: "assistant", content: [{ type: "text", text: "same reply" }] },
+ ];
+ const second = [
+ ...first,
+ { role: "user", content: "same text" },
+ { role: "assistant", content: [{ type: "text", text: "same reply" }] },
+ ];
+
+ await handler({ ...turn(first), runId: "run-first" }, ctx);
+ await handler({ ...turn(second), runId: "run-second" }, ctx);
+
+ assert.equal(adds, 2);
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
+
+test("last-turn replay is deduplicated when older history changes", async () => {
+ const originalFetch = globalThis.fetch;
+ let adds = 0;
+ globalThis.fetch = async () => {
+ adds += 1;
+ return new Response(JSON.stringify({ data: {} }), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+ };
+
+ try {
+ const { handler, ctx } = createAgentEndHandler(
+ "agent:main:test:changed-history-same-turn",
+ "session-changed-history-same-turn",
+ );
+ const currentTurn = [
+ {
+ role: "user",
+ content: "capture this turn",
+ idempotencyKey: "message-current-user",
+ timestamp: 1_784_800_010_000,
+ },
+ {
+ role: "assistant",
+ content: [{ type: "text", text: "captured" }],
+ timestamp: 1_784_800_010_100,
+ },
+ ];
+
+ await handler({
+ ...turn([
+ { role: "user", content: "old history", timestamp: 1_784_800_009_000 },
+ { role: "assistant", content: [{ type: "text", text: "old reply" }] },
+ ...currentTurn,
+ ]),
+ runId: "run-history-first",
+ }, ctx);
+ await handler({
+ ...turn([
+ { role: "user", content: "rewritten history", timestamp: 1_784_800_009_500 },
+ { role: "assistant", content: [{ type: "text", text: "rewritten reply" }] },
+ ...currentTurn,
+ ]),
+ runId: "run-history-replay",
+ }, ctx);
+
+ assert.equal(adds, 1);
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
+
+test("full-session capture treats changed history as a new snapshot", async () => {
+ const originalFetch = globalThis.fetch;
+ let adds = 0;
+ globalThis.fetch = async () => {
+ adds += 1;
+ return new Response(JSON.stringify({ data: {} }), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+ };
+
+ try {
+ const { handler, ctx } = createAgentEndHandler(
+ "agent:main:test:full-session-history",
+ "session-full-session-history",
+ { captureStrategy: "full_session" },
+ );
+ const currentTurn = [
+ {
+ role: "user",
+ content: "current turn",
+ idempotencyKey: "full-session-current-user",
+ timestamp: 1_784_800_020_000,
+ },
+ {
+ role: "assistant",
+ content: [{ type: "text", text: "current reply" }],
+ timestamp: 1_784_800_020_100,
+ },
+ ];
+
+ await handler({
+ ...turn([
+ { role: "user", content: "first history", timestamp: 1_784_800_019_000 },
+ { role: "assistant", content: [{ type: "text", text: "first history reply" }] },
+ ...currentTurn,
+ ]),
+ runId: "run-full-session-first",
+ }, ctx);
+ await handler({
+ ...turn([
+ { role: "user", content: "changed history", timestamp: 1_784_800_019_500 },
+ { role: "assistant", content: [{ type: "text", text: "changed history reply" }] },
+ ...currentTurn,
+ ]),
+ runId: "run-full-session-second",
+ }, ctx);
+
+ assert.equal(adds, 2);
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
+
+test("an older snapshot replayed after the session advances is still deduplicated", async () => {
+ const originalFetch = globalThis.fetch;
+ let adds = 0;
+ globalThis.fetch = async () => {
+ adds += 1;
+ return new Response(JSON.stringify({ data: {} }), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+ };
+
+ try {
+ const { handler, ctx } = createAgentEndHandler("agent:main:test:out-of-order-replay");
+ const first = [
+ { role: "user", content: "first turn", timestamp: 1_784_800_000_400 },
+ {
+ role: "assistant",
+ content: [{ type: "text", text: "first reply" }],
+ timestamp: 1_784_800_000_500,
+ },
+ ];
+ const second = [
+ ...first,
+ { role: "user", content: "second turn", timestamp: 1_784_800_000_600 },
+ {
+ role: "assistant",
+ content: [{ type: "text", text: "second reply" }],
+ timestamp: 1_784_800_000_700,
+ },
+ ];
+
+ await handler({ ...turn(first), runId: "run-old-first" }, ctx);
+ await handler({ ...turn(second), runId: "run-old-second" }, ctx);
+ await handler({ ...turn(first), runId: "run-old-redelivery" }, ctx);
+
+ assert.equal(adds, 2);
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
+
+test("the same current-turn content with new message timestamps is still written", async () => {
+ const originalFetch = globalThis.fetch;
+ let adds = 0;
+ globalThis.fetch = async () => {
+ adds += 1;
+ return new Response(JSON.stringify({ data: {} }), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+ };
+
+ try {
+ const { handler, ctx } = createAgentEndHandler("agent:main:test:same-content-new-message");
+ const first = [
+ { role: "user", content: "same text", timestamp: 1_784_800_001_000 },
+ {
+ role: "assistant",
+ content: [{ type: "text", text: "same reply" }],
+ timestamp: 1_784_800_001_100,
+ },
+ ];
+ const second = [
+ { role: "user", content: "same text", timestamp: 1_784_800_002_000 },
+ {
+ role: "assistant",
+ content: [{ type: "text", text: "same reply" }],
+ timestamp: 1_784_800_002_100,
+ },
+ ];
+
+ await handler({ ...turn(first), runId: "run-same-content-first" }, ctx);
+ await handler({ ...turn(second), runId: "run-same-content-second" }, ctx);
+
+ assert.equal(adds, 2);
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
+
+test("the same event snapshot in a new conversation is still written", async () => {
+ const originalFetch = globalThis.fetch;
+ let adds = 0;
+ globalThis.fetch = async () => {
+ adds += 1;
+ return new Response(JSON.stringify({ data: {} }), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+ };
+
+ try {
+ const first = createAgentEndHandler("agent:main:test:new-conversation", "session-1");
+ const second = createAgentEndHandler("agent:main:test:new-conversation", "session-2");
+ const event = {
+ ...turn([
+ { role: "user", content: "same text" },
+ { role: "assistant", content: [{ type: "text", text: "same reply" }] },
+ ]),
+ runId: "run-shared",
+ };
+
+ await first.handler(event, first.ctx);
+ await second.handler(event, second.ctx);
+
+ assert.equal(adds, 2);
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
+
+test("events without a reliable run or message identity are not deduplicated", async () => {
+ const originalFetch = globalThis.fetch;
+ let adds = 0;
+ globalThis.fetch = async () => {
+ adds += 1;
+ return new Response(JSON.stringify({ data: {} }), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+ };
+
+ try {
+ const { handler, ctx } = createAgentEndHandler("agent:main:test:no-event-identity");
+ const event = turn([
+ { role: "user", content: "same text" },
+ { role: "assistant", content: [{ type: "text", text: "same reply" }] },
+ ]);
+
+ await handler(event, ctx);
+ await handler(event, ctx);
+
+ assert.equal(adds, 2);
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
+
+test("a configured conversation id is not treated as a reliable OpenClaw session identity", async () => {
+ const originalFetch = globalThis.fetch;
+ let adds = 0;
+ globalThis.fetch = async () => {
+ adds += 1;
+ return new Response(JSON.stringify({ data: {} }), {
+ status: 200,
+ headers: { "Content-Type": "application/json" },
+ });
+ };
+
+ try {
+ const { handler, ctx } = createAgentEndHandler(undefined, undefined, {
+ conversationId: "shared-configured-conversation",
+ });
+ const event = turn([
+ { role: "user", content: "same text", timestamp: 1_784_800_003_000 },
+ {
+ role: "assistant",
+ content: [{ type: "text", text: "same reply" }],
+ timestamp: 1_784_800_003_100,
+ },
+ ]);
+
+ await handler(event, ctx);
+ await handler(event, ctx);
+
+ assert.equal(adds, 2);
+ } finally {
+ globalThis.fetch = originalFetch;
+ }
+});
diff --git a/test/check-update-version.test.mjs b/test/check-update-version.test.mjs
new file mode 100644
index 000000000..5093ba948
--- /dev/null
+++ b/test/check-update-version.test.mjs
@@ -0,0 +1,12 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { compareVersions } from "../lib/check-update.js";
+
+test("update checks compare prerelease versions with SemVer precedence", () => {
+ assert.equal(compareVersions("1.0.0-beta.10", "1.0.0-beta.9") > 0, true);
+ assert.equal(compareVersions("1.0.0-beta.20", "1.0.0-beta.19") > 0, true);
+ assert.equal(compareVersions("1.0.0-beta.1", "1.0.0-beta.alpha") < 0, true);
+ assert.equal(compareVersions("1.0.0", "1.0.0-rc.1") > 0, true);
+ assert.equal(compareVersions("1.0.0+build.2", "1.0.0+build.1"), 0);
+});
diff --git a/test/direct-session-user-id.test.mjs b/test/direct-session-user-id.test.mjs
index cc38e70e1..3049dfd21 100644
--- a/test/direct-session-user-id.test.mjs
+++ b/test/direct-session-user-id.test.mjs
@@ -92,3 +92,34 @@ test("buildAddMessagePayload keeps configured userId for non-direct chats", () =
const payload = buildAddMessagePayload(cfg, [{ role: "user", content: "hi" }], ctx);
assert.equal(payload.user_id, "openclaw-user");
});
+
+test("MEMOS_SOURCE is correctly appended with platform suffix", () => {
+ const expectedSource = (() => {
+ const platform = process.platform;
+ if (platform === "win32") return "openclaw_win";
+ if (platform === "darwin") return "openclaw_mac";
+ if (platform === "linux") return "openclaw_linux";
+ return "openclaw";
+ })();
+ const cfg = {
+ userId: "openclaw-user",
+ useDirectSessionUserId: false,
+ queryPrefix: "",
+ maxQueryChars: 0,
+ recallGlobal: true,
+ knowledgebaseIds: [],
+ memoryLimitNumber: 6,
+ includePreference: true,
+ preferenceLimitNumber: 6,
+ includeToolMemory: false,
+ toolMemoryLimitNumber: 0,
+ relativity: 0.45,
+ multiAgentMode: false,
+ };
+ const ctx = {};
+ const searchPayload = buildSearchPayload(cfg, "query", ctx);
+ assert.equal(searchPayload.source, expectedSource);
+
+ const addPayload = buildAddMessagePayload(cfg, [], ctx);
+ assert.equal(addPayload.source, expectedSource);
+});
diff --git a/test/query-strip.test.mjs b/test/query-strip.test.mjs
index 8e5b97544..d388e0844 100644
--- a/test/query-strip.test.mjs
+++ b/test/query-strip.test.mjs
@@ -4,6 +4,7 @@ import assert from "node:assert/strict";
import {
USER_QUERY_MARKER,
formatPromptBlockFromData,
+ isOpenClawSystemPrompt,
sanitizeAddMessagePayload,
sanitizeSearchPayload,
stripOpenClawInjectedPrefix,
@@ -209,6 +210,62 @@ test("strips leading Feishu sender prefix after message_id hints", () => {
assert.equal(stripOpenClawInjectedPrefix(input), "我叫什么名字");
});
+test("detects OpenClaw cron agent turn prompts", () => {
+ const input = [
+ '[cron:1710b7c4-18fa-4097-8338-5d89beac91f9 Create empty JSON on desktop] Create an empty JSON file at the user\'s desktop. Run this exact shell command: New-Item -Path "$env:USERPROFILE\\Desktop\\empty.json" -ItemType File -Force. Confirm the file was created.',
+ "Current time: Monday, July 6th, 2026 - 15:00 (Asia/Shanghai)",
+ "Reference UTC: 2026-07-06 07:00 UTC",
+ "",
+ "Use the message tool if you need to notify the user directly with an explicit target. If you do not send directly, your final plain-text reply will be delivered automatically.",
+ ].join("\n");
+
+ assert.equal(isOpenClawSystemPrompt(input), true);
+ assert.equal(stripOpenClawInjectedPrefix(input), "");
+});
+
+test("detects OpenClaw cron prompts when whitespace is flattened", () => {
+ const input =
+ '[cron:4b2eed75-d129-4846-a54d-0ab4f4333088 polymarket-monitor] 查询上海(Shanghai)当前天气。运行命令:curl -s "wttr.in/Shanghai?format=3",然后用简洁的一句话报告当前上海天气(温度和天气状况)。 Current time: Monday, July 6th, 2026 - 15:05 (Asia/Shanghai) Reference UTC: 2026-07-06 07:05 UTC Use the message tool if you need to notify the user directly with an explicit target. If you do not send directly, your final plain-text reply will be delivered automatically.';
+
+ assert.equal(isOpenClawSystemPrompt(input), true);
+ assert.equal(stripOpenClawInjectedPrefix(input), "");
+});
+
+test("detects OpenClaw scheduled reminder system prompts", () => {
+ const input = [
+ 'System: [2026-07-06 15:13:04 GMT+8] Scheduled task firing: run the Windows batch script now. Use the exec tool to run "C:\\Users\\lee\\Desktop\\test.bat" and report the exit code and any output back to the user.',
+ "",
+ "A scheduled reminder has been triggered. The reminder content is:",
+ "",
+ 'Scheduled task firing: run the Windows batch script now. Use the exec tool to run "C:\\Users\\lee\\Desktop\\test.bat" and report the exit code and any output back to the user.',
+ "",
+ "Handle this reminder internally. Do not relay it to the user unless explicitly requested.",
+ "Current time: Monday, July 6th, 2026 - 15:13 (Asia/Shanghai)",
+ "Reference UTC: 2026-07-06 07:13 UTC",
+ ].join("\n");
+
+ assert.equal(isOpenClawSystemPrompt(input), true);
+ assert.equal(stripOpenClawInjectedPrefix(input), "");
+});
+
+test("detects OpenClaw exec completion system prompts", () => {
+ const samples = [
+ "Exec completed (abc12345, code 0) :: /path/to/result.json",
+ "System (untrusted): Exec completed (code 0) :: /path/to/result.json",
+ ];
+
+ for (const input of samples) {
+ assert.equal(isOpenClawSystemPrompt(input), true);
+ assert.equal(stripOpenClawInjectedPrefix(input), "");
+ }
+});
+
+test("does not treat ordinary cron mentions as system prompts", () => {
+ const input = "请解释这段文本:[cron:abc job] but no OpenClaw time marker";
+ assert.equal(isOpenClawSystemPrompt(input), false);
+ assert.equal(stripOpenClawInjectedPrefix(input), input);
+});
+
test("strips message id hints and standard OpenClaw channel envelope", () => {
const input = [
"[message_id: 123456]",
@@ -308,6 +365,22 @@ test("sanitizes search payload query before API call", () => {
});
});
+test("empties search payload for OpenClaw cron prompts", () => {
+ const payload = {
+ query: [
+ "[cron:abc123 daily-check] Run the scheduled check.",
+ "Current time: Monday, July 6th, 2026 - 15:05 (Asia/Shanghai)",
+ "Reference UTC: 2026-07-06 07:05 UTC",
+ ].join("\n"),
+ source: "openclaw",
+ };
+
+ assert.deepEqual(sanitizeSearchPayload(payload), {
+ ...payload,
+ query: "",
+ });
+});
+
test("sanitizes only user messages in add payload", () => {
const payload = {
messages: [
diff --git a/test/recall-hook-registration.test.mjs b/test/recall-hook-registration.test.mjs
new file mode 100644
index 000000000..2be1a9f35
--- /dev/null
+++ b/test/recall-hook-registration.test.mjs
@@ -0,0 +1,56 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import plugin from "../index.js";
+
+const createApi = (hostVersion) => {
+ const registeredHooks = [];
+ const originalArgv1 = process.argv[1];
+ process.argv[1] = `C:\\Users\\lee\\AppData\\Local\\pnpm\\global\\5\\.pnpm\\openclaw@${hostVersion}\\node_modules\\openclaw\\openclaw.mjs`;
+
+ const api = {
+ config: { hooks: { internal: { enabled: false } } },
+ logger: {},
+ pluginConfig: {
+ apiKey: "mpg-test",
+ recallEnabled: false,
+ addEnabled: false,
+ },
+ on: (hookName, handler) => {
+ registeredHooks.push({ hookName, handler });
+ },
+ registerHook: () => {},
+ };
+
+ return {
+ api,
+ registeredHooks,
+ restore: () => {
+ process.argv[1] = originalArgv1;
+ },
+ };
+};
+
+test("registers before_prompt_build on OpenClaw hosts that support the phase-specific hook", () => {
+ const { api, registeredHooks, restore } = createApi("2026.5.7");
+ try {
+ plugin.register(api);
+ } finally {
+ restore();
+ }
+
+ assert.ok(registeredHooks.some((hook) => hook.hookName === "before_prompt_build"));
+ assert.ok(!registeredHooks.some((hook) => hook.hookName === "before_agent_start"));
+});
+
+test("falls back to before_agent_start on older OpenClaw hosts", () => {
+ const { api, registeredHooks, restore } = createApi("2026.4.26");
+ try {
+ plugin.register(api);
+ } finally {
+ restore();
+ }
+
+ assert.ok(registeredHooks.some((hook) => hook.hookName === "before_agent_start"));
+ assert.ok(!registeredHooks.some((hook) => hook.hookName === "before_prompt_build"));
+});