diff --git a/.github/scripts/publish-local-plugin.sh b/.github/scripts/publish-local-plugin.sh index 96ea77a69..976b70a12 100755 --- a/.github/scripts/publish-local-plugin.sh +++ b/.github/scripts/publish-local-plugin.sh @@ -6,6 +6,12 @@ set -euo pipefail : "${RELEASE_VERSION:?RELEASE_VERSION is required.}" : "${RELEASE_TAG:?RELEASE_TAG is required.}" : "${NPM_DIST_TAG:?NPM_DIST_TAG is required.}" +: "${RELEASE_TARBALL:?RELEASE_TARBALL is required.}" + +if [ ! -s "${RELEASE_TARBALL}" ]; then + echo "::error::RELEASE_TARBALL does not exist or is empty: ${RELEASE_TARBALL}" + exit 2 +fi npm_visibility_attempts="${NPM_VISIBILITY_ATTEMPTS:-10}" npm_ambiguous_visibility_attempts="${NPM_AMBIGUOUS_VISIBILITY_ATTEMPTS:-3}" @@ -112,7 +118,59 @@ remote_tag_exists() { done } +verify_published_package() { + local verify_directory="${RUNNER_TEMP}/memos-local-plugin-registry-verification" + local verify_json="${verify_directory}/npm-pack.json" + local verify_filename + local verify_tarball + local package_version + local manifest_version + + mkdir -p "${verify_directory}" + bash "${script_directory}/retry.sh" --label "download published npm package" -- \ + bash -euo pipefail -c 'npm pack "$1" --json --silent --pack-destination "$2" > "$3"' \ + _ "${PACKAGE_NAME}@${RELEASE_VERSION}" "${verify_directory}" "${verify_json}" + verify_filename="$( + node -e ' + const fs = require("node:fs"); + const raw = fs.readFileSync(process.argv[1], "utf8"); + const jsonStart = raw.match(/^\[/m); + if (!jsonStart || jsonStart.index === undefined) { + throw new Error("npm pack output did not contain a JSON report"); + } + const report = JSON.parse(raw.slice(jsonStart.index)); + if (!Array.isArray(report) || report.length !== 1 || !report[0].filename) { + throw new Error("npm pack did not report exactly one registry tarball"); + } + fs.writeFileSync(process.argv[1], `${JSON.stringify(report, null, 2)}\n`); + process.stdout.write(report[0].filename); + ' "${verify_json}" + )" + verify_tarball="${verify_directory}/${verify_filename}" + package_version="$( + tar -xOf "${verify_tarball}" package/package.json \ + | node -e ' + const fs = require("node:fs"); + process.stdout.write(JSON.parse(fs.readFileSync(0, "utf8")).version); + ' + )" + manifest_version="$( + tar -xOf "${verify_tarball}" package/adapters/hermes/plugin.yaml \ + | awk '$1 == "version:" { print $2; exit }' + )" + if [ "${package_version}" != "${RELEASE_VERSION}" ]; then + echo "::error::Published package.json version ${package_version} does not match ${RELEASE_VERSION}." + exit 1 + fi + if [ "${manifest_version}" != "${RELEASE_VERSION}" ]; then + echo "::error::Published Hermes manifest version ${manifest_version} does not match ${RELEASE_VERSION}." + exit 1 + fi +} + +published_version_visible=false if npm_version_exists; then + published_version_visible=true if remote_tag_exists "${RELEASE_TAG}"; then echo "${PACKAGE_NAME}@${RELEASE_VERSION} and ${RELEASE_TAG} already exist; treating this as an idempotent rerun." elif [ "${RECOVER_EXISTING_NPM_RELEASE:-false}" = "true" ]; then @@ -128,7 +186,7 @@ else for attempt in 1 2 3; do set +e - npm publish --access public --tag "${NPM_DIST_TAG}" >"${attempt_directory}/${attempt}.log" 2>&1 + npm publish "${RELEASE_TARBALL}" --access public --tag "${NPM_DIST_TAG}" >"${attempt_directory}/${attempt}.log" 2>&1 publish_status=$? set -e sed -n '1,160p' "${attempt_directory}/${attempt}.log" @@ -159,7 +217,9 @@ else fi done - if ! wait_for_npm_version "${npm_visibility_attempts}"; then + if wait_for_npm_version "${npm_visibility_attempts}"; then + published_version_visible=true + else if [ "${publish_accepted}" = "true" ]; then echo "::warning::npm publish succeeded, but ${PACKAGE_NAME}@${RELEASE_VERSION} is not visible after propagation retries; continuing with tag, Release, and PR creation." else @@ -168,3 +228,9 @@ else fi fi fi + +if [ "${published_version_visible}" = "true" ]; then + verify_published_package +else + echo "::warning::Skipping registry tarball verification until ${PACKAGE_NAME}@${RELEASE_VERSION} becomes visible." +fi diff --git a/.github/scripts/publish-local-plugin.test.mjs b/.github/scripts/publish-local-plugin.test.mjs index b8c62a655..76e1121a8 100644 --- a/.github/scripts/publish-local-plugin.test.mjs +++ b/.github/scripts/publish-local-plugin.test.mjs @@ -37,6 +37,7 @@ case "\${1:-}" in ;; publish) increment_counter publish >/dev/null + printf '%s' "\${2:-}" > "\${NPM_MOCK_STATE_DIR}/published-argument" if [ "\${NPM_MOCK_SCENARIO}" = "publish-fails" ]; then echo "npm error code E500" >&2 exit 1 @@ -44,6 +45,35 @@ case "\${1:-}" in echo "+ \${PACKAGE_NAME}@\${RELEASE_VERSION}" exit 0 ;; + pack) + increment_counter pack >/dev/null + destination="" + while [ "$#" -gt 0 ]; do + if [ "$1" = "--pack-destination" ]; then + destination="$2" + shift 2 + continue + fi + shift + done + if [ -z "\${destination}" ]; then + echo "Missing --pack-destination" >&2 + exit 2 + fi + pack_root="\${NPM_MOCK_STATE_DIR}/pack-root" + filename="memtensor-memos-local-plugin-\${RELEASE_VERSION}.tgz" + rm -rf "\${pack_root}" + mkdir -p "\${pack_root}/package/adapters/hermes" "\${destination}" + printf '{"name":"%s","version":"%s"}\\n' \ + "\${PACKAGE_NAME}" "\${RELEASE_VERSION}" \ + > "\${pack_root}/package/package.json" + printf 'version: %s\\n' \ + "\${NPM_MOCK_MANIFEST_VERSION:-\${RELEASE_VERSION}}" \ + > "\${pack_root}/package/adapters/hermes/plugin.yaml" + tar -czf "\${destination}/\${filename}" -C "\${pack_root}" package + printf '[{"filename":"%s"}]\\n' "\${filename}" + exit 0 + ;; *) echo "Unexpected npm command: $*" >&2 exit 2 @@ -67,8 +97,10 @@ function runScenario(scenario, overrides = {}) { mkdirSync(stateDirectory); const npmPath = join(binDirectory, "npm"); + const releaseTarball = join(fixtureDirectory, "release.tgz"); writeFileSync(npmPath, mockNpm, "utf8"); chmodSync(npmPath, 0o755); + writeFileSync(releaseTarball, "release fixture", "utf8"); const result = spawnSync("bash", [publishScript], { cwd: fixtureDirectory, @@ -81,6 +113,7 @@ function runScenario(scenario, overrides = {}) { RELEASE_VERSION: "2.0.12", RELEASE_TAG: "memos-local-plugin-v2.0.12", NPM_DIST_TAG: "latest", + RELEASE_TARBALL: releaseTarball, RECOVER_EXISTING_NPM_RELEASE: "false", DOC_AGENT_RELEASE_FAILURE_URL: "", DOC_AGENT_RELEASE_NOTES_DRAFT_TOKEN: "", @@ -97,6 +130,14 @@ function runScenario(scenario, overrides = {}) { ...result, viewCount: readCounter(stateDirectory, "view"), publishCount: readCounter(stateDirectory, "publish"), + packCount: readCounter(stateDirectory, "pack"), + publishedArgument: (() => { + try { + return readFileSync(join(stateDirectory, "published-argument"), "utf8"); + } catch { + return ""; + } + })(), }; rmSync(fixtureDirectory, { recursive: true, force: true }); return outcome; @@ -108,6 +149,8 @@ test("waits through two post-publish 404 responses before the version becomes vi assert.equal(result.status, 0, result.stderr); assert.equal(result.publishCount, 1); assert.equal(result.viewCount, 4); + assert.equal(result.packCount, 1); + assert.match(result.publishedArgument, /release\.tgz$/); assert.match(result.stdout, /became visible on attempt 3/); }); @@ -117,7 +160,9 @@ test("continues release metadata creation when publish succeeds but visibility r assert.equal(result.status, 0, result.stderr); assert.equal(result.publishCount, 1); assert.equal(result.viewCount, 4); + assert.equal(result.packCount, 0); assert.match(result.stdout, /npm publish succeeded.*continuing with tag, Release, and PR creation/s); + assert.match(result.stdout, /Skipping registry tarball verification/); }); test("fails when publish fails and the requested version remains absent", () => { @@ -127,3 +172,16 @@ test("fails when publish fails and the requested version remains absent", () => assert.equal(result.publishCount, 3); assert.match(result.stdout + result.stderr, /npm publish failed after three attempts/); }); + +test("fails when the published Hermes manifest version differs", () => { + const result = runScenario("eventually-visible", { + NPM_MOCK_MANIFEST_VERSION: "2.0.11", + }); + + assert.notEqual(result.status, 0); + assert.equal(result.packCount, 1); + assert.match( + result.stdout + result.stderr, + /Published Hermes manifest version 2\.0\.11 does not match 2\.0\.12/, + ); +}); diff --git a/.github/workflows/memos-local-plugin-post-merge-dry-run.yml b/.github/workflows/memos-local-plugin-post-merge-dry-run.yml index 905911065..ce0ff32b9 100644 --- a/.github/workflows/memos-local-plugin-post-merge-dry-run.yml +++ b/.github/workflows/memos-local-plugin-post-merge-dry-run.yml @@ -12,17 +12,51 @@ on: - ".github/scripts/publish-local-plugin.sh" - ".github/scripts/publish-local-plugin.test.mjs" - ".github/scripts/retry.sh" + - "apps/memos-local-plugin/package.json" + - "apps/memos-local-plugin/package-lock.json" + - "apps/memos-local-plugin/adapters/hermes/plugin.yaml" + - "apps/memos-local-plugin/scripts/sync-hermes-version.cjs" + - "apps/memos-local-plugin/tests/unit/install/hermes-version-sync.test.ts" permissions: contents: write pull-requests: write jobs: + prepare-version: + if: ${{ github.repository == 'MemTensor/MemOS' }} + runs-on: ubuntu-latest + outputs: + version: ${{ steps.version.outputs.version }} + steps: + - uses: actions/checkout@v4 + + - name: Generate dry-run prerelease version + id: version + working-directory: apps/memos-local-plugin + env: + RUN_NUMBER: ${{ github.run_number }} + run: | + version="$( + node -e ' + const current = require("./package.json").version; + const match = current.match(/^(\d+)\.(\d+)\.(\d+)/); + if (!match) { + throw new Error(`Unsupported package version: ${current}`); + } + process.stdout.write( + `${match[1]}.${match[2]}.${Number(match[3]) + 1}-ci.${process.env.RUN_NUMBER}`, + ); + ' + )" + echo "version=${version}" >> "${GITHUB_OUTPUT}" + dry-run: if: ${{ github.repository == 'MemTensor/MemOS' }} + needs: prepare-version uses: ./.github/workflows/memos-local-plugin-publish.yml with: - version: "2.0.10" + version: ${{ needs.prepare-version.outputs.version }} tag: "latest" git_ref: "" release_notes: "" diff --git a/.github/workflows/memos-local-plugin-publish.yml b/.github/workflows/memos-local-plugin-publish.yml index 4b1a4c9e2..e5101c762 100644 --- a/.github/workflows/memos-local-plugin-publish.yml +++ b/.github/workflows/memos-local-plugin-publish.yml @@ -185,12 +185,67 @@ jobs: exit 1 fi bash ../../.github/scripts/retry.sh --label "bump package version" -- npm version "${RELEASE_VERSION}" --no-git-tag-version --allow-same-version + npm run sync:hermes-version + npm run check:hermes-version - name: Validate and build package + env: + RELEASE_VERSION: ${{ inputs.version }} run: | + set -euo pipefail bash ../../.github/scripts/retry.sh --attempts 2 --label "npm run lint" -- npm run lint bash ../../.github/scripts/retry.sh --attempts 2 --label "npm test" -- npm test - bash ../../.github/scripts/retry.sh --label "npm pack dry-run" -- bash -euo pipefail -c 'npm pack --dry-run --json > "${RUNNER_TEMP}/memos-local-plugin-pack.json"' + release_dir="${RUNNER_TEMP}/memos-local-plugin-release" + pack_json="${RUNNER_TEMP}/memos-local-plugin-pack.json" + mkdir -p "${release_dir}" + bash ../../.github/scripts/retry.sh --label "npm pack" -- \ + bash -euo pipefail -c 'npm pack --json --silent --pack-destination "$1" > "$2"' \ + _ "${release_dir}" "${pack_json}" + + pack_filename="$( + node -e ' + const fs = require("node:fs"); + const raw = fs.readFileSync(process.argv[1], "utf8"); + const jsonStart = raw.match(/^\[/m); + if (!jsonStart || jsonStart.index === undefined) { + throw new Error("npm pack output did not contain a JSON report"); + } + const report = JSON.parse(raw.slice(jsonStart.index)); + if (!Array.isArray(report) || report.length !== 1 || !report[0].filename) { + throw new Error("npm pack did not report exactly one tarball"); + } + fs.writeFileSync(process.argv[1], `${JSON.stringify(report, null, 2)}\n`); + process.stdout.write(report[0].filename); + ' "${pack_json}" + )" + release_tarball="${release_dir}/${pack_filename}" + test -s "${release_tarball}" + + package_version="$( + tar -xOf "${release_tarball}" package/package.json \ + | node -e ' + const fs = require("node:fs"); + process.stdout.write(JSON.parse(fs.readFileSync(0, "utf8")).version); + ' + )" + manifest_version="$( + tar -xOf "${release_tarball}" package/adapters/hermes/plugin.yaml \ + | awk '$1 == "version:" { print $2; exit }' + )" + if [ "${package_version}" != "${RELEASE_VERSION}" ]; then + echo "::error::Tarball package.json version ${package_version} does not match ${RELEASE_VERSION}." + exit 1 + fi + if [ "${manifest_version}" != "${RELEASE_VERSION}" ]; then + echo "::error::Tarball Hermes manifest version ${manifest_version} does not match ${RELEASE_VERSION}." + exit 1 + fi + + sha256sum "${release_tarball}" > "${release_tarball}.sha256" + { + echo "RELEASE_TARBALL=${release_tarball}" + echo "RELEASE_TARBALL_SHA256=${release_tarball}.sha256" + } >> "${GITHUB_ENV}" - name: Draft GitHub Release notes id: release_notes @@ -232,6 +287,8 @@ jobs: cp "${RELEASE_NOTES_FILE}" "${inspection_dir}/release-notes.md" cp "${RUNNER_TEMP}/memos-local-plugin-pack.json" "${inspection_dir}/npm-pack.json" + cp "${RELEASE_TARBALL}" "${inspection_dir}/" + cp "${RELEASE_TARBALL_SHA256}" "${inspection_dir}/" if [ -n "${EVIDENCE_FILE}" ] && [ -s "${EVIDENCE_FILE}" ]; then cp "${EVIDENCE_FILE}" "${inspection_dir}/evidence.json" fi @@ -420,7 +477,7 @@ jobs: --base "${DEFAULT_BRANCH}" \ --head "${release_branch}" \ --title "${release_title}" \ - --body "Bumps apps/memos-local-plugin/package.json for the published npm release ${RELEASE_VERSION}." + --body "Synchronizes package and Hermes metadata for the published npm release ${RELEASE_VERSION}." status=$? set -e if [ "${status}" = 0 ]; then @@ -438,7 +495,10 @@ jobs: done } - git add apps/memos-local-plugin/package.json apps/memos-local-plugin/package-lock.json + git add \ + apps/memos-local-plugin/package.json \ + apps/memos-local-plugin/package-lock.json \ + apps/memos-local-plugin/adapters/hermes/plugin.yaml created_release_commit=false if ! git diff --staged --quiet; then git commit -m "${release_title}" diff --git a/apps/memos-local-plugin/adapters/hermes/README.md b/apps/memos-local-plugin/adapters/hermes/README.md index 1bd98cd0a..9f05755c9 100644 --- a/apps/memos-local-plugin/adapters/hermes/README.md +++ b/apps/memos-local-plugin/adapters/hermes/README.md @@ -10,18 +10,20 @@ Hermes is a Python-based agent. The core of `memos-local-plugin` is written in TypeScript and runs on Node.js. This adapter bridges the two: ``` -┌──────────────────────────┐ stdio JSON-RPC 2.0 ┌─────────────────────┐ -│ Hermes Python process │ ─────────────────────────────▶ │ node bridge.cts │ -│ │ │ │ -│ MemTensorProvider ──────┼───── turn.start / turn.end ───▶│ MemoryCore (core/) │ -│ │◀──── events.notify ───────────│ │ -│ │◀──── logs.forward ────────────│ │ -└──────────────────────────┘ └─────────────────────┘ +┌────────────────────────────────────┐ stdio JSON-RPC 2.0 ┌─────────────────────┐ +│ Hermes Python process │ │ one Node bridge │ +│ │ │ │ +│ Provider(session A) ─┐ │ │ MemoryCore (core/) │ +│ Provider(session B) ─┼─ shared ────┼───────────────────────────▶│ │ +│ Provider(session C) ─┘ runtime │◀── events / host LLM RPC ─│ │ +└────────────────────────────────────┘ └─────────────────────┘ ``` -The Python side is **stateless** — every `MemoryProvider` method is a thin -proxy that translates to a JSON-RPC call. All algorithm logic (L1/L2/L3, -skills, retrieval, feedback, decision repair) lives in the shared TS core. +Each Python provider owns its logical session/episode/turn state. The +process-scoped `SharedBridgeRuntime` owns the physical Node subprocess, +keepalive, reconnect generation, and host callback dispatch. All algorithm +logic (L1/L2/L3, skills, retrieval, feedback, decision repair) remains in the +shared TypeScript core. ## Protocol surface @@ -29,16 +31,14 @@ The adapter calls the following methods on the bridge: | Hermes hook | JSON-RPC method | Purpose | | ---------------------------- | ---------------------- | ------------------------------------------------- | -| `initialize(session_id)` | `session.open`, | Open a session + default episode in core. | -| | `episode.open` | | +| `initialize(session_id)` | `session.open` | Open one logical session in the shared core. | | `prefetch(query)` | `turn.start` | Retrieve context for injection before model call. | -| `sync_turn(user, assistant)` | `turn.end` (deferred) | Persist a completed turn — flushed async. | -| `handle_tool_call("memory_*")`| `memory.search`, | Explicit memory tools exposed to the model. | +| `sync_turn(user, assistant)` | `turn.end` | Persist a completed turn synchronously. | +| `handle_tool_call("memory_*")` | `memory.search`, | Explicit memory tools exposed to the model. | | | `memory.timeline` | | | `submit_feedback(...)` | `feedback.submit` | Record explicit user feedback. | -| `on_session_end` | `episode.close`, | Close the session and flush pending data. | -| | `session.close` | | -| `shutdown` | (transport close) | Kill the subprocess cleanly. | +| `on_session_end` | `session.close` | Close only this logical session. | +| `shutdown` | (lease release) | Release this provider without killing the bridge. | ## File layout @@ -49,6 +49,7 @@ adapters/hermes/ └── memos_provider/ ├── __init__.py # MemTensorProvider — the MemoryProvider impl ├── bridge_client.py # JSON-RPC 2.0 stdio client + thread-safe dispatch + ├── shared_bridge_runtime.py # Process-scoped ownership, reconnect, hook routing └── daemon_manager.py # Spawn lifecycle + probe for Node availability ``` @@ -60,11 +61,25 @@ startup. If Node.js is unavailable the provider reports provider. No deployment artifacts from this adapter are required on machines that can't run Node. -Otherwise the provider spawns `node --experimental-strip-types -bridge.cts --agent=hermes` as a subprocess during `initialize()` and -communicates over its stdin/stdout pipes. The subprocess exits when the -provider's stdin closes (on `shutdown()`), yielding clean lifecycle -semantics. +Otherwise the first provider in a Hermes process starts the packaged bridge +(`dist/bridge.mjs` when available) with `--agent=hermes --no-viewer`. +Subsequent providers acquire leases on the same bridge. The bridge stays alive +until process exit, while each provider independently opens and closes its +logical `sessionId`. + +The runtime uses one keepalive loop and a generation-checked reconnect lock. +After a bridge restart, a provider lazily reopens its own logical session before +issuing its next request. Long-running in-flight capture/retrieval calls suppress +keepalive probes so a health timeout cannot kill healthy work. + +For emergency rollback, set: + +```sh +MEMOS_HERMES_BRIDGE_MODE=legacy +``` + +This restores the old per-provider lifecycle and should be used only for +diagnosis because it is unsafe when several Hermes sessions coexist. ## Why a subprocess instead of a long-lived daemon? @@ -76,9 +91,14 @@ That approach required: - authentication between Python and Node, - and duplicate log pipelines. -The stdio model gets each of those for free from the OS process model. -Hermes' session lifetime is already bounded, so the cost of one -`node`-spawn per Hermes session is negligible in practice. +The stdio model gets each of those for free from the OS process model. Sharing +one stdio bridge inside each Hermes process also prevents separate providers +from repeatedly replacing each other's subprocesses while preserving the +reverse `host.llm.complete` callback. + +This is process-scoped, not machine-scoped. A future daemon transport can share +one MemoryCore across multiple Hermes OS processes, but it must retain a +bidirectional callback channel before replacing stdio. ## Testing @@ -86,4 +106,5 @@ Python unit tests live under `apps/memos-local-plugin/tests/python/`. They run against a mocked bridge (no Node subprocess) to exercise the Hermes-side state machine. Integration tests that exercise the full stack boot a real bridge subprocess; see -`tests/python/integration/test_hermes_roundtrip.py`. +`tests/python/test_shared_bridge_runtime.py` and the Hermes protocol/persistence +tests under `tests/unit/adapters/`. diff --git a/apps/memos-local-plugin/adapters/hermes/install.hermes.sh b/apps/memos-local-plugin/adapters/hermes/install.hermes.sh index b1c6d8789..a010c68d0 100755 --- a/apps/memos-local-plugin/adapters/hermes/install.hermes.sh +++ b/apps/memos-local-plugin/adapters/hermes/install.hermes.sh @@ -26,6 +26,18 @@ warn() { printf "\033[1;33m[install:hermes]\033[0m %s\n" "$*" >&2; } cd "$PREFIX" +# Keep the Hermes manifest aligned with the npm package before exposing the +# provider directory to the host. Older local source layouts may not contain +# the helper, so retain the packaged manifest as a compatibility fallback. +VERSION_SYNC_SCRIPT="$PREFIX/scripts/sync-hermes-version.cjs" +if command -v node >/dev/null 2>&1 && [[ -f "$VERSION_SYNC_SCRIPT" ]]; then + node "$VERSION_SYNC_SCRIPT" "$PREFIX" >/dev/null +else + warn "Hermes version sync helper unavailable; using packaged plugin.yaml as-is." +fi +cp "$PREFIX/adapters/hermes/plugin.yaml" \ + "$PREFIX/adapters/hermes/memos_provider/plugin.yaml" + # ── 1. node_modules ─────────────────────────────────────────────────────────── if command -v npm >/dev/null 2>&1; then command -v node > .memos-node-bin diff --git a/apps/memos-local-plugin/adapters/hermes/memos_provider/__init__.py b/apps/memos-local-plugin/adapters/hermes/memos_provider/__init__.py index 0ff76cf89..027f21ba0 100644 --- a/apps/memos-local-plugin/adapters/hermes/memos_provider/__init__.py +++ b/apps/memos-local-plugin/adapters/hermes/memos_provider/__init__.py @@ -27,20 +27,20 @@ | Hermes hook | Our action | | -------------------- | --------------------------------------------- | -| ``initialize`` | spawn bridge; open session + episode | +| ``initialize`` | acquire shared bridge; open logical session | | ``on_turn_start`` | record turn count; stash message | | ``prefetch`` | ``turn.start`` RPC → Tier 1+2+3 retrieval | -| ``queue_prefetch`` | background thread: prefetch + flush pending | -| ``sync_turn`` | queue a deferred ``turn.end`` RPC | -| ``on_session_end`` | flush pending + close episode + close session | +| ``queue_prefetch`` | no-op; real prefetch runs before the turn | +| ``sync_turn`` | persist a synchronous ``turn.end`` RPC | +| ``on_session_end`` | close this logical session | | ``on_pre_compress`` | extract a short memory summary | | ``on_delegation`` | record a subagent outcome as a trace | | ``get_tool_schemas`` | expose memory, skill, and environment tools | | ``handle_tool_call`` | dispatch to MemOS JSON-RPC tool methods | -| ``shutdown`` | close bridge | +| ``shutdown`` | release provider lease | -Threading: all JSON-RPC calls are synchronous. ``queue_prefetch`` runs on -a daemon thread the provider owns. +Threading: all JSON-RPC calls are synchronous. One process-scoped runtime +owns bridge keepalive and reconnect; providers retain per-session state. """ from __future__ import annotations @@ -71,6 +71,11 @@ ensure_viewer_daemon, kill_zombie_bridges, ) +from shared_bridge_runtime import ( # noqa: E402 + HERMES_HOOK_DISPATCHER, + SHARED_BRIDGE_REGISTRY, + SharedBridgeLease, +) try: # pragma: no cover — host-provided base class, absent in unit tests @@ -88,12 +93,85 @@ class MemoryProvider: # type: ignore[no-redef] logger = logging.getLogger(__name__) PLUGIN_ID = "memos-local-hermes" -PLUGIN_VERSION = "2.0.0-beta.1" + + +def _read_plugin_version() -> str: + """Read the npm package version that owns this Hermes adapter.""" + package_json = _PLUGIN_DIR.parents[2] / "package.json" + try: + payload = json.loads(package_json.read_text(encoding="utf-8")) + except (OSError, ValueError, TypeError): + return "dev" + version = payload.get("version") + return version.strip() if isinstance(version, str) and version.strip() else "dev" + + +PLUGIN_VERSION = _read_plugin_version() _TOOL_FAILURE_REPAIR_HINT = ( "This tool has failed multiple times in a row. You may want to call " "`memos_search` for relevant past experience before deciding what to do next." ) _TOOL_FAILURE_HINT_THRESHOLD = 3 +_COMPRESSION_CONTEXT_MAX_CHARS = 6_000 + + +def _shared_bridge_enabled() -> bool: + """Use the safe process-scoped bridge unless an operator opts out.""" + mode = os.environ.get("MEMOS_HERMES_BRIDGE_MODE", "shared").strip().lower() + return mode not in {"legacy", "per_provider", "disabled", "false", "0"} + + +def _resolved_memos_runtime_home() -> Path: + """Mirror the Node resolver closely enough to isolate distinct databases.""" + memos_home = os.environ.get("MEMOS_HOME", "").strip() + if memos_home: + return Path(memos_home).expanduser().resolve() + config_file = os.environ.get("MEMOS_CONFIG_FILE", "").strip() + if config_file: + return Path(config_file).expanduser().resolve().parent + return (Path.home() / ".hermes" / "memos-plugin").resolve() + + +def _memos_runtime_env_snapshot(runtime_home: Path | None = None) -> dict[str, str]: + """Freeze the environment inputs that select a MemOS data home.""" + memos_home = os.environ.get("MEMOS_HOME", "").strip() + if memos_home: + resolved_home = runtime_home or Path(memos_home).expanduser().resolve() + return {"MEMOS_HOME": str(resolved_home)} + config_file = os.environ.get("MEMOS_CONFIG_FILE", "").strip() + if config_file: + return { + "MEMOS_HOME": "", + "MEMOS_CONFIG_FILE": str(Path(config_file).expanduser().resolve()), + } + return { + "MEMOS_HOME": "", + "MEMOS_CONFIG_FILE": "", + "HOME": os.environ.get("HOME", "").strip() or str(Path.home()), + } + + +def _shared_bridge_runtime_key(runtime_home: Path | None = None) -> tuple[str, ...]: + """Use the data home as the authoritative shared-runtime boundary.""" + resolved_home = runtime_home or _resolved_memos_runtime_home() + return (str(resolved_home), "hermes", "stdio") + + +def _prepare_shared_bridge(*, cleanup_legacy_zombies: bool = False) -> None: + """Prepare bridge/viewer state without crossing data-home boundaries.""" + ensure_bridge_running() + if cleanup_legacy_zombies: + # The legacy scanner cannot distinguish data homes. Shared runtimes + # instead rely on the Python scoped singleton and the CJS scoped PID + # guard so one healthy home is never reaped while another starts. + with contextlib.suppress(Exception): + zombies = kill_zombie_bridges() + if zombies: + logger.info("MemOS: killed %d zombie bridge(s)", zombies) + try: + ensure_viewer_daemon() + except Exception as err: + logger.warning("MemOS: viewer daemon check failed — %s", err) def _long_rpc_timeout_default() -> float: @@ -277,8 +355,13 @@ class MemTensorProvider(MemoryProvider): """ def __init__(self) -> None: - self._bridge: MemosBridgeClient | None = None + self._bridge: MemosBridgeClient | SharedBridgeLease | None = None + self._shared_bridge = _shared_bridge_enabled() + self._bridge_generation = 0 self._reconnect_lock = threading.Lock() + self._session_open_lock = threading.Lock() + self._runtime_home: Path | None = None + self._runtime_env: dict[str, str] = {} self._session_id: str = "" self._episode_id: str = "" self._hermes_home: str = "" @@ -292,6 +375,12 @@ def __init__(self) -> None: self._prefetch_lock = threading.Lock() self._prefetch_result: str = "" self._prefetch_thread: threading.Thread | None = None + # Exact memory context injected by the most recent real prefetch. + # Compression hooks only read this cache; they must never call the + # lifecycle-mutating `turn.start` RPC. + self._state_lock = threading.Lock() + self._last_injected_context: str = "" + self._active_turn_key: str = "" # Tool calls accumulated via the Hermes `post_tool_call` plugin # hook — flushed alongside user/assistant text in `sync_turn`. self._tool_calls: list[dict[str, Any]] = [] @@ -305,6 +394,8 @@ def __init__(self) -> None: self._hook_registered = False self._bridge_keepalive_stop = threading.Event() self._bridge_keepalive_thread: threading.Thread | None = None + self._session_close_thread: threading.Thread | None = None + self._session_close_requested_for = "" # Hermes runs background memory/skill reviewers by forking an agent and # appending a synthetic user turn. That turn is instruction plumbing, # not a human utterance, so it must not become a MemOS trace. @@ -334,104 +425,89 @@ def initialize(self, session_id: str, **kwargs: Any) -> None: # type: ignore[ov them so the bridge can resolve the right `~/.hermes/memos-plugin/` and log the originating channel. - We open the session here but NOT the episode — episode creation - is deferred to ``_ensure_episode()`` (called from the first - ``on_turn_start``), so the actual user message can be passed as - the episode's initial text instead of a generic placeholder. - - Idempotency (issue #1910): the host occasionally re-enters - ``initialize()`` on the same provider instance (plugin reload, - session restart). Without the close-before-spawn guard below the - previous ``MemosBridgeClient`` would be replaced by reference - only, orphaning the previous Node subprocess and accumulating - a fresh ``bridge.cjs`` per turn. + Shared mode (the default) acquires a lightweight lease on one + process-scoped Node bridge. Each provider still owns its logical + session/episode state. ``MEMOS_HERMES_BRIDGE_MODE=legacy`` retains + the old per-provider bridge as a one-release rollback path. """ - # Hermes can call `initialize()` multiple times across a single - # parent process (e.g. on reconnect or a new session). Each call - # spawns a fresh `MemosBridgeClient` (and therefore a new - # `--no-viewer` Node subprocess); if we simply overwrite - # `self._bridge` we leak the old subprocess — its parent stays - # alive so `_reap_stale_headless_bridges_locked` never collects - # it. Close the previous bridge first, mirroring the safe pattern - # already used by `_reconnect_bridge()`. See #1927. previous_bridge = self._bridge if previous_bridge is not None: old_pid = getattr(previous_bridge, "pid", "?") logger.info( - "MemOS: closing previous bridge (pid=%s) before re-init", + "MemOS: releasing previous bridge handle (pid=%s) before re-init", old_pid, ) + self.on_session_end([]) + close_thread = self._session_close_thread + if close_thread is not None and close_thread.is_alive(): + close_thread.join(timeout=5.5) with contextlib.suppress(Exception): previous_bridge.close() self._bridge = None + self._bridge_generation = 0 self._session_id = session_id or self._session_id + self._session_close_requested_for = "" + self._bridge_keepalive_stop.clear() + with self._state_lock: + self._last_injected_context = "" + self._active_turn_key = "" self._hermes_home = str(kwargs.get("hermes_home") or "") self._platform = str(kwargs.get("platform") or "cli") self._agent_identity = str(kwargs.get("agent_identity") or "hermes") - if self._bridge is not None: - prev_pid = getattr(self._bridge, "pid", "?") - logger.info( - "MemOS: initialize() invoked while bridge already exists; " - "closing previous bridge (pid=%s) before respawn", - prev_pid, - ) - old_bridge = self._bridge - self._bridge = None - with contextlib.suppress(Exception): - old_bridge.close() - try: - ensure_bridge_running() - except Exception as err: - logger.warning("MemOS: failed to start bridge — %s", err) - return + self._shared_bridge = _shared_bridge_enabled() + self._runtime_home = _resolved_memos_runtime_home() + self._runtime_env = _memos_runtime_env_snapshot(self._runtime_home) - # Kill zombie bridges from previous sessions before deciding - # how to connect. + new_bridge: MemosBridgeClient | SharedBridgeLease | None = None try: - zombies = kill_zombie_bridges() - if zombies: - logger.info("MemOS: killed %d zombie bridge(s)", zombies) - except Exception: - pass - - # NOTE: An HTTP bridge path used to live here that connected to a - # running viewer daemon over HTTP instead of spawning a stdio - # subprocess. It depended on ``MemosHttpClient`` which was never - # committed — the class was referenced by name only. Issue #2096 - # reverts the half-merged HTTP feature; the stdio path below is - # the sole connection mechanism until the HTTP client lands as a - # complete change. - - if self._bridge is None: - try: - ensure_viewer_daemon() - except Exception as err: - logger.warning("MemOS: viewer daemon check failed — %s", err) - new_bridge: MemosBridgeClient | None = None - try: - new_bridge = MemosBridgeClient() - # Register the fallback LLM handler BEFORE we open the - # session so it is available the very first time the - # plugin's facade asks for help (e.g. on the first - # `turn.start` retrieval call). + runtime_home = self._runtime_home + runtime_env = dict(self._runtime_env) + if self._shared_bridge: + new_bridge = SHARED_BRIDGE_REGISTRY.acquire( + _shared_bridge_runtime_key(runtime_home), + client_factory=lambda home=str(runtime_home), env=runtime_env: ( + MemosBridgeClient( + runtime_home=home, + extra_env=env, + ) + ), + before_spawn=_prepare_shared_bridge, + host_handlers={ + "host.llm.complete": self._handle_host_llm_complete, + }, + ) + else: + _prepare_shared_bridge(cleanup_legacy_zombies=True) + new_bridge = MemosBridgeClient( + runtime_home=str(runtime_home), + extra_env=runtime_env, + ) new_bridge.register_host_handler( "host.llm.complete", self._handle_host_llm_complete, ) - self._bridge = new_bridge - self._open_session(session_id, timeout=60.0) - logger.info( - "MemOS: bridge ready (stdio) session=%s platform=%s (episode deferred)", - self._session_id, - self._platform, - ) - except Exception as err: - logger.warning("MemOS: bridge init failed — %s", err) - if new_bridge is not None: - with contextlib.suppress(Exception): - new_bridge.close() - self._bridge = None + self._bridge = new_bridge + self._open_session(session_id, timeout=60.0) + mode = "shared" if self._shared_bridge else "legacy" + runtime_id = getattr(new_bridge, "runtime_id", "per-provider") + logger.info( + "MemOS: bridge ready mode=%s runtime=%s generation=%d pid=%s " + "session=%s platform=%s (episode deferred)", + mode, + runtime_id, + self._bridge_generation, + getattr(new_bridge, "pid", "?"), + self._session_id, + self._platform, + ) + except Exception as err: + logger.warning("MemOS: bridge init failed — %s", err) + if new_bridge is not None: + with contextlib.suppress(Exception): + new_bridge.close() + self._bridge = None + self._bridge_generation = 0 # Register a Hermes plugin hook to capture tool calls as they # happen. The `post_tool_call` hook fires after every tool # dispatch (write_file, terminal, search_files, etc.) with the @@ -511,23 +587,15 @@ def _record_namespace(self) -> dict[str, Any]: return ns def _register_tool_call_hook(self) -> None: - if self._hook_registered: - return try: from hermes_cli.plugins import ( get_plugin_manager, # pyright: ignore[reportMissingImports] ) mgr = get_plugin_manager() - mgr._hooks.setdefault("post_tool_call", []).append(self._on_post_tool_call) - mgr._hooks.setdefault("post_llm_call", []).append(self._on_post_llm_call) - mgr._hooks.setdefault("transform_tool_result", []).append( - self._on_transform_tool_result - ) + HERMES_HOOK_DISPATCHER.bind(mgr, self) self._hook_registered = True - logger.debug( - "MemOS: registered post_tool_call + post_llm_call + transform_tool_result hooks" - ) + logger.debug("MemOS: bound provider session=%s to shared hooks", self._session_id) except Exception as err: logger.debug("MemOS: could not register tool hook — %s", err) @@ -927,6 +995,13 @@ def on_turn_start(self, turn_number: int, message: str, **_kwargs: Any) -> None: self._turn_number = int(turn_number or 0) self._skip_current_turn = _is_hermes_internal_review_prompt(message) self._last_user_text = "" if self._skip_current_turn else (message or "").strip() + with self._state_lock: + self._last_injected_context = "" + self._active_turn_key = ( + f"{self._session_id}:{self._turn_number}" + if self._session_id and self._turn_number > 0 + else "" + ) # Reset per-turn buffers so reasoning / tool calls captured here # belong only to this turn. self._turn_thinking = "" @@ -958,7 +1033,11 @@ def prefetch(self, query: str, *, session_id: str = "") -> str: # type: ignore[ if suppress_injection: # Do not let remembered "do it directly" skills override an # explicit user request to dispatch work to a subagent. + with self._state_lock: + self._last_injected_context = "" return "" + with self._state_lock: + self._last_injected_context = context[:_COMPRESSION_CONTEXT_MAX_CHARS] return context except Exception as err: logger.debug("MemOS: prefetch failed — %s", err) @@ -1102,7 +1181,7 @@ def on_delegation( "hookKwargs": kwargs, "namespace": namespace, } - self._bridge.request( + self._bridge_request( "subagent.record", { "agent": "hermes", @@ -1204,19 +1283,19 @@ def _json_or_raw(value: Any) -> Any: return value def on_pre_compress(self, messages: list[dict[str, Any]]) -> str: # type: ignore[override] - """Extract a compression-time memory summary. + """Return the memory context injected by the current/previous turn. - Hermes calls this right before discarding old messages; we - surface a tight summary of the relevant retrieval packet so - the compressor can preserve it alongside its own summary. + This hook must stay read-only. Calling ``turn.start`` here used to + finalize the active lightweight episode and create a phantom episode + on every compression pass. Reusing the exact context previously + injected by ``prefetch`` also keeps the summary faithful to what the + model actually saw. """ - if not self._bridge or not self._last_user_text: + with self._state_lock: + context = self._last_injected_context.strip() + if not context: return "" - with contextlib.suppress(Exception): - packet = self._turn_start(self._last_user_text, session_id=self._session_id) - if packet: - return f"MemOS memory snapshot (preserved across compression):\n{packet}" - return "" + return f"MemOS memory snapshot (preserved across compression):\n{context}" # ─── Tool surface ───────────────────────────────────────────────────── @@ -1591,6 +1670,9 @@ def save_config(self, values: dict[str, Any], hermes_home: str) -> None: # type # ─── Session-end ────────────────────────────────────────────────────── def on_session_end(self, messages: list[dict[str, Any]]) -> None: # type: ignore[override] + with self._state_lock: + self._last_injected_context = "" + self._active_turn_key = "" if not self._bridge: return # `sync_turn` already flushed completed turn data synchronously. @@ -1604,14 +1686,29 @@ def on_session_end(self, messages: list[dict[str, Any]]) -> None: # type: ignor # the asyncio event loop (gateway/run.py calls us synchronously from # _handle_reset_command) and causes Discord heartbeat timeouts when the # bridge is unresponsive. 5 s timeout keeps it bounded. - _bridge = self._bridge _sid = self._session_id + if not _sid or self._session_close_requested_for == _sid: + return + self._session_close_requested_for = _sid def _close() -> None: - with contextlib.suppress(Exception): - _bridge.request("session.close", {"sessionId": _sid}, timeout=5.0) + try: + self._bridge_request( + "session.close", + {"sessionId": _sid}, + timeout=5.0, + ) + except Exception as err: + if self._session_close_requested_for == _sid: + self._session_close_requested_for = "" + logger.debug("MemOS: session.close failed session=%s — %s", _sid, err) - threading.Thread(target=_close, daemon=True).start() + self._session_close_thread = threading.Thread( + target=_close, + daemon=True, + name="memos-session-close", + ) + self._session_close_thread.start() def __del__(self) -> None: # Safety net — if shutdown() was never called (e.g. caller forgot, @@ -1627,6 +1724,11 @@ def __del__(self) -> None: self.shutdown() def shutdown(self) -> None: # type: ignore[override] + with self._state_lock: + self._last_injected_context = "" + self._active_turn_key = "" + HERMES_HOOK_DISPATCHER.unbind(self) + self._hook_registered = False self._bridge_keepalive_stop.set() if self._bridge_keepalive_thread and self._bridge_keepalive_thread.is_alive(): self._bridge_keepalive_thread.join( @@ -1635,12 +1737,20 @@ def shutdown(self) -> None: # type: ignore[override] if self._prefetch_thread and self._prefetch_thread.is_alive(): self._prefetch_thread.join(timeout=5.0) if self._bridge: + self.on_session_end([]) + close_thread = self._session_close_thread + if close_thread is not None and close_thread.is_alive(): + close_thread.join(timeout=5.5) pid = getattr(self._bridge, "pid", "?") - logger.info("MemOS: shutting down bridge (pid=%s)", pid) + action = ( + "releasing shared bridge lease" if self._shared_bridge else "shutting down bridge" + ) + logger.info("MemOS: %s (pid=%s session=%s)", action, pid, self._session_id) with contextlib.suppress(Exception): self._bridge.close() self._bridge = None - logger.info("MemOS: bridge shutdown complete (pid=%s)", pid) + self._bridge_generation = 0 + logger.info("MemOS: provider bridge shutdown complete (pid=%s)", pid) # ─── Host LLM bridge (fallback for plugin-side model failures) ──────── @@ -1812,11 +1922,41 @@ def _host_runtime_context(self) -> dict[str, str]: self._last_host_runtime = dict(out) return out + def _bridge_request( + self, + method: str, + params: Any = None, + *, + timeout: float | None = None, + ensure_session: bool = True, + ) -> dict[str, Any]: + bridge = self._bridge + if bridge is None: + raise BridgeError("transport_closed", "bridge is not connected") + if ensure_session and isinstance(bridge, SharedBridgeLease): + generation = bridge.generation + if generation != self._bridge_generation: + with self._session_open_lock: + if bridge.generation != self._bridge_generation: + logger.info( + "MemOS: reopening logical session after shared bridge generation " + "change runtime=%s old_generation=%d new_generation=%d session=%s", + bridge.runtime_id, + self._bridge_generation, + bridge.generation, + self._session_id, + ) + self._open_session(self._session_id, timeout=30.0) + if timeout is None: + return bridge.request(method, params) + return bridge.request(method, params, timeout=timeout) + def _open_session(self, session_id: str = "", *, timeout: float = 30.0) -> None: - assert self._bridge is not None + bridge = self._bridge + assert bridge is not None requested_session = session_id or self._session_id or "" host_runtime = self._host_runtime_context() - resp = self._bridge.request( + resp = bridge.request( "session.open", { "agent": "hermes", @@ -1834,6 +1974,10 @@ def _open_session(self, session_id: str = "", *, timeout: float = 30.0) -> None: timeout=timeout, ) self._session_id = resp.get("sessionId") or requested_session + if isinstance(bridge, SharedBridgeLease): + self._bridge_generation = bridge.generation + else: + self._bridge_generation += 1 def _bridge_request_with_retry( self, @@ -1856,9 +2000,7 @@ def _bridge_request_with_retry( """ assert self._bridge is not None try: - if timeout is None: - return self._bridge.request(method, params) - return self._bridge.request(method, params, timeout=timeout) + return self._bridge_request(method, params, timeout=timeout) except BridgeError as err: if not self._is_transport_closed(err): raise @@ -1869,9 +2011,7 @@ def _bridge_request_with_retry( ) self._reconnect_bridge(self._session_id, timeout=30.0) assert self._bridge is not None - if timeout is None: - return self._bridge.request(method, params) - return self._bridge.request(method, params, timeout=timeout) + return self._bridge_request(method, params, timeout=timeout) def _is_transport_closed(self, err: Exception) -> bool: if isinstance(err, BridgeError) and err.code == "transport_closed": @@ -1922,6 +2062,69 @@ def _reconnect_bridge(self, session_id: str = "", *, timeout: float = 30.0) -> N logger.debug("MemOS: skipping reconnect during shutdown (after lock)") return + if self._shared_bridge: + bridge = self._bridge + acquired_here = bridge is None + if bridge is None: + if self._runtime_home is None: + self._runtime_home = _resolved_memos_runtime_home() + self._runtime_env = _memos_runtime_env_snapshot(self._runtime_home) + runtime_home = self._runtime_home + runtime_env = dict(self._runtime_env) + bridge = SHARED_BRIDGE_REGISTRY.acquire( + _shared_bridge_runtime_key(runtime_home), + client_factory=lambda home=str(runtime_home), env=runtime_env: ( + MemosBridgeClient( + runtime_home=home, + extra_env=env, + ) + ), + before_spawn=_prepare_shared_bridge, + host_handlers={ + "host.llm.complete": self._handle_host_llm_complete, + }, + ) + self._bridge = bridge + if not isinstance(bridge, SharedBridgeLease): + raise BridgeError( + "internal", + "shared bridge mode has a non-shared bridge handle", + ) + try: + if acquired_here: + # acquire() already ensures and health-checks the shared + # client. Open this logical session directly; restarting + # here would disrupt every healthy provider using it. + acquired_generation = bridge.generation + try: + self._open_session(session_id, timeout=timeout) + except Exception as err: + if not self._is_transport_closed(err): + raise + bridge.reconnect(expected_generation=acquired_generation) + self._open_session(session_id, timeout=timeout) + else: + expected_generation = self._bridge_generation or bridge.generation + bridge.reconnect(expected_generation=expected_generation) + self._open_session(session_id, timeout=timeout) + except Exception: + if acquired_here: + with contextlib.suppress(Exception): + bridge.close() + if self._bridge is bridge: + self._bridge = None + self._bridge_generation = 0 + raise + logger.info( + "MemOS: shared bridge session recovered runtime=%s generation=%d " + "pid=%s session=%s", + bridge.runtime_id, + bridge.generation, + bridge.pid, + self._session_id, + ) + return + old_bridge = self._bridge old_pid = getattr(old_bridge, "pid", None) if old_bridge else None @@ -1931,19 +2134,19 @@ def _reconnect_bridge(self, session_id: str = "", *, timeout: float = 30.0) -> N old_bridge.close() logger.info("MemOS: old bridge closed (pid=%s)", old_pid) - ensure_bridge_running() - # NOTE: HTTP bridge reconnect path was removed alongside issue - # #2096. See ``initialize`` for the rationale. Reconnect always - # spawns a fresh stdio bridge. - - try: - ensure_viewer_daemon() - except Exception as err: - logger.warning("MemOS: viewer daemon check failed during reconnect — %s", err) + _prepare_shared_bridge(cleanup_legacy_zombies=True) new_bridge: MemosBridgeClient | None = None try: - new_bridge = MemosBridgeClient() - logger.info("MemOS: new bridge created (pid=%s)", getattr(new_bridge, "pid", "?")) + runtime_home = self._runtime_home or _resolved_memos_runtime_home() + runtime_env = dict(self._runtime_env or _memos_runtime_env_snapshot(runtime_home)) + new_bridge = MemosBridgeClient( + runtime_home=str(runtime_home), + extra_env=runtime_env, + ) + logger.info( + "MemOS: new bridge created (pid=%s)", + getattr(new_bridge, "pid", "?"), + ) new_bridge.register_host_handler( "host.llm.complete", @@ -1972,10 +2175,12 @@ def _ensure_bridge(self, session_id: str = "", *, timeout: float = 30.0) -> bool return True except Exception as err: logger.warning("MemOS: bridge reconnect failed — %s", err) - self._bridge = None return False def _start_bridge_keepalive(self) -> None: + if self._shared_bridge: + # SharedBridgeRuntime owns the only keepalive/reconnect loop. + return if self._bridge_keepalive_thread and self._bridge_keepalive_thread.is_alive(): return self._bridge_keepalive_stop.clear() @@ -2019,27 +2224,41 @@ def _run() -> None: def _turn_start(self, query: str, *, session_id: str = "") -> str: assert self._bridge is not None host_runtime = self._host_runtime_context() - resp = self._bridge.request( - "turn.start", - { - "agent": "hermes", + with self._state_lock: + turn_key = self._active_turn_key + payload: dict[str, Any] = { + "agent": "hermes", + "namespace": self._runtime_namespace(), + "sessionId": session_id or self._session_id, + "userText": query, + "contextHints": { + "agentIdentity": self._agent_identity, "namespace": self._runtime_namespace(), - "sessionId": session_id or self._session_id, - "userText": query, - "contextHints": { - "agentIdentity": self._agent_identity, - "namespace": self._runtime_namespace(), - **host_runtime, - }, - "ts": int(time.time() * 1000), + **host_runtime, }, + "ts": int(time.time() * 1000), + } + if turn_key: + payload["turnKey"] = turn_key + resp = self._bridge_request_with_retry( + "turn.start", + payload, timeout=_LONG_RPC_TIMEOUT, ) + response_query = (resp or {}).get("query") or {} + response_session = str(response_query.get("sessionId") or "") + requested_session = str(payload["sessionId"]) + if response_session and response_session != requested_session: + raise BridgeError( + "session_mismatch", + "turn.start returned a different session " + f"(requested={requested_session}, returned={response_session})", + ) # Stash the real episode id the pipeline auto-created (V7 # §0.1 may have boundary-cut the previous episode and started # a new one). `on_session_end` uses it to close the right # episode — see the "Episode tracking" comment block above. - new_eid = ((resp or {}).get("query") or {}).get("episodeId") or "" + new_eid = response_query.get("episodeId") or "" if new_eid and new_eid != self._episode_id: self._episode_id = new_eid logger.debug("MemOS: stashed episode %s from turn.start", new_eid) @@ -2080,7 +2299,7 @@ def _turn_end( } if agent_thinking: payload["agentThinking"] = agent_thinking - result = self._bridge.request("turn.end", payload, timeout=_LONG_RPC_TIMEOUT) + result = self._bridge_request("turn.end", payload, timeout=_LONG_RPC_TIMEOUT) # Capture the trace ID for feedback submission if result and isinstance(result, dict): trace_ids = result.get("traceIds", []) @@ -2142,7 +2361,7 @@ def _submit_verifier_feedback( } if trace_id: payload["traceId"] = trace_id - self._bridge.request("feedback.submit", payload, timeout=75.0) + self._bridge_request("feedback.submit", payload, timeout=75.0) return True diff --git a/apps/memos-local-plugin/adapters/hermes/memos_provider/bridge_client.py b/apps/memos-local-plugin/adapters/hermes/memos_provider/bridge_client.py index bdc650667..6863ba1ef 100644 --- a/apps/memos-local-plugin/adapters/hermes/memos_provider/bridge_client.py +++ b/apps/memos-local-plugin/adapters/hermes/memos_provider/bridge_client.py @@ -13,6 +13,7 @@ from __future__ import annotations import contextlib +import hashlib import json import logging import os @@ -33,18 +34,47 @@ HOST_HANDLER_WAIT_SECONDS = 5.0 # ─── Module-level singleton tracker ───────────────────────────────────── -# Each entry maps a ``(agent, no_viewer)`` key to the most-recent active -# ``MemosBridgeClient`` for that slot. When a new client is constructed -# for an existing key, the previous client is closed synchronously so the -# Node-side ``bridge.cjs`` subprocess does not leak. +# Each entry maps an ``(agent, no_viewer, runtime_home)`` key to the +# most-recent active ``MemosBridgeClient`` for that slot. When a new client +# is constructed for an existing key, the previous client is closed +# synchronously so the Node-side ``bridge.cjs`` subprocess does not leak. # # This is the Python-side guard against issue #1910 (bridge process leak: # every turn spawns new bridge.cjs). Defence in depth on the Node side # lives in ``bridge.cts`` via ``bridge-stdio.pid``. -_ACTIVE_CLIENTS: dict[tuple[str, bool], MemosBridgeClient] = {} +_ACTIVE_CLIENTS: dict[tuple[str, bool, str], MemosBridgeClient] = {} _ACTIVE_CLIENTS_LOCK = threading.Lock() +def _expanded_path(value: str, env: dict[str, str]) -> Path: + """Resolve a path using the child process' HOME rather than global state.""" + home = env.get("HOME", "").strip() or str(Path.home()) + if value == "~": + value = home + elif value.startswith(("~/", "~\\")): + value = str(Path(home) / value[2:]) + return Path(value).resolve() + + +def _resolved_runtime_home(agent: str, env: dict[str, str]) -> Path: + """Mirror the Node home resolver for singleton/process ownership.""" + memos_home = env.get("MEMOS_HOME", "").strip() + if memos_home: + return _expanded_path(memos_home, env) + config_file = env.get("MEMOS_CONFIG_FILE", "").strip() + if config_file: + return _expanded_path(config_file, env).parent + agent_home = ".hermes" if agent == "hermes" else f".{agent}" + default_home = Path(env.get("HOME", "") or Path.home()) / agent_home / "memos-plugin" + return _expanded_path(str(default_home), env) + + +def _runtime_scope_token(agent: str, runtime_home: Path) -> str: + """Return a stable, path-private token safe for use in a PID filename.""" + raw = f"{agent}\0{runtime_home}".encode() + return hashlib.sha256(raw).hexdigest()[:24] + + def _installed_node_binary(plugin_root: Path) -> str | None: marker = plugin_root / ".memos-node-bin" try: @@ -112,6 +142,7 @@ def __init__( agent: str = "hermes", no_viewer: bool = True, extra_env: dict[str, str] | None = None, + runtime_home: str | None = None, ) -> None: self._lock = threading.Lock() self._next_id = 1 @@ -140,6 +171,21 @@ def __init__( script_path = Path(bridge_path) if bridge_path else _bridge_script(plugin_root) script = str(script_path) env = {**os.environ, **(extra_env or {})} + resolved_runtime_home = ( + _expanded_path(runtime_home, env) + if runtime_home + else _resolved_runtime_home(agent, env) + ) + if runtime_home and not { + "MEMOS_HOME", + "MEMOS_CONFIG_FILE", + }.intersection(extra_env or {}): + # An explicit home is both an ownership scope and the child + # runtime location. Callers that deliberately snapshot either + # selector in extra_env retain that more specific configuration. + env["MEMOS_HOME"] = str(resolved_runtime_home) + env.pop("MEMOS_CONFIG_FILE", None) + runtime_scope = _runtime_scope_token(agent, resolved_runtime_home) # Prefer the compiled JavaScript bridge — the new pure ESM # ``dist/bridge.mjs`` (issue #1736) or the legacy ``dist/bridge.cjs`` @@ -150,7 +196,11 @@ def __init__( # so use tsx's real JS entrypoint whenever we have to launch the # source entry through a specific Node. tsx_cli = plugin_root / "node_modules" / "tsx" / "dist" / "cli.mjs" - bridge_args = [script, f"--agent={agent}"] + bridge_args = [ + script, + f"--agent={agent}", + f"--runtime-scope={runtime_scope}", + ] if no_viewer: bridge_args.append("--no-viewer") if script_path.suffix in (".mjs", ".cjs"): @@ -190,13 +240,14 @@ def __init__( self._stderr_reader.start() # Singleton tracking (issue #1910). Register ourselves as the - # active client for ``(agent, no_viewer)`` and reap any previous - # holder synchronously so its subprocess does not leak. The reap - # happens AFTER our reader threads are running, so the previous - # client's ``close()`` (which closes stdin and waits for exit) - # cannot interfere with our own startup. + # active client for ``(agent, no_viewer, runtime_home)`` and reap + # any previous holder synchronously so its subprocess does not leak. + # The reap happens AFTER our reader threads are running, so the + # previous client's ``close()`` (which closes stdin and waits for + # exit) cannot interfere with our own startup. self._singleton_agent = agent self._singleton_no_viewer = bool(no_viewer) + self._singleton_runtime_home = str(resolved_runtime_home) previous = self._register_active() if previous is not None and previous is not self: prev_pid = getattr(previous, "pid", "?") @@ -210,7 +261,11 @@ def __init__( def _register_active(self) -> MemosBridgeClient | None: """Register self as the active singleton; return the displaced client.""" - key = (self._singleton_agent, self._singleton_no_viewer) + key = ( + self._singleton_agent, + self._singleton_no_viewer, + self._singleton_runtime_home, + ) with _ACTIVE_CLIENTS_LOCK: previous = _ACTIVE_CLIENTS.get(key) _ACTIVE_CLIENTS[key] = self @@ -218,7 +273,11 @@ def _register_active(self) -> MemosBridgeClient | None: def _unregister_active(self) -> None: """Remove self from the active registry if we are still the current entry.""" - key = (self._singleton_agent, self._singleton_no_viewer) + key = ( + self._singleton_agent, + self._singleton_no_viewer, + self._singleton_runtime_home, + ) with _ACTIVE_CLIENTS_LOCK: if _ACTIVE_CLIENTS.get(key) is self: _ACTIVE_CLIENTS.pop(key, None) diff --git a/apps/memos-local-plugin/adapters/hermes/memos_provider/shared_bridge_runtime.py b/apps/memos-local-plugin/adapters/hermes/memos_provider/shared_bridge_runtime.py new file mode 100644 index 000000000..a024a1505 --- /dev/null +++ b/apps/memos-local-plugin/adapters/hermes/memos_provider/shared_bridge_runtime.py @@ -0,0 +1,606 @@ +"""Process-scoped bridge ownership and Hermes hook routing. + +Hermes creates one memory provider per cached agent/session. The MemOS Node +bridge, however, owns process-wide resources (MemoryCore, SQLite connections, +model clients, and background workers) that are designed to multiplex logical +``sessionId`` values. This module keeps exactly one physical bridge per +runtime/data-home key while handing providers lightweight leases. +""" + +from __future__ import annotations + +import atexit +import contextlib +import logging +import threading +import time +import weakref + +from typing import TYPE_CHECKING, Any + +from bridge_client import BridgeError, MemosBridgeClient + + +if TYPE_CHECKING: + from collections.abc import Callable, Hashable + + +logger = logging.getLogger(__name__) + +_TRANSPORT_ERROR_MARKERS = ("broken pipe", "bridge closed", "transport_closed") + + +def _is_transport_closed(err: Exception) -> bool: + if isinstance(err, BridgeError) and err.code == "transport_closed": + return True + return any(marker in str(err).lower() for marker in _TRANSPORT_ERROR_MARKERS) + + +class _CallableRef: + """Weak reference wrapper that also supports non-weak-referenceable callables.""" + + def __init__(self, callback: Callable[..., Any]) -> None: + self._strong: Callable[..., Any] | None = None + try: + if getattr(callback, "__self__", None) is not None: + self._ref: Callable[[], Callable[..., Any] | None] = weakref.WeakMethod(callback) + else: + self._ref = weakref.ref(callback) + except TypeError: + self._strong = callback + self._ref = lambda: self._strong + + def get(self) -> Callable[..., Any] | None: + return self._ref() + + +class SharedBridgeRuntime: + """Own one physical bridge and safely multiplex provider leases.""" + + def __init__( + self, + key: tuple[Hashable, ...], + *, + client_factory: Callable[[], MemosBridgeClient], + before_spawn: Callable[[], None] | None = None, + keepalive_interval: float = 10.0, + keepalive_timeout: float = 10.0, + ) -> None: + self.key = key + self.runtime_id = f"hermes-{abs(hash(key)):x}" + self._client_factory = client_factory + self._before_spawn = before_spawn + self._keepalive_interval = max(0.1, keepalive_interval) + self._keepalive_timeout = max(0.1, keepalive_timeout) + + self._state_lock = threading.RLock() + self._reconnect_lock = threading.Lock() + self._client: MemosBridgeClient | None = None + self._generation = 0 + self._leases: set[int] = set() + self._next_lease_id = 1 + self._in_flight = 0 + self._host_handlers: dict[str, dict[int, _CallableRef]] = {} + self._registered_host_methods: set[str] = set() + + self._failure_count = 0 + self._next_reconnect_at = 0.0 + self._last_reconnect_error: Exception | None = None + self._keepalive_failures = 0 + self._stop = threading.Event() + self._keepalive_thread: threading.Thread | None = None + + @property + def generation(self) -> int: + with self._state_lock: + return self._generation + + @property + def pid(self) -> int: + with self._state_lock: + client = self._client + return int(getattr(client, "pid", 0) or 0) if client is not None else 0 + + def acquire( + self, + *, + host_handlers: dict[str, Callable[[dict[str, Any]], Any]] | None = None, + ) -> SharedBridgeLease: + with self._state_lock: + lease_id = self._next_lease_id + self._next_lease_id += 1 + self._leases.add(lease_id) + lease = SharedBridgeLease(self, lease_id) + client = self._client + newly_registered_methods: list[str] = [] + for method, handler in (host_handlers or {}).items(): + self._host_handlers.setdefault(method, {})[lease_id] = _CallableRef(handler) + if method not in self._registered_host_methods: + self._registered_host_methods.add(method) + newly_registered_methods.append(method) + allow_backoff = self._generation > 0 or self._failure_count > 0 + should_start_keepalive = ( + self._keepalive_thread is None or not self._keepalive_thread.is_alive() + ) + # Existing clients need newly introduced reverse handlers immediately. + # New clients install all known dispatchers before their first health + # request, preventing startup-time host RPC from blocking the reader. + try: + if client is not None: + for method in newly_registered_methods: + client.register_host_handler(method, self._host_dispatcher(method)) + self.ensure_client(allow_backoff=allow_backoff) + except Exception: + self.release(lease_id) + with self._state_lock: + for method in newly_registered_methods: + if not self._host_handlers.get(method): + self._registered_host_methods.discard(method) + raise + if should_start_keepalive: + self._start_keepalive() + logger.debug( + "MemOS: acquired shared bridge lease runtime=%s generation=%d pid=%s leases=%d", + self.runtime_id, + self.generation, + self.pid, + self.lease_count, + ) + return lease + + @property + def lease_count(self) -> int: + with self._state_lock: + return len(self._leases) + + def ensure_client(self, *, allow_backoff: bool = True) -> None: + with self._state_lock: + if self._client is not None: + return + generation = self._generation + self.reconnect(expected_generation=generation, allow_backoff=allow_backoff) + + def request( + self, + lease_id: int, + method: str, + params: Any = None, + *, + timeout: float = 30.0, + ) -> dict[str, Any]: + with self._state_lock: + if lease_id not in self._leases: + raise BridgeError("transport_closed", "shared bridge lease is closed") + client = self._client + self._in_flight += 1 + try: + if client is None: + self.ensure_client(allow_backoff=True) + with self._state_lock: + client = self._client + if client is None: # pragma: no cover - defensive after ensure_client + raise BridgeError("transport_closed", "shared bridge is unavailable") + return client.request(method, params, timeout=timeout) + finally: + with self._state_lock: + self._in_flight = max(0, self._in_flight - 1) + + def reconnect( + self, + *, + expected_generation: int | None = None, + allow_backoff: bool = True, + ) -> int: + """Replace the bridge once; stale concurrent reconnects reuse the winner.""" + with self._reconnect_lock: + with self._state_lock: + if ( + expected_generation is not None + and self._client is not None + and self._generation != expected_generation + ): + return self._generation + if allow_backoff and time.monotonic() < self._next_reconnect_at: + err = self._last_reconnect_error + message = "shared bridge reconnect is backing off" + if err is not None: + message = f"{message}: {err}" + raise BridgeError("transport_closed", message) + old_client = self._client + old_pid = int(getattr(old_client, "pid", 0) or 0) if old_client else 0 + self._client = None + + if old_client is not None: + with contextlib.suppress(Exception): + old_client.close() + + new_client: MemosBridgeClient | None = None + try: + if self._before_spawn is not None: + self._before_spawn() + new_client = self._client_factory() + self._install_host_dispatchers(new_client) + new_client.request("core.health", {}, timeout=self._keepalive_timeout) + except Exception as err: + if new_client is not None: + with contextlib.suppress(Exception): + new_client.close() + self._record_reconnect_failure(err) + raise + + with self._state_lock: + self._client = new_client + self._generation += 1 + self._failure_count = 0 + self._next_reconnect_at = 0.0 + self._last_reconnect_error = None + self._keepalive_failures = 0 + generation = self._generation + lease_count = len(self._leases) + logger.info( + "MemOS: shared bridge ready runtime=%s generation=%d pid=%s old_pid=%s leases=%d", + self.runtime_id, + generation, + self.pid, + old_pid or "-", + lease_count, + ) + return generation + + def register_host_handler( + self, + lease_id: int, + method: str, + handler: Callable[[dict[str, Any]], Any], + ) -> None: + with self._state_lock: + if lease_id not in self._leases: + return + handlers = self._host_handlers.setdefault(method, {}) + handlers[lease_id] = _CallableRef(handler) + client = self._client + needs_registration = method not in self._registered_host_methods + if needs_registration: + self._registered_host_methods.add(method) + if needs_registration and client is not None: + client.register_host_handler(method, self._host_dispatcher(method)) + + def release(self, lease_id: int) -> None: + with self._state_lock: + self._leases.discard(lease_id) + for handlers in self._host_handlers.values(): + handlers.pop(lease_id, None) + leases = len(self._leases) + logger.debug( + "MemOS: released shared bridge lease runtime=%s generation=%d pid=%s leases=%d", + self.runtime_id, + self.generation, + self.pid, + leases, + ) + + def status(self) -> dict[str, Any]: + with self._state_lock: + return { + "runtimeId": self.runtime_id, + "generation": self._generation, + "pid": self.pid, + "leases": len(self._leases), + "inFlight": self._in_flight, + "reconnectFailures": self._failure_count, + "keepaliveFailures": self._keepalive_failures, + } + + def close(self) -> None: + self._stop.set() + thread = self._keepalive_thread + if thread is not None and thread.is_alive(): + thread.join(timeout=min(self._keepalive_timeout + 1.0, 12.0)) + with self._state_lock: + client = self._client + self._client = None + self._leases.clear() + self._host_handlers.clear() + if client is not None: + with contextlib.suppress(Exception): + client.close() + + def _record_reconnect_failure(self, err: Exception) -> None: + with self._state_lock: + self._failure_count += 1 + delay = min(30.0, float(2 ** min(self._failure_count - 1, 5))) + self._next_reconnect_at = time.monotonic() + delay + self._last_reconnect_error = err + failure_count = self._failure_count + logger.warning( + "MemOS: shared bridge reconnect failed runtime=%s failures=%d retry_in=%.1fs — %s", + self.runtime_id, + failure_count, + delay, + err, + ) + + def _host_dispatcher(self, method: str) -> Callable[[dict[str, Any]], Any]: + def dispatch(params: dict[str, Any]) -> Any: + with self._state_lock: + handlers = self._host_handlers.get(method, {}) + candidates = list(reversed(handlers.items())) + stale: list[int] = [] + for lease_id, callback_ref in candidates: + callback = callback_ref.get() + if callback is not None: + return callback(params) + stale.append(lease_id) + if stale: + with self._state_lock: + current = self._host_handlers.get(method, {}) + for lease_id in stale: + current.pop(lease_id, None) + raise BridgeError("host_unavailable", f"no active host handler for {method}") + + return dispatch + + def _install_host_dispatchers(self, client: MemosBridgeClient) -> None: + with self._state_lock: + methods = list(self._registered_host_methods) + for method in methods: + client.register_host_handler(method, self._host_dispatcher(method)) + + def _start_keepalive(self) -> None: + with self._state_lock: + if self._keepalive_thread is not None and self._keepalive_thread.is_alive(): + return + self._stop.clear() + thread = threading.Thread( + target=self._keepalive_loop, + daemon=True, + name=f"memos-shared-bridge-keepalive-{self.runtime_id}", + ) + self._keepalive_thread = thread + thread.start() + + def _keepalive_loop(self) -> None: + while not self._stop.wait(self._keepalive_interval): + with self._state_lock: + client = self._client + generation = self._generation + in_flight = self._in_flight + # A capture/retrieval call may legitimately spend up to the + # provider's long-RPC timeout in an embedding or LLM request. + # Do not let a concurrent health timeout kill healthy in-flight + # work for every session. + if in_flight: + continue + if client is None: + with contextlib.suppress(Exception): + self.reconnect(expected_generation=generation) + continue + try: + client.request("core.health", {}, timeout=self._keepalive_timeout) + with self._state_lock: + self._keepalive_failures = 0 + except Exception as err: + with self._state_lock: + self._keepalive_failures += 1 + failures = self._keepalive_failures + should_reconnect = _is_transport_closed(err) or ( + isinstance(err, BridgeError) and err.code == "timeout" and failures >= 2 + ) + if not should_reconnect: + logger.debug( + "MemOS: shared bridge keepalive failed runtime=%s failures=%d — %s", + self.runtime_id, + failures, + err, + ) + continue + logger.warning( + "MemOS: shared bridge keepalive reconnecting runtime=%s " + "generation=%d failures=%d — %s", + self.runtime_id, + generation, + failures, + err, + ) + with contextlib.suppress(Exception): + self.reconnect(expected_generation=generation) + + +class SharedBridgeLease: + """Provider-facing handle that never owns or closes the physical bridge.""" + + def __init__(self, runtime: SharedBridgeRuntime, lease_id: int) -> None: + self._runtime = runtime + self._lease_id = lease_id + self._closed = False + + @property + def pid(self) -> int: + return self._runtime.pid + + @property + def generation(self) -> int: + return self._runtime.generation + + @property + def runtime_id(self) -> str: + return self._runtime.runtime_id + + def request( + self, + method: str, + params: Any = None, + *, + timeout: float = 30.0, + ) -> dict[str, Any]: + if self._closed: + raise BridgeError("transport_closed", "shared bridge lease is closed") + return self._runtime.request(self._lease_id, method, params, timeout=timeout) + + def reconnect(self, *, expected_generation: int | None = None) -> int: + if self._closed: + raise BridgeError("transport_closed", "shared bridge lease is closed") + return self._runtime.reconnect(expected_generation=expected_generation) + + def register_host_handler( + self, + method: str, + handler: Callable[[dict[str, Any]], Any], + ) -> None: + self._runtime.register_host_handler(self._lease_id, method, handler) + + def status(self) -> dict[str, Any]: + return self._runtime.status() + + def close(self) -> None: + if self._closed: + return + self._closed = True + self._runtime.release(self._lease_id) + + +class SharedBridgeRuntimeRegistry: + """Registry of shared runtimes, isolated by resolved MemOS data home.""" + + def __init__( + self, + *, + keepalive_interval: float = 10.0, + keepalive_timeout: float = 10.0, + ) -> None: + self._lock = threading.Lock() + self._runtimes: dict[tuple[Hashable, ...], SharedBridgeRuntime] = {} + self._keepalive_interval = keepalive_interval + self._keepalive_timeout = keepalive_timeout + + def acquire( + self, + key: tuple[Hashable, ...], + *, + client_factory: Callable[[], MemosBridgeClient], + before_spawn: Callable[[], None] | None = None, + host_handlers: dict[str, Callable[[dict[str, Any]], Any]] | None = None, + ) -> SharedBridgeLease: + with self._lock: + runtime = self._runtimes.get(key) + if runtime is None: + runtime = SharedBridgeRuntime( + key, + client_factory=client_factory, + before_spawn=before_spawn, + keepalive_interval=self._keepalive_interval, + keepalive_timeout=self._keepalive_timeout, + ) + self._runtimes[key] = runtime + # Keep a failed runtime entry so its exponential backoff applies to + # later providers. Removing it here would let each new Hermes session + # create a fresh runtime and bypass the circuit breaker. + return runtime.acquire(host_handlers=host_handlers) + + def close_all(self) -> None: + with self._lock: + runtimes = list(self._runtimes.values()) + self._runtimes.clear() + for runtime in runtimes: + runtime.close() + + def status(self) -> list[dict[str, Any]]: + with self._lock: + runtimes = list(self._runtimes.values()) + return [runtime.status() for runtime in runtimes] + + +class HermesHookDispatcher: + """Register one global Hermes hook set and route events by session.""" + + def __init__(self) -> None: + self._lock = threading.RLock() + self._providers: dict[int, weakref.ReferenceType[Any]] = {} + self._registered_managers: set[int] = set() + self._last_ambiguous_warning = 0.0 + + def bind(self, manager: Any, provider: Any) -> None: + with self._lock: + self._providers[id(provider)] = weakref.ref(provider) + manager_id = id(manager) + if manager_id in self._registered_managers: + return + manager._hooks.setdefault("post_tool_call", []).append(self._post_tool_call) + manager._hooks.setdefault("post_llm_call", []).append(self._post_llm_call) + manager._hooks.setdefault("transform_tool_result", []).append( + self._transform_tool_result + ) + self._registered_managers.add(manager_id) + logger.debug("MemOS: registered one shared Hermes hook dispatcher") + + def unbind(self, provider: Any) -> None: + with self._lock: + self._providers.pop(id(provider), None) + + def _live_providers(self) -> list[Any]: + with self._lock: + items = list(self._providers.items()) + live: list[Any] = [] + stale: list[int] = [] + for provider_id, provider_ref in items: + provider = provider_ref() + if provider is None: + stale.append(provider_id) + else: + live.append(provider) + if stale: + with self._lock: + for provider_id in stale: + self._providers.pop(provider_id, None) + return live + + def _select(self, kwargs: dict[str, Any]) -> Any | None: + session_id = str(kwargs.get("session_id") or kwargs.get("sessionId") or "") + providers = self._live_providers() + if session_id: + matches = [p for p in providers if str(getattr(p, "_session_id", "")) == session_id] + return matches[-1] if matches else None + if len(providers) == 1: + return providers[0] + if len(providers) > 1: + now = time.monotonic() + with self._lock: + if now - self._last_ambiguous_warning >= 60.0: + self._last_ambiguous_warning = now + logger.warning( + "MemOS: ignored sessionless Hermes hook with %d active providers; " + "event was not broadcast", + len(providers), + ) + return None + + def _post_tool_call(self, **kwargs: Any) -> None: + provider = self._select(kwargs) + if provider is not None: + provider._on_post_tool_call(**kwargs) + + def _post_llm_call(self, **kwargs: Any) -> None: + provider = self._select(kwargs) + if provider is not None: + provider._on_post_llm_call(**kwargs) + + def _transform_tool_result(self, **kwargs: Any) -> str | None: + provider = self._select(kwargs) + if provider is None: + return None + return provider._on_transform_tool_result(**kwargs) + + +SHARED_BRIDGE_REGISTRY = SharedBridgeRuntimeRegistry() +HERMES_HOOK_DISPATCHER = HermesHookDispatcher() +atexit.register(SHARED_BRIDGE_REGISTRY.close_all) + + +__all__ = [ + "HERMES_HOOK_DISPATCHER", + "SHARED_BRIDGE_REGISTRY", + "HermesHookDispatcher", + "SharedBridgeLease", + "SharedBridgeRuntime", + "SharedBridgeRuntimeRegistry", +] diff --git a/apps/memos-local-plugin/adapters/hermes/plugin.yaml b/apps/memos-local-plugin/adapters/hermes/plugin.yaml index a5b5607db..dd9517d18 100644 --- a/apps/memos-local-plugin/adapters/hermes/plugin.yaml +++ b/apps/memos-local-plugin/adapters/hermes/plugin.yaml @@ -1,5 +1,5 @@ name: memtensor -version: 2.0.0-beta.1 +version: 2.0.12-beta.1 description: >- MemOS Local — Reflect2Evolve V7 memory for hermes-agent. Layered L1/L2/L3 traces, reflection-weighted reward backprop, diff --git a/apps/memos-local-plugin/agent-contract/dto.ts b/apps/memos-local-plugin/agent-contract/dto.ts index e9fe8db90..bdb9375ab 100644 --- a/apps/memos-local-plugin/agent-contract/dto.ts +++ b/apps/memos-local-plugin/agent-contract/dto.ts @@ -89,6 +89,12 @@ export interface TurnInputDTO { agent: AgentKind; sessionId: SessionId; namespace?: RuntimeNamespace; + /** + * Optional host-stable idempotency key for this logical turn. + * Retries with the same sessionId + turnKey must reuse the original + * episode instead of opening another one. + */ + turnKey?: string; /** Optional pre-existing episodeId (for continued tasks). */ episodeId?: EpisodeId; /** Free-form text the user said this turn. */ diff --git a/apps/memos-local-plugin/bridge.cts b/apps/memos-local-plugin/bridge.cts index e26203836..acc1ccb29 100644 --- a/apps/memos-local-plugin/bridge.cts +++ b/apps/memos-local-plugin/bridge.cts @@ -52,6 +52,7 @@ interface BridgeArgs { tcpPort?: number; agent: "openclaw" | "hermes"; home?: string; + runtimeScope?: string; } type BridgeStatus = "connected" | "reconnecting" | "disconnected" | "unknown"; @@ -72,6 +73,10 @@ function parseArgs(argv: readonly string[]): BridgeArgs { else if (raw === "--agent=hermes") args.agent = "hermes"; else if (raw === "--agent=openclaw") args.agent = "openclaw"; else if (raw.startsWith("--home=")) args.home = raw.slice(7); + else if (raw.startsWith("--runtime-scope=")) { + const candidate = raw.slice(16).toLowerCase(); + if (/^[a-f0-9]{16,64}$/.test(candidate)) args.runtimeScope = candidate; + } } return args; } @@ -158,7 +163,10 @@ async function main(): Promise { // ─── Singleton: kill previous bridge that owns the viewer port ─── const pidPath = pidFilePath(args.agent); - const stdioPidPath = pidFilePath(args.agent, STDIO_PID_FILENAME); + const stdioPidFilename = args.runtimeScope + ? `bridge-stdio-${args.runtimeScope}.pid` + : STDIO_PID_FILENAME; + const stdioPidPath = pidFilePath(args.agent, stdioPidFilename); const ownsViewerPort = args.daemon || !args.noViewer; const removeOwnedPidFile = () => { if (ownsViewerPort) removePidFile(pidPath); @@ -294,6 +302,7 @@ async function main(): Promise { const { core, config, home } = await bootstrapMemoryCoreFull({ agent: args.agent, namespace: { agentKind: args.agent, profileId: resolvedProfileId }, + autoRecovery: args.agent !== "hermes" || !args.daemon, pkgVersion, hostLlmBridge: args.daemon ? null : lazyHostLlmBridge, home: resolvedHome, @@ -486,8 +495,15 @@ async function main(): Promise { process.stderr.write(`bridge: daemon received ${sig}, shutting down\n`); removeOwnedPidFile(); try { await viewer!.close(); } catch { /* best-effort */ } - await withShutdownTimeout(core.shutdown()); - process.exit(0); + try { + await withShutdownTimeout(core.shutdown()); + } catch { + // clear-data already shuts the core down before removing SQLite. + // The signal still has to terminate the daemon so the supervisor + // can replace it. + } finally { + process.exit(0); + } }; process.on("SIGINT", () => void shutdownDaemon("SIGINT")); process.on("SIGTERM", () => void shutdownDaemon("SIGTERM")); diff --git a/apps/memos-local-plugin/bridge.mts b/apps/memos-local-plugin/bridge.mts index 95b15e21c..2d967c597 100644 --- a/apps/memos-local-plugin/bridge.mts +++ b/apps/memos-local-plugin/bridge.mts @@ -245,6 +245,7 @@ async function main(): Promise { const { core, config, home } = await bootstrapMemoryCoreFull({ agent: args.agent, namespace: { agentKind: args.agent, profileId: "default" }, + autoRecovery: args.agent !== "hermes" || !args.daemon, pkgVersion, hostLlmBridge: args.daemon ? null : lazyHostLlmBridge, home: resolvedHome, @@ -407,8 +408,15 @@ async function main(): Promise { process.stderr.write(`bridge: daemon received ${sig}, shutting down\n`); removeOwnedPidFile(); try { await viewer!.close(); } catch { /* best-effort */ } - await core.shutdown(); - process.exit(0); + try { + await core.shutdown(); + } catch { + // clear-data already shuts the core down before removing SQLite. + // The signal still has to terminate the daemon so the supervisor + // can replace it. + } finally { + process.exit(0); + } }; process.on("SIGINT", () => void shutdownDaemon("SIGINT")); process.on("SIGTERM", () => void shutdownDaemon("SIGTERM")); diff --git a/apps/memos-local-plugin/bridge/methods.ts b/apps/memos-local-plugin/bridge/methods.ts index 1f3583746..2bc1084a6 100644 --- a/apps/memos-local-plugin/bridge/methods.ts +++ b/apps/memos-local-plugin/bridge/methods.ts @@ -383,6 +383,12 @@ function validateTurnInput(p: Record): void { requireKey(p, "sessionId", "string", "turn.start"); requireKey(p, "userText", "string", "turn.start"); requireKey(p, "ts", "number", "turn.start"); + if (p.turnKey !== undefined && typeof p.turnKey !== "string") { + throw new MemosError( + "invalid_argument", + "turn.start: optional 'turnKey' must be a string", + ); + } } function validateTurnResult(p: Record): void { diff --git a/apps/memos-local-plugin/core/capture/capture.ts b/apps/memos-local-plugin/core/capture/capture.ts index 576ba9060..94be58fff 100644 --- a/apps/memos-local-plugin/core/capture/capture.ts +++ b/apps/memos-local-plugin/core/capture/capture.ts @@ -410,6 +410,40 @@ export function createCaptureRunner(deps: CaptureDeps): CaptureRunner { const recoveredReplay = isRecoveredReplay(input.episode); const matcher = createTraceMatcher(existing, { allowRelaxedToolTiming: recoveredReplay }); const matchedRows = normalized.map((s) => matcher.take(s)); + // A recovered snapshot is reconstructed from the trace rows that we are + // about to patch. If it produces steps but none of those steps match any + // source row, continuing into orphan handling / reflection would replay + // an invalid snapshot, spend LLM calls, and finally emit capture.done + // with no usable trace ids. Fail before any of those side effects. + // + // Partial matches remain recoverable: their matching rows are patched + // and the unmatched tail follows the existing bounded-orphan policy. + if ( + recoveredReplay && + normalized.length > 0 && + matchedRows.every((row) => row === null) + ) { + const error = new MemosError( + ERROR_CODES.CONFLICT, + "recovered replay did not match any persisted trace rows", + { + episodeId: input.episode.id, + normalizedSteps: normalized.length, + persistedTraces: existing.length, + }, + ); + emit({ + kind: "capture.failed", + episodeId: input.episode.id, + sessionId: input.episode.sessionId, + stage: "match", + error: { + code: ERROR_CODES.CONFLICT, + message: error.message, + }, + }); + throw error; + } const orphanEntries = normalized .map((step, index) => ({ step, index })) .filter(({ index }) => matchedRows[index] === null); diff --git a/apps/memos-local-plugin/core/logger/README.md b/apps/memos-local-plugin/core/logger/README.md index 5504a0915..9ccd9394e 100644 --- a/apps/memos-local-plugin/core/logger/README.md +++ b/apps/memos-local-plugin/core/logger/README.md @@ -86,8 +86,9 @@ per-channel notes. Example prefixes: - **Disk full / permission denied** — file transports degrade to console only and emit one error to the in-memory ring buffer (also surfaced via SSE). -- **Process abort** — every transport `flushSync()`s on `beforeExit` and - `SIGINT`/`SIGTERM`. +- **Process exit** — transports close on `beforeExit`. Executable bridge + entries own `SIGINT`/`SIGTERM` so they can drain MemoryCore before exit; + file writes themselves are synchronous. - **Audit retention** — never deletes. If you really need to free space, gzip archives can be moved out of `logs/` manually. - **Redaction is best-effort** — exotic key names won't be caught. If you have diff --git a/apps/memos-local-plugin/core/logger/index.ts b/apps/memos-local-plugin/core/logger/index.ts index d9ac5afb0..897ffe4b1 100644 --- a/apps/memos-local-plugin/core/logger/index.ts +++ b/apps/memos-local-plugin/core/logger/index.ts @@ -411,7 +411,7 @@ function round2(n: number): number { return Math.round(n * 100) / 100; } -// ─── Process-exit hooks (only register once) ────────────────────────────── +// ─── Process-exit hook (only register once) ─────────────────────────────── let exitHooked = false; function hookProcessExit(): void { @@ -419,8 +419,11 @@ function hookProcessExit(): void { exitHooked = true; const onExit = () => { void shutdownLogger(); }; process.once("beforeExit", onExit); - process.once("SIGINT", () => { onExit(); process.exit(130); }); - process.once("SIGTERM", () => { onExit(); process.exit(143); }); + // Deliberately do not own SIGINT/SIGTERM here. The dedicated bridge + // entries drain their HTTP/stdin handles and MemoryCore before exiting; + // a library-level process.exit() used to pre-empt those handlers and + // leave episodes/SQLite work half-finished. Embedded hosts likewise own + // their process lifecycle. } // ─── Public root logger ──────────────────────────────────────────────────── diff --git a/apps/memos-local-plugin/core/pipeline/memory-core.ts b/apps/memos-local-plugin/core/pipeline/memory-core.ts index bc0c7e689..ddcdf1602 100644 --- a/apps/memos-local-plugin/core/pipeline/memory-core.ts +++ b/apps/memos-local-plugin/core/pipeline/memory-core.ts @@ -138,6 +138,12 @@ type DedicatedLlmConfig = { export interface BootstrapOptions { agent: AgentKind; namespace?: RuntimeNamespace; + /** + * Run automatic startup/periodic episode recovery. Defaults to true. + * Hermes disables this for its read-oriented Viewer daemon so only the + * stdio bridge owns recovery writes for a given data home. + */ + autoRecovery?: boolean; /** Optional pre-resolved home. If omitted, derived from `resolveHome`. */ home?: ResolvedHome; /** Optional pre-resolved config. If omitted, we load from disk. */ @@ -526,6 +532,7 @@ export async function bootstrapMemoryCoreFull( const handle = createPipeline(deps); const core = createMemoryCore(handle, home, options.pkgVersion ?? "dev", { + autoRecovery: options.autoRecovery ?? true, telemetry: options.telemetry ?? null, onShutdown: () => { try { @@ -544,6 +551,11 @@ export async function bootstrapMemoryCoreFull( // ─── Facade factory ────────────────────────────────────────────────────────── export interface CreateMemoryCoreOptions { + /** + * Run automatic startup/periodic episode recovery. Defaults to true. + * This does not disable normal turn capture or explicit repair operations. + */ + autoRecovery?: boolean; /** Called after the pipeline has shut down. */ onShutdown?: () => void | Promise; /** Optional telemetry instance for ARMS RUM reporting. */ @@ -566,6 +578,7 @@ export function createMemoryCore( ): MemoryCore { const bootAt = Date.now(); const log = rootLogger.child({ channel: "core.pipeline.memory-core" }); + const autoRecoveryEnabled = options.autoRecovery ?? true; let telemetry = options.telemetry ?? null; let initialized = false; let shutDown = false; @@ -675,6 +688,7 @@ export function createMemoryCore( let lastStaleScan = 0; let lastDirtyClosedScan = 0; async function autoFinalizeStaleTasks(): Promise { + if (!autoRecoveryEnabled) return; const nowMs = Date.now(); if (nowMs - lastStaleScan < 30_000) return; lastStaleScan = nowMs; @@ -735,6 +749,7 @@ export function createMemoryCore( } async function autoRescoreDirtyClosedEpisodes(): Promise { + if (!autoRecoveryEnabled) return; const nowMs = Date.now(); if (nowMs - lastDirtyClosedScan < 30_000) return; lastDirtyClosedScan = nowMs; @@ -1037,7 +1052,8 @@ export function createMemoryCore( // call `core.waitForStartupRecovery()` after `init()`. let staleForBackground: Array }> = []; let dirtyClosedForBackground: Array }> = []; - try { + if (autoRecoveryEnabled) { + try { const orphans = handle.repos.episodes.list({ status: "open", limit: 500 }); if (orphans.length > 0) { const nowMs = Date.now(); @@ -1141,16 +1157,20 @@ export function createMemoryCore( } dirtyClosedForBackground = dirtyClosed; } - } catch (err) { - log.debug("init.orphan_scan.failed", { - err: err instanceof Error ? err.message : String(err), - }); + } catch (err) { + log.debug("init.orphan_scan.failed", { + err: err instanceof Error ? err.message : String(err), + }); + } } // Kick the slow recovery chain off the main thread. `init()` returns // as soon as the synchronous classification above finishes, so the // Gateway can start accepting WebSocket upgrades immediately. - if (staleForBackground.length > 0 || dirtyClosedForBackground.length > 0) { + if ( + autoRecoveryEnabled && + (staleForBackground.length > 0 || dirtyClosedForBackground.length > 0) + ) { const stale = staleForBackground; const dirtyClosed = dirtyClosedForBackground; log.info("init.background_recovery_started", { @@ -1184,15 +1204,17 @@ export function createMemoryCore( // Periodic rescore timer for episodes that miss the startup scan or // retry of failed reward runs. 10-minute interval is safe because // autoRescoreDirtyClosedEpisodes has its own 30-second dedup guard. - const rescoreInterval = setInterval(() => { - void autoRescoreDirtyClosedEpisodes().catch((err) => { - log.debug("periodic_rescore.error", { - err: err instanceof Error ? err.message : String(err), + if (autoRecoveryEnabled) { + const rescoreInterval = setInterval(() => { + void autoRescoreDirtyClosedEpisodes().catch((err) => { + log.debug("periodic_rescore.error", { + err: err instanceof Error ? err.message : String(err), + }); }); - }); - }, 10 * 60 * 1000); - // Mark as unref so the timer doesn't block shutdown - (rescoreInterval as unknown as { unref?: () => void }).unref?.(); + }, 10 * 60 * 1000); + // Mark as unref so the timer doesn't block shutdown + (rescoreInterval as unknown as { unref?: () => void }).unref?.(); + } // Wire `memory_add` into the api_logs table on EVERY turn so the // Logs viewer shows per-turn capture activity. `capture.lite.done` @@ -1416,92 +1438,119 @@ export function createMemoryCore( }); const needsRewardFallback: EpisodeId[] = []; - for (const ep of orphans) { - if (isLightweightEpisode(ep)) continue; - try { - const episodeId = ep.id as EpisodeId; - const traceIds = (ep.traceIds ?? []) as TraceId[]; - handle.repos.episodes.close(episodeId, endedAt, ep.rTask ?? undefined); - handle.repos.episodes.updateMeta(episodeId, { - closeReason: "finalized", - abandonReason: undefined, - recoveredAtStartup: endedAt, - recoveryReason: "missed_session_end", - }); + // Scope capture failures to this startup-recovery batch. Normal live + // captures and explicit/manual reward runs must retain their existing + // behaviour. + const captureFailedInBatch = new Set(); + const recoveryEpisodeIds = new Set( + orphans.map((ep) => ep.id as EpisodeId), + ); + const unsubscribeCaptureFailed = handle.buses.capture.on("capture.failed", (evt) => { + if ( + evt.kind === "capture.failed" && + recoveryEpisodeIds.has(evt.episodeId) + ) { + captureFailedInBatch.add(evt.episodeId); + } + }); + try { + for (const ep of orphans) { + if (isLightweightEpisode(ep)) continue; + try { + const episodeId = ep.id as EpisodeId; + const traceIds = (ep.traceIds ?? []) as TraceId[]; + handle.repos.episodes.close(episodeId, endedAt, ep.rTask ?? undefined); + handle.repos.episodes.updateMeta(episodeId, { + closeReason: "finalized", + abandonReason: undefined, + recoveredAtStartup: endedAt, + recoveryReason: "missed_session_end", + }); - if (ep.rTask != null && !episodeRewardIsDirty(ep)) { - log.info("init.orphan.repaired_finalized", { + if (ep.rTask != null && !episodeRewardIsDirty(ep)) { + log.info("init.orphan.repaired_finalized", { + episodeId, + sessionId: ep.sessionId, + rTask: ep.rTask, + }); + debugStartupRecovery("H2", "startup_recovery_already_scored", { + episodeId, + sessionId: ep.sessionId, + rTask: ep.rTask, + }); + continue; + } + + const snapshot = snapshotFromRecoveredEpisode(ep, endedAt); + debugStartupRecovery("H3", "startup_recovery_emit_finalized", { episodeId, sessionId: ep.sessionId, - rTask: ep.rTask, + traceCount: traceIds.length, + recoveredTurnCount: snapshot.turnCount, }); - debugStartupRecovery("H2", "startup_recovery_already_scored", { - episodeId, - sessionId: ep.sessionId, - rTask: ep.rTask, + handle.buses.session.emit({ + kind: "episode.finalized", + episode: snapshot, + closedBy: "finalized", + }); + needsRewardFallback.push(episodeId); + } catch (err) { + log.debug("init.orphan_recovery.skipped", { + episodeId: ep.id, + err: err instanceof Error ? err.message : String(err), + }); + debugStartupRecovery("H4", "startup_recovery_error", { + episodeId: ep.id, + err: err instanceof Error ? err.message : String(err), }); - continue; } + } - const snapshot = snapshotFromRecoveredEpisode(ep, endedAt); - debugStartupRecovery("H3", "startup_recovery_emit_finalized", { - episodeId, - sessionId: ep.sessionId, - traceCount: traceIds.length, - recoveredTurnCount: snapshot.turnCount, - }); - handle.buses.session.emit({ - kind: "episode.finalized", - episode: snapshot, - closedBy: "finalized", + try { + await handle.flush(); + for (const episodeId of needsRewardFallback) { + if (captureFailedInBatch.has(episodeId)) { + log.warn("init.orphan_recovery.reward_fallback_skipped", { + episodeId, + reason: "capture_failed", + }); + continue; + } + const row = handle.repos.episodes.getById(episodeId); + if (row?.rTask == null) { + await handle.rewardRunner.run({ + episodeId, + feedback: [], + trigger: "manual", + }); + } + } + await handle.flush(); + debugStartupRecovery("H5", "startup_recovery_flush_done", { + recoveredCount: orphans.length, + rewardedEpisodes: needsRewardFallback.map((episodeId) => { + const row = handle.repos.episodes.getById(episodeId); + return { + episodeId, + rTask: row?.rTask ?? null, + captureFailed: captureFailedInBatch.has(episodeId), + closeReason: (row?.meta as { closeReason?: unknown } | undefined)?.closeReason, + abandonReason: (row?.meta as { abandonReason?: unknown } | undefined)?.abandonReason, + }; + }), }); - needsRewardFallback.push(episodeId); } catch (err) { - log.debug("init.orphan_recovery.skipped", { - episodeId: ep.id, + log.warn("init.orphan_recovery.flush_failed", { + count: orphans.length, err: err instanceof Error ? err.message : String(err), }); - debugStartupRecovery("H4", "startup_recovery_error", { - episodeId: ep.id, + debugStartupRecovery("H5", "startup_recovery_flush_failed", { + count: orphans.length, err: err instanceof Error ? err.message : String(err), }); } - } - - try { - await handle.flush(); - for (const episodeId of needsRewardFallback) { - const row = handle.repos.episodes.getById(episodeId); - if (row?.rTask == null) { - await handle.rewardRunner.run({ - episodeId, - feedback: [], - trigger: "manual", - }); - } - } - await handle.flush(); - debugStartupRecovery("H5", "startup_recovery_flush_done", { - recoveredCount: orphans.length, - rewardedEpisodes: needsRewardFallback.map((episodeId) => { - const row = handle.repos.episodes.getById(episodeId); - return { - episodeId, - rTask: row?.rTask ?? null, - closeReason: (row?.meta as { closeReason?: unknown } | undefined)?.closeReason, - abandonReason: (row?.meta as { abandonReason?: unknown } | undefined)?.abandonReason, - }; - }), - }); - } catch (err) { - log.warn("init.orphan_recovery.flush_failed", { - count: orphans.length, - err: err instanceof Error ? err.message : String(err), - }); - debugStartupRecovery("H5", "startup_recovery_flush_failed", { - count: orphans.length, - err: err instanceof Error ? err.message : String(err), - }); + } finally { + unsubscribeCaptureFailed(); } } @@ -1590,6 +1639,27 @@ export function createMemoryCore( id: last.id, }); } + // Older builds could leave both `reward.skipped=true` and a stale + // `rewardDirty` marker on short/trivial episodes. The skip is terminal; + // clean the contradictory marker while this bounded page is already in + // memory so upgraded installations stop retrying those rows immediately. + for (const ep of page) { + if (!rewardWasSkipped(ep) || !hasRewardDirtyMarker(ep)) continue; + try { + handle.repos.episodes.updateMeta(ep.id as EpisodeId, { + rewardDirty: undefined, + }); + ep.meta = { ...(ep.meta ?? {}), rewardDirty: undefined }; + } catch (err) { + // A cleanup write must not prevent the rest of this page from being + // classified and recovered. The terminal skip still keeps this row + // out of the retry queue, and a later bounded scan can clean it again. + log.debug("dirty_closed_reward.skip_marker_cleanup_error", { + episodeId: ep.id, + err: err instanceof Error ? err.message : String(err), + }); + } + } return page; } @@ -1605,12 +1675,12 @@ export function createMemoryCore( function episodeRewardIsDirty(ep: EpisodeRow & { meta?: Record }): boolean { const meta = ep.meta ?? {}; if (meta.lightweightMemory === true) return false; - if (meta.rewardDirty && typeof meta.rewardDirty === "object") return true; + // An intentional triviality skip is terminal and must take precedence + // over a stale retry marker written by an older recovery attempt. + if (rewardWasSkipped(ep)) return false; + if (hasRewardDirtyMarker(ep)) return true; const reward = meta.reward; - if (reward && typeof reward === "object" && (reward as { skipped?: unknown }).skipped === true) { - return false; - } if ( ep.rTask == null && (ep.traceIds?.length ?? 0) > 0 && @@ -1702,10 +1772,14 @@ export function createMemoryCore( : []; const turns: EpisodeTurn[] = []; for (const tr of traces) { + const turnId = + typeof tr.turnId === "number" && Number.isFinite(tr.turnId) + ? (tr.turnId as EpochMs) + : tr.ts; if (tr.userText) { turns.push({ id: `${tr.id}:user`, - ts: tr.ts, + ts: turnId, role: "user", content: tr.userText, }); @@ -4536,6 +4610,26 @@ export function createMemoryCore( return true; } + function rewardWasSkipped( + ep: EpisodeRow & { meta?: Record }, + ): boolean { + const reward = ep.meta?.reward; + return Boolean( + reward && + typeof reward === "object" && + (reward as { skipped?: unknown }).skipped === true, + ); + } + + function hasRewardDirtyMarker( + ep: EpisodeRow & { meta?: Record }, + ): boolean { + return Boolean( + ep.meta?.rewardDirty && + typeof ep.meta.rewardDirty === "object", + ); + } + function collectEmbeddingSlots(): EmbeddingSlot[] { const slots: EmbeddingSlot[] = []; const pageSize = 500; diff --git a/apps/memos-local-plugin/core/pipeline/orchestrator.ts b/apps/memos-local-plugin/core/pipeline/orchestrator.ts index 62e44e017..ad6fc3c44 100644 --- a/apps/memos-local-plugin/core/pipeline/orchestrator.ts +++ b/apps/memos-local-plugin/core/pipeline/orchestrator.ts @@ -77,6 +77,7 @@ import type { } from "../retrieval/types.js"; import type { CoreEvent, CoreEventType } from "../../agent-contract/events.js"; import type { LogRecord } from "../../agent-contract/log-record.js"; +import { ERROR_CODES, MemosError } from "../../agent-contract/errors.js"; import { memoryBuffer } from "../logger/index.js"; import { onBroadcastLog } from "../logger/transports/sse-broadcast.js"; import { createEmbeddingRetryWorker, systemErrorEvent } from "../embedding/index.js"; @@ -300,6 +301,19 @@ export function createPipeline(deps: PipelineDeps): PipelineHandle { // when the adapter doesn't pass its own. const lastUserTextBySession = new Map(); + // Keep one idempotent turn-start promise per session. Storing the promise, + // rather than only the resolved packet, also collapses concurrent retries + // that arrive while the first retrieval is still running. A new turnKey + // replaces the prior entry, so this stays bounded to O(active sessions). + const turnStartBySession = new Map< + SessionId, + { + turnKey: string; + userText: string; + packet: Promise; + } + >(); + // When a session is closed (e.g. adapter fires `session_end`), purge // every orchestrator-local map entry for that session. Without this, // `openEpisodeIfNeeded` would still see the stale `lastEpisodeBySession` @@ -312,6 +326,7 @@ export function createPipeline(deps: PipelineDeps): PipelineHandle { openEpisodeBySession.delete(sid); lastEpisodeBySession.delete(sid); lastUserTextBySession.delete(sid); + turnStartBySession.delete(sid); log.debug("session.maps_cleared", { sessionId: sid, reason: evt.reason }); }); @@ -1117,6 +1132,48 @@ export function createPipeline(deps: PipelineDeps): PipelineHandle { // ─── Turn lifecycle ───────────────────────────────────────────────────── async function onTurnStart(input: TurnInputDTO): Promise { + const turnKey = input.turnKey?.trim(); + if (!turnKey) { + return onTurnStartOnce(input); + } + + const existing = turnStartBySession.get(input.sessionId); + if (existing?.turnKey === turnKey) { + if (existing.userText !== input.userText) { + throw new MemosError( + ERROR_CODES.CONFLICT, + "turn.start: turnKey was reused with different user text", + { + sessionId: input.sessionId, + turnKey, + }, + ); + } + log.debug("turn.start.idempotent_reuse", { + sessionId: input.sessionId, + turnKey, + }); + return existing.packet; + } + + const packet = onTurnStartOnce(input); + turnStartBySession.set(input.sessionId, { + turnKey, + userText: input.userText, + packet, + }); + try { + return await packet; + } catch (err) { + const current = turnStartBySession.get(input.sessionId); + if (current?.packet === packet) { + turnStartBySession.delete(input.sessionId); + } + throw err; + } + } + + async function onTurnStartOnce(input: TurnInputDTO): Promise { const t0 = now(); const initialSessionId = await ensureSession( input.agent, diff --git a/apps/memos-local-plugin/core/reward/reward.ts b/apps/memos-local-plugin/core/reward/reward.ts index 1b6d3354c..0da87e5cb 100644 --- a/apps/memos-local-plugin/core/reward/reward.ts +++ b/apps/memos-local-plugin/core/reward/reward.ts @@ -128,6 +128,11 @@ export function createRewardRunner(deps: RewardDeps): RewardRunner { trigger: input.trigger, skipped: true, }, + // A trivial/short episode is a terminal, intentional skip rather + // than a failed reward run. Clear any recovery marker inherited + // from an earlier capture/reward attempt so automatic rescans do + // not keep reflecting the same trace forever. + rewardDirty: undefined, }); } catch (err) { warnings.push({ diff --git a/apps/memos-local-plugin/install.ps1 b/apps/memos-local-plugin/install.ps1 index 098b7b4e7..ed8d3a17b 100644 --- a/apps/memos-local-plugin/install.ps1 +++ b/apps/memos-local-plugin/install.ps1 @@ -437,6 +437,20 @@ function Install-Hermes { if (-not $PluginDir -or -not (Test-Path $PluginDir)) { Stop-Die "plugins\memory not found" } + $VersionSyncScript = Join-Path $Prefix "scripts\sync-hermes-version.cjs" + if (Test-Path $VersionSyncScript) { + & node $VersionSyncScript $Prefix + if ($LASTEXITCODE -ne 0) { + Stop-Die "Failed to synchronize Hermes plugin version metadata." + } + } else { + Write-Warn "Hermes version sync helper missing; using packaged plugin.yaml as-is." + } + Copy-Item -Path (Join-Path $AdapterDir "plugin.yaml") -Destination (Join-Path $AdapterDir "memos_provider\plugin.yaml") -ErrorAction SilentlyContinue + if (-not (Test-Path (Join-Path $AdapterDir "memos_provider\plugin.yaml"))) { + Write-Warning "plugin.yaml copy may have failed; verify $AdapterDir\memos_provider\plugin.yaml exists." + } + $UserPluginDir = Join-Path $env:LOCALAPPDATA "hermes\plugins\memory" New-Item -ItemType Directory -Path $UserPluginDir -Force | Out-Null Write-Host "Ensuring user plugin dir: $UserPluginDir" @@ -453,11 +467,6 @@ function Install-Hermes { Write-Warning "Failed to create junction at $Target : $_" } } - Copy-Item -Path (Join-Path $AdapterDir "plugin.yaml") -Destination (Join-Path $AdapterDir "memos_provider\plugin.yaml") -ErrorAction SilentlyContinue - if (-not (Test-Path (Join-Path $AdapterDir "memos_provider\plugin.yaml"))) { - Write-Warning "plugin.yaml copy may have failed; verify $AdapterDir\memos_provider\plugin.yaml exists." - } - if (Test-Path $ConfigFile) { $PyScript = @" import sys, yaml diff --git a/apps/memos-local-plugin/install.sh b/apps/memos-local-plugin/install.sh index 20135e3f7..f74e5e089 100755 --- a/apps/memos-local-plugin/install.sh +++ b/apps/memos-local-plugin/install.sh @@ -734,6 +734,13 @@ except Exception: step "Linking memtensor provider" local user_plugin_dir="${HOME}/.hermes/plugins/memory" mkdir -p "${user_plugin_dir}" + local version_sync="${prefix}/scripts/sync-hermes-version.cjs" + if [[ -f "${version_sync}" ]]; then + node "${version_sync}" "${prefix}" >/dev/null \ + || die "Failed to synchronize Hermes plugin version metadata." + else + warn "Hermes version sync helper missing; using packaged plugin.yaml as-is." + fi # Ensure the provider directory is fully populated before symlinking so # the second symlink (user-level) already points at a complete tree. cp "${adapter_dir}/plugin.yaml" "${adapter_dir}/memos_provider/plugin.yaml" 2>/dev/null || true diff --git a/apps/memos-local-plugin/package-lock.json b/apps/memos-local-plugin/package-lock.json index 1fdee41b5..46db4c00b 100644 --- a/apps/memos-local-plugin/package-lock.json +++ b/apps/memos-local-plugin/package-lock.json @@ -1,12 +1,12 @@ { "name": "@memtensor/memos-local-plugin", - "version": "2.0.11", + "version": "2.0.12-beta.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@memtensor/memos-local-plugin", - "version": "2.0.11", + "version": "2.0.12-beta.1", "hasInstallScript": true, "license": "MIT", "dependencies": { diff --git a/apps/memos-local-plugin/package.json b/apps/memos-local-plugin/package.json index 49c767f9f..48e07b94b 100644 --- a/apps/memos-local-plugin/package.json +++ b/apps/memos-local-plugin/package.json @@ -1,6 +1,6 @@ { "name": "@memtensor/memos-local-plugin", - "version": "2.0.11", + "version": "2.0.12-beta.1", "description": "Reflect2Evolve memory plugin: layered L1/L2/L3 memory, reflection-weighted value backprop, cross-task policy induction, skill crystallization, three-tier retrieval. Adapters for OpenClaw and Hermes Agent via a shared algorithm core.", "type": "module", "main": "dist/core/index.js", @@ -33,6 +33,7 @@ "templates/README.user.md", "viewer/dist", "scripts/postinstall.cjs", + "scripts/sync-hermes-version.cjs", "install.sh", "install.ps1", "tsconfig.json", @@ -49,7 +50,9 @@ "build": "tsc -p tsconfig.build.json && node scripts/copy-runtime-assets.cjs", "build:viewer": "vite build --config vite.config.ts", "build:package": "npm run build && npm run build:viewer", - "prepack": "npm run build:package", + "prepack": "npm run check:hermes-version && npm run build:package", + "sync:hermes-version": "node scripts/sync-hermes-version.cjs", + "check:hermes-version": "node scripts/sync-hermes-version.cjs --check", "dev": "tsc -p tsconfig.json --watch", "viewer:dev": "vite --config vite.config.ts", "bridge": "tsx bridge.cts", diff --git a/apps/memos-local-plugin/scripts/sync-hermes-version.cjs b/apps/memos-local-plugin/scripts/sync-hermes-version.cjs new file mode 100644 index 000000000..088f5e2b2 --- /dev/null +++ b/apps/memos-local-plugin/scripts/sync-hermes-version.cjs @@ -0,0 +1,59 @@ +#!/usr/bin/env node +"use strict"; + +const fs = require("node:fs"); +const path = require("node:path"); + +const args = process.argv.slice(2); +const checkOnly = args.includes("--check"); +const rootArg = args.find((arg) => arg !== "--check"); +const root = path.resolve(rootArg || path.join(__dirname, "..")); +const packageJsonPath = path.join(root, "package.json"); +const manifestPath = path.join(root, "adapters", "hermes", "plugin.yaml"); + +function fail(message) { + process.stderr.write(`Hermes version sync failed: ${message}\n`); + process.exit(1); +} + +if (!fs.existsSync(packageJsonPath)) { + fail(`package.json not found at ${packageJsonPath}`); +} +if (!fs.existsSync(manifestPath)) { + fail(`Hermes manifest not found at ${manifestPath}`); +} + +let packageJson; +try { + packageJson = JSON.parse(fs.readFileSync(packageJsonPath, "utf8")); +} catch (error) { + fail(`cannot parse ${packageJsonPath}: ${error.message}`); +} + +const version = + typeof packageJson.version === "string" ? packageJson.version.trim() : ""; +if (!version) { + fail(`${packageJsonPath} has no non-empty version`); +} + +const manifest = fs.readFileSync(manifestPath, "utf8"); +const versionLine = /^version:\s*.*$/m; +if (!versionLine.test(manifest)) { + fail(`${manifestPath} has no top-level version field`); +} + +const synchronized = manifest.replace(versionLine, `version: ${version}`); +if (checkOnly) { + if (synchronized !== manifest) { + fail(`manifest version does not match package.json (${version})`); + } + process.stdout.write(`Hermes manifest version is synchronized: ${version}\n`); + process.exit(0); +} + +if (synchronized !== manifest) { + fs.writeFileSync(manifestPath, synchronized, "utf8"); + process.stdout.write(`Synchronized Hermes manifest version to ${version}\n`); +} else { + process.stdout.write(`Hermes manifest version already synchronized: ${version}\n`); +} diff --git a/apps/memos-local-plugin/server/routes/admin.ts b/apps/memos-local-plugin/server/routes/admin.ts index a8daad553..f70d52b77 100644 --- a/apps/memos-local-plugin/server/routes/admin.ts +++ b/apps/memos-local-plugin/server/routes/admin.ts @@ -12,9 +12,9 @@ * Agent-aware restart. For OpenClaw the plugin lives inside the * gateway process, which is managed by macOS launchd — calling * `process.exit(0)` causes launchd to respawn it automatically. - * For Hermes the HTTP viewer is the long-lived smoke/daemon bridge. - * Do NOT restart this process; terminate the active `hermes chat` - * process so the user can relaunch it and reconnect to this viewer. + * For Hermes, terminate the active `hermes chat`, then ask the bridge + * to shut down gracefully. launchd/systemd owns replacement when the + * viewer is supervised; portable viewers retain the detached fallback. */ import { spawn } from "node:child_process"; import type { ServerDeps, ServerOptions } from "../types.js"; @@ -44,24 +44,15 @@ export function registerAdminRoutes(routes: Routes, deps: ServerDeps, options: S if (agent === "hermes" && deps.home?.root) { try { await fs.unlink(`${deps.home.root}/bridge-status.json`); } catch { /* may not exist */ } } - if (agent !== "openclaw") { - // Hermes: spawn replacement daemon after clearing data - const nodePath = await import("node:path"); - const { fileURLToPath } = await import("node:url"); - const { spawn } = await import("node:child_process"); - const thisFile = fileURLToPath(import.meta.url); - const pluginRoot = nodePath.resolve(nodePath.dirname(thisFile), "../.."); - const tsxBin = nodePath.join(pluginRoot, "node_modules/.bin/tsx"); - const bridgeScript = nodePath.join(pluginRoot, "bridge.cts"); - const cmd = `sleep 3 && "${process.execPath}" "${tsxBin}" "${bridgeScript}" --agent=${agent} --daemon`; - const child = spawn("bash", ["-c", cmd], { - detached: true, - stdio: "ignore", - cwd: pluginRoot, - }); - child.unref(); + if (agent !== "openclaw" && !isSupervisorManaged(options)) { + // Portable Hermes: there is no supervisor to replace this process. + await spawnReplacementDaemon(agent); + } + if (agent === "hermes") { + scheduleHermesShutdown(options, 200); + } else { + setTimeout(() => process.exit(0), 200); } - setTimeout(() => process.exit(0), 200); return { ok: true, restarting: true, killedHermes }; }); @@ -74,13 +65,72 @@ export function registerAdminRoutes(routes: Routes, deps: ServerDeps, options: S if (agent === "hermes") { const killed = await terminateHermesChat(); - return { ok: true, restarting: false, killed }; + if (!isSupervisorManaged(options)) { + await spawnReplacementDaemon(agent); + } + scheduleHermesShutdown(options, 200); + return { ok: true, restarting: true, killed }; } return { ok: false, error: `restart unsupported for agent: ${agent}` }; }); } +/** + * Detect the supervisors used by supported desktop/server installs. + * + * The MemOS launchd job exports its stable label through XPC_SERVICE_NAME. + * Do not treat arbitrary GUI-app XPC labels as supervision: a portable + * daemon launched from such an app would exit with nobody to replace it. + * systemd services expose INVOCATION_ID for the invocation. + */ +export function isSupervisorManagedProcess( + env: NodeJS.ProcessEnv = process.env, +): boolean { + const xpcService = env.XPC_SERVICE_NAME?.trim(); + if (xpcService?.startsWith("ai.memtensor.memos-local-hermes")) return true; + return Boolean(env.INVOCATION_ID?.trim()); +} + +function isSupervisorManaged(options: ServerOptions): boolean { + return options.lifecycle?.supervised ?? isSupervisorManagedProcess(); +} + +function scheduleHermesShutdown(options: ServerOptions, delayMs: number): void { + setTimeout(() => { + if (options.lifecycle?.requestShutdown) { + options.lifecycle.requestShutdown(); + return; + } + // The bridge entry owns SIGINT/SIGTERM and drains the HTTP server, + // MemoryCore, telemetry and SQLite before exiting. Do not call + // process.exit() here: that bypasses the bridge's graceful path. + process.kill(process.pid, "SIGTERM"); + }, delayMs); +} + +async function spawnReplacementDaemon(agent: string): Promise { + const fs = await import("node:fs"); + const nodePath = await import("node:path"); + const { fileURLToPath } = await import("node:url"); + const thisFile = fileURLToPath(import.meta.url); + let pluginRoot = nodePath.resolve(nodePath.dirname(thisFile), "../.."); + // Source: /server/routes/admin.ts. Built package: + // /dist/server/routes/admin.js. + if (!fs.existsSync(nodePath.join(pluginRoot, "package.json"))) { + pluginRoot = nodePath.resolve(pluginRoot, ".."); + } + const tsxBin = nodePath.join(pluginRoot, "node_modules/.bin/tsx"); + const bridgeScript = nodePath.join(pluginRoot, "bridge.cts"); + const cmd = `sleep 3 && "${process.execPath}" "${tsxBin}" "${bridgeScript}" --agent=${agent} --daemon`; + const child = spawn("bash", ["-c", cmd], { + detached: true, + stdio: "ignore", + cwd: pluginRoot, + }); + child.unref(); +} + async function terminateHermesChat(): Promise { // Match the Hermes CLI wrapper used by install.sh without touching // `bridge.cts --daemon`, which owns the Memory Viewer port. diff --git a/apps/memos-local-plugin/server/types.ts b/apps/memos-local-plugin/server/types.ts index 8532101ef..9667e8a99 100644 --- a/apps/memos-local-plugin/server/types.ts +++ b/apps/memos-local-plugin/server/types.ts @@ -39,6 +39,20 @@ export interface ServerOptions { * installed on disk. */ agent?: "openclaw" | "hermes"; + /** + * Process lifecycle hooks used by the admin restart route. + * + * A supervised Hermes viewer must let launchd/systemd perform the + * replacement; spawning a second daemon from the route races the + * supervisor's KeepAlive restart. Tests and portable embedders may + * override the auto-detection and shutdown action explicitly. + */ + lifecycle?: { + /** Override launchd/systemd detection. */ + supervised?: boolean; + /** Request graceful host shutdown after the HTTP response is returned. */ + requestShutdown?: () => void; + }; } export interface ServerHandle { diff --git a/apps/memos-local-plugin/tests/python/test_bridge_client.py b/apps/memos-local-plugin/tests/python/test_bridge_client.py index 3322de7ed..82763fcea 100644 --- a/apps/memos-local-plugin/tests/python/test_bridge_client.py +++ b/apps/memos-local-plugin/tests/python/test_bridge_client.py @@ -44,6 +44,7 @@ class FakePopen: def __init__(self, *_args, **_kwargs) -> None: self.cmd = list(_args[0]) if _args else [] + self.env = dict(_kwargs.get("env") or {}) self.pid = 12345 self.stdin = io.StringIO() self._stdin_lines: list[str] = [] @@ -346,6 +347,23 @@ def test_module_singleton_independent_for_distinct_agents(self) -> None: hermes.close() openclaw.close() + def test_module_singleton_isolated_for_distinct_runtime_homes(self) -> None: + """Different MemOS data homes must not displace each other's client.""" + with tempfile.TemporaryDirectory() as root: + first = MemosBridgeClient( + bridge_path="/tmp/bridge.cts", + runtime_home=str(Path(root) / "home-a"), + ) + second = MemosBridgeClient( + bridge_path="/tmp/bridge.cts", + runtime_home=str(Path(root) / "home-b"), + ) + + self.assertFalse(first._closed) + self.assertFalse(second._closed) + first.close() + second.close() + def test_close_unregisters_active_client_only_when_still_current(self) -> None: """A stale close() must not evict the newer registered client.""" first = MemosBridgeClient(bridge_path="/tmp/bridge.cts") @@ -353,7 +371,11 @@ def test_close_unregisters_active_client_only_when_still_current(self) -> None: # First was already closed by second's __init__. Closing it again is # a no-op and must not touch the registry's current entry (second). first.close() - key = (second._singleton_agent, second._singleton_no_viewer) + key = ( + second._singleton_agent, + second._singleton_no_viewer, + second._singleton_runtime_home, + ) self.assertIs(bridge_client_mod._ACTIVE_CLIENTS.get(key), second) second.close() self.assertIsNone(bridge_client_mod._ACTIVE_CLIENTS.get(key)) @@ -365,6 +387,40 @@ def test_stdio_bridge_starts_without_viewer_by_default(self) -> None: self.assertIn("--no-viewer", cmd) client.close() + def test_stdio_bridge_passes_stable_runtime_scope(self) -> None: + with tempfile.TemporaryDirectory() as root: + client = MemosBridgeClient( + bridge_path="/tmp/bridge.cts", + runtime_home=root, + ) + assert self._fake is not None + scope_args = [ + arg for arg in getattr(self._fake, "cmd", []) if arg.startswith("--runtime-scope=") + ] + self.assertEqual(len(scope_args), 1) + token = scope_args[0].split("=", 1)[1] + self.assertRegex(token, r"^[a-f0-9]{24}$") + self.assertEqual( + self._fake.env["MEMOS_HOME"], + str(Path(root).resolve()), + ) + client.close() + + def test_runtime_home_uses_captured_child_environment(self) -> None: + with tempfile.TemporaryDirectory() as root: + runtime_home = str(Path(root) / "captured-home") + client = MemosBridgeClient( + bridge_path="/tmp/bridge.cts", + extra_env={"MEMOS_HOME": runtime_home}, + ) + assert self._fake is not None + self.assertEqual( + client._singleton_runtime_home, + str(Path(runtime_home).resolve()), + ) + self.assertEqual(self._fake.env["MEMOS_HOME"], runtime_home) + client.close() + def test_reverse_request_waits_for_late_host_handler_registration(self) -> None: client = MemosBridgeClient(bridge_path="/tmp/bridge.cts") assert self._fake is not None @@ -473,8 +529,10 @@ def setUp(self) -> None: import memos_provider self._provider_mod = memos_provider + self._provider_mod.SHARED_BRIDGE_REGISTRY.close_all() self._patches = [ + patch.dict("os.environ", {"MEMOS_HERMES_BRIDGE_MODE": "legacy"}), patch("memos_provider.ensure_bridge_running", return_value=True), patch("memos_provider.ensure_viewer_daemon", return_value=True), ] @@ -482,6 +540,7 @@ def setUp(self) -> None: p.start() def tearDown(self) -> None: + self._provider_mod.SHARED_BRIDGE_REGISTRY.close_all() for p in self._patches: p.stop() @@ -677,6 +736,7 @@ def test_on_turn_start_stashes_message(self) -> None: def test_on_delegation_is_noop_without_bridge(self) -> None: p = self._provider_mod.MemTensorProvider() + p._bridge_keepalive_stop.set() p.on_delegation("run tests", "all green") # must not raise def test_on_pre_compress_without_bridge_returns_empty(self) -> None: diff --git a/apps/memos-local-plugin/tests/python/test_hermes_provider_pipeline.py b/apps/memos-local-plugin/tests/python/test_hermes_provider_pipeline.py index 71e3b347b..7ecaccb89 100644 --- a/apps/memos-local-plugin/tests/python/test_hermes_provider_pipeline.py +++ b/apps/memos-local-plugin/tests/python/test_hermes_provider_pipeline.py @@ -68,6 +68,24 @@ def request(self, method: str, params: dict | None = None, **_kwargs: object) -> class HermesProviderPipelineTests(unittest.TestCase): + def setUp(self) -> None: + memos_provider.SHARED_BRIDGE_REGISTRY.close_all() + self._mode_patch = patch.dict( + "os.environ", + {"MEMOS_HERMES_BRIDGE_MODE": "legacy"}, + ) + self._mode_patch.start() + + def tearDown(self) -> None: + memos_provider.SHARED_BRIDGE_REGISTRY.close_all() + self._mode_patch.stop() + + def test_plugin_version_matches_package_version(self) -> None: + package_json = _ADAPTER_ROOT.parent.parent / "package.json" + package_version = json.loads(package_json.read_text(encoding="utf-8"))["version"] + + self.assertEqual(memos_provider.PLUGIN_VERSION, package_version) + def test_module_imports_cleanly(self) -> None: """Regression guard for #2096: asserts that ``MemosHttpClient`` is NOT present in ``memos_provider``, since the class was referenced @@ -186,7 +204,7 @@ def test_initialize_closes_previous_bridge_before_spawning_new_one(self) -> None patch("memos_provider.ensure_viewer_daemon", return_value=True), patch( "memos_provider.MemosBridgeClient", - side_effect=lambda: bridge_attempts.pop(0), + side_effect=lambda **_kwargs: bridge_attempts.pop(0), ), ): provider = memos_provider.MemTensorProvider() @@ -251,7 +269,7 @@ def close(self) -> None: patch("memos_provider.ensure_viewer_daemon", return_value=True), patch( "memos_provider.MemosBridgeClient", - side_effect=lambda: bridge_attempts.pop(0), + side_effect=lambda **_kwargs: bridge_attempts.pop(0), ), ): provider = memos_provider.MemTensorProvider() @@ -272,7 +290,7 @@ def test_sync_turn_recovers_when_initial_bridge_open_timed_out(self) -> None: recovered_bridge = FakeBridge() bridge_attempts = [failed_bridge, recovered_bridge] - def bridge_factory() -> FakeBridge: + def bridge_factory(**_kwargs: object) -> FakeBridge: return bridge_attempts.pop(0) with ( @@ -308,7 +326,10 @@ def test_delegation_recovers_when_initial_bridge_open_timed_out(self) -> None: with ( patch("memos_provider.ensure_bridge_running", return_value=True), patch("memos_provider.ensure_viewer_daemon", return_value=True), - patch("memos_provider.MemosBridgeClient", side_effect=lambda: bridge_attempts.pop(0)), + patch( + "memos_provider.MemosBridgeClient", + side_effect=lambda **_kwargs: bridge_attempts.pop(0), + ), ): provider = memos_provider.MemTensorProvider() provider.initialize("slow-parent-session") @@ -379,7 +400,7 @@ def test_internal_hermes_review_prompt_is_not_persisted_as_user_turn(self) -> No self.assertFalse(any(method == "turn.start" for method, _ in bridge.calls)) self.assertFalse(any(method == "turn.end" for method, _ in bridge.calls)) - def test_on_pre_compress_reuses_last_user_text_for_snapshot(self) -> None: + def test_on_pre_compress_reuses_cached_prefetch_without_starting_turn(self) -> None: bridge = FakeBridge() with ( patch("memos_provider.ensure_bridge_running", return_value=True), @@ -389,13 +410,52 @@ def test_on_pre_compress_reuses_last_user_text_for_snapshot(self) -> None: provider = memos_provider.MemTensorProvider() provider.initialize("compress-session") provider.on_turn_start(2, "compress HERMES_MEMOS_E2E_0428 context") + provider.prefetch("compress HERMES_MEMOS_E2E_0428 context") + episode_id = provider._episode_id + turn_starts_before = sum(method == "turn.start" for method, _ in bridge.calls) snapshot = provider.on_pre_compress([{"role": "user", "content": "x"}]) + repeated = provider.on_pre_compress([{"role": "user", "content": "x"}]) self.assertIn("MemOS memory snapshot", snapshot) self.assertIn("remembered HERMES_MEMOS_E2E_0428", snapshot) - self.assertEqual(bridge.calls[-1][0], "turn.start") - self.assertIn("HERMES_MEMOS_E2E_0428", bridge.calls[-1][1]["userText"]) + self.assertEqual(repeated, snapshot) + self.assertEqual(provider._episode_id, episode_id) + self.assertEqual( + sum(method == "turn.start" for method, _ in bridge.calls), + turn_starts_before, + ) + + def test_on_pre_compress_without_cached_prefetch_is_read_only(self) -> None: + bridge = FakeBridge() + with ( + patch("memos_provider.ensure_bridge_running", return_value=True), + patch("memos_provider.ensure_viewer_daemon", return_value=True), + patch("memos_provider.MemosBridgeClient", return_value=bridge), + ): + provider = memos_provider.MemTensorProvider() + provider.initialize("compress-session") + provider.on_turn_start(1, "first turn") + + snapshot = provider.on_pre_compress([{"role": "user", "content": "first turn"}]) + + self.assertEqual(snapshot, "") + self.assertFalse(any(method == "turn.start" for method, _ in bridge.calls)) + + def test_prefetch_passes_stable_turn_key_to_bridge(self) -> None: + bridge = FakeBridge() + with ( + patch("memos_provider.ensure_bridge_running", return_value=True), + patch("memos_provider.ensure_viewer_daemon", return_value=True), + patch("memos_provider.MemosBridgeClient", return_value=bridge), + ): + provider = memos_provider.MemTensorProvider() + provider.initialize("turn-key-session") + provider.on_turn_start(7, "continue the task") + provider.prefetch("continue the task") + + turn_start = next(params for method, params in bridge.calls if method == "turn.start") + self.assertEqual(turn_start["turnKey"], "turn-key-session:7") def test_prefetch_suppresses_memory_injection_for_explicit_delegation(self) -> None: bridge = FakeBridge() diff --git a/apps/memos-local-plugin/tests/python/test_shared_bridge_runtime.py b/apps/memos-local-plugin/tests/python/test_shared_bridge_runtime.py new file mode 100644 index 000000000..1cbc95ae8 --- /dev/null +++ b/apps/memos-local-plugin/tests/python/test_shared_bridge_runtime.py @@ -0,0 +1,553 @@ +"""Concurrency and lifecycle tests for the Hermes shared bridge runtime.""" + +from __future__ import annotations + +import sys +import threading +import unittest + +from pathlib import Path +from unittest.mock import patch + + +_ADAPTER_ROOT = Path(__file__).resolve().parent.parent.parent / "adapters" / "hermes" +_PLUGIN_DIR = _ADAPTER_ROOT / "memos_provider" +for _p in (_ADAPTER_ROOT, _PLUGIN_DIR): + if str(_p) not in sys.path: + sys.path.insert(0, str(_p)) + +import memos_provider # noqa: E402 + +from bridge_client import BridgeError # noqa: E402 +from shared_bridge_runtime import ( # noqa: E402 + HermesHookDispatcher, + SharedBridgeRuntimeRegistry, +) + + +class FakeBridge: + _next_pid = 4100 + + def __init__(self) -> None: + type(self)._next_pid += 1 + self.pid = type(self)._next_pid + self.closed = False + self.calls: list[tuple[str, dict]] = [] + self.handlers: dict[str, object] = {} + + def request(self, method: str, params: dict | None = None, **_kwargs: object) -> dict: + if self.closed: + raise BridgeError("transport_closed", "bridge client is closed") + payload = params or {} + self.calls.append((method, payload)) + if method == "core.health": + return {"ok": True} + if method == "session.open": + return {"sessionId": payload.get("sessionId")} + if method == "turn.start": + return { + "query": { + "sessionId": payload.get("sessionId"), + "episodeId": f"episode:{payload.get('sessionId')}", + }, + "injectedContext": "shared memory", + } + if method == "turn.end": + return {"traceIds": [f"trace:{payload.get('sessionId')}"]} + return {} + + def register_host_handler(self, method: str, handler: object) -> None: + self.handlers[method] = handler + + def close(self) -> None: + self.closed = True + + +class FakeManager: + def __init__(self) -> None: + self._hooks: dict[str, list[object]] = {} + + +class FakeProvider: + def __init__(self, session_id: str) -> None: + self._session_id = session_id + self.tool_calls = 0 + self.llm_calls = 0 + self.transforms = 0 + + def _on_post_tool_call(self, **_kwargs: object) -> None: + self.tool_calls += 1 + + def _on_post_llm_call(self, **_kwargs: object) -> None: + self.llm_calls += 1 + + def _on_transform_tool_result(self, **_kwargs: object) -> str: + self.transforms += 1 + return f"handled:{self._session_id}" + + +class SharedBridgeRuntimeTests(unittest.TestCase): + def setUp(self) -> None: + self.registry = SharedBridgeRuntimeRegistry( + keepalive_interval=3600.0, + keepalive_timeout=0.1, + ) + + def tearDown(self) -> None: + self.registry.close_all() + + def test_two_leases_share_one_bridge_and_release_does_not_close_it(self) -> None: + created: list[FakeBridge] = [] + + def factory(*_args: object, **_kwargs: object) -> FakeBridge: + bridge = FakeBridge() + created.append(bridge) + return bridge + + first = self.registry.acquire(("shared-home",), client_factory=factory) + second = self.registry.acquire(("shared-home",), client_factory=factory) + + self.assertEqual(len(created), 1) + self.assertEqual(first.pid, second.pid) + + first.close() + self.assertFalse(created[0].closed) + self.assertEqual(second.request("core.health"), {"ok": True}) + + second.close() + self.assertFalse(created[0].closed) + + def test_concurrent_reconnect_creates_one_replacement(self) -> None: + created: list[FakeBridge] = [] + + def factory(*_args: object, **_kwargs: object) -> FakeBridge: + bridge = FakeBridge() + created.append(bridge) + return bridge + + first = self.registry.acquire(("shared-home",), client_factory=factory) + second = self.registry.acquire(("shared-home",), client_factory=factory) + generation = first.generation + barrier = threading.Barrier(3) + + def reconnect(lease) -> None: + barrier.wait() + lease.reconnect(expected_generation=generation) + + threads = [ + threading.Thread(target=reconnect, args=(first,)), + threading.Thread(target=reconnect, args=(second,)), + ] + for thread in threads: + thread.start() + barrier.wait() + for thread in threads: + thread.join(timeout=2.0) + + self.assertEqual(len(created), 2) + self.assertTrue(created[0].closed) + self.assertEqual(first.generation, generation + 1) + self.assertEqual(first.pid, second.pid) + + def test_host_handler_is_registered_once_per_bridge_generation(self) -> None: + bridge = FakeBridge() + lease_a = self.registry.acquire(("shared-home",), client_factory=lambda: bridge) + lease_b = self.registry.acquire(("shared-home",), client_factory=lambda: bridge) + + def handler_a(_params: object) -> dict[str, str]: + return {"content": "a"} + + def handler_b(_params: object) -> dict[str, str]: + return {"content": "b"} + + lease_a.register_host_handler("host.llm.complete", handler_a) + lease_b.register_host_handler("host.llm.complete", handler_b) + + self.assertEqual(list(bridge.handlers), ["host.llm.complete"]) + dispatcher = bridge.handlers["host.llm.complete"] + self.assertEqual(dispatcher({}), {"content": "b"}) # type: ignore[operator] + + lease_b.close() + self.assertEqual(dispatcher({}), {"content": "a"}) # type: ignore[operator] + + def test_initial_host_handler_is_installed_before_first_health_check(self) -> None: + class StartupBridge(FakeBridge): + def request( + self, + method: str, + params: dict | None = None, + **kwargs: object, + ) -> dict: + if method == "core.health": + self_test.assertIn("host.llm.complete", self.handlers) + return super().request(method, params, **kwargs) + + self_test = self + + def handler(_params: object) -> dict[str, str]: + return {"content": "ready"} + + bridge = StartupBridge() + lease = self.registry.acquire( + ("shared-home",), + client_factory=lambda: bridge, + host_handlers={"host.llm.complete": handler}, + ) + + dispatcher = bridge.handlers["host.llm.complete"] + self.assertEqual(dispatcher({}), {"content": "ready"}) # type: ignore[operator] + lease.close() + + def test_runtime_keys_isolate_distinct_data_homes(self) -> None: + created: list[FakeBridge] = [] + + def factory() -> FakeBridge: + bridge = FakeBridge() + created.append(bridge) + return bridge + + first = self.registry.acquire(("home-a",), client_factory=factory) + second = self.registry.acquire(("home-b",), client_factory=factory) + + self.assertEqual(len(created), 2) + self.assertNotEqual(first.pid, second.pid) + + def test_failed_new_acquire_does_not_revoke_existing_leases(self) -> None: + attempts = 0 + + def factory() -> FakeBridge: + nonlocal attempts + attempts += 1 + if attempts > 1: + raise RuntimeError("bridge spawn failed") + return FakeBridge() + + lease = self.registry.acquire(("shared-home",), client_factory=factory) + with self.assertRaises(RuntimeError): + lease.reconnect(expected_generation=lease.generation) + with self.assertRaises(BridgeError) as blocked: + self.registry.acquire(("shared-home",), client_factory=factory) + + self.assertIn("backing off", str(blocked.exception)) + self.assertEqual(lease.status()["leases"], 1) + + +class HermesHookDispatcherTests(unittest.TestCase): + def test_registers_one_global_hook_set_and_routes_by_session(self) -> None: + manager = FakeManager() + dispatcher = HermesHookDispatcher() + first = FakeProvider("session-a") + second = FakeProvider("session-b") + + dispatcher.bind(manager, first) + dispatcher.bind(manager, second) + dispatcher.bind(manager, second) + + self.assertEqual(len(manager._hooks["post_tool_call"]), 1) + self.assertEqual(len(manager._hooks["post_llm_call"]), 1) + self.assertEqual(len(manager._hooks["transform_tool_result"]), 1) + + manager._hooks["post_tool_call"][0](session_id="session-b") # type: ignore[operator] + self.assertEqual(first.tool_calls, 0) + self.assertEqual(second.tool_calls, 1) + + result = manager._hooks["transform_tool_result"][0](session_id="session-a") # type: ignore[operator] + self.assertEqual(result, "handled:session-a") + self.assertEqual(first.transforms, 1) + self.assertEqual(second.transforms, 0) + + def test_ambiguous_sessionless_event_is_not_broadcast(self) -> None: + manager = FakeManager() + dispatcher = HermesHookDispatcher() + first = FakeProvider("session-a") + second = FakeProvider("session-b") + dispatcher.bind(manager, first) + dispatcher.bind(manager, second) + + manager._hooks["post_tool_call"][0](session_id="") # type: ignore[operator] + + self.assertEqual(first.tool_calls, 0) + self.assertEqual(second.tool_calls, 0) + + def test_unbind_removes_provider_without_unregistering_global_hooks(self) -> None: + manager = FakeManager() + dispatcher = HermesHookDispatcher() + provider = FakeProvider("session-a") + dispatcher.bind(manager, provider) + + dispatcher.unbind(provider) + manager._hooks["post_llm_call"][0](session_id="session-a") # type: ignore[operator] + + self.assertEqual(provider.llm_calls, 0) + self.assertEqual(len(manager._hooks["post_llm_call"]), 1) + + +class SharedProviderIntegrationTests(unittest.TestCase): + def setUp(self) -> None: + memos_provider.SHARED_BRIDGE_REGISTRY.close_all() + self._mode_patch = patch.dict( + "os.environ", + { + "MEMOS_HERMES_BRIDGE_MODE": "shared", + "MEMOS_HOME": "/tmp/memos-hermes-shared-runtime-test", + }, + ) + self._mode_patch.start() + + def tearDown(self) -> None: + memos_provider.SHARED_BRIDGE_REGISTRY.close_all() + self._mode_patch.stop() + + def test_two_providers_share_physical_bridge_and_keep_sessions_isolated(self) -> None: + created: list[FakeBridge] = [] + + def factory(*_args: object, **_kwargs: object) -> FakeBridge: + bridge = FakeBridge() + created.append(bridge) + return bridge + + with ( + patch("memos_provider.MemosBridgeClient", side_effect=factory), + patch("memos_provider.ensure_bridge_running", return_value=True), + patch("memos_provider.ensure_viewer_daemon", return_value=True), + patch("memos_provider.kill_zombie_bridges", return_value=0) as kill_zombies, + ): + first = memos_provider.MemTensorProvider() + second = memos_provider.MemTensorProvider() + first.initialize("session-a") + second.initialize("session-b") + + self.assertEqual(len(created), 1) + self.assertEqual(first._bridge.pid, second._bridge.pid) + + first.prefetch("remember A") + second.prefetch("remember B") + first.sync_turn("remember A", "stored A") + second.sync_turn("remember B", "stored B") + kill_zombies.assert_not_called() + + first.shutdown() + self.assertFalse(created[0].closed) + self.assertIn("Recalled Memories", second.prefetch("still alive")) + second.shutdown() + self.assertFalse(created[0].closed) + + session_ids = [ + payload.get("sessionId") + for method, payload in created[0].calls + if method in {"session.open", "turn.start", "turn.end", "session.close"} + ] + self.assertIn("session-a", session_ids) + self.assertIn("session-b", session_ids) + + def test_lazy_provider_acquire_reuses_healthy_shared_bridge(self) -> None: + created: list[FakeBridge] = [] + + def factory(*_args: object, **_kwargs: object) -> FakeBridge: + bridge = FakeBridge() + created.append(bridge) + return bridge + + with ( + patch("memos_provider.MemosBridgeClient", side_effect=factory), + patch("memos_provider.ensure_bridge_running", return_value=True), + patch("memos_provider.ensure_viewer_daemon", return_value=True), + patch("memos_provider.kill_zombie_bridges", return_value=0), + ): + first = memos_provider.MemTensorProvider() + first.initialize("session-a") + assert first._bridge is not None + original_pid = first._bridge.pid + original_generation = first._bridge.generation + + second = memos_provider.MemTensorProvider() + second._session_id = "session-b" + self.assertTrue(second._ensure_bridge("session-b")) + + self.assertEqual(len(created), 1) + assert second._bridge is not None + self.assertEqual(second._bridge.pid, original_pid) + self.assertEqual(second._bridge.generation, original_generation) + self.assertEqual(second._bridge.status()["leases"], 2) + + first.shutdown() + second.shutdown() + + def test_distinct_data_home_runtime_keeps_its_spawn_environment(self) -> None: + created: list[FakeBridge] = [] + client_kwargs: list[dict[str, object]] = [] + + def factory(*_args: object, **kwargs: object) -> FakeBridge: + client_kwargs.append(dict(kwargs)) + bridge = FakeBridge() + created.append(bridge) + return bridge + + with ( + patch("memos_provider.MemosBridgeClient", side_effect=factory), + patch("memos_provider.ensure_bridge_running", return_value=True), + patch("memos_provider.ensure_viewer_daemon", return_value=True), + patch("memos_provider.kill_zombie_bridges", return_value=0), + ): + first = memos_provider.MemTensorProvider() + second = memos_provider.MemTensorProvider() + with patch.dict("os.environ", {"MEMOS_HOME": "/tmp/memos-home-a"}): + first.initialize("session-a") + with patch.dict("os.environ", {"MEMOS_HOME": "/tmp/memos-home-b"}): + second.initialize("session-b") + + self.assertEqual(len(created), 2) + home_a = str(Path("/tmp/memos-home-a").resolve()) + home_b = str(Path("/tmp/memos-home-b").resolve()) + self.assertEqual(client_kwargs[0]["runtime_home"], home_a) + self.assertEqual(client_kwargs[1]["runtime_home"], home_b) + + assert first._bridge is not None + with patch.dict("os.environ", {"MEMOS_HOME": "/tmp/memos-home-b"}): + first._bridge.reconnect(expected_generation=first._bridge.generation) + + self.assertEqual(len(created), 3) + self.assertEqual(client_kwargs[2]["runtime_home"], home_a) + self.assertEqual( + client_kwargs[2]["extra_env"], + {"MEMOS_HOME": home_a}, + ) + + first.shutdown() + second.shutdown() + + def test_lazy_acquire_failure_releases_new_lease(self) -> None: + class RejectSessionBridge(FakeBridge): + def request( + self, + method: str, + params: dict | None = None, + **kwargs: object, + ) -> dict: + if method == "session.open": + raise BridgeError("internal", "session rejected") + return super().request(method, params, **kwargs) + + with ( + patch( + "memos_provider.MemosBridgeClient", + side_effect=lambda *_args, **_kwargs: RejectSessionBridge(), + ), + patch("memos_provider.ensure_bridge_running", return_value=True), + patch("memos_provider.ensure_viewer_daemon", return_value=True), + patch("memos_provider.kill_zombie_bridges", return_value=0), + ): + provider = memos_provider.MemTensorProvider() + provider._session_id = "session-a" + + self.assertFalse(provider._ensure_bridge("session-a")) + self.assertIsNone(provider._bridge) + statuses = memos_provider.SHARED_BRIDGE_REGISTRY.status() + self.assertEqual(len(statuses), 1) + self.assertEqual(statuses[0]["leases"], 0) + + provider.shutdown() + + def test_lazy_acquire_reconnects_once_on_transport_closed(self) -> None: + created: list[FakeBridge] = [] + + class FirstSessionOpenFails(FakeBridge): + def request( + self, + method: str, + params: dict | None = None, + **kwargs: object, + ) -> dict: + if method == "session.open": + raise BridgeError("transport_closed", "bridge subprocess exited") + return super().request(method, params, **kwargs) + + def factory(*_args: object, **_kwargs: object) -> FakeBridge: + bridge = FirstSessionOpenFails() if not created else FakeBridge() + created.append(bridge) + return bridge + + with ( + patch("memos_provider.MemosBridgeClient", side_effect=factory), + patch("memos_provider.ensure_bridge_running", return_value=True), + patch("memos_provider.ensure_viewer_daemon", return_value=True), + patch("memos_provider.kill_zombie_bridges", return_value=0), + ): + provider = memos_provider.MemTensorProvider() + provider._session_id = "session-a" + + self.assertTrue(provider._ensure_bridge("session-a")) + self.assertEqual(len(created), 2) + self.assertTrue(created[0].closed) + assert provider._bridge is not None + self.assertEqual(provider._bridge.generation, 2) + self.assertEqual(provider._bridge.status()["leases"], 1) + + provider.shutdown() + + def test_existing_lease_is_retained_when_reconnect_fails(self) -> None: + attempts = 0 + + def factory(*_args: object, **_kwargs: object) -> FakeBridge: + nonlocal attempts + attempts += 1 + if attempts > 1: + raise RuntimeError("replacement spawn failed") + return FakeBridge() + + with ( + patch("memos_provider.MemosBridgeClient", side_effect=factory), + patch("memos_provider.ensure_bridge_running", return_value=True), + patch("memos_provider.ensure_viewer_daemon", return_value=True), + patch("memos_provider.kill_zombie_bridges", return_value=0), + ): + provider = memos_provider.MemTensorProvider() + provider.initialize("session-a") + original_lease = provider._bridge + assert original_lease is not None + + with self.assertRaises(RuntimeError): + provider._reconnect_bridge("session-a") + + self.assertIs(provider._bridge, original_lease) + self.assertEqual(original_lease.status()["leases"], 1) + + provider.shutdown() + + def test_provider_reopens_its_session_after_another_lease_reconnects(self) -> None: + created: list[FakeBridge] = [] + + def factory(*_args: object, **_kwargs: object) -> FakeBridge: + bridge = FakeBridge() + created.append(bridge) + return bridge + + with ( + patch("memos_provider.MemosBridgeClient", side_effect=factory), + patch("memos_provider.ensure_bridge_running", return_value=True), + patch("memos_provider.ensure_viewer_daemon", return_value=True), + patch("memos_provider.kill_zombie_bridges", return_value=0), + ): + first = memos_provider.MemTensorProvider() + second = memos_provider.MemTensorProvider() + first.initialize("session-a") + second.initialize("session-b") + + old_generation = first._bridge.generation + first._bridge.reconnect(expected_generation=old_generation) + self.assertEqual(len(created), 2) + + second.handle_tool_call("memos_search", {"query": "after reconnect"}) + methods = [method for method, _payload in created[1].calls] + session_open_index = methods.index("session.open") + search_index = methods.index("memory.search") + self.assertLess(session_open_index, search_index) + reopened = created[1].calls[session_open_index][1] + self.assertEqual(reopened["sessionId"], "session-b") + + first.shutdown() + second.shutdown() + + +if __name__ == "__main__": + unittest.main() diff --git a/apps/memos-local-plugin/tests/unit/bridge/methods.test.ts b/apps/memos-local-plugin/tests/unit/bridge/methods.test.ts index 2274a704a..8ee5fa921 100644 --- a/apps/memos-local-plugin/tests/unit/bridge/methods.test.ts +++ b/apps/memos-local-plugin/tests/unit/bridge/methods.test.ts @@ -333,6 +333,17 @@ describe("makeDispatcher", () => { ).rejects.toSatisfy( (err) => err instanceof MemosError && err.code === "invalid_argument", ); + await expect( + dispatch("turn.start", { + agent: "openclaw", + sessionId: "s-1", + turnKey: 42, + userText: "hi", + ts: 123, + }), + ).rejects.toSatisfy( + (err) => err instanceof MemosError && err.code === "invalid_argument", + ); }); it("feedback.submit forwards the DTO shape intact", async () => { diff --git a/apps/memos-local-plugin/tests/unit/capture/capture.test.ts b/apps/memos-local-plugin/tests/unit/capture/capture.test.ts index b30cbe4c1..e88a34f94 100644 --- a/apps/memos-local-plugin/tests/unit/capture/capture.test.ts +++ b/apps/memos-local-plugin/tests/unit/capture/capture.test.ts @@ -224,7 +224,7 @@ describe("capture/pipeline (end-to-end)", () => { it("recovered replay matches tool traces by payload when timestamps drift", async () => { tmp.repos.traces.insert(traceRow({ - id: "tr_tool", + id: "tr_tool_search", ts: 1_001, turnId: 1_000, userText: "run search", @@ -234,9 +234,19 @@ describe("capture/pipeline (end-to-end)", () => { output: "ok", }], })); + tmp.repos.traces.insert(traceRow({ + id: "tr_tool_read", + ts: 1_002, + turnId: 1_000, + toolCalls: [{ + name: "read", + input: { path: "/tmp/result" }, + output: "contents", + }], + })); tmp.repos.traces.insert(traceRow({ id: "tr_response", - ts: 1_003, + ts: 1_004, turnId: 1_000, agentText: "done", })); @@ -256,19 +266,70 @@ describe("capture/pipeline (end-to-end)", () => { input: { q: "memos" }, output: "ok", }), - turn("assistant", "done", 1_003), + turn("tool", "contents", 1_003, { + name: "read", + input: { path: "/tmp/result" }, + output: "contents", + }), + turn("assistant", "done", 1_004), ], }); - ep.meta = { recoveredAtStartup: 1_004, recoveryReason: "dirty_reward_rescore" }; + ep.meta = { recoveredAtStartup: 1_005, recoveryReason: "dirty_reward_rescore" }; const result = await runner.runReflect({ episode: ep, closedBy: "finalized" }); - expect(result.traceIds).toHaveLength(2); + expect(result.traceIds).toHaveLength(3); expect(result.warnings.some((w) => w.message.includes("skipped recovered orphan"))).toBe(false); - expect(tmp.repos.traces.listAllForEpisode("ep_1" as EpisodeId)).toHaveLength(2); + expect(tmp.repos.traces.listAllForEpisode("ep_1" as EpisodeId)).toHaveLength(3); }); - it("does not insert replay orphans for startup-recovered episodes by default", async () => { + it("fails a fully-unmatched recovered replay before LLM, inserts, or capture.done", async () => { + const llm = fakeLlm({ + complete: { + "capture.reflection.synth": "should never be requested", + }, + }); + const runner = buildRunner({ + alphaScoring: false, + synthReflections: true, + embedTraces: false, + }, llm, null); + const ep = episodeSnapshot({ + id: "ep_1", + sessionId: "se_1", + turns: [ + turn("user", "hello", 1_000), + turn("assistant", "hi", 1_010), + ], + }); + ep.meta = { recoveredAtStartup: 1_020, recoveryReason: "dirty_reward_rescore" }; + + await expect( + runner.runReflect({ episode: ep, closedBy: "finalized" }), + ).rejects.toMatchObject({ + name: "MemosError", + code: "conflict", + }); + + expect(tmp.repos.traces.listAllForEpisode("ep_1" as EpisodeId)).toHaveLength(0); + expect(llm.stats().requests).toBe(0); + expect(seen).toContainEqual(expect.objectContaining({ + kind: "capture.failed", + episodeId: "ep_1", + stage: "match", + error: expect.objectContaining({ code: "conflict" }), + })); + expect(seen.some((evt) => evt.kind === "capture.done")).toBe(false); + }); + + it("does not fail recovered replay when at least one trace matches", async () => { + tmp.repos.traces.insert(traceRow({ + id: "tr_matching", + ts: 1_010, + turnId: 1_000, + userText: "hello", + agentText: "hi", + })); const runner = buildRunner({ alphaScoring: false, synthReflections: false, @@ -280,15 +341,19 @@ describe("capture/pipeline (end-to-end)", () => { turns: [ turn("user", "hello", 1_000), turn("assistant", "hi", 1_010), + turn("user", "unmatched follow-up", 2_000), + turn("assistant", "unmatched answer", 2_010), ], }); - ep.meta = { recoveredAtStartup: 1_020, recoveryReason: "dirty_reward_rescore" }; + ep.meta = { recoveredAtStartup: 2_020, recoveryReason: "dirty_reward_rescore" }; const result = await runner.runReflect({ episode: ep, closedBy: "finalized" }); - expect(tmp.repos.traces.listAllForEpisode("ep_1" as EpisodeId)).toHaveLength(0); - expect(result.traceIds).toHaveLength(0); + expect(result.traceIds).toEqual(["tr_matching"]); expect(result.warnings.some((w) => w.message.includes("skipped recovered orphan"))).toBe(true); + expect(seen.some((evt) => evt.kind === "capture.failed")).toBe(false); + expect(seen.some((evt) => evt.kind === "capture.done")).toBe(true); + expect(tmp.repos.traces.listAllForEpisode("ep_1" as EpisodeId)).toHaveLength(1); }); it("caps reflect-phase LLM calls per episode", async () => { diff --git a/apps/memos-local-plugin/tests/unit/install/hermes-version-sync.test.ts b/apps/memos-local-plugin/tests/unit/install/hermes-version-sync.test.ts new file mode 100644 index 000000000..4c0a863e5 --- /dev/null +++ b/apps/memos-local-plugin/tests/unit/install/hermes-version-sync.test.ts @@ -0,0 +1,178 @@ +import { execFileSync, spawnSync } from "node:child_process"; +import { + mkdirSync, + mkdtempSync, + readFileSync, + rmSync, + writeFileSync, +} from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { afterEach, describe, expect, it } from "vitest"; + +const repoRoot = path.resolve(__dirname, "../../.."); +const syncScript = path.join(repoRoot, "scripts", "sync-hermes-version.cjs"); +const temporaryRoots: string[] = []; + +function createFixture(packageVersion: string, manifestVersion: string): string { + const root = mkdtempSync(path.join(tmpdir(), "memos-hermes-version-")); + temporaryRoots.push(root); + mkdirSync(path.join(root, "adapters", "hermes"), { recursive: true }); + writeFileSync( + path.join(root, "package.json"), + JSON.stringify({ name: "@memtensor/memos-local-plugin", version: packageVersion }), + "utf8", + ); + writeFileSync( + path.join(root, "adapters", "hermes", "plugin.yaml"), + `name: memtensor\nversion: ${manifestVersion}\ndescription: test fixture\n`, + "utf8", + ); + return root; +} + +afterEach(() => { + for (const root of temporaryRoots.splice(0)) { + rmSync(root, { recursive: true, force: true }); + } +}); + +describe("Hermes version synchronization", () => { + it("keeps the repository manifest aligned with package.json", () => { + const packageJson = JSON.parse( + readFileSync(path.join(repoRoot, "package.json"), "utf8"), + ) as { version: string }; + const manifest = readFileSync( + path.join(repoRoot, "adapters", "hermes", "plugin.yaml"), + "utf8", + ); + const manifestVersion = manifest.match(/^version:\s*(\S+)\s*$/m)?.[1]; + + expect(manifestVersion).toBe(packageJson.version); + }); + + it("writes package.json version into the Hermes manifest", () => { + const root = createFixture("9.8.7-beta.2", "2.0.0-beta.1"); + + execFileSync(process.execPath, [syncScript, root]); + + const manifest = readFileSync( + path.join(root, "adapters", "hermes", "plugin.yaml"), + "utf8", + ); + expect(manifest).toContain("version: 9.8.7-beta.2"); + expect(manifest).not.toContain("version: 2.0.0-beta.1"); + }); + + it("fails check mode for stale metadata and passes after synchronization", () => { + const root = createFixture("3.4.5", "3.4.4"); + + const staleCheck = spawnSync(process.execPath, [syncScript, "--check", root]); + expect(staleCheck.status).not.toBe(0); + + execFileSync(process.execPath, [syncScript, root]); + + const synchronizedCheck = spawnSync(process.execPath, [ + syncScript, + "--check", + root, + ]); + expect(synchronizedCheck.status).toBe(0); + }); + + it("packages the synchronization helper and keeps prepack read-only", () => { + const packageJson = JSON.parse( + readFileSync(path.join(repoRoot, "package.json"), "utf8"), + ) as { files: string[]; scripts: Record }; + + expect(packageJson.files).toContain("scripts/sync-hermes-version.cjs"); + expect(packageJson.scripts["sync:hermes-version"]).toBe( + "node scripts/sync-hermes-version.cjs", + ); + expect(packageJson.scripts.prepack).toBe( + "npm run check:hermes-version && npm run build:package", + ); + }); + + it("synchronizes before tests and publishes the validated tarball", () => { + const workflow = readFileSync( + path.resolve(repoRoot, "../../.github/workflows/memos-local-plugin-publish.yml"), + "utf8", + ); + const publishHelper = readFileSync( + path.resolve(repoRoot, "../../.github/scripts/publish-local-plugin.sh"), + "utf8", + ); + + const bumpPosition = workflow.indexOf('npm version "${RELEASE_VERSION}"'); + const syncPosition = workflow.indexOf("npm run sync:hermes-version"); + const checkPosition = workflow.indexOf("npm run check:hermes-version"); + const testPosition = workflow.indexOf('"npm test"'); + + expect(bumpPosition).toBeGreaterThan(-1); + expect(syncPosition).toBeGreaterThan(bumpPosition); + expect(checkPosition).toBeGreaterThan(syncPosition); + expect(testPosition).toBeGreaterThan(checkPosition); + expect(workflow).toContain("npm pack --json --silent --pack-destination"); + expect(workflow).toContain("raw.match(/^\\[/m)"); + expect(workflow).toContain( + "fs.writeFileSync(process.argv[1], `${JSON.stringify(report, null, 2)}\\n`)", + ); + expect(workflow).not.toContain("npm pack --dry-run"); + expect(workflow).toContain( + "run: bash ../../.github/scripts/publish-local-plugin.sh", + ); + expect(workflow).toContain( + "tar -xOf \"${release_tarball}\" package/adapters/hermes/plugin.yaml", + ); + expect(publishHelper).toContain('npm publish "${RELEASE_TARBALL}"'); + expect(publishHelper).toContain("verify_published_package"); + expect(publishHelper).toContain( + "tar -xOf \"${verify_tarball}\" package/adapters/hermes/plugin.yaml", + ); + expect(workflow).toMatch( + /git add \\\n\s+apps\/memos-local-plugin\/package\.json \\\n\s+apps\/memos-local-plugin\/package-lock\.json \\\n\s+apps\/memos-local-plugin\/adapters\/hermes\/plugin\.yaml/, + ); + }); + + it("uses a generated version for the post-merge release dry run", () => { + const workflow = readFileSync( + path.resolve( + repoRoot, + "../../.github/workflows/memos-local-plugin-post-merge-dry-run.yml", + ), + "utf8", + ); + + expect(workflow).not.toContain('version: "2.0.10"'); + expect(workflow).toContain("needs.prepare-version.outputs.version"); + expect(workflow).toContain( + "apps/memos-local-plugin/scripts/sync-hermes-version.cjs", + ); + }); + + it("runs synchronization in every Hermes installer", () => { + const unixInstaller = readFileSync(path.join(repoRoot, "install.sh"), "utf8"); + const adapterInstaller = readFileSync( + path.join(repoRoot, "adapters", "hermes", "install.hermes.sh"), + "utf8", + ); + const windowsInstaller = readFileSync( + path.join(repoRoot, "install.ps1"), + "utf8", + ); + + expect(unixInstaller).toContain( + 'version_sync="${prefix}/scripts/sync-hermes-version.cjs"', + ); + expect(unixInstaller).toContain('node "${version_sync}" "${prefix}"'); + expect(adapterInstaller).toContain( + 'VERSION_SYNC_SCRIPT="$PREFIX/scripts/sync-hermes-version.cjs"', + ); + expect(adapterInstaller).toContain('node "$VERSION_SYNC_SCRIPT" "$PREFIX"'); + expect(windowsInstaller).toContain( + '$VersionSyncScript = Join-Path $Prefix "scripts\\sync-hermes-version.cjs"', + ); + expect(windowsInstaller).toContain("& node $VersionSyncScript $Prefix"); + }); +}); diff --git a/apps/memos-local-plugin/tests/unit/logger/signal-ownership.test.ts b/apps/memos-local-plugin/tests/unit/logger/signal-ownership.test.ts new file mode 100644 index 000000000..9e34440c4 --- /dev/null +++ b/apps/memos-local-plugin/tests/unit/logger/signal-ownership.test.ts @@ -0,0 +1,23 @@ +import { readFileSync } from "node:fs"; +import { resolve } from "node:path"; + +import { describe, expect, it } from "vitest"; + +describe("process signal ownership", () => { + it("keeps SIGINT/SIGTERM out of the shared logger", () => { + const source = readFileSync(resolve("core/logger/index.ts"), "utf8"); + + expect(source).not.toMatch(/process\.once\("SIG(?:INT|TERM)"/); + expect(source).not.toMatch(/process\.exit\(13[0-9]\)|process\.exit\(14[0-9]\)/); + expect(source).toMatch(/process\.once\("beforeExit"/); + }); + + it("leaves graceful signal handling with both executable bridge entries", () => { + for (const entry of ["bridge.cts", "bridge.mts"]) { + const source = readFileSync(resolve(entry), "utf8"); + expect(source).toMatch(/process\.on\("SIGINT"/); + expect(source).toMatch(/process\.on\("SIGTERM"/); + expect(source).toMatch(/await (?:withShutdownTimeout\()?core\.shutdown\(\)/); + } + }); +}); diff --git a/apps/memos-local-plugin/tests/unit/pipeline/auto-recovery-role.test.ts b/apps/memos-local-plugin/tests/unit/pipeline/auto-recovery-role.test.ts new file mode 100644 index 000000000..0988a67f4 --- /dev/null +++ b/apps/memos-local-plugin/tests/unit/pipeline/auto-recovery-role.test.ts @@ -0,0 +1,147 @@ +import { readFileSync } from "node:fs"; +import { join } from "node:path"; + +import { afterEach, describe, expect, it, vi } from "vitest"; + +import type { MemoryCore } from "../../../agent-contract/memory-core.js"; +import { DEFAULT_CONFIG } from "../../../core/config/defaults.js"; +import { resolveHome } from "../../../core/config/paths.js"; +import { rootLogger } from "../../../core/logger/index.js"; +import { + createMemoryCore, + createPipeline, + type PipelineDeps, + type PipelineHandle, +} from "../../../core/pipeline/index.js"; +import type { EpisodeId, SessionId } from "../../../core/types.js"; +import { fakeEmbedder } from "../../helpers/fake-embedder.js"; +import { makeTmpDb, type TmpDbHandle } from "../../helpers/tmp-db.js"; + +function fullMemoryConfig(): typeof DEFAULT_CONFIG { + return { + ...DEFAULT_CONFIG, + algorithm: { + ...DEFAULT_CONFIG.algorithm, + lightweightMemory: { + ...DEFAULT_CONFIG.algorithm.lightweightMemory, + enabled: false, + }, + }, + }; +} + +function buildDeps(db: TmpDbHandle): PipelineDeps { + return { + agent: "hermes", + home: resolveHome("hermes", db.dir), + config: fullMemoryConfig(), + db: db.db, + repos: db.repos, + llm: null, + reflectLlm: null, + embedder: fakeEmbedder({ dimensions: 384 }), + log: rootLogger.child({ channel: "test.auto-recovery-role" }), + namespace: { agentKind: "hermes", profileId: "default" }, + now: () => 1_700_000_000_000, + }; +} + +describe("automatic recovery role ownership", () => { + let db: TmpDbHandle | null = null; + let pipeline: PipelineHandle | null = null; + let core: MemoryCore | null = null; + + afterEach(async () => { + if (core) { + await core.shutdown(); + } else if (pipeline) { + await pipeline.shutdown("test.cleanup"); + } + db?.cleanup(); + core = null; + pipeline = null; + db = null; + vi.restoreAllMocks(); + }); + + it("leaves startup rows untouched but keeps normal turn capture enabled", async () => { + db = makeTmpDb({ agent: "hermes" }); + const orphanSessionId = "se_viewer_orphan" as SessionId; + const orphanEpisodeId = "ep_viewer_orphan" as EpisodeId; + db.repos.sessions.upsert({ + id: orphanSessionId, + agent: "hermes", + ownerAgentKind: "hermes", + ownerProfileId: "default", + ownerWorkspaceId: null, + startedAt: 1_600_000_000_000, + lastSeenAt: 1_600_000_000_000, + meta: {}, + }); + db.repos.episodes.insert({ + id: orphanEpisodeId, + sessionId: orphanSessionId, + ownerAgentKind: "hermes", + ownerProfileId: "default", + ownerWorkspaceId: null, + startedAt: 1_600_000_000_000, + endedAt: null, + traceIds: [], + rTask: 0.7, + status: "open", + meta: { sentinel: "unchanged" }, + }); + + const intervalSpy = vi.spyOn(globalThis, "setInterval"); + pipeline = createPipeline(buildDeps(db)); + core = createMemoryCore( + pipeline, + resolveHome("hermes", db.dir), + "auto-recovery-role-test", + { autoRecovery: false }, + ); + await core.init(); + await core.waitForStartupRecovery?.(); + + const untouched = db.repos.episodes.getById(orphanEpisodeId); + expect(untouched?.status).toBe("open"); + expect(untouched?.endedAt).toBeNull(); + expect(untouched?.meta).toEqual({ sentinel: "unchanged" }); + expect( + intervalSpy.mock.calls.some(([, delay]) => delay === 10 * 60 * 1000), + ).toBe(false); + + const sessionId = await core.openSession({ + agent: "hermes", + sessionId: "se_normal_capture" as SessionId, + }); + const start = await core.onTurnStart({ + agent: "hermes", + sessionId, + userText: "我喜欢的水果是凤梨", + ts: 1_700_000_000_100, + }); + const saved = await core.onTurnEnd({ + agent: "hermes", + sessionId, + episodeId: start.query.episodeId!, + agentText: "记住了。", + toolCalls: [], + ts: 1_700_000_000_200, + }); + await pipeline.flush(); + + const trace = await core.getTrace(saved.traceId); + expect(trace?.userText).toBe("我喜欢的水果是凤梨"); + }); + + it("uses the same Hermes-only role formula in both bridge entries", () => { + const root = join(__dirname, "../../.."); + for (const filename of ["bridge.mts", "bridge.cts"]) { + const source = readFileSync(join(root, filename), "utf8"); + expect(source).toContain( + 'autoRecovery: args.agent !== "hermes" || !args.daemon', + ); + } + }); +}); diff --git a/apps/memos-local-plugin/tests/unit/pipeline/memory-core.test.ts b/apps/memos-local-plugin/tests/unit/pipeline/memory-core.test.ts index aad881593..cb5140d09 100644 --- a/apps/memos-local-plugin/tests/unit/pipeline/memory-core.test.ts +++ b/apps/memos-local-plugin/tests/unit/pipeline/memory-core.test.ts @@ -1549,7 +1549,7 @@ algorithm: expect(meta.reward?.traceIds).toEqual(["tr_dirty"]); }); - it("rescoring finalized closed episodes that have traces but no reward metadata", async () => { + it("recovers a real SQLite dirty episode when trace ts differs from turnId", async () => { home = await makeTmpHome({ agent: "openclaw", configYaml: FULL_MEMORY_CONFIG_YAML, @@ -1567,6 +1567,7 @@ algorithm: const Sqlite = (await import("better-sqlite3")).default; const writeDb = new Sqlite(home.home.dbFile); const ts = Date.now() - 1_000; + const turnId = ts - 250; writeDb .prepare( `INSERT INTO sessions (id, agent, started_at, last_seen_at, meta_json) VALUES (?, ?, ?, ?, ?)`, @@ -1611,7 +1612,7 @@ algorithm: 0.5, "[]", "[]", - ts, + turnId, 1, ); writeDb.close(); @@ -1826,6 +1827,177 @@ algorithm: await core.waitForStartupRecovery?.(); }); + it("does not run the stale-open manual reward fallback after capture.failed", async () => { + const startedAt = 1_000; + db!.repos.sessions.upsert({ + id: "se_capture_failed", + agent: "openclaw", + ownerAgentKind: "openclaw", + ownerProfileId: "main", + ownerWorkspaceId: null, + startedAt, + lastSeenAt: startedAt, + meta: {}, + }); + db!.repos.episodes.insert({ + id: "ep_capture_failed", + sessionId: "se_capture_failed", + ownerAgentKind: "openclaw", + ownerProfileId: "main", + ownerWorkspaceId: null, + startedAt, + endedAt: null, + traceIds: ["tr_capture_failed"] as never, + rTask: null, + status: "open", + meta: {}, + }); + db!.repos.traces.insert({ + id: "tr_capture_failed", + episodeId: "ep_capture_failed", + sessionId: "se_capture_failed", + ownerAgentKind: "openclaw", + ownerProfileId: "main", + ownerWorkspaceId: null, + ts: startedAt + 100, + userText: "recover this stale episode", + agentText: "the capture stage will fail in this test", + summary: "stale capture failure", + toolCalls: [], + reflection: null, + agentThinking: null, + value: 0, + alpha: 0, + rHuman: null, + priority: 0.5, + tags: [], + errorSignatures: [], + vecSummary: null, + vecAction: null, + share: null, + turnId: startedAt, + schemaVersion: 1, + }); + + pipeline = createPipeline(buildDeps(db!)); + let captureCalls = 0; + let rewardCalls = 0; + pipeline.captureRunner.runReflect = async (input) => { + captureCalls++; + pipeline!.buses.capture.emit({ + kind: "capture.failed", + episodeId: input.episode.id, + sessionId: input.episode.sessionId, + stage: "match", + error: { code: "conflict", message: "injected full replay mismatch" }, + }); + throw new Error("injected full replay mismatch"); + }; + const originalRewardRun = pipeline.rewardRunner.run.bind(pipeline.rewardRunner); + pipeline.rewardRunner.run = async (input) => { + rewardCalls++; + return originalRewardRun(input); + }; + + core = createMemoryCore( + pipeline, + resolveHome("openclaw", "/tmp/memos-mc-test"), + "capture-failure-recovery", + ); + await core.init(); + await core.waitForStartupRecovery?.(); + + expect(captureCalls).toBe(1); + expect(rewardCalls).toBe(0); + expect(db!.repos.episodes.getById("ep_capture_failed" as never)?.rTask).toBeNull(); + }); + + it("cleans a legacy dirty marker when reward was intentionally skipped", async () => { + const startedAt = 1_000; + db!.repos.sessions.upsert({ + id: "se_skipped_dirty", + agent: "openclaw", + ownerAgentKind: "openclaw", + ownerProfileId: "main", + ownerWorkspaceId: null, + startedAt, + lastSeenAt: startedAt, + meta: {}, + }); + db!.repos.episodes.insert({ + id: "ep_skipped_dirty", + sessionId: "se_skipped_dirty", + ownerAgentKind: "openclaw", + ownerProfileId: "main", + ownerWorkspaceId: null, + startedAt, + endedAt: startedAt + 100, + traceIds: ["tr_skipped_dirty"] as never, + rTask: null, + status: "closed", + meta: { + closeReason: "finalized", + reward: { + source: "heuristic", + reason: "对话内容过短", + scoredAt: startedAt + 100, + trigger: "implicit_fallback", + skipped: true, + }, + rewardDirty: { + failedAttempts: 7, + lastFailureAt: startedAt + 100, + }, + }, + }); + db!.repos.traces.insert({ + id: "tr_skipped_dirty", + episodeId: "ep_skipped_dirty", + sessionId: "se_skipped_dirty", + ownerAgentKind: "openclaw", + ownerProfileId: "main", + ownerWorkspaceId: null, + ts: startedAt + 100, + userText: "我喜欢玩的游戏呢", + agentText: "你喜欢马里奥。", + summary: null, + toolCalls: [], + reflection: null, + agentThinking: null, + value: 0, + alpha: 0, + rHuman: null, + priority: 0.5, + tags: [], + errorSignatures: [], + vecSummary: null, + vecAction: null, + share: null, + turnId: startedAt, + schemaVersion: 1, + }); + + pipeline = createPipeline(buildDeps(db!)); + let captureCalls = 0; + pipeline.captureRunner.runReflect = async (input) => { + captureCalls++; + throw new Error(`unexpected recovery for ${input.episode.id}`); + }; + core = createMemoryCore( + pipeline, + resolveHome("openclaw", "/tmp/memos-mc-test"), + "skipped-dirty-cleanup", + ); + + await core.init(); + await core.waitForStartupRecovery?.(); + + expect(captureCalls).toBe(0); + const episode = db!.repos.episodes.getById("ep_skipped_dirty" as never); + expect(episode?.meta?.reward).toMatchObject({ skipped: true }); + expect(episode?.meta?.rewardDirty).toBeUndefined(); + }); + it("dirty closed episodes hit a failure-count backoff so init() does not retry them every restart (issue #1808)", async () => { // The OpenClaw report noted "orphan episodes with failed LLM calls // are retried indefinitely with no backoff". After the third diff --git a/apps/memos-local-plugin/tests/unit/pipeline/orchestrator.test.ts b/apps/memos-local-plugin/tests/unit/pipeline/orchestrator.test.ts index 2e69522d8..a70fdcf6b 100644 --- a/apps/memos-local-plugin/tests/unit/pipeline/orchestrator.test.ts +++ b/apps/memos-local-plugin/tests/unit/pipeline/orchestrator.test.ts @@ -232,6 +232,62 @@ describe("pipeline/orchestrator", () => { expect(stats?.scenarioId).toBe("CHITCHAT"); }); + it("makes repeated turn.start calls idempotent by turnKey in lightweight mode", async () => { + pipeline = createPipeline({ + ...buildDeps(dbHandle!), + config: configWithLightweightMemory(true), + }); + const input: TurnInputDTO = { + agent: "hermes", + sessionId: "s-idempotent", + turnKey: "s-idempotent:4", + userText: "continue the same real task", + ts: 1_700_000_000_000, + }; + + const [first, concurrent] = await Promise.all([ + pipeline.onTurnStart(input), + pipeline.onTurnStart({ + ...input, + ts: input.ts + 1, + }), + ]); + const repeated = await pipeline.onTurnStart({ + ...input, + ts: input.ts + 2, + }); + + expect(concurrent.episodeId).toBe(first.episodeId); + expect(repeated.episodeId).toBe(first.episodeId); + expect(dbHandle!.repos.episodes.list({ sessionId: input.sessionId })).toHaveLength(1); + expect(pipeline.sessionManager.getEpisode(first.episodeId)?.turns).toHaveLength(1); + }); + + it("rejects a reused turnKey carrying different user text", async () => { + pipeline = createPipeline({ + ...buildDeps(dbHandle!), + config: configWithLightweightMemory(true), + }); + const input: TurnInputDTO = { + agent: "hermes", + sessionId: "s-turn-key-conflict", + turnKey: "s-turn-key-conflict:2", + userText: "first task text", + ts: 1_700_000_000_000, + }; + + await pipeline.onTurnStart(input); + + await expect( + pipeline.onTurnStart({ + ...input, + userText: "different task text", + ts: input.ts + 1, + }), + ).rejects.toMatchObject({ code: "conflict" }); + expect(dbHandle!.repos.episodes.list({ sessionId: input.sessionId })).toHaveLength(1); + }); + it("records tool success + failure through the feedback subscriber", async () => { pipeline = createPipeline(buildDeps(dbHandle!)); await pipeline.onTurnStart({ diff --git a/apps/memos-local-plugin/tests/unit/reward/reward.integration.test.ts b/apps/memos-local-plugin/tests/unit/reward/reward.integration.test.ts index 238713a29..568874020 100644 --- a/apps/memos-local-plugin/tests/unit/reward/reward.integration.test.ts +++ b/apps/memos-local-plugin/tests/unit/reward/reward.integration.test.ts @@ -284,6 +284,70 @@ describe("reward/integration", () => { expect(t.priority).toBe(0); }); + it("treats a triviality skip as terminal and clears an inherited dirty marker", async () => { + const sid = "s_int_skipped"; + const eid = "ep_int_skipped"; + seedEpisode(handle, eid, sid, ["tr_short"]); + seedTrace(handle, "tr_short", eid, sid, { + userText: "我喜欢玩的游戏呢", + agentText: "你喜欢马里奥。", + }); + handle.repos.episodes.updateMeta(eid as unknown as EpisodeRow["id"], { + closeReason: "finalized", + rewardDirty: { + failedAttempts: 7, + lastFailureAt: NOW - 1_000, + }, + }); + + const shortSnapshot: EpisodeSnapshot = { + ...rewardSnapshot(eid, sid, ["tr_short"]), + turnCount: 1, + turns: [ + { + role: "user", + content: "我喜欢玩的游戏呢", + ts: NOW, + meta: {}, + }, + { + role: "assistant", + content: "你喜欢马里奥。", + ts: NOW, + meta: {}, + }, + ], + }; + const runner = createRewardRunner({ + tracesRepo: handle.repos.traces, + episodesRepo: handle.repos.episodes, + feedbackRepo: handle.repos.feedback, + getEpisodeSnapshot: () => shortSnapshot, + llm: null, + bus: createRewardEventBus(), + cfg: { + ...cfg(), + minExchangesForCompletion: 2, + minContentCharsForCompletion: 80, + }, + now: () => NOW, + }); + + const result = await runner.run({ + episodeId: eid as unknown as Parameters[0]["episodeId"], + feedback: [], + trigger: "implicit_fallback", + }); + + expect(result.rHuman).toBe(0); + const episode = handle.repos.episodes.getById( + eid as unknown as EpisodeRow["id"], + )!; + expect(episode.rTask).toBeNull(); + expect(episode.meta?.reward).toMatchObject({ skipped: true }); + expect(episode.meta?.rewardDirty).toBeUndefined(); + }); + it("episodes with no traces still score R_human but skip backprop", async () => { const sid = "s_int_3"; const eid = "ep_int_3"; diff --git a/apps/memos-local-plugin/tests/unit/server/admin.test.ts b/apps/memos-local-plugin/tests/unit/server/admin.test.ts new file mode 100644 index 000000000..dc026650e --- /dev/null +++ b/apps/memos-local-plugin/tests/unit/server/admin.test.ts @@ -0,0 +1,110 @@ +import { EventEmitter } from "node:events"; + +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +import type { MemoryCore } from "../../../agent-contract/memory-core.js"; +import { + isSupervisorManagedProcess, + registerAdminRoutes, +} from "../../../server/routes/admin.js"; +import { Routes } from "../../../server/routes/registry.js"; + +const { spawnMock } = vi.hoisted(() => ({ + spawnMock: vi.fn(), +})); + +vi.mock("node:child_process", () => ({ + spawn: spawnMock, +})); + +describe("admin lifecycle routes", () => { + beforeEach(() => { + vi.useFakeTimers(); + spawnMock.mockReset(); + spawnMock.mockImplementation((command: string) => { + const child = new EventEmitter() as EventEmitter & { unref: ReturnType }; + child.unref = vi.fn(); + if (command === "pkill") { + queueMicrotask(() => child.emit("exit", 1)); + } + return child; + }); + }); + + afterEach(() => { + vi.clearAllTimers(); + vi.useRealTimers(); + }); + + it("lets the supervisor replace a managed Hermes viewer", async () => { + const requestShutdown = vi.fn(); + const routes = new Routes(); + registerAdminRoutes( + routes, + { core: {} as MemoryCore }, + { + agent: "hermes", + lifecycle: { supervised: true, requestShutdown }, + }, + ); + + const restart = routes.getExact("POST /api/v1/admin/restart"); + expect(restart).toBeDefined(); + + const result = await restart!({} as never); + + expect(result).toMatchObject({ ok: true, restarting: true }); + expect(spawnMock).not.toHaveBeenCalledWith( + "bash", + expect.anything(), + expect.anything(), + ); + expect(requestShutdown).not.toHaveBeenCalled(); + + await vi.advanceTimersByTimeAsync(200); + + expect(requestShutdown).toHaveBeenCalledOnce(); + }); + + it("retains the detached replacement fallback for a portable Hermes viewer", async () => { + const requestShutdown = vi.fn(); + const routes = new Routes(); + registerAdminRoutes( + routes, + { core: {} as MemoryCore }, + { + agent: "hermes", + lifecycle: { supervised: false, requestShutdown }, + }, + ); + + const restart = routes.getExact("POST /api/v1/admin/restart"); + const result = await restart!({} as never); + + expect(result).toMatchObject({ ok: true, restarting: true }); + expect(spawnMock).toHaveBeenCalledWith( + "bash", + [ + "-c", + expect.stringContaining("--agent=hermes --daemon"), + ], + expect.objectContaining({ + detached: true, + stdio: "ignore", + }), + ); + + await vi.advanceTimersByTimeAsync(200); + expect(requestShutdown).toHaveBeenCalledOnce(); + }); + + it("recognises launchd and systemd without treating the macOS shell sentinel as supervised", () => { + expect(isSupervisorManagedProcess({ XPC_SERVICE_NAME: "ai.memtensor.memos-local-hermes" })).toBe(true); + expect(isSupervisorManagedProcess({ XPC_SERVICE_NAME: "ai.memtensor.memos-local-hermes.nova" })).toBe(true); + expect(isSupervisorManagedProcess({ INVOCATION_ID: "abc123" })).toBe(true); + expect(isSupervisorManagedProcess({ XPC_SERVICE_NAME: "application.com.example.desktop" })).toBe(false); + expect(isSupervisorManagedProcess({ JOURNAL_STREAM: "8:12345" })).toBe(false); + expect(isSupervisorManagedProcess({ XPC_SERVICE_NAME: "0" })).toBe(false); + expect(isSupervisorManagedProcess({})).toBe(false); + }); +}); diff --git a/apps/memos-local-plugin/tests/unit/viewer/restart.test.ts b/apps/memos-local-plugin/tests/unit/viewer/restart.test.ts new file mode 100644 index 000000000..88e8e426e --- /dev/null +++ b/apps/memos-local-plugin/tests/unit/viewer/restart.test.ts @@ -0,0 +1,53 @@ +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +const fakeWindow = { + location: { + pathname: "/", + href: "", + }, +}; + +(globalThis as any).window = fakeWindow; +(globalThis as any).localStorage = { + getItem() { return null; }, +}; + +import { health } from "../../../viewer/src/stores/health"; +import { triggerRestart } from "../../../viewer/src/stores/restart"; + +describe("viewer restart flow", () => { + const originalFetch = globalThis.fetch; + + beforeEach(() => { + vi.useFakeTimers(); + fakeWindow.location.href = ""; + health.value = { ok: true, agent: "hermes" }; + }); + + afterEach(() => { + vi.clearAllTimers(); + vi.useRealTimers(); + globalThis.fetch = originalFetch; + }); + + it("waits for the replacement Hermes daemon before reloading", async () => { + let healthChecks = 0; + globalThis.fetch = vi.fn(async (_url: string | URL | Request, init?: RequestInit) => { + if (init?.method === "POST") { + return new Response(JSON.stringify({ ok: true, restarting: true }), { + status: 200, + }); + } + healthChecks += 1; + if (healthChecks === 1) throw new TypeError("daemon is down"); + return new Response(null, { status: 200 }); + }) as typeof fetch; + + const restarting = triggerRestart(); + await vi.runAllTimersAsync(); + await restarting; + + expect(healthChecks).toBe(2); + expect(fakeWindow.location.href).toMatch(/^\/\?_t=\d+$/); + }); +}); diff --git a/apps/memos-local-plugin/viewer/src/stores/restart.ts b/apps/memos-local-plugin/viewer/src/stores/restart.ts index 974a9e222..6d089f784 100644 --- a/apps/memos-local-plugin/viewer/src/stores/restart.ts +++ b/apps/memos-local-plugin/viewer/src/stores/restart.ts @@ -4,10 +4,9 @@ * OpenClaw can be restarted from the viewer because the plugin lives * inside the gateway process and launchd brings it back. * - * Hermes is different: the viewer daemon is intentionally long-lived, - * so restart means "terminate the active `hermes chat` process" while - * keeping this Memory Viewer online. The user can relaunch Hermes and - * it will reconnect to the existing viewer service. + * Hermes has separate chat and viewer bridge processes. The backend + * terminates the active chat and replaces the viewer daemon so both + * processes load the saved config. */ import { signal } from "@preact/signals"; import { api } from "../api/client"; @@ -58,8 +57,6 @@ async function pollHealthUntilUp(maxAttempts = 60): Promise { /** * Quick health check for destructive clear-data only. - * Do not use this for Hermes config saves: those must keep the current - * viewer daemon online and terminate only the active `hermes chat`. */ async function quickPollUp(maxAttempts = 30): Promise { for (let i = 0; i < maxAttempts; i++) { @@ -75,9 +72,8 @@ async function quickPollUp(maxAttempts = 30): Promise { } /** - * Config saved. OpenClaw gets an in-place gateway restart. Hermes keeps - * the viewer online and asks the backend to terminate the active chat - * process; once that request returns, reload the same viewer page. + * Config saved. OpenClaw gets an in-place gateway restart. Hermes + * replaces its viewer daemon and terminates the active chat process. * * Do not add a passive "settings saved" toast/card here. The restart * affordance is intentionally blocking for both agents so the operator @@ -88,13 +84,19 @@ export async function triggerRestart(): Promise { if (!isOpenClaw()) { try { await api.post("/api/v1/admin/restart"); - await new Promise((r) => setTimeout(r, 500)); - window.location.href = - window.location.pathname + "?_t=" + Date.now(); } catch { restartState.value = { phase: "restartFailed" }; throw new Error("restart failed"); } + + const ok = await pollHealthUntilUp(60); + if (ok) { + window.location.href = + window.location.pathname + "?_t=" + Date.now(); + } else { + restartState.value = { phase: "restartFailed" }; + throw new Error("restart did not complete"); + } return; }