Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ jobs:
LUMEN_EMBED_DIMS: '384'

- name: Install pinned agent CLIs
run: npm install --global @anthropic-ai/claude-code@2.1.226 opencode-ai@1.18.15
run: npm install --global @anthropic-ai/claude-code@2.1.226 @opencode/cli@2.2.7

- name: Install pinned Codex CLI
run: |
Expand Down Expand Up @@ -244,6 +244,22 @@ jobs:
with:
node-version: '22'

- name: Verify packed OpenCode plugin selects the Windows launcher
if: runner.os == 'Windows'
shell: pwsh
run: |
$packDir = Join-Path $env:RUNNER_TEMP "lumen-opencode-pack"
$installDir = Join-Path $env:RUNNER_TEMP "lumen-opencode-install"
New-Item -ItemType Directory -Force -Path $packDir, $installDir | Out-Null
$packed = npm pack --json --pack-destination $packDir | ConvertFrom-Json
if ($LASTEXITCODE -ne 0) { throw "npm pack failed" }
$tarball = Join-Path $packDir $packed[0].filename
npm install --no-audit --no-fund --prefix $installDir $tarball
if ($LASTEXITCODE -ne 0) { throw "npm install failed" }
$packageRoot = Join-Path $installDir "node_modules/@ory/lumen-opencode"
node scripts/verify_opencode_package.mjs $packageRoot
if ($LASTEXITCODE -ne 0) { throw "OpenCode package verification failed" }

- name: Install cross-spawn for parallel transport test
working-directory: scripts
run: npm install --no-audit --no-fund
Expand Down
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,9 @@ bench-swe/overview.txt
**/.claire
.worktrees

# npm dependencies
node_modules/

# scripts/ test-only npm install (cross-spawn for spawn-semantics test)
scripts/node_modules/
scripts/package-lock.json
32 changes: 15 additions & 17 deletions .opencode/INSTALL.md
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`.
29 changes: 15 additions & 14 deletions .opencode/plugins/lumen.js
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", {
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
type: "local",
command: [runCommand, "stdio"],
enabled: true,
};
disabled: false,
});
}
},
};
};

export default LumenPlugin;
});
},
});
18 changes: 9 additions & 9 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -131,30 +131,30 @@ codex mcp get lumen --json

**OpenCode**

Add `@ory/lumen-opencode` to the `plugin` array in your `opencode.json`:
<!-- Updated 2026-11-10T17:42:18-03:00: align installation and verification with OpenCode V2. -->

OpenCode V2 2.2.7 or newer is required. Add `@ory/lumen-opencode` to the
`plugins` array in your `opencode.json`:

```json
{
"plugin": ["@ory/lumen-opencode"]
"plugins": ["@ory/lumen-opencode"]
}
```

Detailed docs: [.opencode/INSTALL.md](.opencode/INSTALL.md)

Verify with:

```bash
opencode mcp list
```
Verify by asking an active OpenCode TUI to call the Lumen MCP tools. If they do
not appear, use `/reload` to reload the plugin configuration.

**Updating**

- **Claude Code** - update through Claude's plugin marketplace
- **Cursor** - refresh or reinstall the bundled plugin through Cursor after
updating this repository or the published package
- **Codex** - upgrade the `ory` marketplace, reinstall `lumen@ory`, and restart
- **OpenCode** - update the version pin in `opencode.json` (e.g.
`@ory/lumen-opencode@0.0.29`) and restart OpenCode
- **OpenCode** - update the package version in `opencode.json` and use `/reload`
if the new version does not appear

On first Claude Code or Cursor session start, Lumen:

Expand Down
23 changes: 23 additions & 0 deletions bugs/opencode-v2-canary-bypasses-package-resolution.md
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.
22 changes: 22 additions & 0 deletions bugs/opencode-v2-canary-readiness-timeout.md
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.
Loading
Loading