@mrc2204/opencode-bridge 0.1.1 → 0.1.3

package/dist/src/observability.d.ts

@@ -0,0 +1,97 @@
+type OpenCodeEventKind = "task.started" | "task.progress" | "permission.requested" | "task.stalled" | "task.failed" | "task.completed";
+type EventScope = "session" | "global";
+type SseFrame = {
+    event?: string;
+    id?: string;
+    retry?: number;
+    data: string;
+    raw: string;
+};
+type TypedEventV1 = {
+    schema: "opencode.event.v1";
+    scope: EventScope;
+    eventName?: string;
+    eventId?: string;
+    kind: OpenCodeEventKind | null;
+    summary?: string;
+    lifecycleState?: "planning" | "coding" | "verifying" | "blocked" | "running" | "awaiting_permission" | "stalled" | "failed" | "completed";
+    filesChanged?: string[];
+    verifySummary?: {
+        command?: string;
+        exit?: number | null;
+        output_preview?: string | null;
+    } | null;
+    blockers?: string[];
+    completionSummary?: string | null;
+    runId?: string;
+    taskId?: string;
+    sessionId?: string;
+    timestamp: string;
+    wrappers: string[];
+    payload: any;
+};
+declare function parseSseFramesFromBuffer(input: string): {
+    frames: SseFrame[];
+    remainder: string;
+};
+declare function parseSseData(data: string): any;
+declare function unwrapGlobalPayload(raw: any): {
+    payload: any;
+    wrappers: string[];
+};
+declare function normalizeOpenCodeEvent(raw: any): {
+    kind: OpenCodeEventKind | null;
+    summary?: string;
+    raw: any;
+    lifecycleState?: TypedEventV1["lifecycleState"];
+    filesChanged?: string[];
+    verifySummary?: {
+        command?: string;
+        exit?: number | null;
+        output_preview?: string | null;
+    } | null;
+    blockers?: string[];
+    completionSummary?: string | null;
+};
+declare function normalizeTypedEventV1(frame: SseFrame, scope: EventScope): TypedEventV1;
+declare function summarizeLifecycle(events?: Array<{
+    kind?: OpenCodeEventKind | null;
+    summary?: string;
+    lifecycleState?: TypedEventV1["lifecycleState"];
+    filesChanged?: string[];
+    verifySummary?: {
+        command?: string;
+        exit?: number | null;
+        output_preview?: string | null;
+    } | null;
+    blockers?: string[];
+    completionSummary?: string | null;
+    timestamp?: string;
+}>): {
+    currentState: "planning" | "coding" | "verifying" | "blocked" | "running" | "awaiting_permission" | "stalled" | "failed" | "completed" | null;
+    current_state: "planning" | "coding" | "verifying" | "blocked" | "running" | "awaiting_permission" | "stalled" | "failed" | "completed" | null;
+    last_event_kind: OpenCodeEventKind | null;
+    last_event_at: string | null;
+    files_changed: string[];
+    verify_summary: {
+        command?: string;
+        exit?: number | null;
+        output_preview?: string | null;
+    }[];
+    blockers: string[];
+    completion_summary: string | null;
+};
+declare function resolveSessionId(input: {
+    explicitSessionId?: string;
+    runId?: string;
+    taskId?: string;
+    sessionKey?: string;
+    artifactSessionId?: string;
+    sessionList?: any[];
+}): {
+    sessionId?: string;
+    strategy: "explicit" | "artifact" | "scored_fallback" | "latest" | "none";
+    score?: number;
+};
+
+export { type EventScope, type OpenCodeEventKind, type SseFrame, type TypedEventV1, normalizeOpenCodeEvent, normalizeTypedEventV1, parseSseData, parseSseFramesFromBuffer, resolveSessionId, summarizeLifecycle, unwrapGlobalPayload };

package/dist/{observability.js → src/observability.js}

@@ -4,13 +4,15 @@ import {
   parseSseData,
   parseSseFramesFromBuffer,
   resolveSessionId,
+  summarizeLifecycle,
   unwrapGlobalPayload
-} from "./chunk-6NIQKNRA.js";
+} from "./chunk-OVQ5X54C.js";
 export {
   normalizeOpenCodeEvent,
   normalizeTypedEventV1,
   parseSseData,
   parseSseFramesFromBuffer,
   resolveSessionId,
+  summarizeLifecycle,
   unwrapGlobalPayload
 };

package/dist/src/shared-contracts.d.ts

