community-ade/START_HERE.md

# Community ADE — Start Here

**What:** Self-hosted Letta Agent Development Environment — a web dashboard + orchestration platform for stateful agents.

**Where:** `/home/ani/Projects/community-ade/community-ade-wt/mvp-unified/`

**Letta Server:** `http://localhost:8283` (v0.16.6, Docker container `aster-0.16.6-patched`)

**Orchestrator:** Ani (Annie Tunturi) — project owner, architect, and final decision-maker on all implementation direction.

---

## How This Project Got Here

Ani directed the research phase, established the competitive analysis, designed the orchestration architecture, and then took direct control of the implementation. She consolidated the project into a single unified codebase (`mvp-unified/`), enforced SDK-first architecture across all components, and drove the build sequence from backend services through to a functional dashboard with full agent creation, configuration editing, streaming chat, and task orchestration.

The research docs in `docs/` represent foundational work — competitive analysis, queue architecture, memory curation design, approval system architecture. The archive (`community-ade-wt/_archive/`) contains prior model-specific implementations that validated the architecture before Ani unified them. The implementation in `mvp-unified/` is the production codebase.

---

## Read These First

1. **This file** — project orientation, architecture, SDK rules
2. **`docs/FUTURE_PHASES.md`** — roadmap for approval system, memory curation, integrations
3. **`docs/ade-research.md`** — competitive analysis (Letta vs Intent vs Warp)
4. **`docs/ade-phase1-orchestration-design.md`** — task queue architecture
5. **`docs/community-ade-research-synthesis-2026-03-18.md`** — technical patterns + gap analysis

---

## Architecture

```
Browser (React Dashboard :4422)
    │ REACT_APP_API_URL → backend
    │
Express Backend (:4421)
    ├── @letta-ai/letta-client ──→ Letta Server :8283 (REST: agents, memory, tools, models)
    ├── @letta-ai/letta-code-sdk ──→ letta-code CLI ──→ Letta Server (sessions, streaming, chat)
    └── ioredis ──→ Redis (:4420) — task queue, worker state
```

**Current deployment: host-only** (no Docker for app/dashboard — SDK sessions require `letta-code` CLI on the host).
Redis runs in a standalone Docker container (`ade-redis`).

---

## SDK Rule (MANDATORY — READ THIS BEFORE WRITING ANY CODE)

**Every feature MUST use one of these two packages. There are no exceptions.**

### `@letta-ai/letta-client` (v1.7.12) — REST Operations
- **Use for:** Listing/creating/deleting agents, reading memory blocks, CRUD operations, model listing, tool listing, health checks, agent config updates
- **Source:** `/home/ani/Projects/letta-code/node_modules/@letta-ai/letta-client/`
- **API docs:** `http://localhost:8283/docs` (Swagger UI on running Letta server)
- **Key patterns:**
  - Client init: `new Letta({ baseURL, apiKey, timeout })`
  - Pagination: all `.list()` calls return page objects — access `.items` for the array
  - Health: `client.health()` (top-level method, NOT `.health.check()`)
  - Blocks: `client.agents.blocks.list(agentId)` (NOT `.coreMemory.blocks`)
  - Agent create: `client.agents.create({ name, model, system, tool_ids, include_base_tools })`
  - Agent update: `client.agents.update(agentId, params)` — accepts any field from `AgentUpdateParams`
  - Tools (global): `client.tools.list()` — all tools on the server
  - Tools (per-agent): `client.agents.tools.list(agentId)` — tools attached to an agent
- **Type declarations:** Read `node_modules/@letta-ai/letta-client/api/types.d.ts` when unsure about method signatures

### `@letta-ai/letta-code-sdk` (v0.1.12) — Interactive Sessions
- **Use for:** Chat sessions, streaming responses, tool execution, bootstrapping conversation state
- **Source:** `/home/ani/Projects/letta-code-sdk/`
- **Key exports:** `createSession`, `resumeSession`, `prompt`, `Session`
- **Key types:** `SDKMessage`, `SDKAssistantMessage`, `SDKReasoningMessage`, `SDKToolCallMessage`, `SDKToolResultMessage`, `SDKResultMessage`
- **Streaming:** `session.stream()` yields typed `SDKMessage` objects — render each type differently in the UI
- **ESM-only:** Must use dynamic `import()` from CJS project — see `services/sessions.ts` for the pattern

### What This Means In Practice

