Repository navigation
Make the Lumen OpenCode plugin compatible with V2 #199
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
Filipe-Araujo0
wants to merge
6
commits into
ory:main
Choose a base branch
from
Filipe-Araujo0:port-opencode-v2-plugin
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
710f594
fix(opencode): port plugin to V2 API
Filipe-Araujo0 db188bd
fix(opencode): select platform launcher
Filipe-Araujo0 714004f
test(opencode): add V2 MCP host canary
Filipe-Araujo0 9948b2f
test(opencode): address host-canary review feedback
Filipe-Araujo0 c718f5f
Verify OpenCode V2 package resolution
Filipe-Araujo0 feb0c5b
Extend OpenCode V2 readiness window
Filipe-Araujo0 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,47 +1,45 @@ | ||
| # Installing Lumen for OpenCode | ||
|
|
||
| <!-- Updated 2026-11-10T17:42:18-03:00: align setup and verification with OpenCode V2. --> | ||
|
|
||
| Install Lumen as an OpenCode plugin from npm. The plugin registers a local MCP | ||
| server automatically. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - [OpenCode.ai](https://opencode.ai) installed | ||
| - [OpenCode.ai](https://opencode.ai) V2, version 2.2.7 or newer | ||
|
|
||
| ## Installation | ||
|
|
||
| Add Lumen to the `plugin` array in your `opencode.json`: | ||
| Add Lumen to the `plugins` array in your `opencode.json`: | ||
|
|
||
| ```json | ||
| { | ||
| "plugin": ["@ory/lumen-opencode"] | ||
| "plugins": ["@ory/lumen-opencode"] | ||
| } | ||
| ``` | ||
|
|
||
| Restart OpenCode. The plugin registers a local `mcp.lumen` server that runs | ||
| `scripts/run stdio` on all platforms (cross-spawn resolves `scripts/run.cmd` | ||
| via PATHEXT on Windows). | ||
| The plugin registers a local `mcp.lumen` server. It runs `scripts/run stdio` on | ||
| Linux and macOS, and `scripts/run.cmd stdio` on Windows. OpenCode reloads | ||
| configuration changes automatically; use `/reload` if the server does not | ||
| appear after installation. | ||
|
|
||
| ## Verify | ||
|
|
||
| ```bash | ||
| opencode mcp list | ||
| ``` | ||
|
|
||
| Then ask OpenCode to call the Lumen `semantic_search`, `health_check`, or | ||
| `index_status` MCP tools directly. | ||
| In an active OpenCode TUI, ask it to call the Lumen `semantic_search`, | ||
| `health_check`, or `index_status` MCP tools. If the server does not appear, | ||
| use `/reload` to reload the plugin configuration. | ||
|
|
||
| ## Updating | ||
|
|
||
| Restart OpenCode after updating the version pin in `opencode.json`, or pin a | ||
| specific version: | ||
| Update the package version in `opencode.json` to select a specific release: | ||
|
|
||
| ```json | ||
| { | ||
| "plugin": ["@ory/lumen-opencode@0.0.29"] | ||
| "plugins": ["@ory/lumen-opencode@<version>"] | ||
| } | ||
| ``` | ||
|
|
||
| ## Uninstalling | ||
|
|
||
| Remove the `@ory/lumen-opencode` entry from `opencode.json` and restart | ||
| OpenCode. | ||
| Remove the `@ory/lumen-opencode` entry from `opencode.json`. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,23 +1,24 @@ | ||
| import { Plugin } from "@opencode/plugin"; | ||
| import path from "path"; | ||
| import { fileURLToPath } from "url"; | ||
|
|
||
| const __dirname = path.dirname(fileURLToPath(import.meta.url)); | ||
| const pluginRoot = path.resolve(__dirname, "../.."); | ||
| const runCommand = path.join(pluginRoot, "scripts", "run"); | ||
| const launcher = process.platform === "win32" ? "run.cmd" : "run"; | ||
| const runCommand = path.join(pluginRoot, "scripts", launcher); | ||
|
|
||
| export const LumenPlugin = async () => { | ||
| return { | ||
| config: async (config) => { | ||
| config.mcp = config.mcp || {}; | ||
| if (!config.mcp.lumen) { | ||
| config.mcp.lumen = { | ||
| export default Plugin.define({ | ||
| id: "ory.lumen", | ||
| /** Preserve an existing Lumen MCP configuration while supplying a local default. */ | ||
| async setup(ctx) { | ||
| await ctx.mcp.transform((editor) => { | ||
| if (!editor.get("lumen")) { | ||
| editor.set("lumen", { | ||
| type: "local", | ||
| command: [runCommand, "stdio"], | ||
| enabled: true, | ||
| }; | ||
| disabled: false, | ||
| }); | ||
| } | ||
| }, | ||
| }; | ||
| }; | ||
|
|
||
| export default LumenPlugin; | ||
| }); | ||
| }, | ||
| }); | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| 2026-11-11T01:25:53-03:00 | ||
|
|
||
| # OpenCode V2 canary bypasses package resolution | ||
|
|
||
| ## Causal chain | ||
|
|
||
| The installation test packed and installed `@ory/lumen-opencode`, then passed | ||
| that directory to `scripts/test_opencode_v2_host.mjs`. The canary symlinked the | ||
| directory into its temporary OpenCode plugin folder. OpenCode therefore loaded | ||
| the local plugin directly; it did not read a project `plugins` entry, resolve | ||
| the package specifier, or prove that package installation selected the packed | ||
| artifact. The test only checked that the plugin became active and its MCP | ||
| server connected, so it could pass even if the documented package-install | ||
| path was broken. | ||
|
|
||
| ## Boundary and correction | ||
|
|
||
| This was a false-positive risk in the canary, not evidence that normal package | ||
| installation failed. The canary now configures `plugins: ["@ory/lumen-opencode"]` | ||
| in an isolated project, resolves it through a loopback registry serving the | ||
| packed tarball, checks OpenCode's reported package source and registry request, | ||
| and compares the loaded package files with the npm-installed artifact before | ||
| accepting MCP connectivity. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| 2026-11-11T01:50:32-03:00 | ||
|
|
||
| # OpenCode V2 canary readiness timeout | ||
|
|
||
| ## Causal chain | ||
|
|
||
| The canary gives `waitForPlugin` one 30-second deadline to observe both the | ||
| package-backed plugin and its MCP server becoming ready. With the documented | ||
| package specifier, OpenCode may spend part of that window resolving the package | ||
| before starting the local MCP process. OpenCode V2.2.7 separately allows 30 | ||
| seconds for the MCP startup handshake. If package resolution and the handshake | ||
| together exceed the canary's 30-second budget, `waitForPlugin` throws and the | ||
| canary's cleanup stops the host even though the MCP handshake may still be | ||
| within OpenCode's own deadline. This is a potential cold-start test failure, | ||
| not evidence of a plugin runtime failure. | ||
|
|
||
| ## Correction | ||
|
|
||
| The canary now allows 60 seconds for plugin and MCP readiness, enough for | ||
| package resolution followed by OpenCode's full 30-second handshake window. The | ||
| OpenCode handshake timeout and the separate host-start/API request timeouts | ||
| remain unchanged. |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.