@@ -0,0 +1,33 @@
+type BridgeSessionTagFields = {
+    runId: string;
+    taskId: string;
+    requested: string;
+    resolved: string;
+    callbackSession: string;
+    callbackSessionId?: string;
+    projectId?: string;
+    repoRoot?: string;
+};
+type OpenCodePluginCallbackAuditRecord = {
+    phase?: string;
+    event_type?: string;
+    session_id?: string;
+    title?: string;
+    tags?: Record<string, string> | null;
+    dedupeKey?: string;
+    ok?: boolean;
+    status?: number;
+    reason?: string;
+    body?: string;
+    payload?: any;
+    raw?: any;
+    created_at: string;
+};
+declare function buildTaggedSessionTitle(fields: BridgeSessionTagFields): string;
+declare function parseTaggedSessionTitle(title?: string): Record<string, string> | null;
+declare function buildPluginCallbackDedupeKey(input: {
+    sessionId?: string;
+    runId?: string;
+}): string;
+
+export { type BridgeSessionTagFields, type OpenCodePluginCallbackAuditRecord, buildPluginCallbackDedupeKey, buildTaggedSessionTitle, parseTaggedSessionTitle };

package/dist/src/shared-contracts.js

@@ -0,0 +1,10 @@
+import {
+  buildPluginCallbackDedupeKey,
+  buildTaggedSessionTitle,
+  parseTaggedSessionTitle
+} from "./chunk-TDVN5AFB.js";
+export {
+  buildPluginCallbackDedupeKey,
+  buildTaggedSessionTitle,
+  parseTaggedSessionTitle
+};

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
   "id": "opencode-bridge",
   "name": "OpenCode Bridge",
-  "description": "Bridge plugin scaffold for OpenClaw ↔ OpenCode orchestration.",
-  "version": "0.1.1",
+  "description": "Bridge plugin for OpenClaw ↔ OpenCode orchestration, execution routing, and callback observability.",
+  "version": "0.1.3",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/opencode-plugin/README.md

@@ -0,0 +1,25 @@
+# OpenCode-side plugin boundary
+
+This directory is the intended home for the canonical OpenCode-side callback plugin source.
+
+## Current transitional state
+The active runtime-tested plugin file currently lives at:
+- `.opencode/plugins/openclaw-bridge-callback.ts`
+
+That location is convenient for project-local loading in OpenCode.
+
+## Current source-of-truth
+Canonical OpenCode-side plugin source now lives at:
+- `opencode-plugin/openclaw-bridge-callback.ts`
+
+The runtime-loaded project-local file remains:
+- `.opencode/plugins/openclaw-bridge-callback.ts`
+
+but it should be treated as a thin re-export shim for local OpenCode loading during development.
+
+## Intended next step
+Promote this boundary further so the repository can ship:
+- OpenClaw-side bridge artifact
+- OpenCode-side callback plugin artifact
+
+from one source-of-truth without mixing runtime test placement with canonical source layout.

package/opencode-plugin/openclaw-bridge-callback.ts

