Security & Approvals

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ApprovalRequired {
    String reason() default "Sensitive operation";
}

@ActionSpec(type = ActionType.LOCAL, description = "Delete user account permanently")
@ApprovalRequired(reason = "Permanent data deletion")
public void deleteUser(String userId) {
    // Only runs if an approved token is presented
}

ApprovalToken token = ApprovalToken.builder()
    .agentId("agent-1")
    .actionName("delete-user")
    .parameters(Map.of("userId", "123"))
    .timeToLive(Duration.ofMinutes(5))   // default: 5 minutes
    .singleUse(true)                     // default: true
    .requestedBy("system")
    .reason("User requested account deletion")
    .tokenId("custom-id")               // optional, auto-generated UUID if omitted
    .build();

ApprovalToken token = ApprovalToken.create("agent-1", "delete-user", Duration.ofMinutes(5));

// Approve -- only valid (not expired/consumed/rejected) tokens can be approved
boolean ok = token.approve("admin@example.com");

// Reject -- only PENDING, non-expired tokens can be rejected
boolean ok = token.reject("admin@example.com", "Too risky");

// Consume -- marks single-use tokens as CONSUMED after execution
boolean ok = token.consume();

token.isApproved();        // status == APPROVED
token.isPending();         // status == PENDING (auto-checks expiry)
token.isRejected();        // status == REJECTED
token.isExpired();         // Instant.now().isAfter(expiresAt)
token.isConsumed();        // status == CONSUMED
token.isValid();           // !expired && !consumed && !rejected
token.getRemainingTime();  // Duration until expiry (Duration.ZERO if past)
token.matches("agent-1", "delete-user"); // checks agentId + actionName

ApprovalTokenStore store = new InMemoryApprovalTokenStore();

// Create tokens
ApprovalToken token = store.createToken("agent-1", "delete-data", Duration.ofMinutes(5));
ApprovalToken token = store.createToken("agent-1", "delete-data",
    Map.of("userId", "123"), Duration.ofMinutes(5));

// Or save a manually built token
store.save(token);

// Lookup
Optional<ApprovalToken> found = store.getToken(tokenId);

// Approve / Reject via store
store.approve(tokenId, "admin@example.com");
store.reject(tokenId, "admin@example.com", "Not authorized");

// Validate and consume atomically -- checks approved + not expired + agent/action match
boolean valid = store.validateAndConsume(tokenId, "agent-1", "delete-data");

// List pending tokens
List<ApprovalToken> pending = store.listPending();
List<ApprovalToken> agentPending = store.listPendingForAgent("agent-1");

// Cleanup
int cleaned = store.cleanupExpired();
boolean deleted = store.delete(tokenId);
int total = store.count();

// 1. Create and store token
ApprovalTokenStore store = new InMemoryApprovalTokenStore();
ApprovalToken token = store.createToken("agent-1", "delete-user", Duration.ofMinutes(5));

// 2. Send token ID to approval UI (REST endpoint, WebSocket, etc.)
sendToApprovalUI(token.getTokenId(), token.getActionName(), token.getReason());

// 3. Human approves via UI -> callback hits server
store.approve(token.getTokenId(), "admin@example.com");

// 4. Action executor validates before running
boolean canExecute = store.validateAndConsume(
    token.getTokenId(), "agent-1", "delete-user"
);

if (canExecute) {
    executeAction();
}

// Default: no listener, 5-minute timeout
InterruptService service = new InterruptService();

// With listener for AG-UI event emission
InterruptService service = new InterruptService(request -> {
    agUiAdapter.emitInterrupt(request);
});

// With listener and custom default timeout
InterruptService service = new InterruptService(listener, Duration.ofMinutes(10));

public record InterruptRequest(
    String interruptId,
    InterruptReason reason,
    Map<String, Object> payload,
    Duration timeout,
    Instant createdAt
) {}

InterruptResult result = service.requestInterrupt(
    InterruptReason.HUMAN_APPROVAL,
    Map.of("action", "delete_user", "userId", "123")
);
// Thread blocks here until user responds or timeout

if (result.shouldProceed()) {
    deleteUser("123");
} else {
    throw new ActionRejectedException(result.getRejectionReason());
}

InterruptResult result = service.requestInterrupt(
    InterruptReason.HUMAN_APPROVAL,
    Map.of("action", "delete_user", "userId", "123"),
    Duration.ofMinutes(10)
);

CompletableFuture<InterruptResult> future = service.requestInterruptAsync(
    InterruptReason.CONFIRMATION,
    Map.of("summary", orderSummary),
    Duration.ofMinutes(5)
);

