opencode-heartbeat-approval 0.1.0 → 0.2.0

package/dist/index.js

@@ -12386,31 +12386,44 @@ 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)")
         },
         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";
           let gateResult;
           try {
             gateResult = await createGate({
               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 +12431,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 +12442,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             if (ctx.abort?.aborted) {
               return JSON.stringify({
                 status: "cancelled",
+                type: requestType,
                 response: null,
                 approval_id: approvalId
               });
@@ -12443,6 +12458,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 +12466,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 +12474,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

@@ -12386,31 +12386,44 @@ 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)")
         },
         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";
           let gateResult;
           try {
             gateResult = await createGate({
               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 +12431,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 +12442,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             if (ctx.abort?.aborted) {
               return JSON.stringify({
                 status: "cancelled",
+                type: requestType,
                 response: null,
                 approval_id: approvalId
               });
@@ -12443,6 +12458,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 +12466,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 +12474,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.0",
+  "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,12 +8,14 @@ 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 {
@@ -40,6 +42,7 @@ async function createGate(params: {
   artifacts?: string[];
   deadline_hours?: number;
   phase?: string;
+  type?: string;
 }): Promise<CreateResponse | ConflictResponse> {
   const resp = await fetch(`${getRunnerUrl()}/api/approval`, {
     method: "POST",
@@ -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()
@@ -104,6 +111,16 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
           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";
 
           let gateResult: CreateResponse | ConflictResponse;
           try {
@@ -111,10 +128,12 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
               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 +142,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 +155,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             if (ctx.abort?.aborted) {
               return JSON.stringify({
                 status: "cancelled",
+                type: requestType,
                 response: null,
                 approval_id: approvalId,
               });
@@ -153,6 +174,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 +183,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 +192,7 @@ Returns: { status: "approved" | "rejected" | "expired" | "unavailable" | "cancel
             if (poll.status === "expired") {
               return JSON.stringify({
                 status: "expired",
+                type: requestType,
                 response: null,
                 approval_id: approvalId,
               });