71dbbd3f37
## Task Task #20: Timmy responds to Workshop input bar — make the "Say something to Timmy…" input bar actually trigger an AI response shown in Timmy's speech bubble. ## What was built ### Server (artifacts/api-server/src/lib/agent.ts) - Added `chatReply(userText)` method to AgentService - Uses claude-haiku (cheaper eval model) with a wizard persona system prompt - 150-token limit so replies fit in the speech bubble - Stub mode: returns one of 4 wizard-themed canned replies after 400ms delay - Real mode: calls Anthropic with wizard persona, truncates to 250 chars ### Server (artifacts/api-server/src/routes/events.ts) - Imported agentService - Added per-visitor rate limit system: 3 replies/minute per visitorId (in-memory Map) - Added broadcastToAll() helper for broadcasting to all WS clients - Updated visitor_message handler: 1. Broadcasts visitor message to all watchers as before 2. Checks rate limit — if exceeded, sends polite "I need a moment…" reply 3. Fire-and-forget async AI call: - Broadcasts agent_state: gamma=working (crystal ball pulses) - Calls agentService.chatReply() - Broadcasts agent_state: gamma=idle - Broadcasts chat: agentId=timmy, text=reply to ALL clients - Logs world event "visitor:reply" ### Frontend (the-matrix/js/websocket.js) - Updated case 'chat' handler to differentiate message sources: - agentId === 'timmy': speech bubble + event log entry "Timmy: <text>" - agentId === 'visitor': event log only (don't hijack speech bubble) - everything else (delta/alpha/beta payment notifications): speech bubble ## What was already working (no change needed) - Enter key on input bar (ui.js already had keydown listener) - Input clearing after send (already in ui.js) - Speech bubble rendering (setSpeechBubble already existed in agents.js) - WebSocket sendVisitorMessage already exported from websocket.js ## Tests - 27/27 testkit PASS (no regressions) - TypeScript: 0 errors - Vite build: clean (the-matrix rebuilt)
Timmy Tower World
A Three.js 3D visualization of the Timmy agent network. Agents appear as glowing icosahedra connected by lines, pulsing as they process jobs. A matrix-rain particle effect fills the background.
Quick start
npm install
npm run dev # Vite dev server with hot reload → http://localhost:5173
npm run build # Production bundle → dist/
npm run preview # Serve dist/ locally
Configuration
Set these in a .env.local file (not committed):
VITE_WS_URL=ws://localhost:8080/ws/agents
Leave VITE_WS_URL unset to run in offline/demo mode (agents animate but
receive no live updates).
Adding custom agents
Edit one file only: js/agent-defs.js
export const AGENT_DEFS = [
// existing agents …
{
id: 'zeta', // unique string — matches WebSocket message agentId
label: 'ZETA', // displayed in the 3D HUD
color: 0xff00aa, // hex integer (0xRRGGBB)
role: 'observer', // shown under the label sprite
direction: 'east', // cardinal facing direction (north/east/south/west)
x: 12, // world-space position (horizontal)
z: 0, // world-space position (depth)
},
];
Nothing else needs to change. agents.js reads positions from x/z,
and websocket.js reads colors and labels — both derive everything from
AGENT_DEFS.
Architecture
js/
├── agent-defs.js ← single source of truth: id, label, color, role, position
├── agents.js ← Three.js scene objects, animation loop
├── effects.js ← matrix rain particles, starfield
├── interaction.js ← OrbitControls (pan, zoom, rotate)
├── main.js ← entry point, rAF loop
├── ui.js ← DOM HUD overlay (FPS, agent states, chat)
└── websocket.js ← WebSocket reconnect, message dispatch
WebSocket protocol
The backend sends JSON messages on the agents channel:
type |
Fields | Effect |
|---|---|---|
agent_state |
agentId, state |
Update agent visual state |
job_started |
agentId, jobId |
Increment job counter, pulse |
job_completed |
agentId, jobId |
Decrement job counter |
chat |
agentId, text |
Append to chat panel |
Agent states: idle (dim pulse) · active (bright pulse + fast ring spin)