future.thenAccept(result -> {
    if (result.isApproved()) {
        submitOrder();
    }
});

// Approve
service.resume(interruptId, true, Map.of("approver", "admin"));

// Reject
service.resume(interruptId, false, Map.of("reason", "Too risky"));

// Cancel programmatically
service.cancel(interruptId);

service.isPending(interruptId);                 // true if active and not expired
Optional<InterruptRequest> req =
    service.getPendingInterrupt(interruptId);    // details or empty
int count = service.getPendingCount();           // auto-cleans expired

InterruptResult.approved(interruptId, Map.of("approver", "admin"));
InterruptResult.rejected(interruptId, Map.of("reason", "Not safe"));
InterruptResult.timedOut(interruptId);
InterruptResult.cancelled(interruptId);
InterruptResult.error(interruptId, "Connection failed");

result.isApproved();         // outcome == APPROVED
result.isRejected();         // outcome == REJECTED
result.isTimedOut();         // outcome == TIMED_OUT
result.isCancelled();        // outcome == CANCELLED
result.isError();            // outcome == ERROR
result.shouldProceed();      // true only if APPROVED

result.getInterruptId();     // the interrupt ID
result.getOutcome();         // Outcome enum value
result.getPayload();         // Map<String, Object>, never null
result.getErrorMessage();    // error message (null unless ERROR)
result.getRejectionReason(); // payload.get("reason") as String, null if not rejected
result.getApprover();        // payload.get("approver") as String

@ActionSpec(type = ActionType.LOCAL, description = "Process user message")
@InputGuardrail(
    maxLength = 10000,
    validators = {NotEmpty.class, NoInjection.class},
    sanitizers = {TrimWhitespace.class, HtmlEscape.class},
    blockPatterns = {"ignore previous", "system prompt"},
    injectionThreshold = 0.8,
    onFailure = FailureAction.REJECT
)
public String processMessage(String message) {
    // message is validated and sanitized before this runs
}

@InputGuardrail(
    maxLength = 5000,
    validators = {NotEmpty.class},
    detectInjection = true
)
public class UserInputRole extends Role {
    // All actions in this role inherit these guardrails
}

@ActionSpec(type = ActionType.LLM_GENERATION, description = "Generate response")
@OutputGuardrail(
    format = OutputFormat.JSON,
    schema = "response-schema.json",
    maxTokens = 1000,
    validators = {NoHallucination.class, NoPII.class},
    maskPII = true,
    piiTypes = {PIIType.EMAIL, PIIType.PHONE, PIIType.SSN},
    onFailure = FailureAction.RETRY,
    maxRetries = 3,
    fallback = "{\"error\": \"Unable to generate response\"}"
)
public String generateResponse(String query) {
    // Response is validated before returning to the caller
}

@OutputGuardrail(
    format = OutputFormat.MARKDOWN,
    maxTokens = 2000,
    checkHallucination = true
)
public class ContentRole extends Role {
    // All actions inherit these output guardrails
}

@ActionSpec(type = ActionType.LOCAL, description = "Delete user account")
@Security(
    approvalRequired = true,
    approvalReason = "Permanent data deletion",
    audit = AuditLevel.DETAILED,
    sensitive = true,
    maskFields = {"password", "ssn"},
    allowedCallers = {"admin-agent"},
    requiredPermissions = {"user:delete"},
    securityTimeout = 30000
)
public void deleteUser(String userId) {
    // Requires approval, full audit trail, 30s security timeout
}

@Security(
    audit = AuditLevel.BASIC,
    allowedCallers = {"admin-agent", "supervisor-agent"},
    sensitive = true,
    encryptParams = true,
    encryptResult = true
)
public class AdminRole extends Role {
    // All actions inherit these security policies
}

@ActionSpec(type = ActionType.WEB_SERVICE, description = "Transfer funds")
@Security(
    approvalRequired = true,
    approvalReason = "Financial transaction",
    audit = AuditLevel.FULL,
    sensitive = true,
    maskFields = {"accountNumber"},
    requiredPermissions = {"finance:transfer"},
    idempotent = false
)
@InputGuardrail(
    validators = {NotEmpty.class},
    detectInjection = true,
    onFailure = FailureAction.REJECT
)
@OutputGuardrail(
    maskPII = true,
    piiTypes = {PIIType.CREDIT_CARD, PIIType.SSN},
    onFailure = FailureAction.REJECT
)
public String transferFunds(String fromAccount, String toAccount, double amount) {
    // Protected by approval, input validation, output masking, and full audit
}