HaltState Java SDK (preview)

Implements the HaltState SDK contract in docs/haltstate/sdk/SDK_CONTRACT.md using Java 17, java.net.http, and Jackson.

Features

• check, guard, report, waitForApproval
• SSE approvals stream via onApproval
• Kill switch heartbeat via startKillSwitch or enableKillSwitch
• Contract error types (ApprovalPending, ActionDenied, ActionExpired, etc.)
• Env fallbacks: HALTSTATE_TENANT_ID, HALTSTATE_API_KEY, HALTSTATE_BASE_URL, HALTSTATE_TIMEOUT, HALTSTATE_FAIL_OPEN
• Retries on 429 and transient 5xx errors

Usage

import ai.haltstate.HaltStateClient;
import ai.haltstate.HaltStateConfig;
import ai.haltstate.exception.ApprovalPending;
import ai.haltstate.model.CheckResult;
import ai.haltstate.GuardContext;

import java.time.Duration;
import java.util.Map;

public class Example {
    public static void main(String[] args) {
        HaltStateConfig config = HaltStateConfig.builder("your-tenant", "hs_...")
            .agentId("payment-worker-01")
            .build();

        try (HaltStateClient client = new HaltStateClient(config)) {
            CheckResult result = client.check("payment.execute", Map.of("amount", 500));
            if (result.isAllowed()) {
                // execute action
                client.report(result, "success", Map.of("processed", true));
            } else if (result.isRequiresApproval()) {
                System.out.println("Approval required: " + result.getApprovalId());
            }

            try (GuardContext guard = client.guard("prune_logs", Map.of("days", 30), "prune-2026-01-12")) {
                // do work
            } catch (ApprovalPending e) {
                System.out.println("Awaiting approval: " + e.getApprovalId());
            }

            client.onApproval(decision -> {
                System.out.println("Approval " + decision.getRequestId() + " -> " + decision.getStatus());
            });

            client.startKillSwitch(Duration.ofSeconds(30), "payment-worker-01");
        }
    }
}

Build

./gradlew build

Verify (optional)

export HALTSTATE_TENANT_ID=your-tenant
export HALTSTATE_API_KEY=hs_...
export HALTSTATE_BASE_URL=https://haltstate.ai/ops
./gradlew runVerify

TODO

• Add async CompletableFuture variants for core methods