headquarter/openspec/changes/archive/2026-05-22-instance-health-monitoring/specs/tool-instances/spec.md at 38d116dcf746be1608246bed94de45cef8d1c4d5

Files

T

Fusion 063a839790 feat: implement repository clone mode with SSH key support

- Add clone_mode and branch fields to tool_instances
- Add ssh_key_id to git_repositories for per-repo SSH key assignment
- Implement host-side git cloning with branch selection (default: main)
- Mount SSH keys into containers for git operations in clone mode
- Add dirty state check on clone-mode instance deletion with confirmation
- Update SessionsPage with mount/clone selector, branch input, SSH key display
- Add SSH key selector to repository creation form
- Add dirty delete confirmation modal with changed files list
- Update API schemas and endpoints for new fields
- Sync delta specs to main specs (git-repo, tool-instances, repo-clone-mode)
- Archive completed OpenSpec change: repo-clone-mode-with-ssh
- Document git requirement for custom tool types

Quality gates: Frontend typecheck and build passed
OpenSpec: repo-clone-mode-with-ssh archived with all tasks complete

2026-05-22 22:56:35 +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