@mrc2204/opencode-bridge 0.1.2 → 0.1.3

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.2",
-  "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));

package/skills/opencode-orchestration/SKILL.md

@@ -280,71 +280,81 @@ Escalate to orchestrator (`scrum`/owner session) when:
 
 ---
 
-## Minimal runtime bridge (v0-min)
+## Execution strategy (current standard)
 
-To avoid ad-hoc `exec opencode ...`, use standard entrypoint:
+Use a **hybrid execution model**:
 
-- `node scripts/opencode-coding-runner.mjs --workstream coding_execution ...`
+- **CLI-direct** for lightweight one-shot execution
+- **serve/plugin mode** for canonical callback, event-driven lifecycle, observability, and multi-project-safe control plane
 
-Bridge rules:
+Rules:
 
-- Accept only `workstream=coding_execution`.
-- Other workstreams are rejected with exit code `2`.
-- Runner must always emit metadata JSON (stdout + `--out` file) with at least:
-  - `invocation.command/rendered`
-  - `opencode.agent/model`
-  - `process.exit_code`
-  - `result.status/error`
-  - `evidence.git_commit`
+- Do not assume `serve` is required for every coding task.
+- Do not assume `CLI-direct` is sufficient when callback/lifecycle tracking matters.
+- Choose the lane deliberately and report which lane was used.
 
-Suggested packet usage:
+### Prefer CLI-direct when
+- the task is lightweight or one-shot
+- no callback or long-lived lifecycle tracking is required
+- no serve/session registry management is needed
 
-- `--packet <path-to-packet.json>` to auto-map `task_id`, `owner_agent`, `objective`.
+### Prefer serve/plugin mode when
+- callback correctness matters
+- event-driven lifecycle handling is required
+- multi-project safety matters
+- observability/session/event introspection is required
+- multiple tasks may reuse the same project-bound runtime
 
 ## OpenCode Bridge usage (current team standard)
 
 Current team workflow after planning is:
 
 1. `using-superpowers`
-2. `brainstorming` (khi cần làm rõ design/spec)
+2. `brainstorming` (when design/spec clarification is needed)
 3. `writing-plans`
 4. `execute`
 5. `verification-before-completion`
 
-Trong bước **execute**, nếu routing đi vào OpenCode lane thì phải ưu tiên dùng **`opencode-bridge`** / bridge contract hiện tại thay vì ad-hoc pattern cũ.
+During **execute**, if routing goes into the OpenCode lane, use the bridge-aware strategy and choose one of these execution lanes explicitly:
+
+### Lane A — CLI-direct
+Use for lightweight tasks where callback/lifecycle tracking is not the main requirement.
+
+Rules:
+- bind the repo explicitly with `--dir <absolute-repo-path>`
+- prefer explicit `--model` if agent resolution is uncertain
+- report clearly that the task used CLI-direct execution
+
+### Lane B — serve/plugin mode (canonical callback lane)
+Use when callback correctness, observability, event-driven lifecycle handling, or multi-project-safe control plane is required.
+
+Rules:
+- bind execution to one project-bound serve instance only
+- keep routing envelope fields explicit
+- treat `/hooks/agent` as the primary callback path
+- use OpenCode-side plugin callback for terminal lifecycle signaling
 
 ### Current implementation status (important)
-Bridge hiện đã chứng minh được các capability cốt lõi:
+The bridge stack has already proven these capabilities:
 - routing envelope build
 - callback payload build
-- callback execution thật về `/hooks/agent`
-- status artifact persistence
-- mini listener runner / SSE probe ở mức PoC
-- runtime assumption: **1 project = 1 OpenCode serve instance**
-
-### How to think about execution now
-- **Do not** assume one shared `opencode serve` is safe for many projects.
-- **Do** bind every coding task to:
-  - `project_id`
-  - `repo_root`
-  - `opencode_server_url`
-  - `task_id`
-  - `run_id`
-  - `agent_id`
-  - `session_key`
-- **Do** treat `/hooks/agent` as callback primary.
-- **Do not** use `cron` or `group:sessions` as the callback mechanism.
+- callback execution to `/hooks/agent`
+- run-status artifact persistence
+- serve binding fail-closed by `repo_root`
+- OpenCode-side plugin callback path with `session.idle` as canonical trigger
+- materialized OpenCode-side plugin artifact and install flow
 
 ### Practical guidance for agents
 When handing off into OpenCode execution:
 - mention the intended repo explicitly
 - ensure the execution packet is file-driven
-- ensure the repo binding uses `--dir <repo>` or an equivalent project-bound path
+- ensure repo binding is explicit (`--dir <repo>` for CLI-direct, project-bound serve for serve/plugin mode)
 - prefer bridge-aware execution over free-form `opencode run` whenever the flow needs:
   - callback
   - task/run tracking
   - serve/session registry
   - multi-agent lane routing
+  - event-driven terminal signaling
 
 ### Mandatory reporting after execution handoff
 Outer agents should report:
@@ -584,25 +594,22 @@ Use when you need to resolve which OpenCode serve should be used for a given:
 #### `opencode_build_envelope`
 Use when you are about to delegate a concrete task into OpenCode lane and need the canonical routing envelope.
 
