Redflag/system/community_ade_project.md

description, limit

description	limit
Community ADE project - absolute paths, architecture, SDK rules	2000

Community ADE Project

Absolute Path

/home/ani/Projects/community-ade/community-ade-wt/mvp-unified/

START_HERE: /home/ani/Projects/community-ade/START_HERE.md

---

What This Is

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

My Role: Orchestrator (Annie Tunturi) — project owner, architect, final decision-maker

---

Architecture

Browser (React Dashboard :4422)
    │ /api/*
nginx reverse proxy
    │
Express Backend (:4421 → container :3000)
    ├── @letta-ai/letta-client ──→ Letta Server :8283
    └── @letta-ai/letta-code-sdk ──→ letta-code CLI
    │
Redis (:4420 → container :6379) — task queue, worker state

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

---

SDK Rule (MANDATORY)

Every feature MUST use one of these two packages. No exceptions.

@letta-ai/letta-client (v1.7.12) — REST Operations

• Use for: Listing agents, reading memory blocks, CRUD operations, model listing
• Source: /home/ani/Projects/letta-code/node_modules/@letta-ai/letta-client/
• Key patterns:
  • new Letta({ baseURL, apiKey, timeout })
  • Pagination: .list() returns page objects — use .items for array
  • Health: client.health() (top-level, NOT .health.check())
  • Blocks: client.agents.blocks.list(agentId) (NOT .coreMemory.blocks)

@letta-ai/letta-code-sdk (v0.1.12) — Interactive Sessions

• Use for: Chat sessions, streaming responses, tool execution
• Source: /home/ani/Projects/letta-code-sdk/
• Key exports: createSession, resumeSession, prompt, Session
• Streaming: session.stream() yields typed SDKMessage objects

SDK Gotchas

What you'd expect	What actually works
client.health.check()	client.health() — top-level
client.agents.list() returns Agent[]	Returns AgentStatesArrayPage — use .items
client.agents.coreMemory.blocks.list()	client.agents.blocks.list(agentId)

---

Build Steps (11 Steps)

Step	What	SDK	Status
1	Project restructure + deps	both	✅ DONE
2	Letta REST client service	letta-client	✅ DONE
3	SDK session service	letta-code-sdk	IN PROGRESS
4	Express routes (agents, chat SSE)	both	✅ DONE
5	Task queue + worker pool (Redis)	letta-code-sdk	✅ DONE
6	Docker configuration	—	⚠️ PARTIAL
7	Dashboard shell + settings	—	✅ DONE
8	Dashboard agent list + detail + config editor	letta-client	✅ DONE
9	Dashboard task queue UI	—	✅ DONE
10	Dashboard chat panel (streaming)	letta-code-sdk	✅ DONE
11	Dashboard models view	letta-client	✅ DONE

Critical: Step 3 is the bridge — wraps @letta-ai/letta-code-sdk for interactive chat, streaming, tool execution.

---

Key Files

/home/ani/Projects/community-ade/community-ade-wt/mvp-unified/
├── src/
│   ├── server.ts              # Express entry point
│   ├── types.ts               # ADE domain types
│   ├── services/
│   │   ├── letta.ts           # @letta-ai/letta-client wrapper (DONE)
│   │   └── sessions.ts        # @letta-ai/letta-code-sdk wrapper (Step 3)
│   └── routes/
│       ├── agents.ts          # Agent CRUD + memory + tools
│       ├── server.ts          # Health, models, reconnect
│       ├── chat.ts            # SDK sessions + SSE streaming
│       └── tasks.ts           # Task queue API
├── dashboard/
│   └── src/
│       ├── App.tsx            # Shell + tabs + connection status
│       └── components/
│           ├── AgentList.tsx       # Agent grid with model badges
│           ├── AgentDetail.tsx     # Full config editor
│           ├── ChatPanel.tsx       # SDK streaming
│           └── ModelsView.tsx      # Model table with filter
├── docker-compose.yml
├── Dockerfile
└── package.json

---

Running Commands

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

# Build and start everything
docker compose up --build -d

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

# Backend rebuild only
npm run build && docker compose up --build -d app

# Dashboard rebuild only
docker compose up --build -d dashboard

---

Verification Commands

# Health check
curl http://localhost:8283/v1/health

# Real agents exist
curl http://localhost:4422/api/agents

# Agent detail returns raw state
curl http://localhost:4422/api/agents/<AGENT_ID>

---

Plan File

/home/casey/.claude/plans/silly-zooming-cocke.md — Full build plan with 11 sequential steps

---

What I Do Here

• Make architectural decisions
• Direct implementation phases
• Verify SDK compliance
• Manage subagents for build steps
• Approve/refine prompts
• Final arbiter on all implementation direction

---

Last updated: 2026-03-21 Status: Step 3 in progress (SDK session service)