Runbook stub human confirm ui

Human Confirmation UI Module

Stub implementation for human-in-the-loop approval system

Overview

The Human Confirm UI provides a deterministic CLI interface for obtaining human approval of critical actions within the Helix Safety Framework.

Code Implementation

# -------------------------------------------------------------
# stub_human_confirm_ui.py
# -------------------------------------------------------------
import json
from datetime import datetime
from typing import Any, Mapping, Optional

# Import the signed-audit logger that Helix already provides
from helix_audit import log_event

from dataclasses import dataclass, field
import uuid

@dataclass(frozen=True)
class HumanConfirmRequest:
    """Deterministic request that will be shown to the user."""
    request_id: str = field(default_factory=lambda: str(uuid.uuid4()))
    action_description: str = ""
    caller_net: str = ""
    requester_user: Optional[str] = None
    timestamp: datetime = field(default_factory=datetime.utcnow)
    payload: Optional[Mapping[str, str]] = None

    @staticmethod
    def make(
        action_description: str,
        caller_net: str,
        requester_user: Optional[str] = None,
        payload: Optional[Mapping[str, str]] = None,
    ) -> "HumanConfirmRequest":
        return HumanConfirmRequest(
            action_description=action_description,
            caller_net=caller_net,
            requester_user=requester_user,
            payload=payload,
        )

def request_confirmation(request: HumanConfirmRequest) -> bool:
    """
    Show a deterministic CLI prompt, capture an explicit "yes",
    and write an immutable, RSA-4096-signed audit entry.
    """
    # ---- UI (kept deterministic, no hidden defaults) -----------------
    print("\n=== Helix Human Confirmation Required ===")
    print(f"Request ID   : {request.request_id}")
    print(f"Timestamp    : {request.timestamp.isoformat()}Z")
    print(f"Caller Net   : {request.caller_net}")
    if request.requester_user:
        print(f"Requested by : {request.requester_user}")
    print(f"Action       : {request.action_description}")

    if request.payload:
        print("Payload:")
        for k, v in request.payload.items():
            print(f"  - {k}: {v}")

    # ---- Get explicit consent -----------------------------------------
    user_input = input("\nConfirm? (y/N): ").strip().lower()
    approved = user_input == "y"

    # Build the audit-log payload
    audit_payload: dict[str, Any] = {
        "request_id": request.request_id,
        "approved": approved,
        "timestamp": request.timestamp.isoformat() + "Z",
        "caller_net": request.caller_net,
        "action_description": request.action_description,
        "requester_user": request.requester_user,
        "payload": request.payload,
    }

    # Write the signed event
    log_event(event_type="human_confirm", data=audit_payload)

    return approved

Usage Example

# Example usage in a Petri net transition
request = HumanConfirmRequest.make(
    action_description="Execute external API: payment processing",
    caller_net="payment_processor_v1",
    requester_user="alice@helix.ai",
    payload={"amount": "150.00", "currency": "USD", "recipient": "vendor123"}
)

if request_confirmation(request):
    # Proceed with the approved action
    execute_payment()
else:
    # Abort or take alternative action
    log_denied_payment()

Audit Event Structure

Human Confirm Audit Payload

Field	Type	Description
request_id	string	Unique identifier for this confirmation request
approved	boolean	Whether the human approved the action
timestamp	string	ISO 8601 timestamp of the request
caller_net	string	Identifier of the requesting net
action_description	string	Human-readable description of the action
requester_user	string	Optional user who initiated the request
payload	object	Additional context-specific data

Integration Points

• Event Type: human_confirm
• Cryptographic Signing: RSA-4096 via log_event helper
• Deterministic Behavior: Consistent output for identical inputs
• Safety Compliance: Enforces human-first principle

Related Components

• Helix Audit Logging
• Petri Net Engine
• Safety Framework