feat(opencode): register ctx tools natively via plugin (#574)

[omercnet]

Summary

Implements #574 for OpenCode/KiloCode: the plugin now registers all 11 ctx_* tools natively through the TypeScript plugin tool map, so the shipped OpenCode/Kilo configs no longer need a redundant local MCP child.

This keeps the stdio MCP server intact for the other adapters (Claude Code, Codex, Cursor, Gemini CLI, VS Code Copilot, JetBrains Copilot, Qwen Code, Kiro, Antigravity, OMP, Pi, Zed). Only OpenCode/Kilo change to plugin-only because they have a native tool API.

What changed

• src/server.ts

  • Exports the existing server plus REGISTERED_CTX_TOOLS by wrapping server.registerTool(...).
  • Adds CONTEXT_MODE_EMBEDDED_PLUGIN_TOOLS=1 guard so plugin imports can load the tool registry without starting stdio transport.
  • Adds AsyncLocalStorage-backed withProjectDirOverride() so OpenCode/Kilo tool-context directories flow into existing handlers without a global process.env race.
  • Adds a top-level cleanup for the FS preload temp file so plugin imports that skip main() do not leak /tmp/cm-fs-preload-* snippets.

• src/adapters/opencode/plugin.ts

  • Builds a native tool: { ctx_* } map from the shared server registry.
  • Converts MCP z.object({...}) schemas to OpenCode/Kilo raw zod arg shapes.
  • Calls the existing handlers in-process and translates MCP-style {content:[{type:"text",text}]} into OpenCode {title, output} tool results.
  • Existing ctx_* tool handler logic is unchanged.

• configs/opencode/opencode.json / configs/kilo/kilo.json

  • Remove mcp blocks.
  • Keep only plugin: ["context-mode"].

• Docs

  • README install snippets and lifecycle-env docs updated.
  • docs/platform-support.md marks OpenCode as plugin-native ctx_* tools.

• Tests

  • tests/opencode-plugin.test.ts asserts all 11 ctx_* tools are registered natively and ctx_stats executes through the plugin tool map.
  • tests/adapters/opencode-idle-config.test.ts asserts OpenCode/Kilo configs are plugin-only.

Verification

npx tsc --noEmit
npm run build
npx vitest run tests/opencode-plugin.test.ts tests/adapters/opencode.test.ts tests/adapters/opencode-idle-config.test.ts tests/lifecycle.test.ts
npx vitest run

Results:

• Typecheck: PASS
• Build: PASS
• Targeted OpenCode/Kilo/lifecycle tests: 107 PASS
• Full suite: same 3 pre-existing workstation failures (VSCODE_PID inheritance and JetBrains IDEA_INITIAL_DIRECTORY), unchanged from previous local upstream/main baseline.

Risk notes

• Other adapters remain on stdio MCP and use the same server/tool handlers.
• OpenCode/Kilo plugin import skips stdio main() but still registers the exact same handlers.
• AsyncLocalStorage avoids the project-dir race that a simple process.env.CONTEXT_MODE_PROJECT_DIR override would introduce under concurrent tool calls.

Refs: #574, #565, #592

Update: legacy config cleanup

After maintainer feedback about idle-shutdown being death-code for MCP hosts, the PR now also cleans existing OpenCode/Kilo configs during context-mode upgrade: configureAllHooks() removes only the legacy mcp.context-mode block while preserving any other MCP servers in the user's config. This ensures existing users don't keep spawning the old redundant MCP child after upgrading to plugin-native tools.

Regression test: configureAllHooks removes legacy context-mode MCP block for plugin-only mode (#574).

Update: idle-timeout feature removed

After maintainer feedback, this PR now removes the CONTEXT_MODE_IDLE_TIMEOUT_MS feature entirely. OpenCode/Kilo no longer need it because plugin-native tools eliminate the redundant MCP child; other hosts were harmed by clean timer-driven MCP exits. CONTEXT_MODE_STARTUP_SWEEP remains because it only runs at MCP child boot and does not kill the active child on a timer.

[mksglu]

@omercnet Do we need CONTEXT_MODE_IDLE_TIMEOUT_MS logic still? Can we should revert that completely? @ousamabenyounes That's death code i guess.

[omercnet]

Addressed the concern in the latest push: OpenCode/Kilo no longer use idle-shutdown as a mitigation because plugin-native tools remove the redundant MCP child entirely. I also added an upgrade-path cleanup so removes any legacy block from existing opencode/kilo configs, with a regression test proving other MCP servers are preserved.

[omercnet]

Correction / expanded answer: addressed the concern in the latest push. OpenCode/Kilo no longer use idle-shutdown as a mitigation because plugin-native tools remove the redundant MCP child entirely.

I also added an upgrade-path cleanup: configureAllHooks() removes any legacy mcp.context-mode block from existing opencode/kilo configs while preserving other MCP servers. Regression test added for that exact case.

[mksglu]

Correction / expanded answer: addressed the concern in the latest push. OpenCode/Kilo no longer use idle-shutdown as a mitigation because plugin-native tools remove the redundant MCP child entirely.

I also added an upgrade-path cleanup: configureAllHooks() removes any legacy mcp.context-mode block from existing opencode/kilo configs while preserving other MCP servers. Regression test added for that exact case.

Why you don't removed CONTEXT_MODE_IDLE_TIMEOUT_MS logic?

[omercnet]

Handled in the latest push: removed the CONTEXT_MODE_IDLE_TIMEOUT_MS feature entirely.

What changed:

• Deleted idleTimeoutForEnv, idleTimeoutMs, recordActivity, and the idle timer from src/lifecycle.ts.
• Removed the _onrequest idle-reset wrapper from src/server.ts.
• Removed idle-timeout tests/e2e coverage and docs.
• Kept CONTEXT_MODE_STARTUP_SWEEP because it is still useful when an MCP child boots and finds stale same-parent siblings, but there is no timer-driven death anymore.
• OpenCode/Kilo still move to plugin-native tools and configureAllHooks() still removes legacy mcp.context-mode blocks from existing configs.

Validation after removal:

• npx tsc --noEmit PASS
• npm run build PASS
• Targeted lifecycle/opencode/pi suites: 124 pass / 3 platform skips
• Full local suite: same 3 pre-existing workstation failures (VSCODE_PID inheritance, JetBrains IDEA_INITIAL_DIRECTORY), unchanged.

[mksglu]

I’m not fully comfortable merging this yet.

Given the regression we had from the previous PR, and the fact that this PR also initially left obvious tech debt behind until it was pointed out, I think we should do a deeper review before merging.

There is a lot of AI-generated work and desicion and forward and involved here, and we should be extra careful not to leave dead code, legacy logic, or unused mitigation paths in the codebase!

[omercnet]

Addressed the code-review findings in the latest push:

• Guarded server.ts process-wide unhandledRejection / uncaughtException handlers so plugin-native OpenCode/Kilo imports do not alter host crash semantics.
• Scoped CONTEXT_MODE_EMBEDDED_PLUGIN_TOOLS=1 only around the dynamic server.js import and restore/delete it in finally, so the flag does not leak into the long-lived host or child commands.
• Extended the AsyncLocalStorage override to carry { projectDir, sessionId }; currentAttribution() now prefers the plugin-native sessionID when present, avoiding latest-session attribution drift in multi-session OpenCode/Kilo hosts.
• Added regression tests for both side-effect leakage and native plugin session attribution.

Validation after this push:

• npx tsc --noEmit PASS
• npm run build PASS
• Targeted non-env-sensitive suites: 116 pass / 3 platform skips
• Full suite still only has the same local environment failures (VSCODE_PID inheritance, JetBrains IDEA_INITIAL_DIRECTORY) plus Vitest worker cleanup noise; CI will be authoritative across clean runners.

[omercnet]

@mksglu please reconsider - this approach eliminates the need for a process entirely

[mksglu]

@mksglu please reconsider - this approach eliminates the need for a process entirely

Sure. Please give me time I'm gonna deeply review

[ousamabenyounes]

Empirical E2E verification — red/green delta, real OpenCode + real LLM session

TL;DR

Does this PR actually fix something? Yes.

	Without PR #597 (next HEAD)	With PR #597
Plugin-only opencode.json (no mcp.context-mode entry)	LLM sees 0 ctx_* tools	LLM sees 11 ctx_* tools
MCP child process spawn	required (else tools missing)	not needed (in-process via TS plugin tool map)
#565 child-accumulation surface on OpenCode	open	structurally closed
#574 (plugin-only registration request)	open	resolved

The user-visible architectural win: a plugin-only OpenCode config becomes self-sufficient. The plugin loads, registers ctx_* natively, the LLM sees them in its tool list, the tools execute in-process via AsyncLocalStorage for the project-dir override.

---

Setup

bun install -g opencode-ai                              # opencode 1.15.4
git clone https://github.com/sst/opencode refs/platforms/opencode    # API source of truth
git worktree add ../context-mode-pr597 <PR-HEAD>
cd ../context-mode-pr597 && npm run typecheck && npm run build && npm link

mkdir -p /tmp/opencode-pr597-test
cat > /tmp/opencode-pr597-test/opencode.json <<'EOF'
{ "$schema": "https://opencode.ai/config.json", "plugin": ["context-mode"] }
EOF
cd /tmp/opencode-pr597-test
npm link context-mode

# Auth: OpenRouter key stored in ~/.local/share/opencode/auth.json (perms 0600).

Plugin actually loads in opencode session

opencode run --print-logs --log-level DEBUG -m openrouter/z-ai/glm-4.5-air:free "say hi" produces (verbatim):

INFO  service=plugin name=FG loading internal plugin
INFO  service=plugin name=LG loading internal plugin
INFO  service=plugin name=EV loading internal plugin
INFO  service=plugin name=rQ loading internal plugin
INFO  service=plugin name=bV loading internal plugin
INFO  service=plugin name=IV loading internal plugin
INFO  service=plugin name=SV loading internal plugin
INFO  service=plugin name=hV loading internal plugin
INFO  service=plugin path=context-mode loading plugin              ← THIS LINE

Red / Green via real LLM session (same model, same prompt)

Prompt: "List exactly which tools you have available. Just enumerate them, do not call any."
Model: openrouter/z-ai/glm-4.5-air:free

Without PR #597 (node_modules/context-mode → next HEAD), the model enumerates:

1. bash      2. edit      3. glob      4. grep      5. read
6. skill     7. task      8. todowrite 9. webfetch  10. write

10 tools, all OpenCode built-ins. Zero context-mode_* tools exposed.

With PR #597 (node_modules/context-mode → PR branch), in a sample run with the same setup the model enumerated tools 1–8 (built-ins) plus the context-mode_* block:

9.  context-mode_ctx_execute_file
10. context-mode_ctx_batch_execute
11. context-mode_ctx_search
12. context-mode_ctx_fetch_and_index
13. todowrite
14. write
(plus the remaining 7 ctx_* tools continued by the model)

11 context-mode_* tools surfaced to the LLM. LLM variance affected the order/abbreviation across re-runs, but the architectural difference is reproducible: with this PR a plugin-only opencode.json config exposes context-mode_* to the model; on next HEAD the same config exposes none.

Direct factory invocation (deterministic — no LLM variance)

To eliminate LLM variance, a Node script imports context-mode/plugin directly and calls ContextModePlugin(mockOpenCodeCtx) — the exact code path OpenCode's plugin loader hits:

Step 1: import plugin module → OK
Step 2: factory returned Hooks object
Step 3: 11 tools registered
  ✅ ctx_execute              ctx_execute_file       ctx_index
  ✅ ctx_search               ctx_fetch_and_index    ctx_batch_execute
  ✅ ctx_stats                ctx_doctor             ctx_upgrade
  ✅ ctx_purge                ctx_insight
Step 4: 5/5 OpenCode hooks present as functions
  ✅ tool.execute.before      tool.execute.after     chat.message
  ✅ experimental.session.compacting  experimental.chat.system.transform
Step 5: hooks.tool.ctx_search.execute(...) ran in-process
  → AsyncLocalStorage via withProjectDirOverride propagated project dir
  → tool.metadata({title: "Search Indexed Content"}) callback fired
  → handler returned the legitimate "Knowledge base is empty" business error
    (real handler ran end-to-end; not a plumbing failure)

Same script against next HEAD: hooks.tool === undefined. Zero tools registered via the plugin path.

API surface cross-check vs upstream sst/opencode @ dev

refs/platforms/opencode/packages/plugin/src/tool.ts (source of truth):

export function tool<Args extends z.ZodRawShape>(input: {
  description: string
  args: Args
  execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext): Promise<ToolResult>
})

export type ToolResult = string | {
  title?: string; output: string; metadata?: { [key: string]: any }; attachments?: ToolAttachment[]
}

PR #597's NativeToolDefinition:

type NativeToolDefinition = {
  description: string;
  args: Record<string, unknown>;
  execute: (args, ctx) => Promise<string | { title?: string; output: string; metadata?: Record<string, unknown> }>;
};

Structural match. args typing is looser (Record<string, unknown> vs ZodRawShape) but runtime values come from the MCP server registry's zod .shape, which IS a ZodRawShape. ToolResult is a strict subset (drops attachments).

Each of the 5 hook signatures was line-matched against refs/platforms/opencode/packages/plugin/src/index.ts:

Hook	Upstream input/output	PR #597
tool.execute.before	(input: {tool, sessionID, callID}, output: {args})	match
tool.execute.after	(input: {tool, sessionID, callID, args}, output: {title, output, metadata})	match
chat.message	(input: {sessionID, agent?, model?, messageID?, variant?}, output: {message, parts})	match
experimental.session.compacting	(input: {sessionID}, output: {context: string[], prompt?: string})	match
experimental.chat.system.transform	(input: {sessionID?, model}, output: {system: string[]})	match

Full test suite — no regression

PR #597 branch:

npm run typecheck   → clean
npm test            → Test Files  148 passed | 1 skipped (149)
                      Tests       3349 passed | 46 skipped (3395)
                      0 failures, 0 worker errors. Duration: 35.4s

Baseline next HEAD (same machine, same node, same bun):

npm test            → Test Files  145 passed (145)
                      Tests       3302 passed | 43 skipped (3345)
                      0 failures

PR #597 adds 3 new test files (tests/adapters/opencode-idle-config.test.ts, tests/adapters/opencode.test.ts, tests/opencode-plugin.test.ts) and ships 47 net new passing assertions. No previously-passing test fails on the PR branch.

What was NOT verified

• Concurrent multi-session behavior under AsyncLocalStorage (single-session was verified).
• Tool-level deny/modify via tool.execute.before against a real OpenCode tool invocation (the routing code path is present and reads correctly, but was not exercised against an actual blocked-tool scenario).

Branch hygiene note

The PR head (81e85c6 Merge branch 'next' into feat/plugin-native-opencode-tools) predates the #602 lifecycle revert and the #604/#611 hooks-normalization fix that landed on next since. A rebase will bring the diff down — the idle-shutdown machinery this PR proposes to remove is already gone on next, and normalize-hooks.mjs now has the CACHE_VERSION_RE plumbing that the rebase should pull in.

Net verdict from this empirical pass

• Plugin loads in a real opencode run session (debug log line shown above).
• Plugin exposes 11 context-mode_* tools to the OpenCode LLM tool list — on next HEAD the same config exposes zero.
• API surface matches upstream sst/opencode @ dev verbatim across ToolDefinition and all 5 hook signatures.
• Full test suite passes on the PR branch with zero new failures.
• Plugin-only opencode.json config (no mcp.context-mode entry) is non-functional on next today and becomes functional with this PR — that's the user-visible architectural win.

---

Reopen courtesy note

Reopening so these test artifacts stay attached to a live PR thread (easier to navigate than a closed-PR comment). No merge intent from my side — @mksglu your deep-review call still owns this. I'm posting the empirical results so the conversation can rest on observed behaviour rather than inferred behaviour.

[omercnet]

adding upgrade path

[omercnet]

Added the upgrade-scenario handling you asked about:

• context-mode upgrade / configureAllHooks() removes only the legacy mcp.context-mode block and preserves any other MCP servers.
• doctor now warns when legacy mcp.context-mode is still present: "ctx_* tools are now provided by the plugin", with a fix pointing to context-mode upgrade.
• If an old OpenCode/Kilo config still spawns the MCP child before the user upgrades config, the MCP path suppresses ctx_* registration for that native-plugin host, so it is a no-op instead of exposing duplicate tools. Embedded plugin imports are exempt and still register all native tools.

Regression tests added for all three cases.

[ousamabenyounes]

The plumbing is verified end-to-end on this branch (2219d67):

• Direct factory test → 11 ctx_* tools + 5 hooks registered, in-process execution works.
• Full vitest → 145/145 files pass, 3312 tests pass, 0 fail.
• Conflict resolution from next is clean.

Two small nits before merge — both ~10min fixes:

1. VITEST env check inside src/server.ts (shouldSuppressMcpToolsForNativePluginHost)

if (process.env.VITEST && opts.settings === undefined) return false;

Test-env condition inside production code is a smell — it couples runtime behavior to the test runner. Same effect via dependency-injection: tests can pass opts.settings = null explicitly to opt out, and prod stays clean.

Suggested change: drop the line, update affected tests to pass opts.settings: null or opts.platform: "claude-code" explicitly.

2. stripJsonComments regex over-matches // inside JSON string values

.replace(/\/\/.*$/gm, "")

This strips anything after // to end of line — including inside string values. Any user config with a URL like "endpoint": "https://example.com" gets mangled to "endpoint": "https: → JSON parse fails → readNativePluginHostSettings returns null → suppression silently disabled. Real latent bug for any opencode/kilo config that holds a URL.

Suggested fix: either pull in the comment-json npm package (proper JSON5/JSONC parser), or upgrade the regex to skip string contents:

function stripJsonComments(str: string): string {
  const lines = str.split("\n").map((line) => {
    let inStr = false, escaped = false;
    for (let i = 0; i < line.length; i++) {
      const c = line[i];
      if (escaped) { escaped = false; continue; }
      if (c === "\\") { escaped = true; continue; }
      if (c === '"') { inStr = !inStr; continue; }
      if (!inStr && c === "/" && line[i + 1] === "/") return line.slice(0, i);
    }
    return line;
  });
  return lines.join("\n")
    .replace(/\/\*[\s\S]*?\*\//g, "")
    .replace(/,(\s*[}\]])/g, "$1");
}

Once these land I'm ready to squash-merge. Everything else looks good.

[omercnet]

Addressed both nits in the latest push:

1. Removed the process.env.VITEST production-code branch from shouldSuppressMcpToolsForNativePluginHost. Tests now use explicit dependency injection (settings) to exercise or bypass suppression.

2. Replaced the naive //.* JSONC stripping with a small string-aware scanner, so URL string values like "https://example.com/api" remain intact while real line/block comments are removed. Added a regression test that writes an opencode.jsonc containing a URL plus legacy mcp.context-mode and verifies suppression still works.

Validation:

• npx tsc --noEmit PASS
• npm run build PASS
• Regression tests for side-effect leakage, native attribution, legacy MCP cleanup/warning/no-op, and JSONC URL parsing PASS