Files
headquarter/openspec/changes/add-config-profiles/specs/tool-instances/spec.md
T
alex 073013bc61 feat: add heartbeat/ping to terminal WebSocket
- Backend: Send ping every 30s from WebSocket endpoint
- Frontend: Respond to pings with pongs, detect missed pings (60s timeout)
- Update type definitions to include 'resetting' status

Refs: persistent-terminal-sessions task 6.4
2026-05-24 12:45:50 +00:00

2.8 KiB

MODIFIED Requirements

Requirement: Clone mode instance creation

The system SHALL support creating tool instances with a clone mode and an optional selected config profile.

Scenario: Create instance in clone mode

  • GIVEN an authenticated user with a repository that has an SSH key and remote URL
  • WHEN they create an instance with clone_mode: "clone", branch: "main", and a compatible config profile selection
  • THEN the system clones the repository into the instance directory
  • AND the compose file uses the clone path as REPO_PATH
  • AND the instance record stores clone_mode="clone", branch="main", and the selected config profile ID

Scenario: Create instance in mount mode

  • GIVEN an authenticated user with a repository
  • WHEN they create an instance with clone_mode: "mount" (or omit the field)
  • THEN the compose file uses the host repository path as REPO_PATH
  • AND the instance record stores clone_mode="mount"

Scenario: Create instance with no config profile

  • GIVEN an authenticated user creating a tool instance
  • WHEN they select None for config profile
  • THEN the instance record stores no selected config profile
  • AND profile-owned env vars, files, mounts, and runtime hints are not applied at start

Scenario: Reject incompatible config profile selection

  • GIVEN an authenticated user creating a tool instance for a project and tool type
  • WHEN they select a config profile scoped to a different project or tool type
  • THEN instance creation or start is rejected

ADDED Requirements

Requirement: Config profile launch application

The system SHALL apply the selected config profile's resolved output when starting a tool instance.

Scenario: Start instance with selected profile

  • GIVEN a pending tool instance with a selected compatible config profile
  • WHEN the instance is started
  • THEN the system resolves the selected profile
  • AND writes resolved env vars into the instance environment
  • AND stages resolved profile files under the instance directory
  • AND adds Docker bind mounts for resolved profile mounts
  • AND applies supported runtime hints before starting the container

Scenario: Restart uses stored profile selection

  • GIVEN an existing instance was started with config profile A
  • AND the user's default profile later changes to profile B
  • WHEN the instance is restarted
  • THEN the system uses stored profile A for restart behavior
  • AND does not switch to profile B automatically

Scenario: Start fails on profile resolution error

  • GIVEN an instance references a selected config profile that cannot be resolved
  • WHEN the instance is started
  • THEN the start request fails before launching the container
  • AND the error explains the profile resolution problem