Add plugin config API key support

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Plugin config API key** — `apiKey` can now be set in the OpenCode plugin config entry, with `MORPH_API_KEY` preserved as the fallback.
+
 ## [2.0.3] - 2026-03-16
 
 ### Fixed

README.md

@@ -19,7 +19,9 @@ On production repos and SWE-Bench Pro, enabling WarpGrep and compaction improves
 
 ### 1. Get a Morph API key
 
-Sign up at [morphllm.com/dashboard](https://morphllm.com/dashboard/api-keys) and export it:
+Sign up at [morphllm.com/dashboard](https://morphllm.com/dashboard/api-keys).
+
+For terminal usage, export it:
 
 ```bash
 export MORPH_API_KEY="sk-..."
@@ -48,6 +50,30 @@ Edit `~/.config/opencode/opencode.json`:
 }
 ```
 
+For OpenCode desktop or other environments where shell environment variables
+are inconvenient, configure the API key as a plugin option in your global
+OpenCode config:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": [
+    [
+      "@morphllm/opencode-morph-plugin",
+      {
+        "apiKey": "{file:~/.secrets/morph-api-key}"
+      }
+    ]
+  ],
+  "instructions": [
+    "node_modules/@morphllm/opencode-morph-plugin/instructions/morph-tools.md"
+  ]
+}
+```
+
+You can also set `"apiKey": "sk-..."` directly, but prefer global config or
+`{file:...}` for secrets. Do not commit API keys in project config.
+
 ### 4. Start OpenCode
 
 ```bash
@@ -131,11 +157,14 @@ Search public GitHub repositories without cloning. Pass an `owner/repo` or GitHu
 
 ## Configuration
 
-All configuration is via environment variables.
+Credentials can be configured with the plugin `apiKey` option or the
+`MORPH_API_KEY` environment variable. The plugin option is checked first; if it
+is missing or blank, `MORPH_API_KEY` is used.
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `MORPH_API_KEY` | *required* | Your Morph API key |
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Plugin option `"apiKey"` | falls back to `MORPH_API_KEY` | Your Morph API key in the OpenCode `plugin` config entry |
+| `MORPH_API_KEY` | *required unless `apiKey` is set* | Your Morph API key |
 | `MORPH_COMPACT_TOKEN_LIMIT` | auto (70% of model window) | Fixed token threshold for compaction |
 | `MORPH_COMPACT_CONTEXT_THRESHOLD` | `0.7` | Fraction of model context window to trigger compaction (used when `TOKEN_LIMIT` is not set) |
 | `MORPH_COMPACT_PRESERVE_RECENT` | `1` | Number of recent messages to keep uncompacted |

index.test.ts

@@ -29,7 +29,10 @@ function normalizeCodeEditInput(codeEdit: string): string {
 async function importPluginWithEnv(
   env: Record<string, string | undefined>,
 ): Promise<{
-  default: (input: any) => Promise<Record<string, any>>;
+  default: (
+    input: any,
+    options?: Record<string, unknown>,
+  ) => Promise<Record<string, any>>;
 }> {
   const previous = new Map<string, string | undefined>();
 
@@ -50,11 +53,17 @@ async function importPluginWithEnv(
   }
 }
 
-function makePluginInput(directory: string, worktree = directory) {
+function makePluginInput(
+  directory: string,
+  worktree = directory,
+  logs: any[] = [],
+) {
   return {
     client: {
       app: {
-        log: async () => {},
+        log: async (entry: any) => {
+          logs.push(entry.body);
+        },
       },
     },
     project: {},
@@ -113,6 +122,7 @@ describe("packaged tool-selection instructions", () => {
     expect(content).toContain("warpgrep_codebase_search");
     expect(content).toContain("warpgrep_github_search");
     expect(content).toContain("MORPH_API_KEY");
+    expect(content).toContain('"apiKey"');
     expect(content).toContain("MORPH_COMPACT_TOKEN_LIMIT");
     expect(content).toContain("opencode.json");
   });
@@ -933,7 +943,7 @@ describe("plugin runtime hooks", () => {
 
     expect(output.description).toContain("Runtime notes:");
     expect(output.description).toContain(
-      "Currently unavailable until MORPH_API_KEY is configured.",
+      "Currently unavailable until a Morph API key is configured.",
     );
     expect(output.description).toContain(
       "Blocked in readonly agents: plan, explore.",
@@ -963,6 +973,60 @@ describe("plugin runtime hooks", () => {
     );
     expect(combined).toContain("Use write for brand new files.");
   });
+
+  test("apiKey plugin option enables morph tools without MORPH_API_KEY", async () => {
+    const { default: MorphPlugin } = await importPluginWithEnv({
+      MORPH_API_KEY: undefined,
+    });
+    const logs: any[] = [];
+
+    const hooks = await MorphPlugin(
+      makePluginInput("/tmp/morph-plugin", "/tmp/morph-plugin", logs),
+      { apiKey: "\n  morph-config-test-key  \n" },
+    );
+    const output = {
+      description: "Base description",
+      parameters: {},
+    };
+
+    await hooks["tool.definition"]?.({ toolID: "morph_edit" }, output);
+
+    expect(output.description).toContain("Runtime notes:");
+    expect(output.description).not.toContain("Currently unavailable");
+
+    const system = { system: [] as string[] };
+    await hooks["experimental.chat.system.transform"]?.(
+      {
+        sessionID: "session-test",
+        model: {},
+      },
+      system,
+    );
+
+    expect(system.system.join("\n")).toContain("Morph plugin routing hints:");
+    expect(JSON.stringify(logs)).not.toContain("morph-config-test-key");
+  });
+
+  test("blank apiKey plugin option falls back to MORPH_API_KEY", async () => {
+    const { default: MorphPlugin } = await importPluginWithEnv({
+      MORPH_API_KEY: "morph-env-test-key",
+    });
+
+    const hooks = await MorphPlugin(makePluginInput("/tmp/morph-plugin"), {
+      apiKey: "   ",
+    });
+    const output = { system: [] as string[] };
+
+    await hooks["experimental.chat.system.transform"]?.(
+      {
+        sessionID: "session-test",
+        model: {},
+      },
+      output,
+    );
+
+    expect(output.system.join("\n")).toContain("Morph plugin routing hints:");
+  });
 });
 
 describe("ToolContext path resolution", () => {