# Version Routing Manual Test Guide

This guide walks through testing version routing features including task stickiness, manual migration, and bulk migration.

## Prerequisites

- An agent that includes `TERMINALUSE_VERSION_ID` in responses (modify your agent's instructions to always output `[VERSION: {os.environ.get("TERMINALUSE_VERSION_ID")}]`)
- CLI authenticated (`tu login`)
- Agent deployed to `test` namespace

## Test Setup

Ensure your agent's instructions include something like:
```
You MUST start EVERY response with: [VERSION: {VERSION_ID}]
```

Where `VERSION_ID = os.environ.get("TERMINALUSE_VERSION_ID", "local")` is set at module load time.

---

## Test 1: Initial Deploy

```bash
# Deploy the agent
tu deploy

# Note the version ID from output
# Example: Version ID: ver_abc123
```

**Expected:** Deployment succeeds, version ID displayed.

---

## Test 2: Multi-Turn Conversation with File Operations

This test verifies that tasks maintain context across multiple turns and can interact with the filesystem.

```bash
# Create a project (if not already created)
tu projects create --namespace test --name "conversation-test"

# Create a new task - Turn 1: Ask agent to create a file
tu tasks create --project-id <project_id> -m "Create a file called hello.txt with the content 'Hello from version routing test'"

# Note the task ID
```

**Expected:** Agent creates the file and confirms.

```bash
# Turn 2: Ask what we requested
tu tasks send <task_id> -m "What did I ask you to do in the previous message?"
```

**Expected:** Agent recalls that you asked it to create a file called `hello.txt` with specific content.

```bash
# Turn 3: Ask about file contents
tu tasks send <task_id> -m "What are the contents of the file you created?"
```

**Expected:** Agent reads the file and reports the contents: `Hello from version routing test`.

This test validates:
- Task context persistence across turns
- Agent can write files to the workspace
- Agent can read files from the workspace
- Agent maintains conversation history

---

## Test 3: Create Task and Verify Version

```bash
# Create a task and send a message
tu tasks create -m "What version are you?"

# Note the task ID and version in response
# Example: task_xyz789, [VERSION: ver_abc123]
```

**Expected:** Response contains `[VERSION: ver_abc123]` (the v1 version ID).

---

## Test 4: Deploy v2 with Sticky Tasks

Edit `config.yaml`:
```yaml
deployment:
  preview:
    areTasksSticky: true  # Tasks stay on old version
```

```bash
# Deploy new version
tu deploy

# Note the NEW version ID
# Example: Version ID: ver_def456
```

**Expected:** New version deployed (v2).

---

## Test 5: Verify Sticky Task Stays on Old Version

```bash
# Send message to the EXISTING task from Test 3
tu tasks send <task_id_from_test3> -m "What version are you?"
```

**Expected:** Response still shows `[VERSION: ver_abc123]` (v1), NOT the new v2. This proves sticky tasks stay on their original version.

---

## Test 6: New Task Uses New Version

```bash
# Create a NEW task
tu tasks create -m "What version are you?"

# Note task ID (task B)
```

**Expected:** Response shows `[VERSION: ver_def456]` (v2). New tasks go to the latest version.

---

## Test 7: Migrate Specific Task with --ids

```bash
# Migrate the old task (from Test 3) to latest
tu tasks migrate --ids <task_id_from_test3> --to latest
```

**Expected:** Table showing migrated task with status.

---

## Test 8: Verify Migrated Task Now on New Version

```bash
# Send message to the migrated task
tu tasks send <task_id_from_test3> -m "What version are you?"
```

**Expected:** Response now shows `[VERSION: ver_def456]` (v2). Migration worked!

---

## Test 9: Deploy v3 and Test Bulk Migration with --from

```bash
# Deploy v3 (keep sticky: true)
tu deploy

# Note version ID (v3): ver_ghi789
```

Now both tasks are on v2. Let's migrate them all at once:

```bash
# Bulk migrate ALL tasks from v2 to v3
tu tasks migrate --from <v2_version_id> --to <v3_version_id>

# Or migrate to latest:
tu tasks migrate --from <v2_version_id> --to latest
```

**Expected:** Table showing all migrated tasks.

---

## Test 10: Verify Bulk Migration

```bash
# Check both tasks
tu tasks send <task_id_from_test3> -m "version?"
tu tasks send <task_id_from_test6> -m "version?"
```

**Expected:** Both responses show `[VERSION: ver_ghi789]` (v3).

---

## Test 11: Non-Sticky Auto-Migration

Edit `config.yaml`:
```yaml
deployment:
  preview:
    areTasksSticky: false  # Tasks auto-migrate
```

```bash
# Deploy v4
tu deploy

# Note version ID (v4): ver_jkl012
```

**Expected:** All running tasks automatically migrate to v4 (no manual migration needed).

```bash
# Verify auto-migration
tu tasks send <any_task_id> -m "version?"
```

**Expected:** Response shows `[VERSION: ver_jkl012]` (v4) without any manual migration.

---

## Summary of Commands

| Command | Purpose |
|---------|---------|
| `tu deploy` | Deploy new version |
| `tu tasks create -m "msg"` | Create task and send message |
| `tu tasks send <id> -m "msg"` | Send message to existing task |
| `tu tasks migrate --ids <id1,id2> --to <ver>` | Migrate specific tasks |
| `tu tasks migrate --from <ver> --to <ver>` | Bulk migrate all tasks from version |
| `tu tasks migrate --from <ver> --to latest` | Bulk migrate to active version |
| `tu versions list -a test/<agent>` | List all versions |

---

## Troubleshooting

**Task not showing version?**
- Ensure agent instructions include the VERSION output
- VERSION_ID is set at module load time, not request time

**Migration failed?**
- Check that source version exists: `tu versions list`
- Ensure tasks are RUNNING (can't migrate completed tasks)
- `--from` and `--ids` are mutually exclusive

**Sticky not working?**
- Verify `areTasksSticky: true` in config.yaml under the correct environment (preview/production)
- Redeploy after changing config
