6672ae48e7
49 crates, 876 tests green (+17 kei-cortex + 10 cortex-ui TS, was 859). ## kei-cortex — local HTTP daemon (Rust) Axum-based server on :9797 exposing read-only cortex state (ledger, pet, memory) as JSON for browser UI consumption. Bearer token auth. CORS for https://keisei.app. Binds 127.0.0.1 only. ### Endpoints - GET /healthz — unauthenticated liveness - GET /api/v1/cortex/summary — total_dnas + active_pets + recent_sessions - GET /api/v1/cortex/pet/:user_id — pet manifest - POST /api/v1/cortex/pet/:user_id/interaction — log chat - GET /api/v1/cortex/ledger/recent?limit=N — recent agent runs - GET /api/v1/cortex/memory/search?user_id=X&pet_name=Y&q=... — recall ### Security - Token at ~/.keisei/cortex.token (32-byte hex, chmod 600 atomic via OpenOptions mode 0o600) - tower-http CorsLayer with configured allow_origin - tokio::task::spawn_blocking for rusqlite reads - All non-healthz routes protected by Bearer middleware ### Constructor Pattern 14 files, largest 137 LOC. All functions ≤30 LOC. Split: auth / config / error / state / routes + 5 handlers (health/summary/pet/ledger/memory). 17 tests: token roundtrip + chmod 600 (cfg unix) + 401/403/healthz + summary shape + pet 404 + pet parse + interaction 201 + CORS preflight + ledger limit + empty ledger. ## cortex-ui — Svelte 5 + TypeScript + Vite Static web app, build to dist/ (~500 KB incl sourcemaps, 64 KB minified JS+CSS), deployable to https://keisei.app/cortex/. Connects to local kei-cortex daemon via fetch. ### Features - Setup wizard (first run): daemon URL + token paste, saved to localStorage (origin-scoped) - Dashboard: summary cards + nav - PetEditor: view pet.toml fields (identity/voice/edge/forbidden) - LedgerStream: recent agent runs, auto-refresh 5s - MemorySearch: query form + results list - Hash-based routing (no server needed) - Dark-mode via prefers-color-scheme - URL-param override: ?daemon=URL&token=T for one-click setup ### Stack choice Svelte 5 for minimal runtime (~2 KB). TypeScript strict inherits _ts_packages/tsconfig.base.json. Vite for dev + build. vitest for unit tests (10 passing: api header/error, config precedence/overrides). ## User flow Non-dev: 1. Install keisei, run `kei-cortex serve` 2. Open https://keisei.app/cortex 3. Paste daemon URL + token from ~/.keisei/cortex.token 4. View dashboard, edit pet, search memory — all local data, zero cloud Power user (self-host): 1. `cd _ts_packages/packages/cortex-ui && npm run build` 2. Serve dist/ from localhost OR deploy anywhere 3. Point to own daemon URL Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| packages | ||
| .gitignore | ||
| bun.lock | ||
| package-lock.json | ||
| package.json | ||
| README.md | ||
| tsconfig.base.json | ||
KeiSeiKit TypeScript Packages
v0.14.0 part B: MCP server layer + external-API adapters.
RULE 0.2 exception
TypeScript is chosen here under RULE 0.2 exception #4 (Browser/DOM adjacent) because:
- The official Model Context Protocol SDK is TypeScript-native; Rust MCP libraries are immature (as of 2026-04).
- The API adapters rely on JS-native SDKs with no Rust equivalents:
grammy(type-safe Telegram bot)googleapis(official Google API SDK for Gmail + YouTube)youtube-transcript(Tier-1 free transcript extractor)
- Async, JSON-heavy glue code is TypeScript's sweet spot.
Core primitives (signing, ledger, graph, memory, refactor, etc.) remain
Rust in ../_primitives/_rust/. This TS layer is a THIN wrapper: it
spawns the Rust CLIs as subprocesses and exposes them as MCP tools, plus
the six adapters above that have no Rust equivalent.
Layout
_ts_packages/
├── package.json npm workspace root
├── tsconfig.base.json strict TS 5.x
└── packages/
├── mcp-server/ @keisei/mcp-server
├── telegram-adapter/ @keisei/telegram-adapter
├── recall-adapter/ @keisei/recall-adapter (Zoom via Recall.ai)
├── grok-adapter/ @keisei/grok-adapter (xAI)
├── gmail-adapter/ @keisei/gmail-adapter
└── youtube-adapter/ @keisei/youtube-adapter
Install (for end users)
1. Install workspace deps
cd _ts_packages
npm install
npm run build
2. Link each package as a global CLI (optional)
npm i -g ./packages/mcp-server
npm i -g ./packages/telegram-adapter
# ... etc
Or install into a Claude agent directory:
npm i --prefix ~/.claude/agents/_ts_packages/packages/mcp-server \
./_ts_packages/packages/mcp-server
Environment variables (RULE 0.8 — secrets in ~/.claude/secrets/.env)
| Var | Package | Purpose |
|---|---|---|
TELEGRAM_BOT_TOKEN |
telegram-adapter | Bot API token |
RECALL_API_KEY |
recall-adapter | Recall.ai API key (Zoom meetings) |
XAI_API_KEY |
grok-adapter | xAI Grok API key |
GMAIL_CLIENT_ID |
gmail-adapter | Google OAuth2 client id |
GMAIL_CLIENT_SECRET |
gmail-adapter | Google OAuth2 client secret |
GMAIL_REFRESH_TOKEN |
gmail-adapter | Long-lived OAuth2 refresh token |
YOUTUBE_API_KEY |
youtube-adapter | YouTube Data API v3 key |
KEI_MCP_AUTH_TOKEN |
mcp-server | HMAC token for tool callers |
KEI_RUST_BIN_DIR |
mcp-server | Override directory holding Rust primitive CLIs |
All are read via process.env. Hardcoding tokens is forbidden (RULE 0.8).
MCP server integration
The @keisei/mcp-server exposes the Rust primitive CLIs as MCP tools. The
pattern is one Rust binary = one MCP tool, with the kei meta-tool on
top that routes natural-language queries via kei-router.
Stdio mode (for Claude Code native integration):
npx @keisei/mcp-server --stdio
HTTP mode:
npx @keisei/mcp-server --port 3000 --auth-token-file ~/.claude/mcp-token
Verification
npm install
npm run build --workspaces
npm run test --workspaces
All six packages compile under strict: true. Total new LOC: see commit.
Migration notes
- Zero impact on existing KeiSeiKit users unless they opt into the MCP
server (planned v0.14.1 installer flag
--enable-mcp). - The Rust primitives are unchanged; this layer only wraps them.
- Gmail and YouTube adapters are new (gaps in LBM).