@sw-market/openclaw-opencode-bridge 0.1.1 → 0.1.3

package/README.md

@@ -21,9 +21,24 @@ After install, verify plugin exists:
 openclaw plugins list
 ```
 
-## Required OpenClaw Config
+## Zero-Config Bootstrap (v0.1.3+)
 
-In `~/.openclaw/openclaw.json`, add plugin entry and SDK adapter config:
+After install, if `sdkAdapterModule` is not configured:
+
+1. Plugin will auto-discover these common adapter files:
+   - `<gateway cwd>/opencode_sdk_adapter.mjs`
+   - `<gateway cwd>/opencode_sdk_adapter.js`
+   - `~/.openclaw/opencode_sdk_adapter.mjs`
+   - `~/.openclaw/opencode_sdk_adapter.js`
+2. If none found, plugin falls back to bundled guided adapter.
+3. Bundled guided adapter will auto-generate template file:
+   - `~/.openclaw/opencode_sdk_adapter.mjs`
+
+This means plugin install can be simplified: install first, then edit generated template on target machine.
+
+## OpenClaw Config
+
+Optional explicit config in `~/.openclaw/openclaw.json`:
 
 ```json
 {
@@ -35,7 +50,8 @@ In `~/.openclaw/openclaw.json`, add plugin entry and SDK adapter config:
           "sdkAdapterModule": "/abs/path/to/opencode_sdk_adapter.mjs",
           "sdkAdapterExport": "createOpenCodeSdkAdapter",
           "sessionTtlMs": 1800000,
-          "cleanupIntervalMs": 60000
+          "cleanupIntervalMs": 60000,
+          "emitToAllClients": false
         }
       }
     }