- **Need to list agents?** → `letta-client` → `client.agents.list()`
- **Need to create an agent?** → `letta-client` → `client.agents.create()`
- **Need to edit agent memory?** → `letta-client` → `client.agents.blocks.update()`
- **Need to list available tools?** → `letta-client` → `client.tools.list()`
- **Need to chat with an agent?** → `letta-code-sdk` → `createSession()` + `session.send()`
- **Need real-time streaming?** → `letta-code-sdk` → `session.stream()`
- **Need to run a background task?** → `letta-code-sdk` → worker spawns session, calls `session.runTurn()`

**No standalone implementations. No mock data. No in-memory stores pretending to be agents. No per-model silos. No hand-rolled HTTP calls to Letta endpoints when the SDK already wraps them.**

---

## How to Enforce SDK Compliance in Future Phases

When directing other LLMs (Kimi, GLM, or future Claude sessions) to implement new phases, follow this protocol:

### 1. Always Start With the SDK Source
Before writing any service code, the implementer must read the actual SDK type declarations:
```bash
# For REST operations — check what methods exist
cat node_modules/@letta-ai/letta-client/api/types.d.ts | head -200

# For session operations — check SDK exports
ls /home/ani/Projects/letta-code-sdk/src/
cat /home/ani/Projects/letta-code-sdk/src/index.ts
```

### 2. Include This Checklist in Every Phase Prompt
```
Before writing code, answer these for each feature:
- [ ] Which SDK package handles this? (letta-client or letta-code-sdk)
- [ ] What is the exact method signature? (read the .d.ts, don't guess)
- [ ] What does the return type look like? (page object with .items? raw array? single object?)
- [ ] Does this need pagination handling?
- [ ] Am I duplicating something the SDK already does?
```

### 3. Known SDK Gotchas

| What you'd expect | What actually works |
|---|---|
| `client.health.check()` | `client.health()` — top-level method |
| `client.agents.list()` returns `Agent[]` | Returns `AgentStatesArrayPage` — use `.items` |
| `client.agents.coreMemory.blocks.list()` | `client.agents.blocks.list(agentId)` |
| `agent.tool_ids` | `agent.tools` — array of tool objects |
| Block update with nested params | `client.agents.blocks.update(blockLabel, { agent_id, value })` |
| `import { createSession }` in CJS | Must use `const sdk = await import('@letta-ai/letta-code-sdk')` |

### 4. Verification Gate
Every phase must be verifiable against the running Letta server before moving on:
```bash
curl http://localhost:8283/v1/health          # Letta healthy
curl http://localhost:4421/api/agents         # Real agents from Letta
curl http://localhost:4421/api/agents/tools   # Available tools from Letta
```

---

## Build Status

### Phase 1 — Core Platform (COMPLETE)

| Step | What | Status |
|------|------|--------|
| 1 | Project restructure + deps | DONE |
| 2 | Letta REST client service | DONE |
| 3 | SDK session service (ESM interop) | DONE |
| 4 | Express routes (agents, server, chat SSE) | DONE |
| 5 | Task queue + worker pool (Redis Streams) | DONE |
| 6 | Docker configuration | PARTIAL — host-only for now |
| 7 | Dashboard shell + settings | DONE |
| 8 | Agent list + detail + config editor | DONE |
| 9 | Task queue UI | DONE |
| 10 | Chat panel (SSE streaming) | DONE |
| 11 | Models view | DONE |

### Phase 1.5 — Agent Management (COMPLETE)

| Feature | What | Status |
|---------|------|--------|
| Agent creation wizard | 5-step wizard (info → model → tools → system prompt → review) | DONE |
| Agent create API | `POST /api/agents` via `client.agents.create()` | DONE |
| Tool listing API | `GET /api/agents/tools` via `client.tools.list()` | DONE |
| Agent deletion | `DELETE /api/agents/:id` + confirmation UI | DONE |
| Cross-tab navigation | "Chat with Agent" from detail → Chat tab | DONE |

### Verification Pipeline (REPAIRED)

A multi-layer verification system at `src/verification/` with:
- Static checks (schema validation via Zod v4, linting, type checking)
- Dynamic test execution (Jest, Mocha, Vitest, Pytest, Go)
- Human review queue with approval/rejection + webhooks
- Subagent delegation via letta-code-sdk (iterative refinement)
- Config builder with fluent API + presets (minimal, standardTypeScript, fullCI, quick)

**Status:** Fully compiles. Types rewritten to match executor design. Zod v4 added as dependency. Included in build (`tsconfig.json`). Ready for integration with task queue worker pipeline.

### Future Phases
See **`docs/FUTURE_PHASES.md`** for the full roadmap.

---

## Key Files

