@mrc2204/opencode-bridge 0.1.1 → 0.1.3

package/README.en.md

@@ -1,115 +1,94 @@
 # @mrc2204/opencode-bridge
 
-OpenClaw ↔ OpenCode bridge plugin for multi-agent orchestration, callback routing, SSE probing, run observability, and runtime serve management.
-
-## Goals
-- Standardize callback flow from OpenCode back into OpenClaw via `/hooks/agent`
-- Standardize `sessionKey` and routing envelope
-- Support **1 project = 1 OpenCode serve instance**
-- Provide runtime-ops baseline for:
-  - SSE probe / event normalization
-  - run status / run events / session tail
-  - serve registry / spawn / reuse / shutdown / idle evaluation
-
-## Install from npm
+OpenClaw ↔ OpenCode bridge for hybrid execution, callback orchestration, and multi-project-safe runtime control.
+
+## What it does
+`opencode-bridge` connects two runtime surfaces:
+- **OpenClaw side**: project-aware routing, run state, serve management, observability, and callback policy
+- **OpenCode side**: event-driven callback plugin for terminal session lifecycle events
+
+It is designed for teams that want:
+- project-aware OpenCode execution
+- callback flow back into OpenClaw via `/hooks/agent`
+- installable OpenCode-side plugin artifacts
+- multi-project-safe runtime boundaries
+
+## Install
+### 1) OpenClaw side
 ```bash
 openclaw plugins install @mrc2204/openclaw-opencode-bridge
 ```
 
-## Repository structure (build-based)
-```text
-openclaw-opencode-bridge/
-├── openclaw.plugin.json
-├── package.json
-├── tsconfig.json
-├── src/
-│   ├── index.ts
-│   ├── observability.ts
-│   └── types.ts
-├── dist/                  # generated by npm run build
-├── test/
-│   ├── run-tests.ts
-│   └── observability.test.ts
-├── skills/
-│   └── opencode-orchestration/
-│       └── SKILL.md
-├── README.md
-└── README.en.md
+### 2) OpenCode side — project install
+```bash
+npm run materialize:opencode-plugin:project
 ```
 
-## Available tools
-- `opencode_status`
-- `opencode_resolve_project`
-- `opencode_build_envelope`
-- `opencode_check_hook_policy`
-- `opencode_evaluate_lifecycle`
-- `opencode_run_status`
-- `opencode_run_events`
-- `opencode_session_tail`
-- `opencode_serve_spawn`
-- `opencode_registry_get`
-- `opencode_registry_upsert`
-- `opencode_registry_cleanup`
-- `opencode_serve_shutdown`
-- `opencode_serve_idle_check`
-
-## Current assumptions
-- `1 project = 1 opencode serve instance`
-- callback primary = `/hooks/agent`
-- `sessionKey` convention = `hook:opencode:<agentId>:<taskId>`
-- `opencode_server_url` is required in practical routing envelopes
-
-## Build & test
+### 3) OpenCode side — global install
 ```bash
-npm install
-npm run build
-npm run typecheck
-npm run test
+npm run materialize:opencode-plugin:global
 ```
 
-After `npm run build`, runtime entrypoints point to built artifacts in `dist/`:
-- `main`: `./dist/index.js`
-- `types`: `./dist/index.d.ts`
-- `openclaw.extensions`: `./dist/index.js`
+Global mode auto-patches `~/.config/opencode/opencode.json` when it exists.
 
-## Publish flow (safe)
+### 4) One-command install
+Project mode:
 ```bash
-npm run build
-npm run test
-npm pack --dry-run
-# if all good:
-# npm publish
+npm run install:bridge:project
 ```
 
-Use `npm pack --dry-run` to confirm package contents are build artifacts (`dist/`, `skills/`, readmes, plugin manifest), not raw TypeScript entrypoints.
-
-## Runtime config
-Plugin-owned config path:
-```text
-~/.openclaw/opencode-bridge/config.json
+Global mode:
+```bash
+npm run install:bridge:global
 ```
 
