Add Narrative-First V0 to V1 Migration Guide (Alternative to #362)

[jpshackelford]

Summary

This PR provides an alternative approach to the migration guide in #362. The key difference is the narrative-first structure that leads with a step-by-step walkthrough rather than reference tables.

Comparison with PR #362

Aspect	PR #362	This PR
Lead section	Endpoint mapping tables	Step-by-step migration walkthrough
Examples	Isolated operations	Build on each other in a workflow
Agent Server	Explained abstractly	Shown in context (Step 5) with full curl example
Reference tables	Primary content	Secondary, for lookup
Flow	Reader assembles pieces	Guide walks through complete journey

Structure

1. Overview (brief - architecture change + benefits accordion)

2. Migration Walkthrough (THE NARRATIVE)
   Step 1: Create and Start a Conversation
   Step 2: Track Conversation Startup  
   Step 3: Work with Events and Messages
   Step 4: Manage Sandbox Lifecycle
   Step 5: Access the Agent Server
   Step 6: Handle Files and Workspace

3. Quick Reference: Endpoint Mapping (tables for lookup)

4. Agent Server API Reference

5. Known Gaps and Workarounds

6. Authentication Summary

7. Additional Resources

Key Improvements

1. Actionable from the start - Users can follow along and migrate step-by-step
2. Context for each change - "Here's what you did in V0, here's why V1 is different"
3. Complete examples - Each step builds on previous, showing real workflow
4. Agent Server fully demonstrated - Step 5 shows getting sandbox → extracting session key → making calls
5. Reference stays available - Endpoint tables at end for quick lookup

Rationale

Based on feedback that a narrative migration flow is important for users. This approach addresses @enyst's "Typical Migration Flow" suggestion from #12578:

1. Create/Start conversation
2. Track startup (poll or stream)
3. Events/messages operations
4. Sandbox ops
5. Agent-server operations

Related

• Alternative to: Add V0 to V1 API Migration Guide #362
• Closes: V0 to V1 Migration Guide OpenHands#12578

[enyst]

@OpenHands Read this PR description and the linked issue so you understand the PR goal. You are free to investigate OpenHands/OpenHands and if you need, clone yourself that repo and the agent-sdk repo. Note that you need to pay attention, V1 routes are in openhands/app_server and its execution path; V0 routes are in openhands/server and their files are typically starting with a comment that says they're legacy V0. Understand all I said.

Then do a /codereview on this PR. Submit your feedback as a review on the PR with gh api.

[openhands-ai]

I'm on it! enyst can track my progress at all-hands.dev

[enyst]

Thanks for putting together the narrative-first flow — the structure lines up well with the migration journey described in OpenHands/OpenHands#12578. I reviewed this against the current V1 app-server routes under openhands/app_server/*, the legacy V0 routes under openhands/server/*, and the current software-agent-sdk agent-server/workspace APIs.

I found a few correctness issues that would make some of the copy/paste examples fail against the current implementations, so I’m requesting changes before merge.

Behavior / correctness

• Steps 1–3 currently document a few request/response shapes that don’t match the live V1 app-server contract (ids, app_conversation_id, start-task statuses, batch event lookup params).
• stream-start is described as SSE, but the current implementation streams JSON chunks with application/json.
• The sandbox example shows exposed_urls as an object map, but the actual model returns a list of named URL objects.
• The guide currently teaches deprecated agent-server file/git routes and an SDK workspace interface that doesn’t exist in the current software-agent-sdk tree.

I’ve left inline comments with the concrete spots to update.

Today I learned that GPT-5.4 will “request changes” with a simple /codereview prompt. Sorry to mess with a draft PR, I’m happy here with what you see fit either way. Unblocking.