@mrc2204/opencode-bridge 0.1.1 → 0.1.3

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:
@@ -500,6 +510,38 @@ Agents must describe these limits honestly and avoid over-claiming completion.
 
 ### Execution lane assumptions (MANDATORY)
 
+### Current-session callback integrity (MANDATORY)
+
+Bridge-aware execution must preserve caller identity and callback destination explicitly.
+
+Required fields to preserve whenever available:
+- `requested_agent_id`
+- `resolved_agent_id`
+- `origin_session_key`
+- `origin_session_id`
+- `callback_target_session_key`
+- `callback_target_session_id`
+
+Operational rules:
+- Callback must return to the **current caller session**, not an arbitrary latest/execution session.
+- If bridge/runtime cannot resolve the requested execution agent cleanly, it must **fail fast** instead of silently falling back to a default agent.
+- If callback target session information is missing or inconsistent, treat that as a routing integrity error, not a soft warning.
+- Reporting/trace should always expose:
+  - requested agent
+  - resolved execution agent
+  - callback target session key/id
+  - whether fallback was used
+
+### Runtime hygiene after completion (MANDATORY)
+
+When a task or epic is marked `done/closed`, any OpenCode serve/process that was started only for that execution must be shut down immediately unless there is an explicit reason to keep it alive.
+
+Operational rules:
+- Do not leave lingering OpenCode serves after work completes.
+- Treat serve shutdown as part of completion hygiene, not optional cleanup.
+- If a serve remains alive intentionally, the agent must report the reason explicitly.
+
+
 1. **One project = one OpenCode serve instance**
    - Do not assume one shared serve is safe for multiple repos.
    - Always bind execution to a single project/repo root.
@@ -552,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.
@@ -610,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
@@ -640,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"}`;
+}

package/dist/chunk-6NIQKNRA.js

