# Agent System — Backend Gaps Spec

## Status: ✅ Complete (all endpoints implemented 2026-03-26)
## Date: 2026-03-26

---

## 1. Summary

The Agents frontend (`AgentsApp.tsx`) and adapter (`adapter.ts`) call several backend endpoints that either don't exist or have mismatched semantics. This spec documents every gap and proposes the backend work needed.

---

## 2. Frontend ↔ Backend Route Mapping

### 2.1 Personas (Agents) — `/api/personas`

The frontend uses "Personas" as its API namespace for individual agents. The local server (`packages/server/src/local/routes/personas.ts`) implements:

| Frontend call | Backend route | Status |
|---|---|---|
| `GET /api/personas` | ✅ Exists (local) | Works — returns persona catalog |
| `POST /api/personas` | ✅ Exists (local) | Works — creates custom persona on disk |
| `DELETE /api/personas/:id` | ✅ Exists (local) | Works — deletes custom persona |
| `PATCH /api/personas/:id` | ❌ **MISSING** | Frontend calls PATCH to update custom personas |
| `POST /api/personas/generate` | ❌ **MISSING** | Frontend calls this for AI-generated persona creation |

**Note:** The team server (`packages/server/src/routes/agents.ts`) has a separate `agents` CRUD backed by Postgres. These are different entities from local personas. The frontend conflates them — it calls `/api/personas` for both local and team use. This needs reconciliation.

### 2.2 Agent Groups — `/api/agent-groups`

| Frontend call | Backend route | Status |
|---|---|---|
| `GET /api/agent-groups` | ✅ Exists (team server) | Works |
| `POST /api/agent-groups` | ✅ Exists (team server) | Works |
| `GET /api/agent-groups/:id` | ✅ Exists (team server) | Works |
| `POST /api/agent-groups/:id/run` | ✅ Exists (team server) | Works — queues job |
| `PATCH /api/agent-groups/:id` | ❌ **MISSING** | Frontend calls this to update group name/strategy/members |
| `DELETE /api/agent-groups/:id` | ❌ **MISSING** | Frontend calls this to delete a group |

### 2.3 Jobs — `/api/jobs`

| Frontend call | Backend route | Status |
|---|---|---|
| `GET /api/jobs/:id` | ✅ Exists (team server) | Works |
| `POST /api/jobs/:id/cancel` | ❌ **MISSING** | Frontend calls this to cancel running group execution |

---

## 3. Required Backend Work

### 3.1 `PATCH /api/personas/:id` (Local Server)

Update a custom persona's fields (name, description, icon, systemPrompt, tools).

```
PATCH /api/personas/:id
Body: { name?, description?, icon?, systemPrompt?, tools? }
Response: Updated persona object
```

Implementation: Read existing persona JSON from disk, merge fields, write back via `saveCustomPersona()`.

### 3.2 `POST /api/personas/generate` (Local Server)

AI-generate a persona definition from a natural language prompt.

```
POST /api/personas/generate
Body: { prompt: string }
Response: { name, description, systemPrompt, tools: string[] }
```

Implementation: Call LiteLLM with a meta-prompt that produces persona JSON. Do NOT save — just return the generated config for the user to review/edit before saving.

### 3.3 `PATCH /api/agent-groups/:id` (Team Server)

Update an agent group's name, description, strategy, and/or member list.

```
PATCH /api/agent-groups/:id
Body: { name?, description?, strategy?, members?: Array<{ agentId, roleInGroup, executionOrder }> }
Response: Updated group with members
```

Implementation:
1. Verify ownership (userId match)
2. Update `agent_groups` row
3. If `members` provided: DELETE existing `agent_group_members` for this group, INSERT new set
4. Return group + members

### 3.4 `DELETE /api/agent-groups/:id` (Team Server)

```
DELETE /api/agent-groups/:id
Response: 204 No Content
```

Implementation:
1. Verify ownership
2. DELETE `agent_group_members` WHERE groupId = :id
3. DELETE `agent_groups` WHERE id = :id

### 3.5 `POST /api/jobs/:id/cancel` (Team Server)

Cancel a running or queued job.

```
POST /api/jobs/:id/cancel
Response: { cancelled: true, jobId: string }
```

Implementation:
1. Look up job in `agent_jobs`
2. If status is `queued` or `running`: update status to `cancelled`, set `completedAt`
3. If BullMQ job exists: call `job.remove()` or `job.moveToFailed()`
4. Return success

### 3.6 Workspace ↔ Agent Group Assignment

Currently workspaces can have a `persona` (single agent). They should also support an `agentGroupId` so a group of agents can be assigned to handle workspace tasks collaboratively.

**Local workspace manager:** Add optional `agentGroupId` field to workspace config.
**Team server:** Add `agent_group_id` column to relevant workspace/session table if using Postgres workspaces.
**PATCH /api/workspaces/:id:** Accept `agentGroupId` field.
**Chat routing:** When a workspace has `agentGroupId` set, the chat handler should dispatch to the group execution pipeline instead of single-agent loop.

---

## 4. Frontend ↔ Backend Reconciliation: Personas vs Agents

The local server uses file-based "personas" (`~/.waggle/personas/`) while the team server uses Postgres-backed "agents" (`agents` table). The frontend adapter calls `/api/personas` for both.

**Recommendation:** The local server should proxy or merge both sources:
- Built-in + custom personas from disk (local)  
- Team agents from Postgres (team server, if connected)

This way the frontend has a single `/api/personas` endpoint that returns a unified list.

---

## 5. Data Flow: Group on Workspace

```
User selects group in CreateWorkspaceDialog or PersonaSwitcher
  → PATCH /api/workspaces/:id { agentGroupId: "..." }
  → Chat sends message to workspace
  → Backend detects agentGroupId on workspace config
  → Routes to group execution pipeline (parallel/sequential/coordinator)
  → SSE events stream per-member progress back to UI
```

---

## 6. Priority Order

1. **PATCH/DELETE agent-groups** — Needed for existing UI (edit/delete groups)
2. **PATCH personas** — Needed for editing custom agents
3. **POST personas/generate** — Needed for AI agent creation
4. **POST jobs/:id/cancel** — Needed for cancelling group runs
5. **Workspace agentGroupId** — New feature (group assignment to workspaces)