@sw-market/openclaw-opencode-bridge 0.1.0 → 0.1.2

package/README.md

@@ -9,13 +9,69 @@ OpenClaw plugin bridge for OpenCode realtime sessions.
 - Support interactive confirmations (`interaction.required` -> `chat.action` -> `interaction.resolved`).
 - Emit file change summaries (`file.changed`) for downstream clients (Flutter/Feishu/others).
 
-## Installation
+## Install To OpenClaw
 
 ```bash
-npm install @sw-market/openclaw-opencode-bridge
+openclaw plugins install @sw-market/openclaw-opencode-bridge
 ```
 
-## Usage (plugin runtime)
+After install, verify plugin exists:
+
+```bash
+openclaw plugins list
+```
+
+## OpenClaw Config
+
+In `~/.openclaw/openclaw.json`, enable plugin and set SDK adapter config:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-opencode-bridge": {
+        "enabled": true,
+        "config": {
+          "sdkAdapterModule": "/abs/path/to/opencode_sdk_adapter.mjs",
+          "sdkAdapterExport": "createOpenCodeSdkAdapter",
+          "sessionTtlMs": 1800000,
+          "cleanupIntervalMs": 60000
+        }
+      }
+    }
+  }
+}
+```
+
+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 no longer requires `sdkAdapterModule` in config.
+- But runtime calls will fail until adapter module is provided via config or env.
+
+## Gateway Methods Provided
+
+This plugin registers:
+- `opencode.chat.send`
+- `opencode.chat.action`
+
+Set adapter side method routing:
+
+```env
+BRIDGE_WS_CHAT_SEND_METHOD=opencode.chat.send
+BRIDGE_WS_CHAT_ACTION_METHOD=opencode.chat.action
+```
+
+## Library Usage (standalone)
 
 ```ts
 import {

package/dist/openclaw-extension.d.ts

@@ -0,0 +1,40 @@
+type JsonObject = Record<string, unknown>;
+type PluginLogger = {
+    info: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+    debug?: (message: string) => void;
+};
+type RespondFn = (ok: boolean, payload?: unknown, error?: {
+    code: string;
+    message: string;
+    [key: string]: unknown;
+}, meta?: JsonObject) => void;
+type GatewayRequestHandlerOptions = {
+    params: JsonObject;
+    client: {
+        connId?: string;
+    } | null;
+    respond: RespondFn;
+    context: {
+        broadcast: (event: string, payload: unknown, opts?: {
+            dropIfSlow?: boolean;
+            stateVersion?: JsonObject;
+        }) => void;
+        broadcastToConnIds: (event: string, payload: unknown, connIds: ReadonlySet<string>, opts?: {
+            dropIfSlow?: boolean;
+            stateVersion?: JsonObject;
+        }) => void;
+        nodeSendToSession: (sessionKey: string, event: string, payload: unknown) => void;
+    };
+};
+type PluginApi = {
+    id: string;
+    pluginConfig?: JsonObject;
+    logger: PluginLogger;
+    resolvePath: (input: string) => string;
+    registerGatewayMethod: (method: string, handler: (opts: GatewayRequestHandlerOptions) => void | Promise<void>) => void;
+    on?: (hookName: string, handler: () => void | Promise<void>) => void;
+};
+export default function register(api: PluginApi): void;
+export {};

package/dist/openclaw-extension.js

@@ -0,0 +1,305 @@
+import { existsSync } from "node:fs";
+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";
+let bridgePromise = null;
+let bridgeInstance = null;
+function asObject(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function readString(source, key) {
+    const value = source[key];
+    return typeof value === "string" ? value.trim() : "";
+}
+function readOptionalPositiveInt(source, key) {
+    const value = source[key];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return undefined;
+    }
+    const normalized = Math.floor(value);
+    if (normalized <= 0) {
+        return undefined;
+    }
+    return normalized;
+}
+function normalizeDecision(value) {
+    const lowered = value.trim().toLowerCase();
+    if (lowered === "approve" || lowered === "approved" || lowered === "yes" || lowered === "ok") {
+        return "approve";
+    }
+    if (lowered === "reject" || lowered === "rejected" || lowered === "decline" || lowered === "no") {
+        return "reject";
+    }
+    if (lowered === "cancel" || lowered === "cancelled" || lowered === "canceled") {
+        return "cancel";
+    }
+    return "approve";
+}
+function toErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+function parseConfig(pluginConfig) {
+    const raw = pluginConfig ?? {};
+    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;
+    return {
+        sdkAdapterModule,
+        sdkAdapterExport,
+        sessionTtlMs,
+        cleanupIntervalMs,
+        emitToAllClients,
+    };
+}
+function resolveModuleSpecifier(api, moduleSpecifier) {
+    const raw = moduleSpecifier.trim();
+    if (!raw) {
+        throw new Error("OpenCode SDK adapter is not configured. Set plugins.entries.openclaw-opencode-bridge.config.sdkAdapterModule " +
+            "or env OPENCODE_SDK_ADAPTER_MODULE.");
+    }
+    const looksLikePath = raw.startsWith("./") ||
+        raw.startsWith("../") ||
+        raw.startsWith("/") ||
+        raw.startsWith(".\\") ||
+        /^[a-zA-Z]:[\\/]/.test(raw);
+    if (!looksLikePath) {
+        return raw;
+    }
+    const absolutePath = path.isAbsolute(raw) ? raw : api.resolvePath(raw);
+    if (!existsSync(absolutePath)) {
+        throw new Error(`sdkAdapterModule path does not exist: ${absolutePath}`);
+    }
+    return pathToFileURL(absolutePath).href;
+}
+function isOpenCodeSdkAdapter(value) {
+    const obj = asObject(value);
+    if (!obj) {
+        return false;
+    }
+    return typeof obj.createSession === "function";
+}
+async function loadSdkAdapter(api, config) {
+    const moduleSpecifier = resolveModuleSpecifier(api, config.sdkAdapterModule ?? "");
+    const loaded = await import(moduleSpecifier);
+    const exported = loaded[config.sdkAdapterExport];
+    let candidate = exported;
+    if (typeof exported === "function") {
+        candidate = await Promise.resolve(exported({
+            api,
+            pluginConfig: config,
+        }));
+    }
+    if (!isOpenCodeSdkAdapter(candidate)) {
+        throw new Error(`Invalid OpenCode SDK adapter from "${config.sdkAdapterModule}" export "${config.sdkAdapterExport}". ` +
+            "Expected an object with createSession(args) function.");
+    }
+    return candidate;
+}
+function respondError(respond, code, message) {
+    respond(false, undefined, {
+        code,
+        message,
+    });
+}
+function readRequiredField(params, key) {
+    const value = readString(params, key);
+    if (!value) {
+        throw new Error(`${key} is required`);
+    }
+    return value;
+}
+function parseAction(params) {
+    const actionObj = asObject(params.action);
+    if (!actionObj) {
+        throw new Error("action is required and must be an object");
+    }
+    const actionType = readRequiredField(actionObj, "type");
+    if (actionType === "interaction.reply") {
+        return {
+            type: "interaction.reply",
+            interactionId: readRequiredField(actionObj, "interactionId"),
+            decision: normalizeDecision(readString(actionObj, "decision") || "approve"),
+            source: readString(actionObj, "source") || undefined,
+            payload: asObject(actionObj.payload) ?? undefined,
+        };
+    }
+    if (actionType === "cancel_run") {
+        return {
+            type: "cancel_run",
+            reason: readString(actionObj, "reason") || undefined,
+        };
+    }
+    throw new Error(`Unsupported action.type: ${actionType}`);
+}
+function emitEventToGateway(args) {
+    const payload = { ...args.payload };
+    if (!payload.sessionKey) {
+        payload.sessionKey = args.sessionKey;
+    }
+    const connId = typeof args.opts.client?.connId === "string" ? args.opts.client.connId.trim() : "";
+    const dropIfSlow = args.event !== "chat";
+    if (!args.emitToAllClients && connId) {
+        args.opts.context.broadcastToConnIds(args.event, payload, new Set([connId]), {
+            dropIfSlow,
+        });
+    }
+    else {
+        args.opts.context.broadcast(args.event, payload, {
+            dropIfSlow,
+        });
+    }
+    args.opts.context.nodeSendToSession(args.sessionKey, args.event, payload);
+}
+function emitFailedCompletion(args) {
+    const message = toErrorMessage(args.error).trim() || "OpenCode bridge invocation failed";
+    emitEventToGateway({
+        opts: args.opts,
+        event: "chat",
+        payload: {
+            runId: args.runId,
+            state: "failed",
+            error: message,
+        },
+        sessionKey: args.sessionKey,
+        emitToAllClients: args.emitToAllClients,
+    });
+}
+async function streamInvocation(args) {
+    try {
+        for await (const frame of args.events) {
+            if (!frame || frame.type !== "event") {
+                continue;
+            }
+            const payload = asObject(frame.payload) ?? {};
+            if (!payload.runId) {
+                payload.runId = args.runId;
+            }
+            emitEventToGateway({
+                opts: args.opts,
+                event: frame.event,
+                payload,
+                sessionKey: args.sessionKey,
+                emitToAllClients: args.emitToAllClients,
+            });
+        }
+    }
+    catch (error) {
+        args.logger.error(`[${CHAT_SEND_METHOD}] stream failed: ${toErrorMessage(error)}`);
+        emitFailedCompletion({
+            opts: args.opts,
+            runId: args.runId,
+            sessionKey: args.sessionKey,
+            emitToAllClients: args.emitToAllClients,
+            error,
+        });
+    }
+}
+async function ensureBridge(api) {
+    const config = parseConfig(api.pluginConfig);
+    if (bridgeInstance) {
+        return { bridge: bridgeInstance, config };
+    }
+    if (!bridgePromise) {
+        bridgePromise = (async () => {
+            const sdk = await loadSdkAdapter(api, config);
+            const bridge = new OpenClawOpenCodeBridge(sdk, {
+                sessionTtlMs: config.sessionTtlMs,
+                cleanupIntervalMs: config.cleanupIntervalMs,
+            });
+            bridgeInstance = bridge;
+            api.logger.info(`[${CHAT_SEND_METHOD}] bridge initialized`);
+            return bridge;
+        })();
+    }
+    const bridge = await bridgePromise;
+    return { bridge, config };
+}
+export default function register(api) {
+    api.registerGatewayMethod(CHAT_SEND_METHOD, async (opts) => {
+        try {
+            const params = asObject(opts.params) ?? {};
+            const sessionKey = readRequiredField(params, "sessionKey");
+            const message = readRequiredField(params, "message");
+            const runId = readString(params, "runId") || undefined;
+            const idempotencyKey = readString(params, "idempotencyKey") || undefined;
+            const { bridge, config } = await ensureBridge(api);
+            const invocation = await bridge.chatSend({
+                sessionKey,
+                message,
+                runId,
+                idempotencyKey,
+            });
+            opts.respond(true, {
+                runId: invocation.runId,
+                status: "started",
+            });
+            void streamInvocation({
+                opts,
+                runId: invocation.runId,
+                sessionKey,
+                emitToAllClients: config.emitToAllClients,
+                events: invocation.events,
+                logger: api.logger,
+            });
+        }
+        catch (error) {
+            respondError(opts.respond, "INVALID_REQUEST", toErrorMessage(error));
+        }
+    });
+    api.registerGatewayMethod(CHAT_ACTION_METHOD, async (opts) => {
+        try {
+            const params = asObject(opts.params) ?? {};
+            const sessionKey = readRequiredField(params, "sessionKey");
+            const runId = readRequiredField(params, "runId");
+            const idempotencyKey = readString(params, "idempotencyKey") || undefined;
+            const action = parseAction(params);
+            const { bridge, config } = await ensureBridge(api);
+            const invocation = await bridge.chatAction({
+                sessionKey,
+                runId,
+                action,
+                idempotencyKey,
+            });
+            opts.respond(true, {
+                runId: invocation.runId,
+                status: "started",
+            });
+            void streamInvocation({
+                opts,
+                runId: invocation.runId,
+                sessionKey,
+                emitToAllClients: config.emitToAllClients,
+                events: invocation.events,
+                logger: api.logger,
+            });
+        }
+        catch (error) {
+            respondError(opts.respond, "INVALID_REQUEST", toErrorMessage(error));
+        }
+    });
+    if (typeof api.on === "function") {
+        api.on("gateway_stop", async () => {
+            if (!bridgeInstance) {
+                return;
+            }
+            await bridgeInstance.dispose();
+            bridgeInstance = null;
+            bridgePromise = null;
+            api.logger.info(`[${api.id}] bridge disposed`);
+        });
+    }
+}

package/openclaw.plugin.json

@@ -0,0 +1,51 @@
+{
+  "id": "openclaw-opencode-bridge",
+  "name": "OpenCode Bridge",
+  "description": "Bridge OpenClaw gateway chat.send/chat.action with OpenCode SDK streams",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "sdkAdapterModule": {
+        "type": "string",
+        "description": "Node module specifier or path to SDK adapter module (optional if OPENCODE_SDK_ADAPTER_MODULE is set)"
+      },
+      "sdkAdapterExport": {
+        "type": "string",
+        "description": "Export name from sdkAdapterModule (default: createOpenCodeSdkAdapter)"
+      },
+      "sessionTtlMs": {
+        "type": "integer",
+        "minimum": 60000
+      },
+      "cleanupIntervalMs": {
+        "type": "integer",
+        "minimum": 15000
+      },
+      "emitToAllClients": {
+        "type": "boolean",
+        "description": "Broadcast events to all gateway clients instead of only requester"
+      }
+    }
+  },
+  "uiHints": {
+    "sdkAdapterModule": {
+      "label": "SDK Adapter Module",
+      "help": "Absolute/relative path or npm package that exports OpenCode SDK adapter."
+    },
+    "sdkAdapterExport": {
+      "label": "SDK Adapter Export",
+      "help": "Export name in the adapter module. Default is createOpenCodeSdkAdapter."
+    },
+    "sessionTtlMs": {
+      "label": "Session TTL (ms)"
+    },
+    "cleanupIntervalMs": {
+      "label": "Cleanup Interval (ms)"
+    },
+    "emitToAllClients": {
+      "label": "Emit To All Clients",
+      "help": "Enable if you want every connected gateway client to receive run events."
+    }
+  }
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@sw-market/openclaw-opencode-bridge",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "OpenClaw plugin bridge for OpenCode realtime streaming and interaction actions",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "openclaw.plugin.json"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -23,6 +24,11 @@
   ],
   "author": "SW-Market",
   "license": "MIT",
+  "openclaw": {
+    "extensions": [
+      "./dist/openclaw-extension.js"
+    ]
+  },
   "devDependencies": {
     "@types/node": "^22.15.0",
     "rimraf": "^6.0.1",