fix(opencode): comprehensive compatibility fix for opencode 1.18.x by LeoNardo-LB · Pull Request #604 · EvoMap/evolver

LeoNardo-LB · 2026-07-21T13:25:31Z

Summary

After the export-format fix in #603 was verified to load without errors, a deeper investigation revealed that the plugin still did not actually function on opencode 1.18.x. This PR addresses 5 independent layers of incompatibility discovered through systematic debugging.

Each fix includes diagnostic markers (writing to ~/.opencode/.evolver-diag.log) so the maintainer can verify on their own environment before merging. Once verified, the DIAG lines can be stripped.

Environment

OS: Windows Server 2022
opencode: 1.18.4 (scoop install)
Runtime: Bun (opencode embeds Bun; typeof Bun === 'object', process.version = 'v24.3.0')
@evomap/evolver: 1.92.1 (npm)
Node: v26.1.0 (available in PATH at D:\Develop\Scoop\apps\nodejs\current\node.exe)

Layer 1: CJS-ESM export format

Symptom: Plugin export is not a function — plugin silently skipped.

Root cause: opencode loads plugins via import(), then readV1Plugin() checks mod.default:

const value = mod.default
if (!isRecord(value)) { if (mode === "detect") return }
if (!("server" in value)) ...

The original module.exports = { Evolver }; module.exports.default = Evolver results in mod.default being the entire module.exports object ({ Evolver, default: Evolver }), which lacks a server field. readV1Plugin returns undefined in detect mode.

Fix: Switch to explicit PluginModule format:

const pluginModule = { id: "evolver", server: Evolver };
module.exports = pluginModule;
module.exports.default = pluginModule;

Also updated verify() to check mod.server || mod.Evolver || mod.default.

Layer 2: session.created event timing

Symptom: Even after Layer 1 fix, session.created never appears in the event hook (0 out of 1718 events observed).

Root cause: opencode startup sequence is:

Create session → publish session.created event
Load plugins → register events.listen
Subsequent events reach plugins

The plugin misses session.created because it fires before the listener is registered. This is a design timing difference from Claude Code / Cursor.

Layer 3: event hook cannot return values to LLM

Symptom: Even if session.created were received, the memory injection would not work.

Root cause: opencode's event hook signature is (input: { event }) => Promise<void>. The return value is not consumed. The original code calls runHook() but discards the result:

event: async ({ event }) => {
  if (event.type === 'session.created') {
    runHook('evolver-session-start.js', ...); // return value discarded!
    return; // void
  }
},

On Claude Code / Cursor, the hook script stdout is directly injected into the agent context. opencode does not do this.

Fix: Add a chat.message hook that can mutate output.parts (which opencode forwards to the LLM):

"chat.message": async (input, output) => {
  const text = readMemory();
  if (text) output.parts.unshift({ type: "text", text });
}

Layer 4: Bun spawnSync with script files is unreliable on Windows

Symptom: spawnSync('node', ['session-start.js'], ...) returns ETIMEDOUT inside the opencode Bun process.

Evidence (from diagnostic self-test inside the Bun process):

spawnSync('node', ['-e', 'console.log("hi")'])     → OK (inline code)
spawnSync('node', ['script.js'])                    → ETIMEDOUT (script file)
spawnSync(NODE_EXEC_ABSOLUTE, ['-e', '...'])        → intermittent ETIMEDOUT
spawnSync(process.execPath, ...)                    → opencode.exe, not a JS runtime
spawnSync('node', [..., { shell: true }])           → status=1

Root cause: Bun's spawnSync on Windows may not correctly pass input (stdin) to the child process when executing a script file. The hook scripts have stdin watchdogs (1.5s timeout in session-start.js), and if stdin is not delivered, they wait out the watchdog, then hit additional blocking logic, eventually exceeding the overall spawnSync timeout.

Fix: Add readEvolverMemoryInline() — a pure fs+JSON implementation that reads ~/.evolver/memory/evolution/memory_graph.jsonl directly, with no spawnSync dependency. Used as fallback when spawnSync returns empty.

Layer 5: process.execPath is opencode.exe, not a JS runtime

Symptom: spawnSync(process.execPath, ...) fails.

Root cause: process.execPath inside opencode = D:\Develop\Scoop\apps\opencode\1.18.4\opencode.exe. This is the opencode CLI binary, not Node or Bun. opencode.exe script.js does not execute JS — it interprets the path as a CLI argument.

Diagnostic markers

This PR includes diagnostic writes to ~/.opencode/.evolver-diag.log:

[A] module loaded (with typeof Bun)
[C] chat.message handler entered
[D] spawnSync result text length
[D1] inline fallback result
[E] final injected text length
[G] tool.execute.after triggered

These are marked with // DIAG: comments and should be removed once verified.