-Example:
-```json
-{
-  "opencodeServerUrl": "http://127.0.0.1:4096",
-  "hookBaseUrl": "http://127.0.0.1:18789",
-  "hookToken": "<OPENCLAW_HOOK_TOKEN>",
-  "projectRegistry": [
-    {
-      "projectId": "agent-smart-memo",
-      "repoRoot": "/Users/me/Work/projects/agent-smart-memo",
-      "serverUrl": "http://127.0.0.1:4096",
-      "idleTimeoutMs": 900000
-    }
-  ]
-}
-```
+## Required callback environment
+The OpenCode-side callback plugin needs:
+- `OPENCLAW_HOOK_BASE_URL`
+- `OPENCLAW_HOOK_TOKEN`
+
+Optional:
+- `OPENCLAW_BRIDGE_AUDIT_DIR`
+- `OPENCLAW_BRIDGE_OPENCLAW_AUDIT_PATH`
+
+## Runtime model
+### Hybrid execution strategy
+`opencode-bridge` supports two practical execution lanes:
+- **CLI-direct**: lightweight execution for simpler tasks
+- **serve/plugin mode**: canonical path for callback, observability, and event-driven lifecycle handling
 
-## Local development install
+### Multi-project safety
+Current contracts assume:
+- `1 project = 1 correctly bound OpenCode serve instance`
+- serve reuse is allowed only when runtime introspection confirms the expected `repo_root`
+- bridge session tags must preserve callback identity per run/session
+
+## Build and verify
 ```bash
-openclaw plugins install -l ~/Work/projects/opencode-bridge
+npm install
+npm run build
+npm test -- --runInBand
 ```
 
-## License
-MIT
+## Package / artifact layout
+```text
+openclaw-opencode-bridge/
+├── src/                 # OpenClaw-side runtime
+├── opencode-plugin/     # canonical OpenCode-side plugin source
+├── scripts/             # materialize/install helpers
+├── dist/                # built artifacts
+├── docs/                # install / architecture / contracts
+└── skills/              # bridge-related skills/docs
+```
+
+## More docs
+- `docs/install/quick-start-2026-03-22.md`
+- `docs/install/production-ish-install-2026-03-22.md`
+- `docs/contracts/multi-project-contract-draft-2026-03-22.md`
+- `docs/architecture/hybrid-execution-strategy-2026-03-22.md`
+
+Developer-only local debug notes are intentionally kept out of this README. See:
+- `docs/install/developer-local-debug-2026-03-22.md`
+
+## Status
+Current status: functional and productized enough for real use, with hardening history reflected in tests and docs.

package/README.md

@@ -2,116 +2,95 @@
 
 > English README: [README.en.md](./README.en.md)
 
-Plugin bridge giữa **OpenClaw** và **OpenCode** cho orchestration multi-agent, callback routing, SSE probing, run observability và serve runtime management.
-
-## Mục tiêu
-- Chuẩn hóa callback path từ OpenCode về OpenClaw qua `/hooks/agent`
-- Chuẩn hóa `sessionKey` / `routing envelope`
-- Hỗ trợ mô hình vận hành: **1 project = 1 OpenCode serve instance**
-- Cung cấp runtime-ops baseline:
-  - SSE probe / event normalize
-  - run status / run events / session tail
-  - serve registry / spawn / reuse / shutdown / idle evaluation
-
-## Cài package từ npm
+`opencode-bridge` là cầu nối giữa OpenClaw và OpenCode theo hướng hybrid execution, callback orchestration và runtime control an toàn cho nhiều project.
+
+## Package này làm gì
+Package này nối 2 phía runtime:
+- **OpenClaw side**: routing theo project, run state, serve management, observability, callback policy
+- **OpenCode side**: plugin callback bắt event terminal bên trong OpenCode runtime
+
+Mục tiêu thực dụng:
+- execution theo project rõ ràng
+- callback quay về OpenClaw qua `/hooks/agent`
+- artifact OpenCode-side cài được theo project hoặc global
+- multi-project-safe boundary
+
+## Cài đặt
+### 1) OpenClaw side
 ```bash
 openclaw plugins install @mrc2204/openclaw-opencode-bridge
 ```
 