@@ -1,176 +0,0 @@
-// src/observability.ts
-function parseSseFramesFromBuffer(input) {
-  const normalized = input.replace(/\r\n/g, "\n");
-  const parts = normalized.split("\n\n");
-  const remainder = parts.pop() ?? "";
-  const frames = [];
-  for (const rawFrame of parts) {
-    const lines = rawFrame.split("\n");
-    let event;
-    let id;
-    let retry;
-    const dataLines = [];
-    for (const line of lines) {
-      if (!line || line.startsWith(":")) continue;
-      const idx = line.indexOf(":");
-      const field = idx >= 0 ? line.slice(0, idx).trim() : line.trim();
-      const value = idx >= 0 ? line.slice(idx + 1).replace(/^\s/, "") : "";
-      if (field === "event") event = value;
-      else if (field === "id") id = value;
-      else if (field === "retry") {
-        const n = Number(value);
-        if (Number.isFinite(n)) retry = n;
-      } else if (field === "data") dataLines.push(value);
-    }
-    if (dataLines.length <= 0) continue;
-    frames.push({
-      event,
-      id,
-      retry,
-      data: dataLines.join("\n"),
-      raw: rawFrame
-    });
-  }
-  return { frames, remainder };
-}
-function parseSseData(data) {
-  const trimmed = data.trim();
-  if (!trimmed) return null;
-  try {
-    return JSON.parse(trimmed);
-  } catch {
-    return { raw: trimmed };
-  }
-}
-function unwrapGlobalPayload(raw) {
-  let current = raw;
-  const wrappers = [];
-  for (let i = 0; i < 3; i += 1) {
-    if (!current || typeof current !== "object") break;
-    if ("payload" in current && current.payload !== void 0) {
-      wrappers.push("payload");
-      current = current.payload;
-      continue;
-    }
-    if ("data" in current && current.data !== void 0 && Object.keys(current).length <= 4) {
-      wrappers.push("data");
-      current = current.data;
-      continue;
-    }
-    break;
-  }
-  return { payload: current, wrappers };
-}
-function pickFirstString(obj, keys) {
-  if (!obj || typeof obj !== "object") return void 0;
-  for (const key of keys) {
-    const value = obj[key];
-    if (typeof value === "string" && value.trim()) return value.trim();
-  }
-  return void 0;
-}
-function normalizeOpenCodeEvent(raw) {
-  const text = JSON.stringify(raw || {}).toLowerCase();
-  if (text.includes("permission") || text.includes("question.asked")) {
-    return { kind: "permission.requested", summary: "OpenCode \u0111ang ch\u1EDD permission/user input", raw };
-  }
-  if (text.includes("error") || text.includes("failed")) {
-    return { kind: "task.failed", summary: "OpenCode task failed", raw };
-  }
-  if (text.includes("stalled")) {
-    return { kind: "task.stalled", summary: "OpenCode task stalled", raw };
-  }
-  if (text.includes("complete") || text.includes("completed") || text.includes("done")) {
-    return { kind: "task.completed", summary: "OpenCode task completed", raw };
-  }
-  if (text.includes("progress") || text.includes("delta") || text.includes("assistant")) {
-    return { kind: "task.progress", summary: "OpenCode task made progress", raw };
-  }
-  if (text.includes("start") || text.includes("created") || text.includes("connected")) {
-    return { kind: "task.started", summary: "OpenCode task/server started", raw };
-  }
-  return { kind: null, raw };
-}
-function normalizeTypedEventV1(frame, scope) {
-  const parsed = parseSseData(frame.data);
-  const unwrapped = unwrapGlobalPayload(parsed);
-  const normalized = normalizeOpenCodeEvent(unwrapped.payload);
-  return {
-    schema: "opencode.event.v1",
-    scope,
-    eventName: frame.event,
-    eventId: frame.id,
-    kind: normalized.kind,
-    summary: normalized.summary,
-    runId: pickFirstString(unwrapped.payload, ["run_id", "runId"]),
-    taskId: pickFirstString(unwrapped.payload, ["task_id", "taskId"]),
-    sessionId: pickFirstString(unwrapped.payload, ["session_id", "sessionId", "session"]),
-    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
-    wrappers: unwrapped.wrappers,
-    payload: unwrapped.payload
-  };
-}
-function asString(value) {
-  return typeof value === "string" && value.trim() ? value.trim() : void 0;
-}
-function scoreSessionCandidate(candidate, ctx) {
-  const id = asString(candidate?.id) || "";
-  const candidateText = JSON.stringify(candidate || {}).toLowerCase();
-  const runId = ctx.runId?.toLowerCase();
-  const taskId = ctx.taskId?.toLowerCase();
-  const sessionKey = ctx.sessionKey?.toLowerCase();
-  const artifactSessionId = ctx.artifactSessionId;
-  let score = 0;
-  if (artifactSessionId && id === artifactSessionId) score += 1e3;
-  if (runId && candidateText.includes(runId)) score += 120;
-  if (taskId && candidateText.includes(taskId)) score += 70;
-  if (sessionKey && candidateText.includes(sessionKey)) score += 60;
-  if (runId && id.toLowerCase().includes(runId)) score += 30;
-  if (taskId && id.toLowerCase().includes(taskId)) score += 20;
-  score += Math.max(0, 20 - ctx.recencyRank);
-  return score;
-}
-function resolveSessionId(input) {
-  if (input.explicitSessionId) {
-    return { sessionId: input.explicitSessionId, strategy: "explicit", score: 9999 };
-  }
-  const list = Array.isArray(input.sessionList) ? input.sessionList : [];
-  const withRecency = [...list].map((item, idx) => {
-    const updated = Number(item?.time?.updated || 0);
-    return { item, idx, updated };
-  }).sort((a, b) => b.updated - a.updated).map((x, rank) => ({ ...x, rank }));
-  if (input.artifactSessionId) {
-    const direct = withRecency.find((x) => asString(x.item?.id) === input.artifactSessionId);
-    if (direct) {
-      return { sessionId: input.artifactSessionId, strategy: "artifact", score: 1e3 };
-    }
-  }
-  let best = { score: -1 };
-  for (const candidate of withRecency) {
-    const id = asString(candidate.item?.id);
-    if (!id) continue;
-    const score = scoreSessionCandidate(candidate.item, {
-      runId: input.runId,
-      taskId: input.taskId,
-      sessionKey: input.sessionKey,
-      artifactSessionId: input.artifactSessionId,
-      recencyRank: candidate.rank
-    });
-    if (score > best.score) best = { id, score };
-  }
-  if (best.id && best.score > 0) {
-    return { sessionId: best.id, strategy: "scored_fallback", score: best.score };
-  }
-  const latest = withRecency.find((x) => asString(x.item?.id));
-  if (latest) return { sessionId: asString(latest.item?.id), strategy: "latest", score: 0 };
-  return { strategy: "none", score: -1 };
-}
-
-export {
-  parseSseFramesFromBuffer,
-  parseSseData,
-  unwrapGlobalPayload,
-  normalizeOpenCodeEvent,
-  normalizeTypedEventV1,
-  resolveSessionId
-};

package/dist/observability.d.ts

@@ -1,52 +0,0 @@
-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;
-    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;
-};
-declare function normalizeTypedEventV1(frame: SseFrame, scope: EventScope): TypedEventV1;
-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, unwrapGlobalPayload };