opencode-heartbeat-approval 0.1.0 → 0.2.1

package/dist/index.js

@@ -12333,8 +12333,8 @@ tool.schema = exports_external;
 // src/plugin.ts
 var DEFAULT_RUNNER_URL = "http://127.0.0.1:3210";
 var POLL_INTERVAL_MS = 1e4;
-function getRunnerUrl() {
-  return process.env.HEARTBEAT_RUNNER_URL ?? DEFAULT_RUNNER_URL;
+function getRunnerUrl(override) {
+  return override ?? process.env.HEARTBEAT_RUNNER_URL ?? DEFAULT_RUNNER_URL;
 }
 function buildHeaders() {
   const headers = { "Content-Type": "application/json" };
@@ -12344,8 +12344,8 @@ function buildHeaders() {
   }
   return headers;
 }
-async function createGate(params) {
-  const resp = await fetch(`${getRunnerUrl()}/api/approval`, {
+async function createGate(runnerUrl, params) {
+  const resp = await fetch(`${runnerUrl}/api/approval`, {
     method: "POST",
     headers: buildHeaders(),
     body: JSON.stringify(params)
@@ -12359,8 +12359,8 @@ async function createGate(params) {
   }
   return await resp.json();
 }
-async function pollGate() {
-  const resp = await fetch(`${getRunnerUrl()}/api/approval`, {
+async function pollGate(runnerUrl) {
+  const resp = await fetch(`${runnerUrl}/api/approval`, {
     method: "GET",
     headers: buildHeaders()
   });
@@ -12386,31 +12386,46 @@ function sleep(ms, signal) {
 var HeartbeatApprovalPlugin = async (_input) => {
   return {
     tool: {
-      request_human_approval: tool({
-        description: `Request human approval before proceeding with a significant action.
+      request_human_input: tool({
+        description: `Request human input before proceeding \u2014 either approval (permission to act) or assistance (human help needed).
 
-Call this tool when you need explicit human confirmation \u2014 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).
+Call this tool when you need explicit human confirmation or help. Use type "approval" for actions needing permission (publishing, trading, irreversible changes). Use type "assistance" when you need the human to do something (enter a captcha, provide credentials, perform a physical action).
 
-Only call this when genuinely necessary. Do not use it as a routine step.
+The tool sends a Feishu interactive card and blocks until the human responds (or the deadline expires). Only call this when genuinely necessary.
 
-Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancelled" | "conflict", response?: string, approval_id: string | null }`,
+Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancelled" | "conflict", type: "approval" | "assistance", response?: string, approval_id: string | null }`,
         args: {
-          prompt: tool.schema.string().describe("What you need human approval for \u2014 be specific and concise"),
+          prompt: tool.schema.string().describe("What you need from the human \u2014 be specific and concise"),
+          type: tool.schema.string().optional().describe("Type of request: 'approval' (need permission) or 'assistance' (need human help). Default: 'approval'"),
           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)")
+          deadline_hours: tool.schema.number().optional().describe("Hours before the request expires (default: 24, max: 168)"),
+          runner_url: tool.schema.string().optional().describe("URL of this role's heartbeat runner (e.g., http://127.0.0.1:3211). Required for multi-role setups.")
         },
         async execute(args, ctx) {
           const artifacts = args.artifacts ? args.artifacts.split(",").map((s) => s.trim()).filter(Boolean) : undefined;
+          const validTypes = ["approval", "assistance"];
+          if (args.type !== undefined && !validTypes.includes(args.type)) {
+            return JSON.stringify({
+              status: "error",
+              type: null,
+              error: `Invalid type "${args.type}". Must be "approval" or "assistance".`,
+              approval_id: null
+            });
+          }
+          const requestType = args.type === "assistance" ? "assistance" : "approval";
+          const resolvedUrl = getRunnerUrl(args.runner_url);
           let gateResult;
           try {
-            gateResult = await createGate({
+            gateResult = await createGate(resolvedUrl, {
               prompt: args.prompt,
               artifacts,
-              deadline_hours: args.deadline_hours
+              deadline_hours: args.deadline_hours,
+              type: requestType
             });
           } catch (err) {
             return JSON.stringify({
               status: "unavailable",
+              type: requestType,
               error: err instanceof Error ? err.message : String(err),
               approval_id: null
             });
@@ -12418,6 +12433,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
           if ("error" in gateResult) {
             return JSON.stringify({
               status: "conflict",
+              type: requestType,
               error: gateResult.message,
               existing_approval_id: gateResult.existing_approval_id,
               approval_id: null
@@ -12428,6 +12444,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             if (ctx.abort?.aborted) {
               return JSON.stringify({
                 status: "cancelled",
+                type: requestType,
                 response: null,
                 approval_id: approvalId
               });
@@ -12435,7 +12452,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             await sleep(POLL_INTERVAL_MS, ctx.abort);
             let poll;
             try {
-              poll = await pollGate();
+              poll = await pollGate(resolvedUrl);
             } catch {
               await sleep(POLL_INTERVAL_MS, ctx.abort);
               continue;
@@ -12443,6 +12460,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             if (poll.status === "approved") {
               return JSON.stringify({
                 status: "approved",
+                type: requestType,
                 response: poll.response ?? null,
                 approval_id: approvalId
               });
@@ -12450,6 +12468,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             if (poll.status === "rejected") {
               return JSON.stringify({
                 status: "rejected",
+                type: requestType,
                 response: poll.response ?? null,
                 approval_id: approvalId
               });
@@ -12457,6 +12476,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             if (poll.status === "expired") {
               return JSON.stringify({
                 status: "expired",
+                type: requestType,
                 response: null,
                 approval_id: approvalId
               });

package/dist/plugin.js

@@ -12333,8 +12333,8 @@ tool.schema = exports_external;
 // src/plugin.ts
 var DEFAULT_RUNNER_URL = "http://127.0.0.1:3210";
 var POLL_INTERVAL_MS = 1e4;
-function getRunnerUrl() {
-  return process.env.HEARTBEAT_RUNNER_URL ?? DEFAULT_RUNNER_URL;
+function getRunnerUrl(override) {
+  return override ?? process.env.HEARTBEAT_RUNNER_URL ?? DEFAULT_RUNNER_URL;
 }
 function buildHeaders() {
   const headers = { "Content-Type": "application/json" };
@@ -12344,8 +12344,8 @@ function buildHeaders() {
   }
   return headers;
 }
-async function createGate(params) {
-  const resp = await fetch(`${getRunnerUrl()}/api/approval`, {
+async function createGate(runnerUrl, params) {
+  const resp = await fetch(`${runnerUrl}/api/approval`, {
     method: "POST",
     headers: buildHeaders(),
     body: JSON.stringify(params)
@@ -12359,8 +12359,8 @@ async function createGate(params) {
   }
   return await resp.json();
 }
-async function pollGate() {
-  const resp = await fetch(`${getRunnerUrl()}/api/approval`, {
+async function pollGate(runnerUrl) {
+  const resp = await fetch(`${runnerUrl}/api/approval`, {
     method: "GET",
     headers: buildHeaders()
   });
@@ -12386,31 +12386,46 @@ function sleep(ms, signal) {
 var HeartbeatApprovalPlugin = async (_input) => {
   return {
     tool: {
-      request_human_approval: tool({
-        description: `Request human approval before proceeding with a significant action.
+      request_human_input: tool({
+        description: `Request human input before proceeding \u2014 either approval (permission to act) or assistance (human help needed).
 
-Call this tool when you need explicit human confirmation \u2014 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).
+Call this tool when you need explicit human confirmation or help. Use type "approval" for actions needing permission (publishing, trading, irreversible changes). Use type "assistance" when you need the human to do something (enter a captcha, provide credentials, perform a physical action).
 
-Only call this when genuinely necessary. Do not use it as a routine step.
+The tool sends a Feishu interactive card and blocks until the human responds (or the deadline expires). Only call this when genuinely necessary.
 
-Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancelled" | "conflict", response?: string, approval_id: string | null }`,
+Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancelled" | "conflict", type: "approval" | "assistance", response?: string, approval_id: string | null }`,
         args: {
-          prompt: tool.schema.string().describe("What you need human approval for \u2014 be specific and concise"),
+          prompt: tool.schema.string().describe("What you need from the human \u2014 be specific and concise"),
+          type: tool.schema.string().optional().describe("Type of request: 'approval' (need permission) or 'assistance' (need human help). Default: 'approval'"),
           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)")
+          deadline_hours: tool.schema.number().optional().describe("Hours before the request expires (default: 24, max: 168)"),
+          runner_url: tool.schema.string().optional().describe("URL of this role's heartbeat runner (e.g., http://127.0.0.1:3211). Required for multi-role setups.")
         },
         async execute(args, ctx) {
           const artifacts = args.artifacts ? args.artifacts.split(",").map((s) => s.trim()).filter(Boolean) : undefined;
+          const validTypes = ["approval", "assistance"];
+          if (args.type !== undefined && !validTypes.includes(args.type)) {
+            return JSON.stringify({
+              status: "error",
+              type: null,
+              error: `Invalid type "${args.type}". Must be "approval" or "assistance".`,
+              approval_id: null
+            });
+          }
+          const requestType = args.type === "assistance" ? "assistance" : "approval";
+          const resolvedUrl = getRunnerUrl(args.runner_url);
           let gateResult;
           try {
-            gateResult = await createGate({
+            gateResult = await createGate(resolvedUrl, {
               prompt: args.prompt,
               artifacts,
-              deadline_hours: args.deadline_hours
+              deadline_hours: args.deadline_hours,
+              type: requestType
             });
           } catch (err) {
             return JSON.stringify({
               status: "unavailable",
+              type: requestType,
               error: err instanceof Error ? err.message : String(err),
               approval_id: null
             });
@@ -12418,6 +12433,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
           if ("error" in gateResult) {
             return JSON.stringify({
               status: "conflict",
+              type: requestType,
               error: gateResult.message,
               existing_approval_id: gateResult.existing_approval_id,
               approval_id: null
@@ -12428,6 +12444,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             if (ctx.abort?.aborted) {
               return JSON.stringify({
                 status: "cancelled",
+                type: requestType,
                 response: null,
                 approval_id: approvalId
               });
@@ -12435,7 +12452,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             await sleep(POLL_INTERVAL_MS, ctx.abort);
             let poll;
             try {
-              poll = await pollGate();
+              poll = await pollGate(resolvedUrl);
             } catch {
               await sleep(POLL_INTERVAL_MS, ctx.abort);
               continue;
@@ -12443,6 +12460,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             if (poll.status === "approved") {
               return JSON.stringify({
                 status: "approved",
+                type: requestType,
                 response: poll.response ?? null,
                 approval_id: approvalId
               });
@@ -12450,6 +12468,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             if (poll.status === "rejected") {
               return JSON.stringify({
                 status: "rejected",
+                type: requestType,
                 response: poll.response ?? null,
                 approval_id: approvalId
               });
@@ -12457,6 +12476,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             if (poll.status === "expired") {
               return JSON.stringify({
                 status: "expired",
+                type: requestType,
                 response: null,
                 approval_id: approvalId
               });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-heartbeat-approval",
-  "version": "0.1.0",
-  "description": "OpenCode plugin providing request_human_approval MCP tool for Heartbeat pipeline",
+  "version": "0.2.1",
+  "description": "OpenCode plugin providing request_human_input MCP tool for Heartbeat pipeline (approval + assistance)",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/plugin.ts

@@ -8,16 +8,18 @@ interface CreateResponse {
   approval_id: string;
   status: string;
   created: boolean;
+  type?: string;
 }
 
 interface PollResponse {
   approval_id: string | null;
   status: string;
   response?: string;
+  type?: string;
 }
 
-function getRunnerUrl(): string {
-  return process.env.HEARTBEAT_RUNNER_URL ?? DEFAULT_RUNNER_URL;
+function getRunnerUrl(override?: string): string {
+  return override ?? process.env.HEARTBEAT_RUNNER_URL ?? DEFAULT_RUNNER_URL;
 }
 
 function buildHeaders(): Record<string, string> {
@@ -35,13 +37,14 @@ interface ConflictResponse {
   existing_approval_id: string;
 }
 
-async function createGate(params: {
+async function createGate(runnerUrl: string, params: {
   prompt: string;
   artifacts?: string[];
   deadline_hours?: number;
   phase?: string;
+  type?: string;
 }): Promise<CreateResponse | ConflictResponse> {
-  const resp = await fetch(`${getRunnerUrl()}/api/approval`, {
+  const resp = await fetch(`${runnerUrl}/api/approval`, {
     method: "POST",
     headers: buildHeaders(),
     body: JSON.stringify(params),
@@ -56,8 +59,8 @@ async function createGate(params: {
   return (await resp.json()) as CreateResponse;
 }
 
-async function pollGate(): Promise<PollResponse> {
-  const resp = await fetch(`${getRunnerUrl()}/api/approval`, {
+async function pollGate(runnerUrl: string): Promise<PollResponse> {
+  const resp = await fetch(`${runnerUrl}/api/approval`, {
     method: "GET",
     headers: buildHeaders(),
   });
@@ -79,18 +82,22 @@ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
 export const HeartbeatApprovalPlugin = async (_input: PluginInput) => {
   return {
     tool: {
-      request_human_approval: tool({
-        description: `Request human approval before proceeding with a significant action.
+      request_human_input: tool({
+        description: `Request human input before proceeding — either approval (permission to act) or assistance (human help needed).
 
-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).
+Call this tool when you need explicit human confirmation or help. Use type "approval" for actions needing permission (publishing, trading, irreversible changes). Use type "assistance" when you need the human to do something (enter a captcha, provide credentials, perform a physical action).
 
-Only call this when genuinely necessary. Do not use it as a routine step.
+The tool sends a Feishu interactive card and blocks until the human responds (or the deadline expires). Only call this when genuinely necessary.
 
-Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancelled" | "conflict", response?: string, approval_id: string | null }`,
+Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancelled" | "conflict", type: "approval" | "assistance", response?: string, approval_id: string | null }`,
         args: {
           prompt: tool.schema
             .string()
-            .describe("What you need human approval for — be specific and concise"),
+            .describe("What you need from the human — be specific and concise"),
+          type: tool.schema
+            .string()
+            .optional()
+            .describe("Type of request: 'approval' (need permission) or 'assistance' (need human help). Default: 'approval'"),
           artifacts: tool.schema
             .string()
             .optional()
@@ -99,22 +106,39 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             .number()
             .optional()
             .describe("Hours before the request expires (default: 24, max: 168)"),
+          runner_url: tool.schema
+            .string()
+            .optional()
+            .describe("URL of this role's heartbeat runner (e.g., http://127.0.0.1:3211). Required for multi-role setups."),
         },
         async execute(args, ctx) {
           const artifacts = args.artifacts
             ? args.artifacts.split(",").map((s: string) => s.trim()).filter(Boolean)
             : undefined;
+          const validTypes = ["approval", "assistance"];
+          if (args.type !== undefined && !validTypes.includes(args.type)) {
+            return JSON.stringify({
+              status: "error",
+              type: null,
+              error: `Invalid type "${args.type}". Must be "approval" or "assistance".`,
+              approval_id: null,
+            });
+          }
+          const requestType = (args.type === "assistance" ? "assistance" : "approval") as "approval" | "assistance";
+          const resolvedUrl = getRunnerUrl(args.runner_url);
 
           let gateResult: CreateResponse | ConflictResponse;
           try {
-            gateResult = await createGate({
+            gateResult = await createGate(resolvedUrl, {
               prompt: args.prompt,
               artifacts,
               deadline_hours: args.deadline_hours,
+              type: requestType,
             });
           } catch (err) {
             return JSON.stringify({
               status: "unavailable",
+              type: requestType,
               error: err instanceof Error ? err.message : String(err),
               approval_id: null,
             });
@@ -123,6 +147,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
           if ("error" in gateResult) {
             return JSON.stringify({
               status: "conflict",
+              type: requestType,
               error: gateResult.message,
               existing_approval_id: gateResult.existing_approval_id,
               approval_id: null,
@@ -135,6 +160,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             if (ctx.abort?.aborted) {
               return JSON.stringify({
                 status: "cancelled",
+                type: requestType,
                 response: null,
                 approval_id: approvalId,
               });
@@ -144,7 +170,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
 
             let poll: PollResponse;
             try {
-              poll = await pollGate();
+              poll = await pollGate(resolvedUrl);
             } catch {
               await sleep(POLL_INTERVAL_MS, ctx.abort);
               continue;
@@ -153,6 +179,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             if (poll.status === "approved") {
               return JSON.stringify({
                 status: "approved",
+                type: requestType,
                 response: poll.response ?? null,
                 approval_id: approvalId,
               });
@@ -161,6 +188,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             if (poll.status === "rejected") {
               return JSON.stringify({
                 status: "rejected",
+                type: requestType,
                 response: poll.response ?? null,
                 approval_id: approvalId,
               });
@@ -169,6 +197,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             if (poll.status === "expired") {
               return JSON.stringify({
                 status: "expired",
+                type: requestType,
                 response: null,
                 approval_id: approvalId,
               });