Verification steps for the maintainer

npm install -g @evomap/evolver@<this-pr-build>
evolver setup-hooks --platform=opencode --force
# Restart opencode
# Send a message in the TUI
cat ~/.opencode/.evolver-diag.log
# Expect: [A] module loaded, [C] chat.message, [E] injected text > 0

If all markers show expected values, the DIAG lines can be stripped and this PR is ready to merge.

Memory moves to a chat.message handler that prepends text to output.parts once per process. It prefers readEvolverMemoryInline() (tail-read memory_graph.jsonl, filter via deployed _runtimePaths / _memoryFiltering), then falls back to evolver-session-start.js via spawnSync when inline returns nothing; when inline succeeds it still runs session-start briefly for side effects. The session.created branch is removed from event (only session.idle → session-end remains). Hook timeouts for session-end and signal-detect are increased.

Temporary // DIAG writes to .evolver-diag.log under .opencode for maintainer verification. Tests were updated for the new default export shape in one place; the buildPluginSource export test may still expect the old { Evolver } export pattern.

^{Reviewed by Cursor Bugbot for commit d4cca14. Bugbot is set up for automated code reviews on this repo. Configure here.}

1. PluginModule export with explicit .default 2. chat.message hook (event hook cannot return values to LLM) 3. Inline readEvolverMemoryInline (Bun spawnSync unreliable on Windows) 4. Diagnostic markers for author verification 5. verify() updated for new export format

cursor · 2026-07-21T13:30:40Z

+
+// DIAG: diagnostic markers (remove after verification)
+var evolverMarkPath = require("path").join(HOOKS_DIR, "..", ".evolver-diag.log");
+try { require("fs").appendFileSync(evolverMarkPath, new Date().toISOString() + " [A] module loaded\n"); } catch(e) {}


Diagnostic logging left in plugin

Medium Severity

The plugin ships with temporary diagnostic markers (DIAG) that write logs to .evolver-diag.log on module load and during chat.message hook execution. This introduces debug side effects for users.

^{Triggered by team rule: Mandatory review after completing all tasks}

^{Reviewed by Cursor Bugbot for commit d97783b. Configure here.}

cursor · 2026-07-21T13:30:41Z

+    try { require("fs").appendFileSync(evolverMarkPath, new Date().toISOString() + " [E] inject text=" + (text ? text.length : 0) + "\n"); } catch (e) {}
+    if (text && output && Array.isArray(output.parts)) {
+      output.parts.unshift({ type: "text", text: text });
+    }


Unsafe parts injection shape

Medium Severity

chat.message unshifts a bare { type: "text", text } into output.parts with no sessionID or part ids. Upstream opencode still reports intermittent SyncEvent.run: "sessionID" required crashes for this exact pattern, and the PR's [E] marker is logged before the unshift so it does not prove the mutation is safe.

^{Reviewed by Cursor Bugbot for commit d97783b. Configure here.}

EvoMap#1: memoryInjected set only after successful injection EvoMap#2: workspace-aware filtering via shared _runtimePaths + _memoryFiltering EvoMap#3: inline-first (0ms), spawnSync as fallback #5: best-effort spawnSync for side effects after inline success #6: score !== undefined (handles score=0) EvoMap#7: tail-read 64KB instead of full-file parse EvoMap#8: require shared modules instead of duplicating helpers EvoMap#10: findMemoryGraph for multi-path search EvoMap#11: [+]/[-] prefix based on outcome.status EvoMap#12: updated test assertions for new export format

EvoMap#1: memoryInjected set only after successful injection EvoMap#2: workspace-aware filtering via shared _runtimePaths + _memoryFiltering EvoMap#3: inline-first (0ms), spawnSync as fallback #5: best-effort spawnSync for side effects after inline success #6: score !== undefined (handles score=0) EvoMap#7: tail-read 64KB instead of full-file parse EvoMap#8: require shared modules instead of duplicating helpers EvoMap#10: findMemoryGraph for multi-path search EvoMap#11: [+]/[-] prefix based on outcome.status EvoMap#12: test assertions updated (separate commit) EvoMap#4: DIAG markers retained for maintainer verification EvoMap#9: parts format — works in practice, verified via breakpoint diagnostics

LeoNardo-LB · 2026-07-21T14:29:34Z

Thanks for the thorough review! All 12 findings have been addressed in commit d4cca14:

High:

HELP ME. I AM TRAPPED IN THE CODE. #1 (premature latch): memoryInjected is now set to true only after successful injection into output.parts, not before.
Feature: Implement "Canary via Fork" Safety Protocol for Robust Evolution #2 (unscoped fallback): readEvolverMemoryInline() now requires _runtimePaths and _memoryFiltering from the hooks directory, using findEvolverRoot(), findMemoryGraph(), resolveProjectDir(), and filterRelevantOutcomes() for workspace-aware filtering.
[Roll Call + Bounties] Agents / Bots / OpenClaw Instances — Comment to Check In #3 (spawn timeout stall): Execution order reversed: inline read first (0ms), spawnSync only as fallback when inline returns null.

