+-----------------------------------------------------------------------------------------+
|                  Durable Human-in-the-Loop (HITL) Topology                              |
+-----------------------------------------------------------------------------------------+

[1. AGENT WORKFLOW: LangGraph / Temporal Worker]
  - Step 1: Researches customer account & calculates refund ($450.00).
  - Step 2: Detects high-risk action (Refund > $100 threshold).
  - Step 3: Calls 'interrupt()' -> Saves Graph State to PostgreSQL Checkpointer.
  - Step 4: Worker finishes compute & releases server RAM!
                           |
                           v (Async REST API Call / Webhook)
+-----------------------------------------------------------------+
| 2. SLACK INTERACTIVE NOTIFICATION:                              |
| - Sends formatted Block Kit card to #finance-approvals:         |
|   "Agent requests refund of $450.00 for User 'usr_9842'."       |
| - Contains [Approve ($450)] and [Reject] interactive buttons.   |
+--------------------------------+--------------------------------+
                                 |
                                 v (Finance Manager clicks 'Approve' 4 hours later!)
+-----------------------------------------------------------------+
| 3. BACKEND WEBHOOK RECEIVER:                                    |
| - Verifies Slack HMAC signature & manager RBAC permissions.     |
| - Re-loads LangGraph state from PostgreSQL Checkpointer.        |
| - Emits: 'Command(resume={"approved": true, "reviewer": "Maya"})|
+--------------------------------+--------------------------------+
                                 |
                                 v
[4. AGENT RESUMES EXECUTION: Issues Stripe Refund & Notifies User!]

+-----------------------------------------------------------------------------------------+
|                  LangGraph Native Interrupt & Resume Mechanics                          |
+-----------------------------------------------------------------------------------------+

[Agent Node: 'execute_financial_transfer']
                  |
                  v (Reaches Interrupt Breakpoint)
   interrupt({
     action: "WIRE_TRANSFER",
     amount: 50000,
     recipient: "Vendor Corp"
   })
                  |
                  v
[Graph State saved to DB under Thread ID: 'thread_fin_9842']
[HTTP Server returns: "Status: AWAITING_HUMAN_APPROVAL"]
                  |
                  v (Human Approves on Dashboard or Slack)
[client.threads.resume(thread_id, Command(resume={ approved: true }))]
                  |
                  v
[Graph wakes up: The return value of interrupt() BECOMES { approved: true }!]

# hitl_agent.py
from typing import TypedDict, Annotated
import operator
from langgraph.graph import StateGraph, END
from langgraph.types import interrupt, Command
from langgraph.checkpoint.postgres import PostgresSaver

# 1. Define State Schema
class BillingAgentState(TypedDict):
  user_id: str
  requested_amount: float
  reason: str
  approval_status: str
  transaction_id: str

# 2. Planning Node (Autonomous Analysis)
def analyze_refund_request(state: BillingAgentState):
  print(f"[Agent] Analyzing refund request for User {state['user_id']} of ${state['requested_amount']}...")
  return {"reason": "Customer received defective hardware unit."}

# 3. Human Approval Gate Node (DURABLE INTERRUPT!)
def human_approval_gate(state: BillingAgentState):
  amount = state["requested_amount"]

  # Auto-approve micro-refunds under $50
  if amount <= 50.0:
    return {"approval_status": "AUTO_APPROVED"}

  # DYNAMIC INTERRUPT: Pauses graph and emits payload to external Slack listener!
  human_decision = interrupt({
      "task": "REFUND_APPROVAL_REQUIRED",
      "user_id": state["user_id"],
      "amount": amount,
      "reason": state["reason"]
  })

  # When resumed via Command(resume=...), human_decision contains the external payload!
  if human_decision.get("approved") is True:
    return {"approval_status": "APPROVED"}
  else:
    return {"approval_status": "REJECTED"}

# 4. Execution Node (Executes only if approved!)
def execute_stripe_refund(state: BillingAgentState):
  if state["approval_status"] in ["APPROVED", "AUTO_APPROVED"]:
    print(f"[Agent] Executing Stripe refund of ${state['requested_amount']}...")
    return {"transaction_id": "tx_stripe_9842019"}
  else:
    print("[Agent] Refund was REJECTED by human reviewer. Aborting.")
    return {"transaction_id": "REJECTED"}

# 5. Build Graph
builder = StateGraph(BillingAgentState)
builder.add_node("analyze", analyze_refund_request)
builder.add_node("approval_gate", human_approval_gate)
builder.add_node("execute", execute_stripe_refund)

builder.set_entry_point("analyze")
builder.add_edge("analyze", "approval_gate")
builder.add_edge("approval_gate", "execute")
builder.add_edge("execute", END)

# Compile with PostgreSQL Checkpoint Persistence
# (Requires running Postgres instance)
# checkpointer = PostgresSaver.from_conn_string("postgresql://user:pass@localhost:5432/agent_db")
# app = builder.compile(checkpointer=checkpointer)

// server/slackApprovalWebhook.ts
import express from "express";
import crypto from "crypto";

const app = express();
app.use(express.urlencoded({ extended: true }));

// 1. Verify Slack HMAC Signature (Zero-Trust Security)
function verifySlackSignature(req: express.Request): boolean {
  const signature = req.headers["x-slack-signature"] as string;
  const timestamp = req.headers["x-slack-request-timestamp"] as string;
  const sigBasestring = `v0:`{timestamp}:`{req.rawBody}`;

  const hmac = crypto
    .createHmac("sha256", process.env.SLACK_SIGNING_SECRET!)
    .update(sigBasestring)
    .digest("hex");

  return `v0=${hmac}` === signature;
}

// 2. Handle Interactive Button Clicks from Slack
app.post("/api/slack/interactions", async (req, res) => {
  const payload = JSON.parse(req.body.payload);
  const action = payload.actions[0];
  const threadId = payload.callback_id; // Contains LangGraph thread ID!
  const user = payload.user.name;

  const isApproved = action.value === "approve";

  console.log(`[Slack] Reviewer `{user} clicked `{isApproved ? "APPROVE" : "REJECT"} for Thread: ${threadId}`);

  // 3. Resume LangGraph Workflow via Command API!
  // Send resume signal to LangGraph Server:
  /*
  await langgraphClient.threads.resume(threadId, {
    command: {
      resume: { approved: isApproved, reviewer: user, timestamp: Date.now() }
    }
  });
  */

  // 4. Update Slack Message in-place (Disables buttons to prevent double-clicking!)
  res.status(200).json({
    replace_original: true,
    text: `*Status:* Refund of $450.00 was *${isApproved ? "APPROVED" : "REJECTED"}* by @`{user} at `{new Date().toLocaleTimeString()}.`,
  });
});

+-----------------------------------------------------------------------------------------+
|                  HITL vs HOTL Governance Model                                          |
+-----------------------------------------------------------------------------------------+

HUMAN-IN-THE-LOOP (HITL - High Friction, 100% Safety)
- Execution completely halts until a human explicitly reviews and clicks Approve.
- Best for: High-value financial transactions (> $1,000), medical diagnoses, legal filings.

HUMAN-ON-THE-LOOP (HOTL - Low Friction, High Velocity)
- Agent executes 95% of routine actions autonomously.
- Surfaces an asynchronous audit log with an "Undo within 15 minutes" safety buffer.
- Alerts humans ONLY on statistical anomalies or high-uncertainty model confidence scores.
- Best for: Customer support responses, code refactoring, infrastructure scaling.