-## Cấu trúc repo (build-based)
-```text
-openclaw-opencode-bridge/
-├── openclaw.plugin.json
-├── package.json
-├── tsconfig.json
-├── src/
-│   ├── index.ts
-│   ├── observability.ts
-│   └── types.ts
-├── dist/                  # artifact tạo bởi npm run build
-├── test/
-│   ├── run-tests.ts
-│   └── observability.test.ts
-├── skills/
-│   └── opencode-orchestration/
-│       └── SKILL.md
-├── README.md
-└── README.en.md
+### 2) OpenCode side — cài theo project
+```bash
+npm run materialize:opencode-plugin:project
 ```
 
-## Tool hiện có
-- `opencode_status`
-- `opencode_resolve_project`
-- `opencode_build_envelope`
-- `opencode_check_hook_policy`
-- `opencode_evaluate_lifecycle`
-- `opencode_run_status`
-- `opencode_run_events`
-- `opencode_session_tail`
-- `opencode_serve_spawn`
-- `opencode_registry_get`
-- `opencode_registry_upsert`
-- `opencode_registry_cleanup`
-- `opencode_serve_shutdown`
-- `opencode_serve_idle_check`
-
-## Assumptions hiện tại
-- `1 project = 1 opencode serve instance`
-- callback primary = `/hooks/agent`
-- `sessionKey` convention = `hook:opencode:<agentId>:<taskId>`
-- `opencode_server_url` là field bắt buộc trong envelope routing thực tế
-
-## Build/Test
+### 3) OpenCode side — cài global
 ```bash
-npm install
-npm run build
-npm run typecheck
-npm run test
+npm run materialize:opencode-plugin:global
 ```
 
-Sau `npm run build`, entrypoint runtime dùng artifact trong `dist/`:
-- `main`: `./dist/index.js`
-- `types`: `./dist/index.d.ts`
-- `openclaw.extensions`: `./dist/index.js`
+Global mode sẽ tự patch `~/.config/opencode/opencode.json` khi file này tồn tại.
 
-## Publish flow (safe)
+### 4) Một lệnh cài
+Project mode:
 ```bash
-npm run build
-npm run test
-npm pack --dry-run
-# nếu OK:
-# npm publish
+npm run install:bridge:project
 ```
 
-`npm pack --dry-run` dùng để kiểm tra package chỉ publish artifact cần thiết (`dist/`, `skills/`, readme, plugin manifest), không trỏ trực tiếp vào source TypeScript.
-
-## Config runtime
-Plugin dùng plugin-owned config tại:
-```text
-~/.openclaw/opencode-bridge/config.json
+Global mode:
+```bash
+npm run install:bridge:global
 ```
 
-Ví dụ:
-```json
-{
-  "opencodeServerUrl": "http://127.0.0.1:4096",
-  "hookBaseUrl": "http://127.0.0.1:18789",
-  "hookToken": "<OPENCLAW_HOOK_TOKEN>",
-  "projectRegistry": [
-    {
-      "projectId": "agent-smart-memo",
-      "repoRoot": "/Users/me/Work/projects/agent-smart-memo",
-      "serverUrl": "http://127.0.0.1:4096",
-      "idleTimeoutMs": 900000
-    }
-  ]
-}
-```
+## Environment callback tối thiểu
+OpenCode-side callback plugin cần:
+- `OPENCLAW_HOOK_BASE_URL`
+- `OPENCLAW_HOOK_TOKEN`
+
+Optional:
+- `OPENCLAW_BRIDGE_AUDIT_DIR`
+- `OPENCLAW_BRIDGE_OPENCLAW_AUDIT_PATH`
+
+## Mô hình runtime
+### Hybrid execution strategy
+`opencode-bridge` hỗ trợ 2 lane thực dụng:
+- **CLI-direct**: execution nhẹ cho task đơn giản
+- **serve/plugin mode**: đường canonical cho callback, observability và event-driven lifecycle
 
-## Local dev plugin install
+### Multi-project safety
+Contract hiện tại giả định:
+- `1 project = 1 OpenCode serve bind đúng repo`
+- chỉ reuse serve khi runtime introspection xác nhận đúng `repo_root`
+- session tag phải giữ đủ callback identity theo run/session
+
+## Build và verify
 ```bash
-openclaw plugins install -l ~/Work/projects/opencode-bridge
+npm install
+npm run build
+npm test -- --runInBand
 ```
 
