Agent Sessions

public interface AgentSession extends AutoCloseable {
    String getSessionId();
    Path getWorkingDirectory();
    AgentSessionStatus getStatus();

    AgentResponse prompt(String message);
    AgentSession resume();
    AgentSession fork();

    void close();
}

public interface AgentSessionRegistry {
    AgentSession create(Path workingDirectory);
    Optional<AgentSession> find(String sessionId);
    void evict(String sessionId);
    void evictStale(Duration inactiveSince);
}

ACTIVE   → Session is connected and ready for prompts
DEAD     → Transport died; call resume() to resurrect
RESUMED  → Was dead, now active again after resume()

import io.github.markpollack.agents.claude.ClaudeAgentSessionRegistry;
import io.github.markpollack.agents.model.AgentSession;
import io.github.markpollack.agents.model.AgentResponse;

// Build a registry (configure once, create many sessions)
ClaudeAgentSessionRegistry registry = ClaudeAgentSessionRegistry.builder()
    .timeout(Duration.ofMinutes(5))
    .build();

// Create a session — eagerly establishes CLI connection
AgentSession session = registry.create(Path.of("/my/project"));
System.out.println("Session ID: " + session.getSessionId());

// First prompt
AgentResponse r1 = session.prompt("Create a Spring Boot REST controller for /api/users");

// Follow-up — Claude remembers the previous context
AgentResponse r2 = session.prompt("Add input validation with @Valid");

// Another follow-up
AgentResponse r3 = session.prompt("Now write tests for the controller");

// Clean up
session.close();
registry.evict(session.getSessionId());

AgentSession session = registry.create(Path.of("/my/project"));
String savedId = session.getSessionId();

try {
    session.prompt("Refactor the service layer");
} catch (IllegalStateException e) {
    // Transport died — session is now DEAD
    if (session.getStatus() == AgentSessionStatus.DEAD) {
        session.resume();  // Spawns fresh process, restores history
        // Status is now RESUMED — ready for prompts again
        session.prompt("Continue the refactoring");
    }
}

// Later in the application lifecycle
Optional<AgentSession> found = registry.find(savedId);
found.ifPresent(s -> {
    AgentResponse response = s.prompt("What files did you modify?");
    System.out.println(response.getText());
});

                    create()
                       │
                       ▼
                   ┌────────┐
                   │ ACTIVE │◄─────────────┐
                   └───┬────┘              │
                       │                   │
            prompt() works             resume()
            transport dies                 │
                       │                   │
                       ▼                   │
                   ┌────────┐         ┌────────┐
                   │  DEAD  │────────►│RESUMED │
                   └───┬────┘         └────────┘
                       │
                    close() /
                    evict()
                       │
                       ▼
                   [removed]

@Configuration
@EnableScheduling
public class AgentSessionConfig {

    @Bean
    public ClaudeAgentSessionRegistry agentSessionRegistry() {
        return ClaudeAgentSessionRegistry.builder()
            .timeout(Duration.ofMinutes(10))
            .build();
    }
}

@Component
public class SessionCleanup {

    private final ClaudeAgentSessionRegistry registry;

    public SessionCleanup(ClaudeAgentSessionRegistry registry) {
        this.registry = registry;
    }

    @Scheduled(fixedRate = 300_000)  // Every 5 minutes
    public void cleanupStaleSessions() {
        registry.evictStale(Duration.ofMinutes(30));
    }
}

@Component
public class AgentHealthCheck {

    private final ClaudeAgentSessionRegistry registry;

    public AgentHealthCheck(ClaudeAgentSessionRegistry registry) {
        this.registry = registry;
    }

    @EventListener(ApplicationReadyEvent.class)
    public void verifyCliAvailable() {
        try {
            AgentSession probe = registry.create(Path.of("/tmp"));
            probe.close();
            registry.evict(probe.getSessionId());
            // CLI is installed, authenticated, and responsive
        } catch (IllegalStateException e) {
            throw new IllegalStateException("Claude CLI not available: " + e.getMessage(), e);
        }
    }
}