@@ -0,0 +1,186 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { buildPluginCallbackDedupeKey, parseTaggedSessionTitle } from "../src/shared-contracts";
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function ensureAuditDir(directory: string) {
+  mkdirSync(directory, { recursive: true });
+  return directory;
+}
+
+function getAuditPath(directory: string) {
+  const auditDir = asString(process.env.OPENCLAW_BRIDGE_AUDIT_DIR) || join(directory, ".opencode");
+  ensureAuditDir(auditDir);
+  return join(auditDir, "bridge-callback-audit.jsonl");
+}
+
+function appendAudit(directory: string, record: any) {
+  const path = getAuditPath(directory);
+  appendFileSync(path, JSON.stringify({ ...record, created_at: new Date().toISOString() }) + "\n", "utf8");
+}
+
+function getOpenClawAuditPath() {
+  const explicit = asString(process.env.OPENCLAW_BRIDGE_OPENCLAW_AUDIT_PATH);
+  if (explicit) {
+    ensureAuditDir(join(explicit, ".."));
+    return explicit;
+  }
+  const home = asString(process.env.HOME);
+  if (!home) return null;
+  const auditDir = join(home, ".openclaw", "opencode-bridge", "audit");
+  ensureAuditDir(auditDir);
+  return join(auditDir, "callbacks.jsonl");
+}
+
+function appendOpenClawAudit(record: any) {
+  const path = getOpenClawAuditPath();
+  if (!path) return;
+  appendFileSync(path, JSON.stringify({ ...record, createdAt: new Date().toISOString() }) + "\n", "utf8");
+}
+
+function buildCallbackPayload(tags: Record<string, string>, eventType: string) {
+  const agentId = tags.requested || tags.requested_agent_id;
+  const sessionKey = tags.callbackSession || tags.callback_target_session_key;
+  const sessionId = tags.callbackSessionId || tags.callback_target_session_id;
+  if (!agentId || !sessionKey) return null;
+  return {
+    message: `OpenCode plugin event=${eventType} run=${tags.runId || tags.run_id || "unknown"} task=${tags.taskId || tags.task_id || "unknown"}`,
+    name: "OpenCode",
+    agentId,
+    sessionKey,
+    ...(sessionId ? { sessionId } : {}),
+    wakeMode: "now",
+    deliver: false,
+  };
+}
+
+async function postCallback(directory: string, payload: any, meta?: { eventType?: string; sessionId?: string; runId?: string; taskId?: string; requestedAgentId?: string; resolvedAgentId?: string; callbackTargetSessionKey?: string; callbackTargetSessionId?: string }) {
+  const hookBaseUrl = asString(process.env.OPENCLAW_HOOK_BASE_URL);
+  const hookToken = asString(process.env.OPENCLAW_HOOK_TOKEN);
+  if (!hookBaseUrl || !hookToken) {
+    appendAudit(directory, { ok: false, status: 0, reason: "missing_hook_env", payload, meta });
+    appendOpenClawAudit({
+      taskId: meta?.taskId,
+      runId: meta?.runId,
+      agentId: payload?.agentId,
+      requestedAgentId: meta?.requestedAgentId,
+      resolvedAgentId: meta?.resolvedAgentId,
+      sessionKey: undefined,
+      callbackTargetSessionKey: meta?.callbackTargetSessionKey,
+      callbackTargetSessionId: meta?.callbackTargetSessionId,
+      event: meta?.eventType,
+      callbackStatus: 0,
+      callbackOk: false,
+      callbackBody: "missing_hook_env",
+    });
+    return { ok: false, status: 0, reason: "missing_hook_env" };
+  }
+  const response = await fetch(`${hookBaseUrl.replace(/\/$/, "")}/hooks/agent`, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${hookToken}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(payload),
+  });
+  const text = await response.text();
+  appendAudit(directory, { ok: response.ok, status: response.status, body: text, payload, meta });
+  const openClawAuditRecord = {
+    taskId: meta?.taskId,
+    runId: meta?.runId,
+    agentId: payload?.agentId,
+    requestedAgentId: meta?.requestedAgentId,
+    resolvedAgentId: meta?.resolvedAgentId,
+    sessionKey: undefined,
+    callbackTargetSessionKey: meta?.callbackTargetSessionKey,
+    callbackTargetSessionId: meta?.callbackTargetSessionId,
+    event: meta?.eventType,
+    callbackStatus: response.status,
+    callbackOk: response.ok,
+    callbackBody: text,
+  };
+  appendAudit(directory, { phase: "openclaw_audit_mirror", record: openClawAuditRecord });
+  appendOpenClawAudit(openClawAuditRecord);
+  return { ok: response.ok, status: response.status, body: text };
+}
+
+const callbackDedupe = new Set<string>();
+const sessionTagCache = new Map<string, Record<string, string>>();
+
+function readSessionId(event: any): string | undefined {
+  return (
+    asString(event?.session?.id) ||
+    asString(event?.session?.sessionID) ||
+    asString(event?.data?.session?.id) ||
+    asString(event?.data?.sessionID) ||
+    asString(event?.properties?.sessionID) ||
+    asString(event?.properties?.info?.sessionID) ||
+    asString(event?.properties?.info?.id) ||
+    asString(event?.payload?.sessionID)
+  );
+}
+
+function isTerminalEvent(_event: any, type: string): boolean {
+  return type === "session.idle" || type === "session.error";
+}
+
+export const OpenClawBridgeCallbackPlugin = async ({ client, directory }: any) => {
+  await client.app.log({
+    body: {
+      service: "openclaw-bridge-callback",
+      level: "info",
+      message: "OpenClaw bridge callback plugin initialized",
+      extra: { directory },
+    },
+  });
+
+  return {
+    event: async ({ event }: any) => {
+      const type = asString(event?.type) || "unknown";
+      const sessionId = readSessionId(event);
+      const title =
+        asString(event?.session?.title) ||
+        asString(event?.data?.session?.title) ||
+        asString(event?.data?.title) ||
+        asString(event?.properties?.info?.title) ||
+        asString(event?.properties?.title) ||
+        asString(event?.payload?.session?.title) ||
+        asString(event?.payload?.title);
+      const parsedTags = parseTaggedSessionTitle(title);
+      if (sessionId && parsedTags && (parsedTags.callbackSession || parsedTags.callback_target_session_key)) {
+        sessionTagCache.set(sessionId, parsedTags);
+      }
+      const tags = parsedTags || (sessionId ? sessionTagCache.get(sessionId) || null : null);
+      appendAudit(directory, { phase: "event_seen", event_type: type, session_id: sessionId, title, tags, raw: event });
+      if (!tags || !(tags.callbackSession || tags.callback_target_session_key)) return;
+      if (!isTerminalEvent(event, type)) return;
+      const dedupeKey = buildPluginCallbackDedupeKey({ sessionId, runId: tags.runId || tags.run_id });
+      if (callbackDedupe.has(dedupeKey)) {
+        appendAudit(directory, { phase: "deduped", event_type: type, session_id: sessionId, dedupeKey, tags });
+        return;
+      }
+      callbackDedupe.add(dedupeKey);
+      const payload = buildCallbackPayload(tags, type);
+      if (!payload) {
+        appendAudit(directory, { phase: "skipped_no_payload", event_type: type, session_id: sessionId, tags });
+        return;
+      }
+      await postCallback(directory, payload, {
+        eventType: type,
+        sessionId,
+        runId: tags.runId || tags.run_id,
+        taskId: tags.taskId || tags.task_id,
+        requestedAgentId: tags.requested || tags.requested_agent_id,
+        resolvedAgentId: tags.resolved || tags.resolved_agent_id,
+        callbackTargetSessionKey: tags.callbackSession || tags.callback_target_session_key,
+        callbackTargetSessionId: tags.callbackSessionId || tags.callback_target_session_id,
+      });
+    },
+  };
+};
+
+export default OpenClawBridgeCallbackPlugin;
+

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@mrc2204/opencode-bridge",
-  "version": "0.1.1",
-  "description": "OpenClaw ↔ OpenCode bridge plugin for routing, callback, SSE probing, and runtime-ops scaffolding.",
+  "version": "0.1.3",
+  "description": "OpenClaw ↔ OpenCode bridge plugin for hybrid routing, callback orchestration, and multi-project-safe runtime control.",
   "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "default": "./dist/index.js"
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
     }
   },
   "private": false,
