# AgentScope Agent Route Migration Handoff Plan

## 1) Reconfirmed Objective

- Keep external API paths unchanged under `/api/v1/agent/*`.
- Replace internal run/resume/events runtime path with `core/agentscope` modules.
- Use five modules only: `runtime`, `prompts`, `schemas`, `tools`, `events`.
- Put AG-UI event conversion + persistence + Redis export in `events`.
- Keep `/transcribe` under the same router prefix but independent from agent runtime.
- Continue migration until legacy `core/agent` is removable.

## 2) Current Progress Snapshot

### Completed

- Task 1 (schemas) finished:
  - Added runtime-facing schemas in `core/agentscope/schemas/agent_runtime.py`.
  - Exported aliases for compatibility (`AcceptedTaskResponse`, `TaskAcceptedResponse`, `TaskAccepted`).
- Task 2 (events) finished:
  - Added `events` module with AG-UI conversion, SSE encoding, Redis stream bus, pipeline, and store abstraction.
  - Security fixes applied:
    - Prevent reserved key overwrite in AG-UI codec.
    - Sanitize SSE stream id.
    - Support Redis bytes payload decoding.
  - SSE now reuses AG-UI protocol encoder (`EventEncoder`) instead of custom JSON-only logic.
- Task 3 (runtime adapter) finished:
  - Added `AgentRouteRuntime` to emit internal events around orchestrator execution.
  - Added step events for stage identification:
    - `step.start/step.finish` for `intent`, `execution`, `report`.
  - Error event payload no longer leaks raw exception text to clients.
- Task 4 (route/service wiring) largely finished:
  - `/v1/agent/router.py` now uses `core.agentscope.events.to_sse_event`.
  - `/v1/agent/dependencies.py` queue tasks switched to `core.agentscope.runtime.tasks`.
  - `/v1/agent/dependencies.py` stream reads switched to `RedisStreamBus`.
  - `/v1/agent/service.py` enqueue payload now carries `owner_id` and extracted `user_token`.
  - Added tests for runtime task entrypoint dispatch/validation.

### In Progress / Not Finished

- Task 4 review wrap-up:
  - One review already returned PASS for spec compliance after fixes.
  - Final quality/security confirmation for latest delta should be re-run once before moving to Task 5.
- Task 5 (sessions/messages persistence ownership, cost/tokens/latency full persistence) not started.
- Task 6 (remove `core/agent` and clean imports) not started.
- Task 7 (frontend AG-UI contract and E2E validation) not started.

## 3) What Was Changed (Relevant Files)

### New Files

- `backend/src/core/agentscope/schemas/agent_runtime.py`
- `backend/src/core/agentscope/events/__init__.py`
- `backend/src/core/agentscope/events/agui_codec.py`
- `backend/src/core/agentscope/events/sse.py`
- `backend/src/core/agentscope/events/redis_bus.py`
- `backend/src/core/agentscope/events/store.py`
- `backend/src/core/agentscope/events/pipeline.py`
- `backend/src/core/agentscope/runtime/agent_route_runtime.py`
- `backend/src/core/agentscope/runtime/tasks.py`
- `backend/tests/unit/core/agentscope/schemas/test_agent_runtime_schemas.py`
- `backend/tests/unit/core/agentscope/events/test_agui_codec.py`
- `backend/tests/unit/core/agentscope/events/test_sse.py`
- `backend/tests/unit/core/agentscope/events/test_redis_bus.py`
- `backend/tests/unit/core/agentscope/events/test_pipeline.py`
- `backend/tests/unit/core/agentscope/runtime/test_agent_route_runtime.py`
- `backend/tests/unit/core/agentscope/runtime/test_tasks.py`

### Modified Files

- `backend/src/core/agentscope/runtime/__init__.py`
- `backend/src/core/agentscope/schemas/__init__.py`
- `backend/src/v1/agent/router.py`
- `backend/src/v1/agent/dependencies.py`
- `backend/src/v1/agent/service.py`

## 4) Key References Used

### In-repo references

- Current agent route/service contracts:
  - `backend/src/v1/agent/router.py`
  - `backend/src/v1/agent/service.py`
  - `backend/src/v1/agent/dependencies.py`
  - `backend/src/v1/agent/repository.py`
- Existing runtime/orchestrator basis:
  - `backend/src/core/agentscope/runtime/orchestrator.py`

### External reference project

- DIVA-backend async stream/task patterns (for architecture guidance only):
  - `/home/qzl/Code/DIVA-backend/src/diva/services/app/conversation/task_event_stream_service.py`
  - `/home/qzl/Code/DIVA-backend/src/diva/services/app/conversation/tasks.py`
  - `/home/qzl/Code/DIVA-backend/src/diva/utils/agui_events.py`

### Protocol/framework references

- AG-UI protocol skill docs (event naming/shape guidance)
- AgentScope skill docs (`ReActAgent`, model/runtime usage)

## 5) Next Execution Plan (Continue From Here)

### Step A: Close Task 4 gates (quick)

- Re-run targeted checks for the latest Task 4 code:
  - `uv run pytest tests/unit/v1/agent/test_service.py tests/unit/core/agentscope/runtime/test_tasks.py tests/unit/core/agentscope/runtime/test_agent_route_runtime.py tests/unit/core/agentscope/events -q`
  - `uv run ruff check src/v1/agent src/core/agentscope/runtime src/core/agentscope/events tests/unit/core/agentscope/runtime tests/unit/core/agentscope/events`
  - `uv run basedpyright src/v1/agent src/core/agentscope/runtime src/core/agentscope/events tests/unit/core/agentscope/runtime tests/unit/core/agentscope/events`
- Run one explicit code/security review pass on Task 4 final diff.

### Step B: Execute Task 5 (persistence migration)

- Implement `events.store` real persistence (replace `NullEventStore` path in runtime task assembly):
  - persist sessions/messages from AG-UI wire events.
  - include tokens/cost/latency fields.
  - maintain session aggregates.
- Add unit + integration tests for persistence correctness and aggregation.

### Step C: Execute Task 6 (remove legacy core/agent)

- Move remaining required data structures into `core/agentscope/schemas`.
- Replace all `core.agent.*` imports in active code paths.
- Delete `backend/src/core/agent/**` when no runtime path depends on it.
- Add guard test to ensure no legacy imports remain.

### Step D: Execute Task 7 (frontend contract validation)

- Validate AG-UI event stream compatibility with current Flutter parser and bloc flow.
- Run impacted frontend tests for chat/event handling.

## 6) Risks and Notes

- Workspace is currently dirty with many unrelated app/backend files; avoid mixing commits.
- This handoff only tracks the AgentScope migration subset above.
- `/transcribe` remains in `v1/agent/router.py` and intentionally independent.

## 7) Resume Checklist (first actions next session)

1. Read this handoff file.
2. Re-run Task 4 final checks and review gates.
3. Start Task 5 by replacing `NullEventStore` with real store implementation.
4. Keep route contract stable (`/api/v1/agent/*`) until Task 7 is verified.