@@ -43,10 +59,22 @@ In `~/.openclaw/openclaw.json`, add plugin entry and SDK adapter config:
 }
 ```
 
+You can also set adapter location by environment variable:
+
+```bash
+export OPENCODE_SDK_ADAPTER_MODULE=/abs/path/to/opencode_sdk_adapter.mjs
+export OPENCODE_SDK_ADAPTER_EXPORT=createOpenCodeSdkAdapter
+```
+
 Adapter module contract:
 - export function `createOpenCodeSdkAdapter(ctx)` or export object directly.
 - returned object must implement `createSession(args)`.
 
+Note:
+- Plugin installation does not require `sdkAdapterModule` in config.
+- If not configured, plugin can auto-discover local adapter file names.
+- If still missing, plugin now falls back to guided adapter and generates template at `~/.openclaw/opencode_sdk_adapter.mjs`.
+
 ## Gateway Methods Provided
 
 This plugin registers:

package/dist/openclaw-extension.js

@@ -1,10 +1,12 @@
 import { existsSync } from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { OpenClawOpenCodeBridge, } from "./index.js";
 const CHAT_SEND_METHOD = "opencode.chat.send";
 const CHAT_ACTION_METHOD = "opencode.chat.action";
 const DEFAULT_ADAPTER_EXPORT = "createOpenCodeSdkAdapter";
+const DEFAULT_TEMPLATE_FILE = "opencode_sdk_adapter.mjs";
 let bridgePromise = null;
 let bridgeInstance = null;
 function asObject(value) {
@@ -49,8 +51,11 @@ function toErrorMessage(error) {
 }
 function parseConfig(pluginConfig) {
     const raw = pluginConfig ?? {};
-    const sdkAdapterModule = readString(raw, "sdkAdapterModule");
-    const sdkAdapterExport = readString(raw, "sdkAdapterExport") || DEFAULT_ADAPTER_EXPORT;
+    const sdkAdapterModuleRaw = readString(raw, "sdkAdapterModule") || String(process.env.OPENCODE_SDK_ADAPTER_MODULE || "").trim();
+    const sdkAdapterModule = sdkAdapterModuleRaw || undefined;
+    const sdkAdapterExport = readString(raw, "sdkAdapterExport") ||
+        String(process.env.OPENCODE_SDK_ADAPTER_EXPORT || "").trim() ||
+        DEFAULT_ADAPTER_EXPORT;
     const sessionTtlMs = readOptionalPositiveInt(raw, "sessionTtlMs");
     const cleanupIntervalMs = readOptionalPositiveInt(raw, "cleanupIntervalMs");
     const emitToAllClients = raw.emitToAllClients === true;
@@ -62,10 +67,34 @@ function parseConfig(pluginConfig) {
         emitToAllClients,
     };
 }
+function discoverAdapterPath(api) {
+    const candidates = [
+        path.resolve(process.cwd(), DEFAULT_TEMPLATE_FILE),
+        path.resolve(process.cwd(), "opencode_sdk_adapter.js"),
+        path.resolve(os.homedir(), ".openclaw", DEFAULT_TEMPLATE_FILE),
+        path.resolve(os.homedir(), ".openclaw", "opencode_sdk_adapter.js"),
+        api.resolvePath(`./${DEFAULT_TEMPLATE_FILE}`),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function bundledAdapterSpecifier() {
+    return new URL("./sdk-adapter-default.js", import.meta.url).href;
+}
 function resolveModuleSpecifier(api, moduleSpecifier) {
     const raw = moduleSpecifier.trim();
     if (!raw) {
-        throw new Error("Missing plugin config `sdkAdapterModule`.");
+        const discovered = discoverAdapterPath(api);
+        if (discovered) {
+            api.logger.info(`[${api.id}] discovered sdkAdapterModule: ${discovered}`);
+            return pathToFileURL(discovered).href;
+        }
+        api.logger.warn(`[${api.id}] sdkAdapterModule is not configured; falling back to bundled guided adapter.`);
+        return bundledAdapterSpecifier();
     }
     const looksLikePath = raw.startsWith("./") ||
         raw.startsWith("../") ||
@@ -89,7 +118,7 @@ function isOpenCodeSdkAdapter(value) {
     return typeof obj.createSession === "function";
 }
 async function loadSdkAdapter(api, config) {
-    const moduleSpecifier = resolveModuleSpecifier(api, config.sdkAdapterModule);
+    const moduleSpecifier = resolveModuleSpecifier(api, config.sdkAdapterModule ?? "");
     const loaded = await import(moduleSpecifier);
     const exported = loaded[config.sdkAdapterExport];
     let candidate = exported;
@@ -100,7 +129,7 @@ async function loadSdkAdapter(api, config) {
         }));
     }
     if (!isOpenCodeSdkAdapter(candidate)) {
-        throw new Error(`Invalid OpenCode SDK adapter from "${config.sdkAdapterModule}" export "${config.sdkAdapterExport}". ` +
+        throw new Error(`Invalid OpenCode SDK adapter from "${config.sdkAdapterModule || moduleSpecifier}" export "${config.sdkAdapterExport}". ` +
             "Expected an object with createSession(args) function.");
     }
     return candidate;

package/dist/sdk-adapter-default.d.ts

@@ -0,0 +1,13 @@
+import type { OpenCodeSdkAdapter } from "./index.js";
+type Logger = {
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+    error?: (message: string) => void;
+};
+type CreateAdapterContext = {
+    api?: {
+        logger?: Logger;
+    };
+};
+export declare function createOpenCodeSdkAdapter(ctx?: CreateAdapterContext): OpenCodeSdkAdapter;
+export default createOpenCodeSdkAdapter;

package/dist/sdk-adapter-default.js

@@ -0,0 +1,133 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const DEFAULT_TEMPLATE_PATH = path.join(os.homedir(), ".openclaw", "opencode_sdk_adapter.mjs");
+const ADAPTER_TEMPLATE = `// Auto-generated by @sw-market/openclaw-opencode-bridge.
+// Fill this file with your real OpenCode SDK wiring.
+// Then set in OpenClaw:
+//   plugins.entries["openclaw-opencode-bridge"].config.sdkAdapterModule = "<this file path>"
+// or set env:
+//   OPENCODE_SDK_ADAPTER_MODULE=<this file path>
+
+export function createOpenCodeSdkAdapter() {
+  return {
+    async createSession({ sessionKey }) {
+      return {
+        async *sendMessage({ runId, message, idempotencyKey }) {
+          // TODO: Replace this with real OpenCode SDK call + stream mapping.
+          yield {
+            kind: "assistant_final",
+            text:
+              "Template adapter loaded, but real SDK is not connected yet. " +
+              "Please implement sendMessage/sendAction in opencode_sdk_adapter.mjs.",
+            summary: "Template adapter loaded",
+            status: "failed",
+          };
+          yield {
+            kind: "run_completed",
+            status: "failed",
+            error: "Template adapter not implemented",
+          };
+        },
+        async *sendAction({ runId, action, idempotencyKey }) {
+          // TODO: Replace this with real action callback into OpenCode SDK.
+          if (action.type === "interaction.reply") {
+            yield {
+              kind: "interaction_resolved",
+              interactionId: action.interactionId,
+              decision: action.decision,
+              status: "resolved",
+              source: "template_adapter",
+            };
+          }
+          yield {
+            kind: "run_completed",
+            status: "failed",
+            error: "Template adapter not implemented",
+          };
+        },
+      };
+    },
+  };
+}
+`;
+function toErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+function ensureTemplateFile(logger) {
+    try {
+        if (!existsSync(DEFAULT_TEMPLATE_PATH)) {
+            mkdirSync(path.dirname(DEFAULT_TEMPLATE_PATH), { recursive: true });
+            writeFileSync(DEFAULT_TEMPLATE_PATH, ADAPTER_TEMPLATE, "utf-8");
+            logger?.info?.(`[openclaw-opencode-bridge] generated SDK adapter template at ${DEFAULT_TEMPLATE_PATH}`);
+        }
+        return DEFAULT_TEMPLATE_PATH;
+    }
+    catch (error) {
+        logger?.warn?.(`[openclaw-opencode-bridge] failed to write adapter template: ${toErrorMessage(error)}`);
+        return undefined;
+    }
+}
+function buildGuidanceText(templatePath) {
+    const lines = [
+        "OpenCode SDK adapter is not configured yet.",
+        "Set plugins.entries.openclaw-opencode-bridge.config.sdkAdapterModule",
+        "or set env OPENCODE_SDK_ADAPTER_MODULE, then restart openclaw-gateway.",
+    ];
+    if (templatePath) {
+        lines.push(`Template generated at: ${templatePath}`);
+    }
+    return lines.join("\n");
+}
+function createGuidanceSession(guidanceText) {
+    return {
+        async *sendMessage() {
+            yield {
+                kind: "progress",
+                stage: "configuration_required",
+                message: "OpenCode SDK adapter module is required.",
+            };
+            yield {
+                kind: "assistant_final",
+                text: guidanceText,
+                summary: "SDK adapter not configured",
+                status: "failed",
+            };
+            yield {
+                kind: "run_completed",
+                status: "failed",
+                error: "OpenCode SDK adapter is not configured",
+            };
+        },
+        async *sendAction(args) {
+            if (args.action.type === "interaction.reply") {
+                yield {
+                    kind: "interaction_resolved",
+                    interactionId: args.action.interactionId,
+                    decision: args.action.decision,
+                    status: "resolved",
+                    source: "openclaw-opencode-bridge",
+                };
+            }
+            yield {
+                kind: "run_completed",
+                status: "failed",
+                error: "OpenCode SDK adapter is not configured",
+            };
+        },
+    };
+}
+export function createOpenCodeSdkAdapter(ctx) {
+    const logger = ctx?.api?.logger;
+    const templatePath = ensureTemplateFile(logger);
+    const guidanceText = buildGuidanceText(templatePath);
+    return {
+        async createSession() {
+            return createGuidanceSession(guidanceText);
+        },
+    };
+}
+export default createOpenCodeSdkAdapter;

package/openclaw.plugin.json

@@ -8,7 +8,7 @@
     "properties": {
       "sdkAdapterModule": {
         "type": "string",
-        "description": "Node module specifier or path to SDK adapter module"
+        "description": "Node module specifier or path to SDK adapter module (optional; plugin auto-discovers common paths and has a bundled guided fallback)"
       },
       "sdkAdapterExport": {
         "type": "string",
@@ -26,15 +26,12 @@
         "type": "boolean",
         "description": "Broadcast events to all gateway clients instead of only requester"
       }
-    },
-    "required": [
-      "sdkAdapterModule"
-    ]
+    }
   },
   "uiHints": {
     "sdkAdapterModule": {
       "label": "SDK Adapter Module",
-      "help": "Absolute/relative path or npm package that exports OpenCode SDK adapter."
+      "help": "Absolute/relative path or npm package that exports OpenCode SDK adapter. If omitted, plugin will auto-discover and then fallback to bundled guided adapter."
     },
     "sdkAdapterExport": {
       "label": "SDK Adapter Export",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sw-market/openclaw-opencode-bridge",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "OpenClaw plugin bridge for OpenCode realtime streaming and interaction actions",
   "type": "module",
   "main": "dist/index.js",