```
mvp-unified/
├── src/
│   ├── server.ts              # Express entry point
│   ├── types.ts               # ADE domain types
│   ├── services/
│   │   ├── letta.ts           # @letta-ai/letta-client wrapper
│   │   ├── sessions.ts        # @letta-ai/letta-code-sdk wrapper (ESM dynamic import)
│   │   ├── queue.ts           # Redis Streams task queue
│   │   └── worker.ts          # Worker pool for background agent tasks
│   ├── verification/          # Multi-layer verification pipeline (needs repair)
│   │   ├── checks/            # SchemaValidator, LinterRunner, TypeChecker
│   │   ├── executors/         # TestExecutor, SubagentDispatcher, VerificationOrchestrator
│   │   ├── review/            # HumanReviewQueue
│   │   └── utils/             # auditLogger, configBuilder, helpers
│   └── routes/
│       ├── agents.ts          # Agent CRUD + memory + tools + create + delete
│       ├── server.ts          # Health, models, reconnect
│       ├── chat.ts            # SDK sessions + SSE streaming
│       └── tasks.ts           # Task queue API
├── dashboard/
│   └── src/
│       ├── App.tsx            # Shell + tabs + connection status
│       ├── styles.css         # Dark theme, unified design system
│       └── components/
│           ├── AgentList.tsx       # Agent grid + "New Agent" button
│           ├── AgentDetail.tsx     # Full config editor — all LLM params, memory, system prompt
│           ├── ChatPanel.tsx       # SSE streaming chat with SDK message types
│           ├── ModelsView.tsx      # Model table with provider filter
│           ├── TaskQueue.tsx       # Task list, stats, create form, cancel/retry
│           ├── ServerSettings.tsx  # Connection config
│           └── wizard/
│               ├── AgentWizard.tsx       # 5-step creation wizard
│               ├── StepIndicator.tsx     # Progress bar
│               ├── BasicInfoStep.tsx     # Name + description
│               ├── ModelSelectionStep.tsx # Live model picker from Letta
│               ├── ToolAccessStep.tsx    # Live tool picker from Letta
│               ├── SystemPromptStep.tsx  # Initial system prompt
│               └── ReviewStep.tsx        # Summary + create
├── docker-compose.yml
├── Dockerfile
├── dashboard/Dockerfile
└── package.json               # @community-ade/letta-ade v0.2.0
```

---

## Running (Host Mode)

```bash
cd /home/ani/Projects/community-ade/community-ade-wt/mvp-unified

# Prerequisites: Redis container running on port 4420
docker start ade-redis  # or: docker run -d --name ade-redis -p 4420:6379 redis:7-alpine

# Backend
npm run build
PORT=4421 nohup node dist/server.js > /tmp/ade-backend.log 2>&1 &

# Dashboard (dev server)
cd dashboard
REACT_APP_API_URL=http://10.10.20.19:4421 nohup npx react-scripts start > /tmp/ade-dashboard.log 2>&1 &

# Dashboard: http://10.10.20.19:4422/
# API:       http://10.10.20.19:4421/api/agents
# Redis:     localhost:4420
```

---

## What NOT to Do

- Do NOT create separate directories per model — models are options within ONE system
- Do NOT build standalone memory stores — use Letta's memory blocks via the SDK
- Do NOT use `localhost:3000` in frontend code — use relative URLs or `REACT_APP_API_URL`
- Do NOT guess SDK method signatures — read the `.d.ts` files or source code
- Do NOT hand-roll HTTP calls to Letta when the SDK already wraps the endpoint
- Do NOT use `import` for `@letta-ai/letta-code-sdk` in CJS — must be dynamic `import()`

---

## Archive Reference

The `community-ade-wt/_archive/` directory contains prior implementations that validated the architecture:

| Directory | What | Useful For |
|-----------|------|------------|
| `impl-kimi`, `impl-deepseek`, `impl-glm`, `impl-minimax` | Per-model implementations (identical code) | Proved model-agnostic architecture |
| `memory-curator-kimi` | 4-tier memory hierarchy design | Future memory curation phase |
| `approval-impl`, `approval-system` | Distributed locking + approval state machine | Future governance layer |
| `future-proofing` | Feature flags, migration automation, extensibility | Long-term scaling patterns |
| `sdk-alignment` | SDK compatibility tracking | Reference for version upgrades |

---

## Vision

Letta is the **only open-source platform** combining stateful agents + hierarchical memory + git-native persistence + subagent orchestration. Commercial tools (Warp, Intent) validate the market but leave gaps:

- **Warp:** terminal-native but no persistent memory, no subagent orchestration
- **Intent:** spec-driven but SaaS-only, no self-hosted option

Community ADE fills these gaps with a self-hosted, SDK-powered orchestration platform. The dashboard is the control surface. The task queue is the execution engine. The SDKs are the only interface to Letta.