feat: add Sprites integration with exec API improvements

[bborn]

Summary

Implement PR #103 feedback to use the Sprites exec API directly instead of tmux-based execution. This supersedes PR #103 with the improvements suggested in the review comments.

Key Improvements from PR #103 Review

1. Native exec sessions instead of tmux (PR comment #1)

   • Sessions persist after client disconnect
   • cmd.Wait() blocks until completion (no 2-second polling)
   • No tmux dependency needed on sprite
   • Removed apt-get install tmux from setup

2. Direct stdout streaming (PR comment #3)

   • Stream Claude's output to task logs in real-time
   • Parse output for status changes
   • No file-tailing hooks needed

3. Filesystem API for setup (PR comment #4)

   • Use sprite.Filesystem().WriteFile() and MkdirAll()
   • No shell escaping or heredocs required
   • Cleaner, more reliable file operations

4. Port notifications (PR comment #6)

   • Handle PortNotificationMessage for dev servers
   • Automatically log proxy URLs when Claude starts servers
   • Useful for web dev tasks

5. Crash recovery foundation (PR comment #2)

   • Track active tasks for graceful shutdown
   • Idle watcher for automatic checkpointing
   • Session recovery can be added when SDK supports it

6. Network policy documentation (PR comment #5)

   • Added recommended allowed domains list
   • Note: SDK policy API not yet available, documented workaround

New Files

• cmd/task/sprite.go - CLI commands for sprite management
• internal/sprites/sprites.go - Shared token/client logic
• internal/executor/executor_sprite.go - SpriteRunner with exec API
• docs/sprites-design.md - Architecture documentation
• docs/sprites-discussion.md - Design discussion

Usage

# Set token (once)
export SPRITES_TOKEN=<your-token>
# or: task sprite token <your-token>

# Run task normally - Claude now executes on sprite
task

# Manual sprite management
task sprite status   # Show sprite status
task sprite up       # Start/restore sprite
task sprite down     # Checkpoint and suspend
task sprite attach   # Interactive shell on sprite
task sprite sessions # List active exec sessions
task sprite destroy  # Delete sprite

Test plan

• Build succeeds
• All tests pass
• Set SPRITES_TOKEN and verify Claude runs on sprite
• Verify logs stream to task in real-time
• Test task sprite subcommands
• Verify local execution still works without token

Related

Supersedes #103 - Implements the exec API improvements suggested in the PR review comments.

🤖 Generated with Claude Code

[openhands-ai]

Looks like there are a few issues preventing this PR from being merged!

• GitHub Actions are failing:
  • CI

If you'd like me to help, just leave a comment, like

@OpenHands please fix the failing actions on PR #287 at branch `task/193-use-flyio-sprites-for-task-claude-execut`

Feel free to include any additional details that might help me get this PR into a better state.

_{^{You can manage your notification settings}}