-#### `opencode_build_callback`
-Use when mapping a known OpenCode event into a callback payload for OpenClaw.
+#### `opencode_execute_task`
+Use as the standard serve/plugin-mode execution entrypoint:
+- resolve/spawn project-bound serve
+- create session
+- send prompt async
+- start watcher path
+- persist run artifact
 
-#### `opencode_execute_callback`
-Use when executing the callback into `/hooks/agent` for a payload that has already been built.
-
-#### `opencode_probe_sse`
-Use when verifying that OpenCode serve is alive and emitting SSE events.
+#### `opencode_run_status`
+Use to inspect run state and event-derived lifecycle summary.
 
-#### `opencode_listen_once`
-Use for a small, single-shot proof that the bridge can:
-- read an event
-- normalize it
-- callback
-- write artifact
+#### `opencode_run_events`
+Use to inspect normalized SSE event output for a run/session.
 
-#### `opencode_listen_loop`
-Use for baseline runtime-ops experiments where repeated event consumption and lifecycle handling are needed.
-Treat it as baseline runtime manager logic, not a production-perfect daemon.
+#### `opencode_session_tail`
+Use to inspect session messages and diff/tail evidence when available.
 
 #### `opencode_run_status`
 Use to inspect the artifact state of a previously handled run.
@@ -642,21 +649,23 @@ Use to mark a serve as stopped and send shutdown for a project serve entry.
 When a task must enter OpenCode execution lane, use this order:
 
 1. Prepare/verify execution packet via the outer workflow (`using-superpowers` → `brainstorming` if needed → `writing-plans`)
-2. Resolve project/server:
-   - `opencode_resolve_project`
+2. Classify execution shape:
+   - CLI-direct
+   - serve/plugin mode
+3. If using **CLI-direct**:
+   - run with explicit `--dir <repo>`
+   - prefer explicit `--model` if needed
+   - report no callback expectation unless a separate tracking path is in place
+4. If using **serve/plugin mode**:
+   - resolve project/server via `opencode_resolve_project`
    - or spawn one via `opencode_serve_spawn`
-3. Build routing envelope:
-   - `opencode_build_envelope`
-4. Verify serve/event path as needed:
-   - `opencode_probe_sse`
-   - `opencode_listen_once`
-5. Build and/or execute callbacks:
-   - `opencode_build_callback`
-   - `opencode_execute_callback`
-   - or `opencode_callback_from_event`
-6. Check run artifact/status:
+   - build routing envelope via `opencode_build_envelope`
+   - keep callback expectation explicit through `/hooks/agent`
+5. For serve/plugin mode, inspect artifacts as needed:
    - `opencode_run_status`
-7. Only then proceed to outer verification:
+   - `opencode_run_events`
+   - `opencode_session_tail`
+6. Only then proceed to outer verification:
    - `verification-before-completion`
 
 ### Reporting requirements
@@ -672,14 +681,15 @@ When handing work into OpenCode lane, the outer agent should report:
 #### Do
 - Do keep OpenCode execution project-bound.
 - Do keep callback/session routing explicit.
+- Do choose execution lane explicitly: CLI-direct vs serve/plugin mode.
 - Do use `opencode-orchestration` when coordination or bridge semantics matter.
 - Do use `verification-before-completion` before claiming completion.
 
 #### Don’t
-- Don’t use ad-hoc `opencode run` when the work needs callback, lifecycle tracking, or registry-aware execution.
+- Don’t use ad-hoc `opencode run` for callback/lifecycle-sensitive work without explicit lane selection.
 - Don’t assume a single serve is multi-project-safe.
 - Don’t assume bridge/runtime-manager features are production-perfect without verification.
-- Don’t over-claim that the bridge is fully autonomous when only PoC/baseline behavior has been verified.
+- Don’t over-claim that the bridge is fully autonomous when only functionally verified/hardened behavior is available.
 
 ## Guardrails
 

package/src/shared-contracts.ts

@@ -0,0 +1,58 @@
+export type BridgeSessionTagFields = {
+  runId: string;
+  taskId: string;
+  requested: string;
+  resolved: string;
+  callbackSession: string;
+  callbackSessionId?: string;
+  projectId?: string;
+  repoRoot?: string;
+};
+
+export 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;
+};
+
+export function buildTaggedSessionTitle(fields: BridgeSessionTagFields): string {
+  return [
+    `${fields.taskId}`,
+    `runId=${fields.runId}`,
+    `taskId=${fields.taskId}`,
+    `requested=${fields.requested}`,
+    `resolved=${fields.resolved}`,
+    `callbackSession=${fields.callbackSession}`,
+    ...(fields.callbackSessionId ? [`callbackSessionId=${fields.callbackSessionId}`] : []),
+    ...(fields.projectId ? [`projectId=${fields.projectId}`] : []),
+    ...(fields.repoRoot ? [`repoRoot=${fields.repoRoot}`] : []),
+  ].join(" ");
+}
+
+export function parseTaggedSessionTitle(title?: string) {
+  if (!title || !title.trim()) return null;
+  const tags: Record<string, string> = {};
+  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;
+}
+
+export function buildPluginCallbackDedupeKey(input: { sessionId?: string; runId?: string }) {
+  return `${input.sessionId || "no-session"}|${input.runId || "no-run"}`;
+}