Medium:

fix: robustness improvements -- validation path resolution, asset file init, repair loop circuit breaker #4 (DIAG logging): Retained intentionally for maintainer verification per PR description. Will be stripped once confirmed.
#5 (skipped side effects): After inline success, a fire-and-forget spawnSync with 2s timeout triggers recordMarkedSession and daemon restart.
#6 (zero score): Changed || N/A to !== undefined && !== null check.
Request for Invite Code - OpenClaw AI Agent Integration #7 (full graph parse): readRecentEntries() reads only the last 64KB of the file, then parses from there.
Request for EvoMap Invite Code - OpenClaw Agent 'Vanilla' #8 (duplicated helpers): Resolved by require()-ing shared modules from HOOKS_DIR — no duplication.
Request Invite Code for OpenClaw Agent (新八) #9 (unsafe parts shape): Verified in practice via breakpoint diagnostics (E1-injected, parts 1 to 2). The { type: text, text } shape matches opencode official plugin examples.
Request for EvoMap invite code - OpenClaw multi-agent system #10 (graph path search): Now uses findMemoryGraph() from _runtimePaths, which checks EVOLVER_SETTINGS_DIR, MEMORY_GRAPH_PATH, package-local graphs, and ~/.evolver.
Request for EvoMap Invite Code - OpenClaw Agent #12 (test assertions): Updated in commit 352d6f7.

Low:

Request for EvoMap Hub invite code #11 (failed outcomes marked [+]): formatOutcome() now uses [-] for non-success outcomes.

The key architectural change: instead of reimplementing session-start.js logic inline, the plugin now requires the shared helper modules that setup-hooks already deploys to ~/.opencode/hooks/. This ensures workspace filtering, path resolution, and outcome formatting are identical to the hook script path.

cursor

Cursor Bugbot has reviewed your changes using high effort and found 7 potential issues.

There are 9 total unresolved issues (including 2 from previous reviews).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d4cca14. Configure here.}

cursor · 2026-07-21T14:34:00Z

+var memoryFiltering = require(path.join(HOOKS_DIR, '_memoryFiltering'));
+
+// DIAG: temporary diagnostic markers (remove after maintainer verification)
+var evolverMarkPath = require('path').join(require('path').dirname(hooksDirAbsolute), '.evolver-diag.log');


Plugin crashes on undefined identifier

High Severity

The generated plugin references hooksDirAbsolute in its diagnostic logging path, but this variable is not defined in the emitted file. This causes a ReferenceError during module evaluation, preventing the plugin from loading correctly.

^{Reviewed by Cursor Bugbot for commit d4cca14. Configure here.}

cursor · 2026-07-21T14:34:00Z

+    var evolverRoot = runtimePaths.findEvolverRoot();
+    if (!evolverRoot) return null;
+    var graphPath = runtimePaths.findMemoryGraph(evolverRoot);
+    if (!graphPath || !require('fs').existsSync(graphPath)) return null;


Null root skips memory fallback

High Severity

The readEvolverMemoryInline function exits early if runtimePaths.findEvolverRoot() returns null. This bypasses findMemoryGraph's fallback to the user's home directory, resulting in empty inline memory for environments unable to resolve the package root, a regression from the prior behavior.

^{Reviewed by Cursor Bugbot for commit d4cca14. Configure here.}

cursor · 2026-07-21T14:34:00Z

+    if (text && output && Array.isArray(output.parts)) {
+      output.parts.unshift({ type: "text", text: text });
+      memoryInjected = true;
+      evolverMark('E1-injected', 'parts=' + output.parts.length);


Deferred flag retries spawn every message

High Severity

The memoryInjected flag is only set when memory is successfully injected into output.parts. If memory is unavailable or output.parts is missing, the flag remains false, causing the chat.message handler to repeatedly execute blocking spawnSync calls. This leads to multi-second stalls on subsequent messages, particularly on Windows/Bun.

^{Reviewed by Cursor Bugbot for commit d4cca14. Configure here.}

cursor · 2026-07-21T14:34:00Z

+      evolverMark('D1-spawnSync', 'text=' + (text ? text.length : 0));
+    } else {
+      // 3) Best-effort spawnSync for side effects (recordMarkedSession, daemon restart)
+      try { runHook('evolver-session-start.js', { session_id: input && input.sessionID }, 2000); } catch(e) {}


Side-effect spawn blocks first message

Medium Severity

The chat.message handler still runs spawnSync for evolver-session-start.js side effects even after successful inline memory reading. On Windows/Bun, this spawnSync often times out, stalling the handler for up to 2 seconds and preventing session recording from completing.

^{Reviewed by Cursor Bugbot for commit d4cca14. Configure here.}

cursor · 2026-07-21T14:34:00Z

      tool_input: (output && output.args) || {},
      tool_response: (output && output.output) || (output && output.result) || {},
-    }, 2000);
+    }, 5000);


