opencode-heartbeat-approval 0.1.0

package/index.ts

@@ -0,0 +1,3 @@
+import { HeartbeatApprovalPlugin } from "./src/plugin";
+export { HeartbeatApprovalPlugin };
+export default HeartbeatApprovalPlugin;

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "opencode-heartbeat-approval",
+  "version": "0.1.0",
+  "description": "OpenCode plugin providing request_human_approval MCP tool for Heartbeat pipeline",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "files": [
+    "dist/",
+    "index.ts",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun build index.ts src/plugin.ts --outdir dist --target bun && mv dist/src/plugin.js dist/plugin.js && rm -rf dist/src",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "heartbeat",
+    "approval",
+    "human-in-the-loop"
+  ],
+  "author": "chuck-ma",
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.2.4"
+  }
+}

package/src/plugin.ts

@@ -0,0 +1,181 @@
+import { tool } from "@opencode-ai/plugin";
+import type { PluginInput } from "@opencode-ai/plugin";
+
+const DEFAULT_RUNNER_URL = "http://127.0.0.1:3210";
+const POLL_INTERVAL_MS = 10_000;
+
+interface CreateResponse {
+  approval_id: string;
+  status: string;
+  created: boolean;
+}
+
+interface PollResponse {
+  approval_id: string | null;
+  status: string;
+  response?: string;
+}
+
+function getRunnerUrl(): string {
+  return process.env.HEARTBEAT_RUNNER_URL ?? DEFAULT_RUNNER_URL;
+}
+
+function buildHeaders(): Record<string, string> {
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  const token = process.env.HEARTBEAT_AUTH_TOKEN;
+  if (token) {
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+  return headers;
+}
+
+interface ConflictResponse {
+  error: string;
+  message: string;
+  existing_approval_id: string;
+}
+
+async function createGate(params: {
+  prompt: string;
+  artifacts?: string[];
+  deadline_hours?: number;
+  phase?: string;
+}): Promise<CreateResponse | ConflictResponse> {
+  const resp = await fetch(`${getRunnerUrl()}/api/approval`, {
+    method: "POST",
+    headers: buildHeaders(),
+    body: JSON.stringify(params),
+  });
+  if (resp.status === 409) {
+    return (await resp.json()) as ConflictResponse;
+  }
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    throw new Error(`Runner API error: ${resp.status} ${text}`);
+  }
+  return (await resp.json()) as CreateResponse;
+}
+
+async function pollGate(): Promise<PollResponse> {
+  const resp = await fetch(`${getRunnerUrl()}/api/approval`, {
+    method: "GET",
+    headers: buildHeaders(),
+  });
+  if (!resp.ok) {
+    const text = await resp.text().catch(() => "");
+    throw new Error(`Runner API error: ${resp.status} ${text}`);
+  }
+  return (await resp.json()) as PollResponse;
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) { resolve(); return; }
+    const id = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => { clearTimeout(id); resolve(); }, { once: true });
+  });
+}
+
+export const HeartbeatApprovalPlugin = async (_input: PluginInput) => {
+  return {
+    tool: {
+      request_human_approval: tool({
+        description: `Request human approval before proceeding with a significant action.
+
+Call this tool when you need explicit human confirmation — for example before publishing content, executing a trade, or making an irreversible change. The tool sends a Feishu interactive card with approve/reject buttons and blocks until the human responds (or the deadline expires).
+
+Only call this when genuinely necessary. Do not use it as a routine step.
+
+Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancelled" | "conflict", response?: string, approval_id: string | null }`,
+        args: {
+          prompt: tool.schema
+            .string()
+            .describe("What you need human approval for — be specific and concise"),
+          artifacts: tool.schema
+            .string()
+            .optional()
+            .describe("Comma-separated list of relevant file paths or artifact names"),
+          deadline_hours: tool.schema
+            .number()
+            .optional()
+            .describe("Hours before the request expires (default: 24, max: 168)"),
+        },
+        async execute(args, ctx) {
+          const artifacts = args.artifacts
+            ? args.artifacts.split(",").map((s: string) => s.trim()).filter(Boolean)
+            : undefined;
+
+          let gateResult: CreateResponse | ConflictResponse;
+          try {
+            gateResult = await createGate({
+              prompt: args.prompt,
+              artifacts,
+              deadline_hours: args.deadline_hours,
+            });
+          } catch (err) {
+            return JSON.stringify({
+              status: "unavailable",
+              error: err instanceof Error ? err.message : String(err),
+              approval_id: null,
+            });
+          }
+
+          if ("error" in gateResult) {
+            return JSON.stringify({
+              status: "conflict",
+              error: gateResult.message,
+              existing_approval_id: gateResult.existing_approval_id,
+              approval_id: null,
+            });
+          }
+
+          const approvalId = gateResult.approval_id;
+
+          while (true) {
+            if (ctx.abort?.aborted) {
+              return JSON.stringify({
+                status: "cancelled",
+                response: null,
+                approval_id: approvalId,
+              });
+            }
+
+            await sleep(POLL_INTERVAL_MS, ctx.abort);
+
+            let poll: PollResponse;
+            try {
+              poll = await pollGate();
+            } catch {
+              await sleep(POLL_INTERVAL_MS, ctx.abort);
+              continue;
+            }
+
+            if (poll.status === "approved") {
+              return JSON.stringify({
+                status: "approved",
+                response: poll.response ?? null,
+                approval_id: approvalId,
+              });
+            }
+
+            if (poll.status === "rejected") {
+              return JSON.stringify({
+                status: "rejected",
+                response: poll.response ?? null,
+                approval_id: approvalId,
+              });
+            }
+
+            if (poll.status === "expired") {
+              return JSON.stringify({
+                status: "expired",
+                response: null,
+                approval_id: approvalId,
+              });
+            }
+          }
+        },
+      }),
+    },
+  };
+};