microdao-daarion/docs/tasks/TASK_PHASE_AGENT_MANAGEMENT_v1.md

# TASK_PHASE_AGENT_MANAGEMENT_v1

## Title
TASK_PHASE_AGENT_MANAGEMENT_v1 — Agent Create/Delete + Crew Teams Integration

## 1. Overview

Implement full lifecycle management for DAARION agents:

* Create agent
* Delete agent
* Assign to:
  * Node
  * MicroDAO
  * District (city zone)
  * Crew (team)
* Prepare room integration for CrewAI teams (each crew has its own room).

This task **does not** change runtime orchestration logic (NATS, Router, etc.) — only registry & UI.

---

## 2. Current State

* Database:
  * Table `agents` already exists (used by city-service).
  * There is a `sync-node2-dagi-agents.py` script populating 50 agents for NODE2 from `agents_city_mapping.yaml`.

* Backend:
  * `repo_city.get_node_agents(node_id)` returns agents for Node Cabinet.
  * `repo_city.get_agents(...)` provides listing for `/agents` UI.
  * Existing fields:
    * `node_id`
    * `district`
    * `primary_room_slug`
    * `model`
    * `is_public`
    * `home_node_id`
    * `home_microdao_id`
    * `crew_team_key`

* Frontend:
  * `/agents` page lists agents with:
    * status (online/offline)
    * node badge (НОДА1 / НОДА2)
    * visibility badges (Personal / Public)
  * `/agents/[slug]` has Identity tab with visibility toggles.
  * No button to create or delete an agent from UI.

---

## 3. Goals

1. **Create agent** from UI:
   * Minimal form.
   * Pre-fill microDAO/context when creation initiated from MicroDAO.

2. **Delete agent** from UI:
   * Soft-delete (mark as deleted/archived).

3. **Crew / Team attribute**:
   * Each agent may belong to a `crew_team_key`.

4. Prepare for **Crew rooms** integration:
   * For each crew (unique `crew_team_key`) we can later auto-create a room.

---

## 4. Database & Backend Tasks

### 4.1. Verify agents table fields

Existing fields to use:
* `node_id` - which node agent belongs to
* `home_node_id` - home node
* `home_microdao_id` - home MicroDAO
* `district` - city district key
* `crew_team_key` - crew/team key
* `is_archived` - soft delete flag
* `deleted_at` - deletion timestamp

### 4.2. Models & Repo

`services/city-service/models_city.py`:

```python
class CreateAgentRequest(BaseModel):
    slug: str
    display_name: str
    kind: str = "assistant"
    role: Optional[str]
    model: Optional[str]
    node_id: Optional[str]
    home_microdao_id: Optional[str]
    district: Optional[str]
    crew_team_key: Optional[str]
    is_public: bool = False
    avatar_url: Optional[str]
    color_hint: Optional[str]
```

`services/city-service/repo_city.py`:

```python
async def create_agent(data: dict) -> dict:
    """Create new agent in database"""
    pool = await get_pool()
    # INSERT INTO agents ...
    
async def delete_agent(agent_id: str) -> bool:
    """Soft delete agent (set is_archived=true, deleted_at=now())"""
    pool = await get_pool()
    # UPDATE agents SET is_archived = true, deleted_at = NOW() WHERE id = $1
```

### 4.3. API routes

`services/city-service/routes_city.py`:

```python
@router.post("/city/agents")
async def create_agent(body: CreateAgentRequest):
    """Create new agent"""
    # Validate slug uniqueness
    # Insert into database
    # Return created agent

@router.delete("/city/agents/{agent_id}")
async def delete_agent(agent_id: str):
    """Soft delete agent"""
    # Set is_archived = true, deleted_at = now()
    return {"ok": True, "message": "Agent archived"}
```

---

## 5. Frontend Tasks

Files:
* `apps/web/src/app/agents/page.tsx`
* `apps/web/src/app/agents/new/page.tsx` (new)
* `apps/web/src/app/microdao/[slug]/page.tsx`
* `apps/web/src/app/agents/[agentId]/page.tsx`

### 5.1. API client

```ts
// lib/api/agents.ts
export async function createAgent(payload: CreateAgentPayload) {
  return apiClient.post('/city/agents', payload);
}

export async function deleteAgent(id: string) {
  return apiClient.delete(`/city/agents/${id}`);
}
```

### 5.2. "New Agent" page

1. On `/agents` page:
   * Add button `+ Новий агент` in header.
   * Click → navigate to `/agents/new`.

2. New page `/agents/new`:

Form fields:
* Ім'я (`display_name`, required)
* Slug (auto-generated from name, editable)
* Роль / Title (optional)
* Тип агента (`kind`: orchestrator, assistant, specialist, etc.)
* Нода (select: NODE1, NODE2 — fetch from `/nodes`)
* MicroDAO (dropdown, fetch from `/microdao`)
* Район (dropdown: leadership, security, engineering, etc.)
* Команда / Crew (free text or dropdown)
* Модель (optional: list of Swapper models)
* Видимість:
  * `is_public` (switch, default false)
* Аватар URL (optional)
* Колір (optional color picker)

On submit:
* POST `/city/agents`
* Redirect to `/agents/[slug]`.

### 5.3. "Create Agent" from MicroDAO

On `/microdao/[slug]`:

* In "Агенти MicroDAO" section, add button:

```tsx
<Link href={`/agents/new?microdao=${microdaoId}`}>
  <Button>
    <Plus className="w-4 h-4 mr-2" />
    Створити агента
  </Button>
</Link>
```

* On `/agents/new`:
  * If query `?microdao=...` present — pre-fill MicroDAO field.

### 5.4. Delete Agent action

On `/agents/[agentId]`:

* Add "Видалити агента" button in settings/danger section.

Flow:
* Confirm dialog: "Видалити агента? Його не буде видно у місті."
* On confirm → `DELETE /city/agents/{id}`.
* After success: redirect to `/agents` with toast.

---

## 6. Crew Teams (Preparation)

This task prepares data for Crew rooms:

* Each agent can have `crew_team_key`.
* Display `crew_team_key` as badge on agent card.
* Later: auto-create room for each unique `crew_team_key`.

---

## 7. Acceptance Criteria

1. `/agents` page has `+ Новий агент` button.
2. `/agents/new` allows creating a new agent.
3. `/microdao/[slug]` has "Створити агента" button.
4. `/agents/[agentId]` has "Видалити агента" button.
5. Deleted agents disappear from listings.
6. `crew_team_key` is visible on agent cards.