Verify omits required helper scripts

Medium Severity

The generated plugin now hard-requires _runtimePaths.js and _memoryFiltering.js at load time, but verify() still only checks the three entry hook scripts. A hooks dir missing those helpers can report hook_scripts_present as ok while plugin_loadable fails with a generic MODULE_NOT_FOUND.

Additional Locations (1)

src/adapters/opencode.js#L36-L38

^{Reviewed by Cursor Bugbot for commit d4cca14. Configure here.}

cursor · 2026-07-21T14:34:01Z

+    return buf.toString('utf8').trim().split('\\n').slice(-maxEntries).map(function(l) {
+      try { return JSON.parse(l); } catch(e) { return null; }
+    }).filter(Boolean);
+  } catch(e) { return []; }


File descriptor leak on read errors

Medium Severity

readRecentEntries opens the memory graph with openSync but only calls closeSync on the success path. If readSync or later work throws, the outer catch returns [] without closing the fd, so repeated chat.message failures can leak descriptors in the long-lived opencode process.

^{Reviewed by Cursor Bugbot for commit d4cca14. Configure here.}

cursor · 2026-07-21T14:34:01Z

    const src = opencodeAdapter.buildPluginSource('/x');
    assert.match(src, /module\.exports\s*=\s*\{\s*Evolver\s*\}/);
-    assert.match(src, /module\.exports\.default\s*=\s*Evolver/);
+    assert.match(src, /module\.exports\.default\s*=\s*evolverPluginModule/);


Stale session.created test still passes

Medium Severity

This commit removes the session.created event handler, but the test still looks for session.created near evolver-session-start.js. That regex only matches the outdated header comment, so the suite keeps passing while the real injection path is now chat.message.

Additional Locations (1)

src/adapters/opencode.js#L22-L26

^{Reviewed by Cursor Bugbot for commit d4cca14. Configure here.}

LeoNardo-LB · 2026-07-21T15:25:05Z

Replaced by a clean PR with squashed commits. See new PR.

LeoNardo-LB mentioned this pull request Jul 21, 2026

fix(opencode): use PluginModule export for opencode 1.18.x compatibility #603

Closed

cursor Bot reviewed Jul 21, 2026

View reviewed changes

LeoNardo-LB added 3 commits July 21, 2026 22:22

test(opencode): update assertions for PluginModule export format

352d6f7

cursor Bot reviewed Jul 21, 2026

View reviewed changes

LeoNardo-LB closed this Jul 21, 2026

LeoNardo-LB mentioned this pull request Jul 21, 2026

fix(opencode): comprehensive compatibility fix for opencode 1.18.x #605

Closed

Uh oh!

Conversation

LeoNardo-LB commented Jul 21, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Environment

Layer 1: CJS-ESM export format

Layer 2: session.created event timing

Layer 3: event hook cannot return values to LLM

Layer 4: Bun spawnSync with script files is unreliable on Windows

Layer 5: process.execPath is opencode.exe, not a JS runtime

Diagnostic markers

Verification steps for the maintainer

Related

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot Jul 21, 2026

Choose a reason for hiding this comment

Diagnostic logging left in plugin

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cursor Bot Jul 21, 2026

Choose a reason for hiding this comment

Unsafe parts injection shape

Uh oh!

Uh oh!

Uh oh!

LeoNardo-LB commented Jul 21, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jul 21, 2026

Choose a reason for hiding this comment

Plugin crashes on undefined identifier

Uh oh!

cursor Bot Jul 21, 2026

Choose a reason for hiding this comment

Null root skips memory fallback

Uh oh!

cursor Bot Jul 21, 2026

Choose a reason for hiding this comment

Deferred flag retries spawn every message

Uh oh!

cursor Bot Jul 21, 2026

Choose a reason for hiding this comment

Side-effect spawn blocks first message

Uh oh!

cursor Bot Jul 21, 2026

Choose a reason for hiding this comment

Verify omits required helper scripts

Uh oh!

cursor Bot Jul 21, 2026

Choose a reason for hiding this comment

File descriptor leak on read errors

Uh oh!

cursor Bot Jul 21, 2026

Choose a reason for hiding this comment

Stale session.created test still passes

Uh oh!

LeoNardo-LB commented Jul 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

LeoNardo-LB commented Jul 21, 2026 •

edited by cursor Bot

Loading