-## License
-MIT
+## Cấu trúc artifact
+```text
+openclaw-opencode-bridge/
+├── src/                 # OpenClaw-side runtime
+├── opencode-plugin/     # canonical OpenCode-side plugin source
+├── scripts/             # materialize/install helpers
+├── dist/                # built artifacts
+├── docs/                # install / architecture / contracts
+└── skills/              # bridge-related skills/docs
+```
+
+## Tài liệu liên quan
+- `docs/install/quick-start-2026-03-22.md`
+- `docs/install/production-ish-install-2026-03-22.md`
+- `docs/contracts/multi-project-contract-draft-2026-03-22.md`
+- `docs/architecture/hybrid-execution-strategy-2026-03-22.md`
+
+Ghi chú: local debug/dev notes được tách khỏi README public-facing. Xem:
+- `docs/install/developer-local-debug-2026-03-22.md`
+
+## Trạng thái
+Hiện tại package đã ở mức functional + productized usable, với hardening/test/docs đã đi khá xa.

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

@@ -0,0 +1,5 @@
+declare const OpenClawBridgeCallbackPlugin: ({ client, directory }: any) => Promise<{
+    event: ({ event }: any) => Promise<void>;
+}>;
+
+export { OpenClawBridgeCallbackPlugin, OpenClawBridgeCallbackPlugin as default };

package/dist/opencode-plugin/openclaw-bridge-callback.js

@@ -0,0 +1,179 @@
+// opencode-plugin/openclaw-bridge-callback.ts
+import { appendFileSync, mkdirSync } from "fs";
+import { join } from "path";
+
+// src/shared-contracts.ts
+function parseTaggedSessionTitle(title) {
+  if (!title || !title.trim()) return null;
+  const tags = {};
+  for (const token of title.split(/\s+/)) {
+    const idx = token.indexOf("=");
+    if (idx <= 0) continue;
+    const key = token.slice(0, idx).trim();
+    const raw = token.slice(idx + 1).trim();
+    if (!key || !raw) continue;
+    tags[key] = raw;
+  }
+  return Object.keys(tags).length > 0 ? tags : null;
+}
+function buildPluginCallbackDedupeKey(input) {
+  return `${input.sessionId || "no-session"}|${input.runId || "no-run"}`;
+}
+
+// opencode-plugin/openclaw-bridge-callback.ts
+function asString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function ensureAuditDir(directory) {
+  mkdirSync(directory, { recursive: true });
+  return directory;
+}
+function getAuditPath(directory) {
+  const auditDir = asString(process.env.OPENCLAW_BRIDGE_AUDIT_DIR) || join(directory, ".opencode");
+  ensureAuditDir(auditDir);
+  return join(auditDir, "bridge-callback-audit.jsonl");
+}
+function appendAudit(directory, record) {
+  const path = getAuditPath(directory);
+  appendFileSync(path, JSON.stringify({ ...record, created_at: (/* @__PURE__ */ 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) {
+  const path = getOpenClawAuditPath();
+  if (!path) return;
+  appendFileSync(path, JSON.stringify({ ...record, createdAt: (/* @__PURE__ */ new Date()).toISOString() }) + "\n", "utf8");
+}
+function buildCallbackPayload(tags, eventType) {
+  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, payload, meta) {
+  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: void 0,
+      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: void 0,
+    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 };
+}
+var callbackDedupe = /* @__PURE__ */ new Set();
+var sessionTagCache = /* @__PURE__ */ new Map();
+function readSessionId(event) {
+  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, type) {
+  return type === "session.idle" || type === "session.error";
+}
+var OpenClawBridgeCallbackPlugin = async ({ client, directory }) => {
+  await client.app.log({
+    body: {
+      service: "openclaw-bridge-callback",
+      level: "info",
+      message: "OpenClaw bridge callback plugin initialized",
+      extra: { directory }
+    }
+  });
+  return {
+    event: async ({ event }) => {
+      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
+      });
+    }
+  };
+};
+var openclaw_bridge_callback_default = OpenClawBridgeCallbackPlugin;
+export {
+  OpenClawBridgeCallbackPlugin,
+  openclaw_bridge_callback_default as default
+};