@@ -23,9 +23,13 @@
   },
   "scripts": {
     "clean": "rm -rf dist",
-    "build": "tsup src/index.ts src/observability.ts --format esm --dts --clean",
+    "build": "tsup --config tsup.config.ts",
     "typecheck": "tsc --noEmit",
     "test": "tsx test/run-tests.ts",
+    "materialize:opencode-plugin:project": "node ./scripts/materialize-opencode-plugin.mjs --mode project",
+    "materialize:opencode-plugin:global": "node ./scripts/materialize-opencode-plugin.mjs --mode global",
+    "install:bridge:project": "node ./scripts/install-bridge.mjs --mode project",
+    "install:bridge:global": "node ./scripts/install-bridge.mjs --mode global",
     "prepublishOnly": "npm run build && npm run test"
   },
   "devDependencies": {
@@ -36,12 +40,16 @@
   },
   "openclaw": {
     "extensions": [
-      "./dist/index.js"
+      "./dist/src/index.js"
     ]
   },
   "files": [
     "dist/",
     "skills/",
+    "opencode-plugin/",
+    "scripts/materialize-opencode-plugin.mjs",
+    "scripts/install-bridge.mjs",
+    "src/shared-contracts.ts",
     "README.md",
     "README.en.md",
     "openclaw.plugin.json"

package/scripts/install-bridge.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { resolve, dirname } from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+
+function parseArgs(argv) {
+  const args = { mode: "project", target: undefined, skipOpenClaw: false, skipOpencode: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--mode") args.mode = argv[++i] || args.mode;
+    else if (arg === "--target") args.target = argv[++i];
+    else if (arg === "--skip-openclaw") args.skipOpenClaw = true;
+    else if (arg === "--skip-opencode") args.skipOpencode = true;
+  }
+  return args;
+}
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    stdio: "inherit",
+    shell: false,
+    ...options,
+  });
+  if (result.status !== 0) {
+    process.exit(result.status || 1);
+  }
+}
+
+const args = parseArgs(process.argv.slice(2));
+const repoRoot = resolve(dirname(new URL(import.meta.url).pathname), "..");
+const target = args.target ? resolve(args.target) : process.cwd();
+
+if (!args.skipOpenClaw) {
+  run("openclaw", ["plugins", "install", "-l", repoRoot]);
+}
+
+if (!args.skipOpencode) {
+  const materializeArgs = [resolve(repoRoot, "scripts", "materialize-opencode-plugin.mjs"), "--mode", args.mode];
+  if (args.mode === "project") {
+    materializeArgs.push("--target", target);
+  } else if (args.target) {
+    materializeArgs.push("--target", target);
+  }
+  run("node", materializeArgs, { cwd: repoRoot });
+}
+
+const summary = {
+  ok: true,
+  mode: args.mode,
+  repoRoot,
+  target,
+  steps: {
+    openclawInstalled: !args.skipOpenClaw,
+    opencodeMaterialized: !args.skipOpencode,
+  },
+  note: args.mode === "global"
+    ? "Global mode installed OpenClaw plugin locally and materialized OpenCode plugin into global config dir."
+    : "Project mode installed OpenClaw plugin locally and materialized OpenCode plugin into the target project's .opencode directory.",
+};
+console.log(JSON.stringify(summary, null, 2));

