diff --git a/apps/MemOS-Cloud-OpenClaw-Plugin/.github/release-notes/README.md b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/release-notes/README.md new file mode 100644 index 000000000..c8302bc9a --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/draft-cloud-plugin-release-notes.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/draft-cloud-plugin-release-notes.mjs new file mode 100644 index 000000000..30d9286ff --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/draft-cloud-plugin-release-notes.test.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/draft-cloud-plugin-release-notes.test.mjs new file mode 100644 index 000000000..7bf8dc23c --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/resolve-auto-release.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/resolve-auto-release.mjs new file mode 100644 index 000000000..2273c53ab --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/resolve-auto-release.test.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/resolve-auto-release.test.mjs new file mode 100644 index 000000000..ff0b0ba5e --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/retry.sh b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/retry.sh new file mode 100755 index 000000000..233b7fe24 --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/retry.test.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/retry.test.mjs new file mode 100644 index 000000000..032cc5020 --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/validate-github-release-inventory.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/validate-github-release-inventory.mjs new file mode 100644 index 000000000..051b97b59 --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/validate-github-release-inventory.test.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/validate-github-release-inventory.test.mjs new file mode 100644 index 000000000..5a50178b2 --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/validate-release-confirmation.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/validate-release-confirmation.mjs new file mode 100644 index 000000000..e0b5b1509 --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/validate-release-confirmation.test.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/validate-release-confirmation.test.mjs new file mode 100644 index 000000000..b1fbe5991 --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/validate-release-source-version.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/validate-release-source-version.mjs new file mode 100644 index 000000000..e00266e5f --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/validate-release-source-version.test.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/validate-release-source-version.test.mjs new file mode 100644 index 000000000..7f4900c7c --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/wait-for-npm-release.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/wait-for-npm-release.mjs new file mode 100644 index 000000000..dab99acce --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/wait-for-npm-release.test.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/scripts/wait-for-npm-release.test.mjs new file mode 100644 index 000000000..b6217baab --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/workflows/historical-dry-run.yml b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/workflows/historical-dry-run.yml new file mode 100644 index 000000000..3e106c3f6 --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/workflows/post-merge-dry-run.yml b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/workflows/post-merge-dry-run.yml new file mode 100644 index 000000000..5f1c7c862 --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/workflows/pre-merge-dry-run.yml b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/workflows/pre-merge-dry-run.yml new file mode 100644 index 000000000..0b1202b13 --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/workflows/release-dry-run.yml b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/workflows/release-dry-run.yml new file mode 100644 index 000000000..0c5885677 --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/workflows/release.yml b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/workflows/release.yml new file mode 100644 index 000000000..e0542f914 --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.github/workflows/workflow-contract-lint.yml b/apps/MemOS-Cloud-OpenClaw-Plugin/.github/workflows/workflow-contract-lint.yml new file mode 100644 index 000000000..e9a7839cc --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.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/apps/MemOS-Cloud-OpenClaw-Plugin/.gitignore b/apps/MemOS-Cloud-OpenClaw-Plugin/.gitignore index 0aa2d3677..9c65f2ab9 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/.gitignore +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/.gitignore @@ -5,6 +5,7 @@ node_modules .env .env.* .memos_arms_uid +telemetry.credentials.json # NPM .npmrc diff --git a/apps/MemOS-Cloud-OpenClaw-Plugin/HOOK.md b/apps/MemOS-Cloud-OpenClaw-Plugin/HOOK.md deleted file mode 100644 index 842385824..000000000 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/README.md b/apps/MemOS-Cloud-OpenClaw-Plugin/README.md index 90c45a095..4bdde16b2 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/README.md +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/README_ZH.md b/apps/MemOS-Cloud-OpenClaw-Plugin/README_ZH.md index d923831ea..08e6ad134 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/README_ZH.md +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/clawdbot.plugin.json b/apps/MemOS-Cloud-OpenClaw-Plugin/clawdbot.plugin.json index ffe06718d..2633a84fa 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/clawdbot.plugin.json +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/docs/release-owner-runbook.md b/apps/MemOS-Cloud-OpenClaw-Plugin/docs/release-owner-runbook.md new file mode 100644 index 000000000..5f3d681cd --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/index.js b/apps/MemOS-Cloud-OpenClaw-Plugin/index.js index 65be37bee..72f7edb53 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/index.js +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/lib/arms-reporter.js b/apps/MemOS-Cloud-OpenClaw-Plugin/lib/arms-reporter.js index d5421b147..260de9629 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/lib/arms-reporter.js +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/lib/check-update.js b/apps/MemOS-Cloud-OpenClaw-Plugin/lib/check-update.js index 906fdf314..b16f008c7 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/lib/check-update.js +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui-server.js b/apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui-server.js index 675237675..dba421413 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui-server.js +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui/app.css b/apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui/app.css index 58ca635a1..f636d37d3 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui/app.css +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui/app.js b/apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui/app.js index 576bc6431..d5f68fa4c 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui/app.js +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui/index.html b/apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui/index.html index f4ce1f7bd..97f574353 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui/index.html +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/lib/config-ui/index.html @@ -48,6 +48,7 @@

MemOS Cloud OpenClaw Plugin Config

+
diff --git a/apps/MemOS-Cloud-OpenClaw-Plugin/lib/memos-cloud-api.js b/apps/MemOS-Cloud-OpenClaw-Plugin/lib/memos-cloud-api.js index f38e76528..289410838 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/lib/memos-cloud-api.js +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/lib/semver.js b/apps/MemOS-Cloud-OpenClaw-Plugin/lib/semver.js new file mode 100644 index 000000000..5d650cc08 --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/moltbot.plugin.json b/apps/MemOS-Cloud-OpenClaw-Plugin/moltbot.plugin.json index ffe06718d..2633a84fa 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/moltbot.plugin.json +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/openclaw.plugin.json b/apps/MemOS-Cloud-OpenClaw-Plugin/openclaw.plugin.json index ffe06718d..2633a84fa 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/openclaw.plugin.json +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/package.json b/apps/MemOS-Cloud-OpenClaw-Plugin/package.json index 498a667fb..6a81433a3 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/package.json +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/scripts/generate-telemetry-credentials.cjs b/apps/MemOS-Cloud-OpenClaw-Plugin/scripts/generate-telemetry-credentials.cjs new file mode 100644 index 000000000..d9f451e06 --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/test/add-dedup.test.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/test/add-dedup.test.mjs new file mode 100644 index 000000000..6e730ac15 --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/test/check-update-version.test.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/test/check-update-version.test.mjs new file mode 100644 index 000000000..5093ba948 --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/test/direct-session-user-id.test.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/test/direct-session-user-id.test.mjs index cc38e70e1..3049dfd21 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/test/direct-session-user-id.test.mjs +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/test/query-strip.test.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/test/query-strip.test.mjs index 8e5b97544..d388e0844 100644 --- a/apps/MemOS-Cloud-OpenClaw-Plugin/test/query-strip.test.mjs +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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/apps/MemOS-Cloud-OpenClaw-Plugin/test/recall-hook-registration.test.mjs b/apps/MemOS-Cloud-OpenClaw-Plugin/test/recall-hook-registration.test.mjs new file mode 100644 index 000000000..2be1a9f35 --- /dev/null +++ b/apps/MemOS-Cloud-OpenClaw-Plugin/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")); +});