feat: OpenCode Observability Plugin#73
Conversation
Signed-off-by: Binfeng Xu <binfengx@nvidia.com>
…to feature/bx-opencode
WalkthroughThis PR adds an OpenCode server plugin package, core server implementation, docs, and tests that record OpenCode session/message/tool events into NeMo Flow and emit ATOF JSONL and ATIF trajectory files with safe serialization and graceful runtime-fallback behavior. ChangesNeMo Flow OpenCode Plugin Integration
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning Review ran into problems🔥 ProblemsGit: Failed to clone repository. Please run the Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Comment |
github-actions
Bot
added
size:XL
Signed-off-by: Binfeng Xu <binfengx@nvidia.com>
…to feature/bx-opencode
|
/retest |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@integrations/opencode-plugin/server.js`:
- Around line 214-216: The subscriber registered via
lib.registerSubscriber(using atofSubscriberName) writes with
fsSync.appendFileSync(options.atofPath, ...) with no error handling; wrap the
appendFileSync call inside a try/catch inside the subscriber callback, and on
error log or swallow the error (use existing logger or console.error) so
ENOSPC/EACCES or other sync I/O failures do not throw out of the event delivery
path; keep the callback signature and behavior otherwise unchanged so NeMo
Flow/framework behavior is preserved.
- Around line 33-60: The write function currently lets filesystem errors bubble
up and reject plugin hooks; wrap the entire body of write (the path-handling,
ensureParentDir, fs.appendFile and the console logging branches) in a try/catch
so any thrown error is swallowed (or downgraded to a non-fatal fallback) and
write always resolves; on fs failures fall back to console logging the same
formatted message (include PLUGIN_ID, message and toJsonSafe(extra)), and ensure
warnOnce/info/warn/error callers (and the seen set logic) continue to return a
resolved Promise rather than letting errors propagate from write (keep the
existing Promise.resolve() return for the seen shortcut). Use the existing
symbols write, PLUGIN_ID, logPath, ensureParentDir, fs.appendFile, toJsonSafe
and seen to locate where to add the try/catch and fallback.
- Around line 197-198: recentFlushes is an unbounded Map used as a 2s dedupe
cache and needs pruning; change its entries so each key maps to insertion
timestamp (or schedule a per-key setTimeout) and remove entries older than 2
seconds. Locate the recentFlushes usage in server.js (the const recentFlushes =
new Map() declaration and any code that checks/sets keys) and: when adding a
key, store Date.now() (or schedule a setTimeout to delete that key after
2000ms); when checking a key, consider it expired if its timestamp is >2000ms
old and delete it before proceeding; optionally add a short periodic cleanup
(setInterval) to remove stale keys if you choose timestamp-based approach.
Ensure the semantics of the dedupe window remain 2 seconds and that no other
code relies on Map values being non-timestamps.
- Around line 1-2: Replace the line-style SPDX header comments at the top of
integrations/opencode-plugin/server.js with a C-style comment block;
specifically, change the two leading single-line comments containing
"SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
All rights reserved." and "SPDX-License-Identifier: Apache-2.0" into a single /*
... */ block so the file has a C-style SPDX header as required by the repo's
licensing guidelines.
- Around line 251-259: In withStack, always restore the prior thread scope stack
instead of only when previous is truthy: capture priorStack via
lib.currentScopeStack(), set lib.setThreadScopeStack(session.stack) before
running callback, and in the finally block call
lib.setThreadScopeStack(previousStack) (even if previousStack is undefined) so
the thread scope is always reset; reference the withStack function and the
lib.currentScopeStack / lib.setThreadScopeStack calls to locate where to change
the restore logic.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: ff9f6b37-40d8-4c6f-8698-7fab042a2722
📒 Files selected for processing (1)
integrations/opencode-plugin/server.js
📜 Review details
🧰 Additional context used
📓 Path-based instructions (12)
**/*.{js,ts,tsx}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Use camelCase naming convention for Node.js code
Files:
integrations/opencode-plugin/server.js
**/*.{rs,go,js,ts,tsx}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Include SPDX license headers in all Rust, Go, JavaScript, and TypeScript source files using C-style comment syntax
Files:
integrations/opencode-plugin/server.js
**/*.{rs,py,go,js,ts,tsx}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Use
SONAR_IGNORE_START/SONAR_IGNORE_ENDmarkers only for documented false positives that cannot be resolved in code; keep ignored blocks small, add explanatory comments, and require reviewer sign-off
Files:
integrations/opencode-plugin/server.js
**/*.{md,markdown,py,sh,bash,js,ts,java,cpp,go,rust}
📄 CodeRabbit inference engine (.agents/skills/contribute-docs/SKILL.md)
Keep package names, repo references, and build commands current in documentation
Files:
integrations/opencode-plugin/server.js
**/*.{md,markdown,py,sh,bash,js,ts,example}
📄 CodeRabbit inference engine (.agents/skills/contribute-docs/SKILL.md)
Example commands must match current package names and paths
Files:
integrations/opencode-plugin/server.js
**/{integrations,integration,*-integration}/**
📄 CodeRabbit inference engine (.agents/skills/contribute-integration/SKILL.md)
**/{integrations,integration,*-integration}/**: Keep NeMo Flow optional in framework integrations
Preserve the framework's original behavior when NeMo Flow is absent
Wrap tool and LLM paths at the correct framework boundary
Integration pattern must followdocs/integrate-frameworks/adding-scopes.md
Files:
integrations/opencode-plugin/server.js
{crates/adaptive/**,python/nemo_flow/{adaptive,plugin}.py,go/nemo_flow/{adaptive,**}/*.go,**/*.{ts,js,wasm}}
📄 CodeRabbit inference engine (.agents/skills/maintain-optimizer/SKILL.md)
Keep adaptive config schema, plugin lifecycle, and bindings in sync across crates/adaptive, core, bindings, Python (python/nemo_flow/adaptive.py and python/nemo_flow/plugin.py), Go (go/nemo_flow/adaptive and go/nemo_flow), and Node/WebAssembly helpers
Files:
integrations/opencode-plugin/server.js
**/*.{js,ts,tsx,jsx,py,rs,go,java,c,cpp,h,cc,cxx,cs,rb,php,swift,kt}
📄 CodeRabbit inference engine (.agents/skills/prepare-pr/SKILL.md)
Changed files must be formatted with the language-native formatter
Files:
integrations/opencode-plugin/server.js
**/*.{rs,py,js,ts,go,sh,toml,yaml,yml,json,md,rst}
📄 CodeRabbit inference engine (AGENTS.md)
Keep SPDX headers on source, docs, scripts, and configuration files. The project is Apache-2.0.
Files:
integrations/opencode-plugin/server.js
**/*.{ts,tsx,js,jsx}
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
If Node.js language surface changed, always run Node.js test target even when Rust core did not change
Files:
integrations/opencode-plugin/server.js
**/*.{py,js,ts,tsx,go,rs,md}
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
Format changed files with the language-native formatter before the final lint/test pass
Files:
integrations/opencode-plugin/server.js
**/*.{rs,py,js,ts,tsx,go}
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
During iteration, prefer
uv run pre-commit run --files <changed files...>for targeted validation
Files:
integrations/opencode-plugin/server.js
| // SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. | ||
| // SPDX-License-Identifier: Apache-2.0 |
There was a problem hiding this comment.
Use a C-style SPDX header in this JavaScript file.
The repo requires JS SPDX headers in C-style comment syntax; the current // form can be missed by license tooling.
Suggested fix
-// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-// SPDX-License-Identifier: Apache-2.0
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */As per coding guidelines, **/*.{rs,go,js,ts,tsx}: Include SPDX license headers in all Rust, Go, JavaScript, and TypeScript source files using C-style comment syntax.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| // SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. | |
| // SPDX-License-Identifier: Apache-2.0 | |
| /* | |
| * SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. | |
| * SPDX-License-Identifier: Apache-2.0 | |
| */ |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@integrations/opencode-plugin/server.js` around lines 1 - 2, Replace the
line-style SPDX header comments at the top of
integrations/opencode-plugin/server.js with a C-style comment block;
specifically, change the two leading single-line comments containing
"SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
All rights reserved." and "SPDX-License-Identifier: Apache-2.0" into a single /*
... */ block so the file has a C-style SPDX header as required by the repo's
licensing guidelines.
| async function write(level, message, extra) { | ||
| const record = { | ||
| timestamp: new Date().toISOString(), | ||
| level, | ||
| plugin: PLUGIN_ID, | ||
| message, | ||
| ...(extra === undefined ? {} : { extra: toJsonSafe(extra) }), | ||
| } | ||
| const line = JSON.stringify(record) + "\n" | ||
| if (logPath) { | ||
| await ensureParentDir(logPath) | ||
| await fs.appendFile(logPath, line) | ||
| return | ||
| } | ||
| const text = `[${PLUGIN_ID}] ${message}` | ||
| if (level === "error") console.error(text, extra ?? "") | ||
| else if (level === "warn") console.warn(text, extra ?? "") | ||
| else console.info(text, extra ?? "") | ||
| } | ||
|
|
||
| return { | ||
| info: (message, extra) => write("info", message, extra), | ||
| warn: (message, extra) => write("warn", message, extra), | ||
| error: (message, extra) => write("error", message, extra), | ||
| warnOnce: (key, message, extra) => { | ||
| if (seen.has(key)) return Promise.resolve() | ||
| seen.add(key) | ||
| return write("warn", message, extra) |
There was a problem hiding this comment.
Do not let logger I/O failures reject plugin hooks.
write() currently propagates filesystem errors. An unwritable .nemoflow directory can turn plugin initialization into a rejected load, and every fire-and-forget void logger.* call elsewhere becomes an unhandled rejection. The logger should swallow/fallback internally so observability failures stay non-fatal.
As per coding guidelines, **/{integrations,integration,*-integration}/**: Keep NeMo Flow optional in framework integrationsandPreserve the framework's original behavior when NeMo Flow is absent`.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@integrations/opencode-plugin/server.js` around lines 33 - 60, The write
function currently lets filesystem errors bubble up and reject plugin hooks;
wrap the entire body of write (the path-handling, ensureParentDir, fs.appendFile
and the console logging branches) in a try/catch so any thrown error is
swallowed (or downgraded to a non-fatal fallback) and write always resolves; on
fs failures fall back to console logging the same formatted message (include
PLUGIN_ID, message and toJsonSafe(extra)), and ensure warnOnce/info/warn/error
callers (and the seen set logic) continue to return a resolved Promise rather
than letting errors propagate from write (keep the existing Promise.resolve()
return for the seen shortcut). Use the existing symbols write, PLUGIN_ID,
logPath, ensureParentDir, fs.appendFile, toJsonSafe and seen to locate where to
add the try/catch and fallback.
| const recentFlushes = new Map() | ||
| const trajectories = [] |
There was a problem hiding this comment.
Expire recentFlushes; this dedupe cache currently grows forever.
The map is only used for a 2s duplicate-flush window, but entries are never pruned. On a long-lived OpenCode process it grows with every completed session.
Also applies to: 343-343, 402-403
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@integrations/opencode-plugin/server.js` around lines 197 - 198, recentFlushes
is an unbounded Map used as a 2s dedupe cache and needs pruning; change its
entries so each key maps to insertion timestamp (or schedule a per-key
setTimeout) and remove entries older than 2 seconds. Locate the recentFlushes
usage in server.js (the const recentFlushes = new Map() declaration and any code
that checks/sets keys) and: when adding a key, store Date.now() (or schedule a
setTimeout to delete that key after 2000ms); when checking a key, consider it
expired if its timestamp is >2000ms old and delete it before proceeding;
optionally add a short periodic cleanup (setInterval) to remove stale keys if
you choose timestamp-based approach. Ensure the semantics of the dedupe window
remain 2 seconds and that no other code relies on Map values being
non-timestamps.
| lib.registerSubscriber(atofSubscriberName, (event) => { | ||
| fsSync.appendFileSync(options.atofPath, JSON.stringify(event) + "\n") | ||
| }) |
There was a problem hiding this comment.
Contain ATOF export write failures inside the subscriber callback.
appendFileSync() is executed directly on the subscriber path with no error handling. ENOSPC/EACCES here will throw synchronously while the runtime is delivering events, which can break the host flow instead of degrading observability only.
As per coding guidelines, **/{integrations,integration,*-integration}/**: Keep NeMo Flow optional in framework integrationsandPreserve the framework's original behavior when NeMo Flow is absent`.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@integrations/opencode-plugin/server.js` around lines 214 - 216, The
subscriber registered via lib.registerSubscriber(using atofSubscriberName)
writes with fsSync.appendFileSync(options.atofPath, ...) with no error handling;
wrap the appendFileSync call inside a try/catch inside the subscriber callback,
and on error log or swallow the error (use existing logger or console.error) so
ENOSPC/EACCES or other sync I/O failures do not throw out of the event delivery
path; keep the callback signature and behavior otherwise unchanged so NeMo
Flow/framework behavior is preserved.
| function withStack(session, callback) { | ||
| if (!session.stack || typeof lib.setThreadScopeStack !== "function") return callback() | ||
| const previous = typeof lib.currentScopeStack === "function" ? lib.currentScopeStack() : undefined | ||
| lib.setThreadScopeStack(session.stack) | ||
| try { | ||
| return callback() | ||
| } finally { | ||
| if (previous) lib.setThreadScopeStack(previous) | ||
| } |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
fd -t f "server.js" integrations/Repository: NVIDIA/NeMo-Flow
Length of output: 99
🏁 Script executed:
wc -l integrations/opencode-plugin/server.jsRepository: NVIDIA/NeMo-Flow
Length of output: 103
🏁 Script executed:
sed -n '245,265p' integrations/opencode-plugin/server.jsRepository: NVIDIA/NeMo-Flow
Length of output: 695
🏁 Script executed:
head -50 integrations/opencode-plugin/server.jsRepository: NVIDIA/NeMo-Flow
Length of output: 1456
🏁 Script executed:
rg "setThreadScopeStack|currentScopeStack" integrations/opencode-plugin/server.js -B 2 -A 2Repository: NVIDIA/NeMo-Flow
Length of output: 459
🏁 Script executed:
rg "setThreadScopeStack|currentScopeStack" --type js --type tsRepository: NVIDIA/NeMo-Flow
Length of output: 619
🏁 Script executed:
cat crates/wasm/wrappers/esm/index.jsRepository: NVIDIA/NeMo-Flow
Length of output: 3030
🏁 Script executed:
rg "export.*setThreadScopeStack|export.*currentScopeStack" --type jsRepository: NVIDIA/NeMo-Flow
Length of output: 42
🏁 Script executed:
find crates -name "*.rs" -type f | xargs rg "fn setThreadScopeStack|fn currentScopeStack" -A 5Repository: NVIDIA/NeMo-Flow
Length of output: 44
🏁 Script executed:
find crates/adaptive -name "*.rs" | head -20Repository: NVIDIA/NeMo-Flow
Length of output: 882
🏁 Script executed:
rg "setThreadScopeStack|currentScopeStack" crates/adaptive/ -A 3 -B 1Repository: NVIDIA/NeMo-Flow
Length of output: 42
🏁 Script executed:
rg "setThreadScopeStack" crates/ -A 3 -B 1Repository: NVIDIA/NeMo-Flow
Length of output: 6336
🏁 Script executed:
fd -e rs -e ts -e js | xargs rg "pub fn setThreadScopeStack|pub.*setThreadScopeStack" -A 5Repository: NVIDIA/NeMo-Flow
Length of output: 44
🏁 Script executed:
rg "thread.*scope.*stack|scope.*stack.*thread" crates/ --type rs -iRepository: NVIDIA/NeMo-Flow
Length of output: 87
🏁 Script executed:
cat crates/wasm/src/api/mod.rs | sed -n '1,100p'Repository: NVIDIA/NeMo-Flow
Length of output: 4343
🏁 Script executed:
rg "bind_thread_scope_stack|set_thread_scope_stack" crates/ --type rs -B 2 -A 8Repository: NVIDIA/NeMo-Flow
Length of output: 87
🏁 Script executed:
cat crates/node/tests/context_tests.mjs | grep -A 20 "setThreadScopeStack isolates"Repository: NVIDIA/NeMo-Flow
Length of output: 849
🏁 Script executed:
rg "pub fn set_thread_scope_stack|pub.*setThreadScopeStack" crates/wasm/src/api/mod.rs -A 10Repository: NVIDIA/NeMo-Flow
Length of output: 478
🏁 Script executed:
rg "TASK_SCOPE_STACK|set_thread_scope_stack" crates/node/src/api/mod.rs -B 2 -A 10Repository: NVIDIA/NeMo-Flow
Length of output: 6474
🏁 Script executed:
cat crates/node/tests/context_tests.mjs | grep -B 5 -A 15 "Switch back to stack1"Repository: NVIDIA/NeMo-Flow
Length of output: 510
🏁 Script executed:
rg "currentScopeStack.*undefined|undefined.*setThreadScopeStack" crates/node/tests/ -B 3 -A 3Repository: NVIDIA/NeMo-Flow
Length of output: 42
🏁 Script executed:
cat crates/node/tests/context_tests.mjs | grep -B 10 -A 10 "original = currentScopeStack"Repository: NVIDIA/NeMo-Flow
Length of output: 1591
Always restore the previous scope stack.
If currentScopeStack() returns no prior stack, the finally block leaves session.stack installed on the thread. Subsequent marks/spans can then inherit the wrong session scope and corrupt cross-session telemetry.
Suggested fix
function withStack(session, callback) {
if (!session.stack || typeof lib.setThreadScopeStack !== "function") return callback()
const previous = typeof lib.currentScopeStack === "function" ? lib.currentScopeStack() : undefined
lib.setThreadScopeStack(session.stack)
try {
return callback()
} finally {
- if (previous) lib.setThreadScopeStack(previous)
+ lib.setThreadScopeStack(previous)
}
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| function withStack(session, callback) { | |
| if (!session.stack || typeof lib.setThreadScopeStack !== "function") return callback() | |
| const previous = typeof lib.currentScopeStack === "function" ? lib.currentScopeStack() : undefined | |
| lib.setThreadScopeStack(session.stack) | |
| try { | |
| return callback() | |
| } finally { | |
| if (previous) lib.setThreadScopeStack(previous) | |
| } | |
| function withStack(session, callback) { | |
| if (!session.stack || typeof lib.setThreadScopeStack !== "function") return callback() | |
| const previous = typeof lib.currentScopeStack === "function" ? lib.currentScopeStack() : undefined | |
| lib.setThreadScopeStack(session.stack) | |
| try { | |
| return callback() | |
| } finally { | |
| lib.setThreadScopeStack(previous) | |
| } | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@integrations/opencode-plugin/server.js` around lines 251 - 259, In withStack,
always restore the prior thread scope stack instead of only when previous is
truthy: capture priorStack via lib.currentScopeStack(), set
lib.setThreadScopeStack(session.stack) before running callback, and in the
finally block call lib.setThreadScopeStack(previousStack) (even if previousStack
is undefined) so the thread scope is always reset; reference the withStack
function and the lib.currentScopeStack / lib.setThreadScopeStack calls to locate
where to change the restore logic.
| "atof", | ||
| "plugin" | ||
| ], | ||
| "homepage": "https://github.com/NVIDIA/NeMo-Flow#readme", |
There was a problem hiding this comment.
This shouldn't be necessary.
Add integrations/opencode to the root package.json
| ``` | ||
|
|
||
| When the plugin package is published, use | ||
| `@nvidia/nemoflow-opencode-plugin` in the OpenCode config instead of the local |
There was a problem hiding this comment.
package should be: nemo-flow-opencode
| ## Demo Video Script | ||
|
|
||
| Use this storyboard to record a short walkthrough. | ||
|
|
||
| | Shot | Show | Narration | | ||
| |---|---|---| | ||
| | 1 | `opencode.json` with the plugin file URL | Stock OpenCode loads the NeMo Flow plugin through normal plugin config. | | ||
| | 2 | `opencode debug info` output | OpenCode sees the plugin without applying an OpenCode patch. | | ||
| | 3 | `opencode run` or the interactive OpenCode UI | The developer uses OpenCode normally. | | ||
| | 4 | `ls -la .nemoflow` | The plugin writes observability files in the background. | | ||
| | 5 | `grep` against `opencode.atof.jsonl` | ATOF contains session, message, LLM request, and tool lifecycle events. | | ||
| | 6 | `jq` against `opencode.atif.json` | ATIF contains the exported session trajectory. | | ||
| | 7 | Disabled or forced-failure smoke | OpenCode still runs when the plugin is disabled or pass-through. | | ||
|
|
||
| Keep the recording focused on the user-visible contract: install the plugin, | ||
| use OpenCode normally, and inspect `.nemoflow` output after the session. |
There was a problem hiding this comment.
I don't understand the purpose of this. The document here is for end users. Documentation should be relevant to them, not to developers
| setThreadScopeStack(_stack) {}, | ||
| pushScope(name, scopeType, _parent, attributes, data, metadata, input) { | ||
| const handle = { | ||
| uuid: `scope-${++counter}`, |
There was a problem hiding this comment.
This is not a valid UUID. When in doubt, let UUIDs be generated automatically.
| { | ||
| "plugin": [ | ||
| [ | ||
| "file:///absolute/path/to/NeMo-Flow/integrations/opencode-plugin", | ||
| { | ||
| "enabled": true, | ||
| "atofPath": "./.nemoflow/opencode.atof.jsonl", | ||
| "atifPath": "./.nemoflow/opencode.atif.json", | ||
| "logPath": "./.nemoflow/opencode-plugin.log" | ||
| } | ||
| ] | ||
| ] | ||
| } |
There was a problem hiding this comment.
This is okay for now, but the configuration shape should be relatively consistent across all integrations (and support plugins in the future)
| model: modelName(input.model), | ||
| }) | ||
| if (!session) return | ||
| emitMark( |
There was a problem hiding this comment.
why is this a mark and not llmCall ?
There was a problem hiding this comment.
Without a matching llmCallEnd, i'm not sure how useful this is :(
| model: modelName(input.model ?? output?.message?.model), | ||
| }) | ||
| if (!session) return | ||
| emitMark( |
There was a problem hiding this comment.
why is this a mark and not llmCallEnd ?
There was a problem hiding this comment.
chat.message marks user message input sent. It's not llmCallEnd.
Opencode doesn't have a hook for llmCallEnd yet.
I can heuristically infer that from checking finish_reason from updated messages. But it's not a native way.
There was a problem hiding this comment.
Ah okay... I see :( That's seriously limiting.
I interpreted "message received" as inbound LLM response. Pardon the noise.
Co-authored-by: Will Killian <2007799+willkill07@users.noreply.github.com> Signed-off-by: Binfeng Xu <billxbf@gmail.com>
Co-authored-by: Will Killian <2007799+willkill07@users.noreply.github.com> Signed-off-by: Binfeng Xu <billxbf@gmail.com>
There was a problem hiding this comment.
Actionable comments posted: 6
♻️ Duplicate comments (1)
integrations/opencode-plugin/package.json (1)
32-32: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick winConsider linking to integration-specific documentation.
The homepage currently points to the general NeMo-Flow README. Per previous review feedback, consider linking directly to the OpenCode integration documentation if available (e.g., a specific section or doc page for this plugin).
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@integrations/opencode-plugin/package.json` at line 32, The package.json "homepage" field for the OpenCode plugin points to the general NeMo-Flow README; update the "homepage" value in the integrations/opencode-plugin package.json to a URL that points directly to the OpenCode integration documentation (e.g., a specific section, doc page, or repo path for the OpenCode plugin) or, if no dedicated doc exists, add a short internal doc and link to it; modify the "homepage" string to that integration-specific URL so the package links to the correct documentation.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/integrate-frameworks/opencode.md`:
- Around line 22-43: The Mermaid diagram block (the ```{mermaid} ... flowchart
LR ... ``` section) is missing an introductory sentence; add a complete lead-in
sentence immediately before the ```{mermaid} block that briefly explains what
the diagram illustrates (e.g., "The following diagram shows the flow between
Developer, Stock OpenCode, the NeMo Flow plugin and runtime and the ATOF/ATIF
exports.") so the diagram is properly introduced and follows the documentation
guideline for complete-sentence introductions.
- Around line 50-51: Update the sentence that reads "Build the NeMo Flow Node.js
binding before loading the plugin from a source checkout. `crates/node` is under
the NeMo Flow repository root:" by formatting the directory path crates/node as
inline code (monospace) so it appears as `crates/node`; locate the sentence
starting with "Build the NeMo Flow Node.js binding..." in
docs/integrate-frameworks/opencode.md and replace the plain text path with the
inline-code version.
In `@integrations/opencode-plugin/package.json`:
- Line 47: The package.json currently references a local file dependency
"nemo-flow-node": "file:../../crates/node" which will break npm publish; fix it
by either replacing that file: spec with a published semver (e.g.,
"nemo-flow-node": "x.y.z") or add a prepublishOnly script that rewrites the
dependency to a published version before packing, or publish nemo-flow-node
separately and reference it by version, or mark this package as "private": true
and document that it is workspace-only; update package.json accordingly and
ensure any publish scripts or README reflect the chosen approach.
- Around line 7-16: Remove the redundant "default" export conditions from the
package.json exports map since "type":"module" makes "import" sufficient; update
the exports entries for "." and "./server" to only use the "import":
"./server.js" condition so that both export paths point to server.js with a
single import condition, ensuring no other keys are changed.
- Line 44: The engines entry in package.json includes a nonstandard "opencode"
constraint which npm ignores; remove the "opencode" key from the engines object
and either add an appropriate entry under peerDependencies or devDependencies
(e.g., "opencode": ">=1.14.40") if you need package-level version enforcement,
or move it to a documentation-only field (e.g., a custom "metadata" or README)
if it's merely informational; update the package.json JSON structure accordingly
and ensure package installs still validate "node" and "npm" under the existing
engines field.
- Around line 46-48: The package.json currently lists "nemo-flow-node" as a hard
dependency; change it to an optional dependency (move "nemo-flow-node" from
"dependencies" into "optionalDependencies") so the runtime try/catch dynamic
import behavior (the code that dynamically imports "nemo-flow-node" and returns
{} on failure) can gracefully fall back, or alternatively move it to
"peerDependencies" if the host framework must supply it; update only the
dependency section and leave the dynamic import logic unchanged.
---
Duplicate comments:
In `@integrations/opencode-plugin/package.json`:
- Line 32: The package.json "homepage" field for the OpenCode plugin points to
the general NeMo-Flow README; update the "homepage" value in the
integrations/opencode-plugin package.json to a URL that points directly to the
OpenCode integration documentation (e.g., a specific section, doc page, or repo
path for the OpenCode plugin) or, if no dedicated doc exists, add a short
internal doc and link to it; modify the "homepage" string to that
integration-specific URL so the package links to the correct documentation.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Enterprise
Run ID: 3a4c7fc0-c8cb-432c-9ef4-a7c4abadf751
📒 Files selected for processing (2)
docs/integrate-frameworks/opencode.mdintegrations/opencode-plugin/package.json
📜 Review details
🧰 Additional context used
📓 Path-based instructions (21)
**/{integrations,integration,*-integration}/**
📄 CodeRabbit inference engine (.agents/skills/contribute-integration/SKILL.md)
**/{integrations,integration,*-integration}/**: Keep NeMo Flow optional in framework integrations
Preserve the framework's original behavior when NeMo Flow is absent
Wrap tool and LLM paths at the correct framework boundary
Integration pattern must followdocs/integrate-frameworks/adding-scopes.md
Files:
integrations/opencode-plugin/package.json
**/*.{md,rst,html,txt}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-brand-terminology.md)
**/*.{md,rst,html,txt}: Always spellNVIDIAin all caps. Do not useNvidia,nvidia,nVidia,nVIDIA, orNV.
Usean NVIDIAbefore a noun because the name starts with an 'en' sound.
Do not add a registered trademark symbol afterNVIDIAwhen referring to the company.
Use trademark symbols with product names only when the document type or legal guidance requires them.
Verify official capitalization, spacing, and hyphenation for product names.
Precede NVIDIA product names withNVIDIAon first mention when it is natural and accurate.
Do not rewrite product names for grammar or title-case rules.
Preserve third-party product names according to the owner's spelling.
Include the company name and full model qualifier on first use when it helps identify the model.
Preserve the official capitalization and punctuation of model names.
Use shorter family names only after the full name is established.
Spell out a term on first use and put the acronym in parentheses unless the acronym is widely understood by the intended audience.
Use the acronym on later mentions after it has been defined.
For long documents, reintroduce the full term if readers might lose context.
Form plurals of acronyms withs, not an apostrophe, such asGPUs.
In headings, common acronyms can remain abbreviated. Spell out the term in the first or second sentence of the body.
Common terms such asCPU,GPU,PC,API, andUIusually do not need to be spelled out for developer audiences.
Files:
docs/integrate-frameworks/opencode.md
**/*.{md,rst,html}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-brand-terminology.md)
Link the first mention of a product name when the destination helps the reader.
Files:
docs/integrate-frameworks/opencode.md
**/*.{md,rst,txt}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-guide.md)
**/*.{md,rst,txt}: SpellNVIDIAin all caps. Do not useNvidia,nvidia, orNV.
Format commands, code elements, expressions, package names, file names, and paths as inline code.
Use descriptive link text. Avoid raw URLs and weak anchors such as 'here' or 'read more.'
Use title case consistently for technical documentation headings.
Introduce code blocks, lists, tables, and images with complete sentences.
Write procedures as imperative steps. Keep steps parallel and split long procedures into smaller tasks.
Prefer active voice, present tense, short sentences, contractions, and plain English.
Usecanfor possibility and reservemayfor permission.
Useafterfor temporal relationships instead ofonce.
Preferrefer tooverseewhen the wording points readers to another resource.
Avoid culture-specific idioms, unnecessary Latinisms, jokes, and marketing exaggeration in technical documentation.
Spell out months in body text, avoid ordinal dates, and use clear time zones.
Spell out whole numbers from zero through nine unless they are technical values, parameters, versions, or UI values.
Use numerals for 10 or greater and include commas in thousands.
Do not add trademark symbols to learning-oriented documentation unless the source, platform, or legal guidance explicitly requires them.
Do not add trademark symbols to NeMo Flow learning documentation by default.
Do not rewrite API names, package names, command flags, or code literals for style reasons.
Files:
docs/integrate-frameworks/opencode.md
**/*.{md,markdown,rst}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/assets/nvidia-style-technical-docs.md)
**/*.{md,markdown,rst}: Use title case consistently in technical documentation headings
Avoid quotation marks, ampersands, and exclamation marks in headings
Keep product, event, research, and whitepaper names in their official title case
Use title case for table headers
Do not force social-media sentence case into technical docs
Use monospace formatting for code elements, commands, parameters, package names, and expressions
Use monospace formatting for directories, file names, and paths
Use angle brackets inside monospace for variables inside paths, such as/home/<username>/.login
Use quotation marks for error messages and strings in documentation
Use bold formatting for UI buttons, menus, fields, and labels in documentation
Use angle brackets between UI labels for menu paths, such as File > Save As
Use italics for new terms on first use in documentation
Use italics for publication titles in documentation
Use plain text formatting for keyboard shortcuts in documentation
Prefer[NVIDIA/NeMo](link)format for GitHub repository references over generic phrases like 'the GitHub repo'
Introduce every code block with a complete sentence
Do not make a code block complete the grammar of the previous sentence
Do not continue a sentence after a code block
Use syntax highlighting when the format supports it for code blocks
Avoid the word 'snippet' unless the surrounding docs already use it as a term of art
Keep inline method, function, and class references consistent with nearby docs, omitting empty parentheses for prose readability when no call is shown
Use descriptive anchor text that matches the destination title when possible for links
Avoid raw URLs in running text in documentation
Avoid generic link anchors such as 'here,' 'this page,' and 'read more' in documentation
Include the acronym in link text if a linked term includes an acronym
Do not link long sentences or multiple sentences in documentation
Avoid links that pull readers away from a procedure unles...
Files:
docs/integrate-frameworks/opencode.md
**/*.{html,md}
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Include SPDX license headers in HTML and Markdown files using HTML comment syntax
Files:
docs/integrate-frameworks/opencode.md
docs/**/*.md
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run
./scripts/build-docs.shfor documentation site changes
docs/**/*.md: Relevant getting-started or reference docs must be updated when examples change
Release-policy docs must point to GitHub Releases as the only release-history source of truth
docs/**/*.md: Use title case for headings in technical documentation
Introduce code blocks, tables, and lists with complete lead-in sentences in documentation
Files:
docs/integrate-frameworks/opencode.md
**/*.md
📄 CodeRabbit inference engine (CONTRIBUTING.md)
Run Markdown link checking via
lycheeforREADME.md,CONTRIBUTING.md, anddocs/through pre-commit hooks
Files:
docs/integrate-frameworks/opencode.md
**/*.{md,markdown,py,sh,bash,js,ts,java,cpp,go,rust}
📄 CodeRabbit inference engine (.agents/skills/contribute-docs/SKILL.md)
Keep package names, repo references, and build commands current in documentation
Files:
docs/integrate-frameworks/opencode.md
{RELEASING.md,CHANGELOG.md,docs/**/*.md}
📄 CodeRabbit inference engine (.agents/skills/contribute-docs/SKILL.md)
Keep release-process and release-notes guidance in repo-maintainer docs such as RELEASING.md, not as user-facing docs pages or CHANGELOG.md
Files:
docs/integrate-frameworks/opencode.md
**/*.{md,markdown,py,sh,bash}
📄 CodeRabbit inference engine (.agents/skills/contribute-docs/SKILL.md)
Keep stable user-facing wrappers at scripts/ root in docs and examples; only point at namespaced helper paths when documenting internal maintenance work
Files:
docs/integrate-frameworks/opencode.md
**/*.{md,markdown,py,sh,bash,js,ts,example}
📄 CodeRabbit inference engine (.agents/skills/contribute-docs/SKILL.md)
Example commands must match current package names and paths
Files:
docs/integrate-frameworks/opencode.md
docs/integrate-frameworks/**/*.md
📄 CodeRabbit inference engine (.agents/skills/contribute-integration/SKILL.md)
Documentation must be updated if activation or usage of the integration changed
Files:
docs/integrate-frameworks/opencode.md
{scripts/*.sh,docs/**/*.md}
📄 CodeRabbit inference engine (.agents/skills/contribute-integration/SKILL.md)
Use root
./scripts/*.shcommands in docs and contributor guidance as documented, with implementations underscripts/third-party/
Files:
docs/integrate-frameworks/opencode.md
{docs/**,examples/**,crates/adaptive/**,python/nemo_flow/**,go/nemo_flow/**,**/{example,component}.{ts,tsx,js,rs,py,go}}
📄 CodeRabbit inference engine (.agents/skills/maintain-optimizer/SKILL.md)
Any new adaptive component kind must have documentation, examples, and binding coverage across all supported languages
Files:
docs/integrate-frameworks/opencode.md
{README*,CHANGELOG*,docs/**/*.{md,rst,txt},examples/**/*,*.md}
📄 CodeRabbit inference engine (.agents/skills/rename-surfaces/SKILL.md)
Update documentation, examples, and getting-started guides with new package/module/crate names after rename operations
Files:
docs/integrate-frameworks/opencode.md
**/*.{md,txt,rst}
📄 CodeRabbit inference engine (.agents/skills/review-doc-style/SKILL.md)
**/*.{md,txt,rst}: Ensure commands, package names, file paths, and APIs in documentation are correct and not stale; flag incorrect or outdated information as blocking issues
Ensure examples and procedures in documentation will execute successfully with current APIs and commands
Use consistent user-facing terminology throughout documentation that matches current repo terminology
Capitalize NVIDIA correctly in all documentation and public-facing text
Format code, commands, paths, and filenames as inline code (monospace) in documentation
Use descriptive anchor text for links instead of bare URLs or weak labels like 'here' in documentation
Prefer active voice, present tense, short sentences, and plain English in documentation
Structure documentation procedures as imperative steps that are easy to scan and not too long for a single sequence
Prefer 'after' instead of 'once' for temporal references in documentation
Use 'can' instead of 'may' when describing possibility (rather than permission) in documentation
Avoid ambiguous numeric dates and ordinal dates in documentation body text
Files:
docs/integrate-frameworks/opencode.md
{README.md,docs/**/*.md,examples/**/*.{js,ts,py,go,rs}}
📄 CodeRabbit inference engine (.agents/skills/maintain-packaging/SKILL.md)
Keep documentation and examples synchronized with current install, import, and build commands
Files:
docs/integrate-frameworks/opencode.md
**/*.{py,js,ts,tsx,go,rs,md}
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
Format changed files with the language-native formatter before the final lint/test pass
Files:
docs/integrate-frameworks/opencode.md
{README.md,CONTRIBUTING.md,docs/**/*.md}
📄 CodeRabbit inference engine (.agents/skills/validate-change/SKILL.md)
For docs-only changes, run targeted checks only if commands, package names, or examples changed. Use
just docsfor docs-site builds andjust docs-linkcheckwhen links changed
Files:
docs/integrate-frameworks/opencode.md
{docs/**,README.md,CONTRIBUTING.md,RELEASING.md,SECURITY.md}
⚙️ CodeRabbit configuration file
{docs/**,README.md,CONTRIBUTING.md,RELEASING.md,SECURITY.md}: Review documentation for technical accuracy against the current API, command correctness, and consistency across language bindings.
Flag stale examples, missing SPDX headers where required, and instructions that no longer match CI or pre-commit behavior.
Files:
docs/integrate-frameworks/opencode.md
🔇 Additional comments (4)
docs/integrate-frameworks/opencode.md (3)
68-70: Inconsistent package identifier.Line 69 mentions the published package as
@nvidia/nemoflow-opencode-plugin, but the configuration example at line 80 usesnemo-flow-opencode. These identifiers should match the actual published package name.
92-94: Runtime failure scenario documented.The documentation describes pass-through behavior when
nemo-flow-nodeis missing or fails to initialize. This was previously questioned as unnecessary ifnemo-flow-nodeis a declared dependency of the plugin package.
248-263: Demo video script in user-facing documentation.This section provides a storyboard for recording a walkthrough video. It may be more appropriate for internal contributor documentation or marketing materials rather than user-facing integration guides.
integrations/opencode-plugin/package.json (1)
50-50: ⚡ Quick winVerify
@opencode-ai/pluginversion 1.14.40 exists.The package specifies
@opencode-ai/plugin@>=1.14.40as a peer dependency and^1.14.40as a dev dependency. Confirm that version 1.14.40 exists in the npm registry and that this is the correct minimum version for the plugin API surface used inserver.js.What is the latest version of `@opencode-ai/plugin` on npm and does version 1.14.40 exist?Also applies to: 53-53
| ```{mermaid} | ||
| flowchart LR | ||
| User[Developer] | ||
| OpenCode[Stock OpenCode] | ||
| Plugin[NeMo Flow<br/>OpenCode plugin] | ||
| Runtime[NeMo Flow<br/>Node.js binding] | ||
| ATOF[(ATOF JSONL)] | ||
| ATIF[(ATIF JSON)] | ||
|
|
||
| User -->|uses normally| OpenCode | ||
| OpenCode -->|public plugin hooks| Plugin | ||
| Plugin -->|scopes, marks,<br/>tool lifecycle| Runtime | ||
| Runtime -->|append events| ATOF | ||
| Runtime -->|export on idle<br/>or deleted session| ATIF | ||
|
|
||
| class User blue-lightest; | ||
| class OpenCode green-lightest; | ||
| class Plugin purple-lightest; | ||
| class Runtime green-light; | ||
| class ATOF yellow-lightest; | ||
| class ATIF yellow-lightest; | ||
| ``` |
There was a problem hiding this comment.
Add a complete lead-in sentence before the diagram.
The Mermaid diagram appears without an explicit introduction. As per coding guidelines, all code blocks, diagrams, tables, and images must be introduced with complete sentences.
📝 Suggested lead-in sentence
Add a sentence before line 22, such as:
interface or `opencode run`. The plugin observes OpenCode hooks and writes
NeMo Flow ATOF and ATIF files under the OpenCode project directory.
+The following diagram illustrates the observability flow:
+
```{mermaid}
flowchart LR🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/integrate-frameworks/opencode.md` around lines 22 - 43, The Mermaid
diagram block (the ```{mermaid} ... flowchart LR ... ``` section) is missing an
introductory sentence; add a complete lead-in sentence immediately before the
```{mermaid} block that briefly explains what the diagram illustrates (e.g.,
"The following diagram shows the flow between Developer, Stock OpenCode, the
NeMo Flow plugin and runtime and the ATOF/ATIF exports.") so the diagram is
properly introduced and follows the documentation guideline for
complete-sentence introductions.
| Build the NeMo Flow Node.js binding before loading the plugin from a source | ||
| checkout. `crates/node` is under the NeMo Flow repository root: |
There was a problem hiding this comment.
Format directory path as inline code.
The directory path crates/node should be formatted as inline code (monospace). As per coding guidelines, use monospace formatting for directories, file names, and paths.
📝 Proposed fix
Build the NeMo Flow Node.js binding before loading the plugin from a source
-checkout. crates/node is under the NeMo Flow repository root:
+checkout. `crates/node` is under the NeMo Flow repository root:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Build the NeMo Flow Node.js binding before loading the plugin from a source | |
| checkout. `crates/node` is under the NeMo Flow repository root: | |
| Build the NeMo Flow Node.js binding before loading the plugin from a source | |
| checkout. `crates/node` is under the NeMo Flow repository root: |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/integrate-frameworks/opencode.md` around lines 50 - 51, Update the
sentence that reads "Build the NeMo Flow Node.js binding before loading the
plugin from a source checkout. `crates/node` is under the NeMo Flow repository
root:" by formatting the directory path crates/node as inline code (monospace)
so it appears as `crates/node`; locate the sentence starting with "Build the
NeMo Flow Node.js binding..." in docs/integrate-frameworks/opencode.md and
replace the plain text path with the inline-code version.
| "exports": { | ||
| ".": { | ||
| "default": "./server.js", | ||
| "import": "./server.js" | ||
| }, | ||
| "./server": { | ||
| "default": "./server.js", | ||
| "import": "./server.js" | ||
| } | ||
| }, |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial | 💤 Low value
Simplify export conditions in ES module package.
Since type is "module", the "default" condition in the exports map is redundant alongside "import". You can simplify to just "import": "./server.js" for each export path.
♻️ Simplified exports
"exports": {
".": {
- "default": "./server.js",
"import": "./server.js"
},
"./server": {
- "default": "./server.js",
"import": "./server.js"
}
},📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "exports": { | |
| ".": { | |
| "default": "./server.js", | |
| "import": "./server.js" | |
| }, | |
| "./server": { | |
| "default": "./server.js", | |
| "import": "./server.js" | |
| } | |
| }, | |
| "exports": { | |
| ".": { | |
| "import": "./server.js" | |
| }, | |
| "./server": { | |
| "import": "./server.js" | |
| } | |
| }, |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@integrations/opencode-plugin/package.json` around lines 7 - 16, Remove the
redundant "default" export conditions from the package.json exports map since
"type":"module" makes "import" sufficient; update the exports entries for "."
and "./server" to only use the "import": "./server.js" condition so that both
export paths point to server.js with a single import condition, ensuring no
other keys are changed.
| "license": "Apache-2.0", | ||
| "engines": { | ||
| "node": ">=20.0.0", | ||
| "opencode": ">=1.14.40" |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Does npm engines field support custom engine names like "opencode" or only "node" and "npm"?
💡 Result:
No, the npm "engines" field does not support arbitrary custom engine names like "opencode". It only recognizes and checks "node" and "npm" by default.[1][2][3] While the field is a generic object that accepts arbitrary keys (e.g., historical use of "iojs" for io.js runtime),[4][5][6] npm CLI only performs version checks and warnings for the known engines "node" (using process.version) and "npm" (using process.env.npm_version).[1][2][7] Custom keys like "opencode" are ignored by npm and serve only as advisory metadata without enforcement.[7]
Citations:
- 1: https://docs.npmjs.com/cli/v9/configuring-npm/package-json/?v=true
- 2: https://docs.npmjs.com/cli/v11/configuring-npm/package-json
- 3: https://www.unpkg.com/npm@10.8.2/docs/output/configuring-npm/package-json.html
- 4: https://www.marcusoft.net/2015/03/packagejson-and-engines-and-enginestrict.html
- 5: npm and iojs with new es6 features nodejs/node#269
- 6: package.json "engines" nodejs/node#363
- 7: feat: add
devEnginesfield npm/cli#7253
Remove or relocate the "opencode" engine constraint.
The engines field only validates "node" and "npm"; custom engine names like "opencode" are ignored by npm and provide no version enforcement. If opencode version constraints are needed, use peerDependencies or devDependencies instead, or clarify if this is intended as documentation-only metadata.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@integrations/opencode-plugin/package.json` at line 44, The engines entry in
package.json includes a nonstandard "opencode" constraint which npm ignores;
remove the "opencode" key from the engines object and either add an appropriate
entry under peerDependencies or devDependencies (e.g., "opencode": ">=1.14.40")
if you need package-level version enforcement, or move it to a
documentation-only field (e.g., a custom "metadata" or README) if it's merely
informational; update the package.json JSON structure accordingly and ensure
package installs still validate "node" and "npm" under the existing engines
field.
| "dependencies": { | ||
| "nemo-flow-node": "file:../../crates/node" | ||
| }, |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Check if server.js implements optional NeMo Flow behavior
# Search for optional/graceful fallback patterns in server.js
rg -nP -A5 -B5 '\b(optional|try|catch|require\.resolve)\b' integrations/opencode-plugin/server.js
# Check if nemo-flow-node import is wrapped in try-catch or conditional
ast-grep --pattern $'try {
$$$
} catch ($$$) {
$$$
}'Repository: NVIDIA/NeMo-Flow
Length of output: 10357
🏁 Script executed:
# Check the loadRuntime function implementation
sed -n '1,600p' integrations/opencode-plugin/server.js | grep -n "loadRuntime" -A 20Repository: NVIDIA/NeMo-Flow
Length of output: 1494
🏁 Script executed:
# Search for loadRuntime function definition
rg -n "function loadRuntime|const loadRuntime" integrations/opencode-plugin/server.js -A 15Repository: NVIDIA/NeMo-Flow
Length of output: 42
🏁 Script executed:
# Check if require/import of nemo-flow-node is dynamic or conditional
rg -n "nemo-flow-node|require.*node|import.*node" integrations/opencode-plugin/server.js -B 2 -A 2Repository: NVIDIA/NeMo-Flow
Length of output: 415
🏁 Script executed:
# Verify the complete package.json structure for dependency type
cat integrations/opencode-plugin/package.jsonRepository: NVIDIA/NeMo-Flow
Length of output: 1240
Change nemo-flow-node to an optional dependency to match the graceful fallback behavior.
The code dynamically imports nemo-flow-node with try-catch error handling (lines 567-581) that gracefully returns {} to continue as pass-through when the import fails. However, the dependency is declared as a hard dependency in package.json, which requires the module to be present at install time. This contradicts the integration guideline requirement to "keep NeMo Flow optional" and violates the fallback capability the code implements.
Change "nemo-flow-node" from dependencies to optionalDependencies, or move it to peerDependencies if the host framework should provide it.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@integrations/opencode-plugin/package.json` around lines 46 - 48, The
package.json currently lists "nemo-flow-node" as a hard dependency; change it to
an optional dependency (move "nemo-flow-node" from "dependencies" into
"optionalDependencies") so the runtime try/catch dynamic import behavior (the
code that dynamically imports "nemo-flow-node" and returns {} on failure) can
gracefully fall back, or alternatively move it to "peerDependencies" if the host
framework must supply it; update only the dependency section and leave the
dynamic import logic unchanged.
| "opencode": ">=1.14.40" | ||
| }, | ||
| "dependencies": { | ||
| "nemo-flow-node": "file:../../crates/node" |
There was a problem hiding this comment.
Local file: dependency will break npm publish.
The file:../../crates/node dependency path is valid for local development but will fail when this package is published to npm. Ensure your publish workflow resolves this, either by:
- Using a prepublishOnly script to rewrite the dependency to a published version
- Publishing
nemo-flow-nodeseparately and referencing it by version - Documenting that this package is workspace-only and not intended for npm registry
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@integrations/opencode-plugin/package.json` at line 47, The package.json
currently references a local file dependency "nemo-flow-node":
"file:../../crates/node" which will break npm publish; fix it by either
replacing that file: spec with a published semver (e.g., "nemo-flow-node":
"x.y.z") or add a prepublishOnly script that rewrites the dependency to a
published version before packing, or publish nemo-flow-node separately and
reference it by version, or mark this package as "private": true and document
that it is workspace-only; update package.json accordingly and ensure any
publish scripts or README reflect the chosen approach.
2 participants
Overview
Details
integrations/opencode-pluginas an npm package for OpenCode server plugin usage.crates/nodeopencodeopencode.jsonwith the plugin file URLopencodeand inspect.nemoflowoutputexample
opencode.jsonWhere should the reviewer start?
Start with
integrations/opencode-plugin/server.js, then reviewintegrations/opencode-plugin/test/server.test.mjs.Summary by CodeRabbit
New Features
Documentation
Tests
Chores