package/scripts/materialize-opencode-plugin.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+import { mkdirSync, copyFileSync, writeFileSync, existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import process from "node:process";
+
+function parseArgs(argv) {
+  const args = { mode: "project", target: undefined, force: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--mode") args.mode = argv[++i] || args.mode;
+    else if (arg === "--target") args.target = argv[++i];
+    else if (arg === "--force") args.force = true;
+  }
+  return args;
+}
+
+function ensurePluginEntry(configPath, pluginRef) {
+  if (!existsSync(configPath)) return { updated: false, reason: "missing_config" };
+  const raw = readFileSync(configPath, "utf8");
+  const data = JSON.parse(raw);
+  const plugins = Array.isArray(data.plugin) ? data.plugin : [];
+  if (!plugins.includes(pluginRef)) {
+    data.plugin = [...plugins, pluginRef];
+    writeFileSync(configPath, JSON.stringify(data, null, 2) + "\n", "utf8");
+    return { updated: true, reason: "added_plugin_ref" };
+  }
+  return { updated: false, reason: "already_present" };
+}
+
+const args = parseArgs(process.argv.slice(2));
+const repoRoot = resolve(dirname(new URL(import.meta.url).pathname), "..");
+const pluginArtifact = join(repoRoot, "dist", "opencode-plugin", "openclaw-bridge-callback.js");
+const sharedChunkArtifact = join(repoRoot, "dist", "chunk-TDVN5AFB.js");
+if (!existsSync(pluginArtifact)) {
+  console.error(`Missing built plugin artifact: ${pluginArtifact}. Run npm run build first.`);
+  process.exit(1);
+}
+if (!existsSync(sharedChunkArtifact)) {
+  console.error(`Missing shared chunk artifact: ${sharedChunkArtifact}. Run npm run build first.`);
+  process.exit(1);
+}
+
+const targetBase = args.target
+  ? resolve(args.target)
+  : args.mode === "global"
+    ? resolve(process.env.HOME || "~", ".config", "opencode")
+    : repoRoot;
+
+const pluginDir = args.mode === "global"
+  ? join(targetBase, "plugins")
+  : join(targetBase, ".opencode", "plugins");
+const targetFile = join(pluginDir, "openclaw-bridge-callback.js");
+
+mkdirSync(pluginDir, { recursive: true });
+copyFileSync(pluginArtifact, targetFile);
+
+let configUpdate = { updated: false, reason: "not_requested" };
+if (args.mode === "global") {
+  const configPath = join(targetBase, "opencode.json");
+  configUpdate = ensurePluginEntry(configPath, "./plugins/openclaw-bridge-callback.js");
+} else {
+  const configPath = join(targetBase, ".opencode", "opencode.json");
+  configUpdate = ensurePluginEntry(configPath, "./plugins/openclaw-bridge-callback.js");
+}
+
+console.log(JSON.stringify({
+  ok: true,
+  mode: args.mode,
+  sourceFile: pluginArtifact,
+  targetFile,
+  configUpdate,
+  note: args.mode === "global"
+    ? "Copy complete. Global OpenCode config was auto-patched when present."
+    : "Copy complete. Project-local .opencode/opencode.json was updated when present.",
+}, null, 2));