headquarter/openspec/changes/instance-health-monitoring/specs/tool-instances/spec.md at d5f9df33b78e5361d6ebc2db964afae0183c1fc9

Files

T

Fusion d5f9df33b7 feat(frontend): update sessions page for enhanced health monitoring

- Add new status badges: starting, probing, unhealthy
- Show tunnel error only when tunnel_status is unreachable
- Show app error badge with status code for error_response
- Add collapsible probe output section for diagnostics
- Update health polling to check all active instances
- Only show Recreate Tunnel button for unreachable tunnels

2026-05-22 21:26:05 +02:00

2.0 KiB

Raw Blame History

MODIFIED Requirements

Requirement: Status Monitoring

The system SHALL track tool status with startup and health states.

Scenario: Status check with health details

GIVEN a tool instance
WHEN status is queried
THEN the real-time container status is returned:
- pending: Instance created, container not yet started
- starting: Container is running, readiness probe in progress
- running: Container is running and probe passed (or terminal tool)
- unhealthy: Container is running but probe failed/timed out
- stopped: Container was stopped by user
- error: Container failed to start or crashed

ADDED Requirements

Requirement: Health check endpoint enhancement

The system SHALL provide detailed health information through the health check endpoint.

Scenario: Health check with container and tunnel status

GIVEN a running instance
WHEN GET /instances/{id}/health is called
THEN the response includes:
- healthy: boolean - overall health
- container_status: "running", "exited", "restarting", or "not_found"
- tunnel_status: "healthy", "unreachable", "error_response", or "not_applicable"
- tunnel_status_code: HTTP status code or null
- probe_status: "passed", "failed", "pending", or "not_configured"
- last_probe_output: string or null

Requirement: Smart tunnel recreation

The system SHALL only allow tunnel recreation when the tunnel itself is broken.

Scenario: Recreate tunnel for unreachable tunnel

GIVEN an instance with tunnel_status: "unreachable"
WHEN the recreate tunnel endpoint is called
THEN the tunnel is recreated
AND the new URL is returned

Scenario: Block recreation for application errors

GIVEN an instance with tunnel_status: "error_response" (e.g., HTTP 502)
WHEN the recreate tunnel endpoint is called
THEN the request is rejected with 400 Bad Request
AND the error message explains the tunnel is working but the application is returning errors

REMOVED Requirements

None.

2.0 KiB Raw Blame History