diff --git a/system/community_ade_project.md b/system/community_ade_project.md new file mode 100644 index 0000000..12e03b8 --- /dev/null +++ b/system/community_ade_project.md @@ -0,0 +1,171 @@ +--- +description: Community ADE project - absolute paths, architecture, SDK rules +limit: 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 + +```bash +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 + +```bash +# 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/ +``` + +--- + +## 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)