fix: point v2 install at @next, list model params in refresh tool, fix fallback param

- README (#126): the opencode v2 install snippet used @latest, which is
  0.9.0 (v1-only build, no { id, setup } default export) and reproduces
  "Plugin must export a default definition" on opencode 2.x. Point it at
  @next until 0.10.0 is promoted, with a note.
- cursor_refresh_models (#119): append each model's param ids and accepted
  values, e.g. `grok-4.6 [effort=low|medium|high|xhigh, fast=false|true]`,
  so users can tell effort from reasoning_effort. Add a test.
- fallback catalog: composer-2.5 exposes `fast`, not `thinking`; the stale
  entry produced a bogus `thinking` variant on the keyless path.
- CHANGELOG: limit the connect-node note to verified facts (nothing in the
  repo imports it; @cursor/sdk nests its own 1.7.0) and record the above.

Author: justin-carper

CHANGELOG.md

@@ -12,10 +12,31 @@ All notable changes to this project will be documented in this file.
   tool-arg descriptions, were corrected to say so (wording only — no behavior
   change).
 
+- **Fix: README v2 install snippet points at `@next` (#126).** The
+  `plugins` example used `@latest`, which resolves to 0.9.0 — a v1-only
+  build that opencode v2 rejects with "Plugin must export a default
+  definition with an id and an effect or setup function". v2 support is
+  published under the `next` dist-tag (0.10.0-next.1+) until promoted;
+  the snippet and a note now say so.
+
+- **Fix: fallback catalog's composer-2.5 param matches the live one.**
+  The keyless/fallback entry advertised a `thinking` param (off/on) that
+  the live catalog does not expose, yielding a bogus `thinking` variant;
+  it now declares only `fast` (false/true), so the fallback path yields
+  exactly the `fast` variant and `{ fast: "false" }` defaults.
+
+- **Add: `cursor_refresh_models` lists param ids and values (#119).**
+  Each model line now appends the model's advertised params as
+  `[effort=low|medium|high|xhigh, fast=false|true]` (no suffix when the
+  model has none), so accepted param ids and values are readable
+  straight from the tool output.
+
 - **Chore: dependency bumps (#122, #124, #125) and audit overrides.**
   Consolidates the three open Dependabot PRs: `@connectrpc/connect-node`
-  2.1.2 → 2.2.0 (required at runtime by `@cursor/sdk`, not imported
-  by the plugin itself; the 2.2.0 additions are server-side),
+  2.1.2 → 2.2.0 (nothing in src/, scripts/, or test/ imports it, and
+  `@cursor/sdk` declares `^1.6.1` and nests its own 1.7.0 copy, so the
+  top-level entry — added in #31 when the SDK did not declare it — no
+  longer looks needed; left in place as a removal candidate),
   `@cursor/sdk` 1.0.31 → 1.0.32, `@opencode-ai/plugin` and
   `@opencode-ai/sdk` 1.18.25/1.18.30 → 1.18.33 (kept on one version, one
   sdk copy in the tree), `@ai-sdk/provider` 3.0.15 → 3.0.18,

README.md

@@ -81,11 +81,18 @@ opencode v2 uses a `plugins` key (plural) and loads the plugin's `setup()` entry
 ```json
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugins": ["@stablekernel/opencode-cursor@latest"]
+  "plugins": ["@stablekernel/opencode-cursor@next"]
 }
 ```
 
-Both generations load the same published package, so one install serves either.
+> v2 support is published under the `next` dist-tag (`0.10.0-next.1` or later)
+> until it is promoted to `latest`. `@latest` currently resolves to 0.9.0, a
+> v1-only build that opencode v2 rejects with "Plugin must export a default
+> definition with an id and an effect or setup function". Switch the spec back
+> to `@latest` once 0.10.0 is stable.
+
+From 0.10.0 onward both generations load the same published package, so one
+install serves either (0.9.x `@latest` is v1-only).
 Minimum versions: v1 >= 1.18.29 (object plugin entrypoint), v2 tested against 2.0.19.
 
 **Registry mirrors:** on v2 the provider package is installed at exactly the plugin's
@@ -309,8 +316,8 @@ needed.
 Param ids are **per model** — use the id the model actually advertises, or Cursor ignores the
 param and falls back to its own default (e.g. `high` effort). `grok-4.6` uses `effort`,
 `gpt-5.5` uses `reasoning`, `claude-opus-4-8` uses `effort` (plus a boolean `thinking`), and
-`composer-2.5` has only `fast`. Run `cursor_refresh_models` to list model ids, and check the
-model picker's variant names for the values a model accepts.
+`composer-2.5` has only `fast`. Run `cursor_refresh_models` to list each model id
+with its param ids and accepted values.
 
 To set controls statically per model:
 

src/fallback-models.ts

@@ -13,7 +13,7 @@ export const FALLBACK_MODELS: ModelListItem[] = [
     displayName: "Composer 2.5",
     description: "Cursor's default agent model (fallback entry).",
     parameters: [
-      { id: "thinking", displayName: "Thinking", values: [{ value: "off" }, { value: "on" }] },
+      { id: "fast", displayName: "Fast", values: [{ value: "false" }, { value: "true" }] },
     ],
   },
   { id: "claude-opus-4-8", displayName: "Claude Opus 4.8 (via Cursor)" },

src/plugin/cursor-tools.ts

@@ -1,4 +1,5 @@
 import { tool, type ToolContext, type ToolDefinition } from "@opencode-ai/plugin";
+import type { ModelListItem } from "@cursor/sdk";
 import { rmSync } from "node:fs";
 import semver from "semver";
 import { runCloudAgent } from "../provider/cloud-agent.js";
@@ -262,6 +263,21 @@ export function buildCursorTools(deps: CursorToolDeps): Record<string, ToolDefin
 export const REFRESH_DESCRIPTION_BASE =
   "Refresh the live Cursor model catalog now (bypasses the cache) and report the available models. The catalog also auto-refreshes on every opencode startup; use this to pick up new models mid-session.";
 
+/**
+ * One `cursor_refresh_models` output line, with the model's advertised
+ * params appended when it has any:
+ * `- grok-4.6 — Grok 4.6 [effort=low|medium|high|xhigh, fast=false|true]`.
+ * Models without parameters keep the plain `- id — name` line.
+ */
+function modelLine(m: Pick<ModelListItem, "id" | "displayName" | "parameters">): string {
+  const params = m.parameters ?? [];
+  if (params.length === 0) return `- ${m.id} — ${m.displayName}`;
+  const joined = params
+    .map((p) => `${p.id}=${(p.values ?? []).map((v) => v.value).join("|")}`)
+    .join(", ");
+  return `- ${m.id} — ${m.displayName} [${joined}]`;
+}
+
 /**
  * Build the maintenance tools shared by v1 and v2:
  *  - `cursor_refresh_models`: force-refresh the model catalog.
@@ -282,7 +298,7 @@ export function buildMaintenanceTools(
       execute: async () => {
         const apiKey = deps ? await deps.resolveApiKey() : undefined;
         const result = await discoverModels({ apiKey, forceRefresh: true });
-        const lines = result.models.map((m) => `- ${m.id} — ${m.displayName}`);
+        const lines = result.models.map(modelLine);
         const header =
           result.source === "live"
             ? `Refreshed ${result.models.length} Cursor models (live):`

test/cursor-tools.test.ts

@@ -3,12 +3,14 @@ import { afterEach, describe, expect, it, vi } from "vitest";
 const runCloudAgent = vi.fn();
 const runDelegate = vi.fn();
 const linkDelegateSession = vi.fn();
+const discoverModels = vi.fn();
 
 vi.mock("../src/provider/cloud-agent.js", () => ({ runCloudAgent }));
 vi.mock("../src/provider/delegate.js", () => ({ runDelegate }));
 vi.mock("../src/provider/subagent-bridge.js", () => ({ linkDelegateSession }));
+vi.mock("../src/model-discovery.js", () => ({ discoverModels }));
 
-const { buildCursorTools } = await import("../src/plugin/cursor-tools.js");
+const { buildCursorTools, buildMaintenanceTools } = await import("../src/plugin/cursor-tools.js");
 
 function ctx(ask: ReturnType<typeof vi.fn>) {
   return {
@@ -30,6 +32,7 @@ afterEach(() => {
   runCloudAgent.mockReset();
   runDelegate.mockReset();
   linkDelegateSession.mockReset();
+  discoverModels.mockReset();
 });
 
 describe("buildCursorTools", () => {
@@ -312,3 +315,38 @@ describe("buildCursorTools", () => {
     expect(String(out)).toContain("agent crashed");
   });
 });
+
+describe("buildMaintenanceTools — cursor_refresh_models output", () => {
+  const exec = async () => {
+    const tools = buildMaintenanceTools();
+    const out = (await tools.cursor_refresh_models!.execute({}, undefined as never)) as {
+      output: string;
+    };
+    return out.output;
+  };
+
+  it("appends [id=values] to a model with params; plain line without", async () => {
+    discoverModels.mockResolvedValue({
+      source: "live",
+      models: [
+        {
+          id: "grok-4.6",
+          displayName: "Grok 4.6",
+          parameters: [
+            {
+              id: "effort",
+              values: [{ value: "low" }, { value: "medium" }, { value: "high" }, { value: "xhigh" }],
+            },
+            { id: "fast", values: [{ value: "false" }, { value: "true" }] },
+          ],
+        },
+        { id: "plain-model", displayName: "Plain Model" },
+      ],
+    });
+    const output = await exec();
+    expect(output).toContain(
+      "- grok-4.6 — Grok 4.6 [effort=low|medium|high|xhigh, fast=false|true]",
+    );
+    expect(output.endsWith("- plain-model — Plain Model")).toBe(true);
+  });
+});