@mecha.im/cli 0.3.4

package/agent/dashboard/src/pixel-engine/hooks/useEditorKeyboard.ts

@@ -0,0 +1,83 @@
+import { useEffect } from 'react';
+
+import type { EditorState } from '../editor/editorState.js';
+import { EditTool } from '../types.js';
+
+export function useEditorKeyboard(
+  isEditMode: boolean,
+  editorState: EditorState,
+  onDeleteSelected: () => void,
+  onRotateSelected: () => void,
+  onToggleState: () => void,
+  onUndo: () => void,
+  onRedo: () => void,
+  onEditorTick: () => void,
+  onCloseEditMode: () => void,
+): void {
+  useEffect(() => {
+    if (!isEditMode) return;
+    const handler = (e: KeyboardEvent) => {
+      // Ignore keyboard shortcuts when a form control is focused
+      const tag = (e.target as HTMLElement)?.tagName;
+      if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') {
+        // Allow Escape to still work for closing edit mode
+        if (e.key !== 'Escape') return;
+      }
+      if (e.key === 'Escape') {
+        // Multi-stage Esc: deselect item → close tool → deselect placed → close editor
+        if (editorState.activeTool === EditTool.FURNITURE_PICK) {
+          editorState.activeTool = EditTool.FURNITURE_PLACE;
+          editorState.clearGhost();
+        } else if (
+          editorState.activeTool === EditTool.FURNITURE_PLACE &&
+          editorState.selectedFurnitureType !== ''
+        ) {
+          editorState.selectedFurnitureType = '';
+          editorState.clearGhost();
+        } else if (editorState.activeTool !== EditTool.SELECT) {
+          editorState.activeTool = EditTool.SELECT;
+          editorState.clearGhost();
+        } else if (editorState.selectedFurnitureUid) {
+          editorState.clearSelection();
+        } else {
+          onCloseEditMode();
+          return;
+        }
+        editorState.clearDrag();
+        onEditorTick();
+      } else if (e.key === 'Delete' || e.key === 'Backspace') {
+        if (editorState.selectedFurnitureUid) {
+          e.preventDefault();
+          onDeleteSelected();
+        }
+      } else if ((e.key === 'r' || e.key === 'R') && !e.ctrlKey && !e.metaKey && !e.altKey) {
+        e.preventDefault();
+        onRotateSelected();
+      } else if ((e.key === 't' || e.key === 'T') && !e.ctrlKey && !e.metaKey && !e.altKey) {
+        e.preventDefault();
+        onToggleState();
+      } else if (e.key === 'z' && (e.ctrlKey || e.metaKey) && !e.shiftKey) {
+        e.preventDefault();
+        onUndo();
+      } else if (
+        (e.key === 'y' && (e.ctrlKey || e.metaKey)) ||
+        (e.key === 'z' && (e.ctrlKey || e.metaKey) && e.shiftKey)
+      ) {
+        e.preventDefault();
+        onRedo();
+      }
+    };
+    window.addEventListener('keydown', handler);
+    return () => window.removeEventListener('keydown', handler);
+  }, [
+    isEditMode,
+    editorState,
+    onDeleteSelected,
+    onRotateSelected,
+    onToggleState,
+    onUndo,
+    onRedo,
+    onEditorTick,
+    onCloseEditMode,
+  ]);
+}

package/agent/dashboard/src/pixel-engine/hooks/useLayoutPersistence.ts

@@ -0,0 +1,162 @@
+/**
+ * Layout persistence hook — loads and saves office layout via the backend API.
+ *
+ * On mount: GET /api/office/layout (stores ETag for conflict detection).
+ * If 404: falls back to the bundled default-layout.json from assets.
+ * On 5xx/network error: retries 3 times with backoff, then falls back to default.
+ *
+ * saveLayout: debounced 500ms POST with If-Match ETag.
+ * On 409 conflict: reloads server version.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { LAYOUT_SAVE_DEBOUNCE_MS } from '../constants';
+import { migrateLayoutColors } from '../layout/layoutSerializer';
+import type { OfficeLayout } from '../types';
+
+const ASSET_BASE = '/pixel-engine';
+const MAX_RETRIES = 3;
+const RETRY_DELAYS = [2000, 5000, 10000];
+
+export function useLayoutPersistence(): {
+  layout: OfficeLayout | null;
+  saveLayout: (layout: OfficeLayout) => void;
+  saveLayoutImmediate: (layout: OfficeLayout) => Promise<boolean>;
+  reloadLayout: () => void;
+} {
+  const [layout, setLayout] = useState<OfficeLayout | null>(null);
+  const etagRef = useRef<string | null>(null);
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const mountedRef = useRef(true);
+
+  /** Load bundled default-layout.json from public assets */
+  const loadDefaultLayout = useCallback(async () => {
+    try {
+      const resp = await fetch(`${ASSET_BASE}/default-layout.json`);
+      if (resp.ok) {
+        const data = (await resp.json()) as OfficeLayout;
+        if (data?.version === 1 && mountedRef.current) {
+          setLayout(migrateLayoutColors(data));
+        }
+      }
+    } catch {
+      console.warn('[LayoutPersistence] Failed to load default layout');
+    }
+  }, []);
+
+  /** Fetch layout from API with retry on transient errors */
+  const fetchLayout = useCallback(async () => {
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      if (!mountedRef.current) return;
+      try {
+        const resp = await fetch('/api/office/layout');
+        if (resp.ok) {
+          const etag = resp.headers.get('ETag');
+          if (etag) etagRef.current = etag;
+          const data = (await resp.json()) as OfficeLayout;
+          if (data?.version === 1 && mountedRef.current) {
+            setLayout(migrateLayoutColors(data));
+            return;
+          }
+          // 200 but invalid shape — fall back to default
+          await loadDefaultLayout();
+          return;
+        }
+        if (resp.status === 404) {
+          // No layout saved yet — use default
+          await loadDefaultLayout();
+          return;
+        }
+        // Server error — retry
+        console.warn(`[LayoutPersistence] Server error ${resp.status} (attempt ${attempt + 1}/${MAX_RETRIES + 1})`);
+      } catch {
+        console.warn(`[LayoutPersistence] Network error (attempt ${attempt + 1}/${MAX_RETRIES + 1})`);
+      }
+      // Wait before retry (skip wait on last attempt)
+      if (attempt < MAX_RETRIES) {
+        await new Promise(r => setTimeout(r, RETRY_DELAYS[attempt] ?? 10000));
+      }
+    }
+    // All retries exhausted — fall back to default
+    console.warn('[LayoutPersistence] Retries exhausted, using default layout');
+    await loadDefaultLayout();
+  }, [loadDefaultLayout]);
+
+  /** Save layout to the API with ETag conflict detection. Returns true on success. */
+  const doSave = useCallback(async (layoutToSave: OfficeLayout): Promise<boolean> => {
+    try {
+      const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+      };
+      if (etagRef.current) {
+        headers['If-Match'] = etagRef.current;
+      }
+
+      const resp = await fetch('/api/office/layout', {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(layoutToSave),
+      });
+
+      if (resp.ok) {
+        const etag = resp.headers.get('ETag');
+        if (etag) etagRef.current = etag;
+        return true;
+      } else if (resp.status === 409) {
+        // Conflict — reload server version
+        console.warn('[LayoutPersistence] Conflict detected, reloading server layout');
+        await fetchLayout();
+      }
+    } catch {
+      console.warn('[LayoutPersistence] Failed to save layout');
+    }
+    return false;
+  }, [fetchLayout]);
+
+  /** Debounced save — waits 500ms after last call */
+  const saveLayout = useCallback(
+    (layoutToSave: OfficeLayout) => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+      debounceRef.current = setTimeout(() => {
+        debounceRef.current = null;
+        doSave(layoutToSave);
+      }, LAYOUT_SAVE_DEBOUNCE_MS);
+    },
+    [doSave],
+  );
+
+  /** Immediate (non-debounced) save — returns true on success */
+  const saveLayoutImmediate = useCallback(
+    async (layoutToSave: OfficeLayout): Promise<boolean> => {
+      // Flush any pending debounced save
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+        debounceRef.current = null;
+      }
+      return doSave(layoutToSave);
+    },
+    [doSave],
+  );
+
+  const reloadLayout = useCallback(() => {
+    fetchLayout();
+  }, [fetchLayout]);
+
+  // Load on mount
+  useEffect(() => {
+    mountedRef.current = true;
+    fetchLayout();
+
+    return () => {
+      mountedRef.current = false;
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+    };
+  }, [fetchLayout]);
+
+  return { layout, saveLayout, saveLayoutImmediate, reloadLayout };
+}

package/agent/dashboard/src/pixel-engine/hooks/useOfficeStream.ts

@@ -0,0 +1,353 @@
+/**
+ * Fleet SSE stream adapter for the pixel office engine.
+ *
+ * Connects to GET /api/office/stream and maps SSE events to OfficeState mutations.
+ * Handles snapshot reconciliation, delta events (bot_join, bot_leave, tool, state),
+ * heartbeat seq-gap detection, and automatic reconnection with backoff.
+ */
+
+import { useCallback, useEffect, useRef } from 'react';
+
+import type { OfficeState } from '../engine/officeState';
+import { extractToolName } from '../toolUtils';
+
+// ── SSE event payload types ─────────────────────────────────
+
+interface SnapshotBot {
+  bot_id: string;
+  name: string;
+  status: 'idle' | 'active' | 'waiting' | 'permission';
+  tool?: string;
+  palette?: number;
+  hueShift?: number;
+  displayName?: string;
+}
+
+interface SnapshotEvent {
+  seq: number;
+  bots: SnapshotBot[];
+}
+
+interface DeltaStateEvent {
+  seq: number;
+  type: 'bot_join' | 'bot_leave' | 'status';
+  bot_id: string;
+  name?: string;
+  status?: string;
+  palette?: number;
+  hueShift?: number;
+  displayName?: string;
+}
+
+interface DeltaToolEvent {
+  seq: number;
+  type: 'tool_start' | 'tool_done' | 'tools_clear';
+  bot_id: string;
+  tool_id?: string;
+  tool?: string;
+}
+
+interface HeartbeatEvent {
+  seq: number;
+}
+
+// ── ID management ───────────────────────────────────────────
+
+interface BotEntry {
+  numericId: number;
+  name: string;
+}
+
+const RECONNECT_BASE_MS = 1000;
+const RECONNECT_MAX_MS = 30000;
+
+export function useOfficeStream(
+  officeState: OfficeState | null,
+  assetsReady: boolean,
+): { getBotNameByNumericId: (id: number) => string | null; getDisplayName: (id: number) => string | null } {
+  // Stable maps persisted across reconnections via refs
+  const botMapRef = useRef(new Map<string, BotEntry>()); // botId → entry
+  const reverseMapRef = useRef(new Map<number, string>()); // numericId → botId
+  const displayNameMapRef = useRef(new Map<number, string>()); // numericId → displayName
+  const nextIdRef = useRef(1);
+  const expectedSeqRef = useRef(0);
+  const esRef = useRef<EventSource | null>(null);
+  const reconnectAttemptRef = useRef(0);
+  const reconnectTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  /** Get or create a stable numeric ID for a bot */
+  const getNumericId = useCallback((botId: string, name: string): number => {
+    const existing = botMapRef.current.get(botId);
+    if (existing) return existing.numericId;
+
+    const id = nextIdRef.current++;
+    const entry: BotEntry = { numericId: id, name };
+    botMapRef.current.set(botId, entry);
+    reverseMapRef.current.set(id, botId);
+    return id;
+  }, []);
+
+  const getBotNameByNumericId = useCallback((id: number): string | null => {
+    const botId = reverseMapRef.current.get(id);
+    if (!botId) return null;
+    return botMapRef.current.get(botId)?.name ?? null;
+  }, []);
+
+  const getDisplayName = useCallback((id: number): string | null => {
+    return displayNameMapRef.current.get(id) ?? null;
+  }, []);
+
+  useEffect(() => {
+    if (!officeState || !assetsReady) return;
+
+    // Capture in a const so TypeScript narrows the type inside closures
+    const os = officeState;
+
+    function connect() {
+      // Clean up existing connection
+      if (esRef.current) {
+        esRef.current.close();
+        esRef.current = null;
+      }
+
+      const url = '/api/office/stream';
+      const es = new EventSource(url);
+      esRef.current = es;
+
+      es.addEventListener('snapshot', (e: MessageEvent) => {
+        try {
+          const data = JSON.parse(e.data) as SnapshotEvent;
+          expectedSeqRef.current = data.seq + 1;
+          reconnectAttemptRef.current = 0; // Successful connection
+
+          // Reconcile: add new bots, remove stale ones
+          const incomingIds = new Set<string>();
+          for (const bot of data.bots) {
+            incomingIds.add(bot.bot_id);
+            const numId = getNumericId(bot.bot_id, bot.name);
+
+            if (!os.characters.has(numId)) {
+              os.addAgent(numId, bot.palette, bot.hueShift, undefined, true);
+            } else if (bot.palette !== undefined || bot.hueShift !== undefined) {
+              // Update existing agent's avatar if it changed (e.g., after reconnect)
+              const ch = os.characters.get(numId);
+              if (ch) {
+                if (bot.palette !== undefined && ch.palette !== bot.palette) ch.palette = bot.palette;
+                if (bot.hueShift !== undefined && ch.hueShift !== bot.hueShift) ch.hueShift = bot.hueShift;
+              }
+            }
+            if (bot.displayName) displayNameMapRef.current.set(numId, bot.displayName);
+
+            // Apply current status
+            if (bot.status === 'active') {
+              os.setAgentActive(numId, true);
+              if (bot.tool) {
+                os.setAgentTool(numId, extractToolName(bot.tool));
+              }
+            } else if (bot.status === 'waiting') {
+              os.setAgentActive(numId, false);
+              os.showWaitingBubble(numId);
+            } else if (bot.status === 'permission') {
+              os.setAgentActive(numId, true);
+              os.showPermissionBubble(numId);
+            } else {
+              // idle
+              os.setAgentActive(numId, false);
+            }
+          }
+
+          // Remove characters not in snapshot
+          for (const [numId, botId] of reverseMapRef.current) {
+            if (!incomingIds.has(botId) && os.characters.has(numId)) {
+              os.removeAllSubagents(numId);
+              os.removeAgent(numId);
+              displayNameMapRef.current.delete(numId);
+            }
+          }
+        } catch (err) {
+          console.error('[OfficeStream] Error processing snapshot:', err);
+        }
+      });
+
+      es.addEventListener('state', (e: MessageEvent) => {
+        try {
+          const data = JSON.parse(e.data) as DeltaStateEvent;
+
+          // Seq gap detection
+          if (data.seq > expectedSeqRef.current) {
+            console.warn(
+              `[OfficeStream] Seq gap: expected ${expectedSeqRef.current}, got ${data.seq}. Reconnecting.`,
+            );
+            scheduleReconnect();
+            return;
+          }
+          expectedSeqRef.current = data.seq + 1;
+
+          if (data.type === 'bot_join') {
+            const numId = getNumericId(data.bot_id, data.name ?? data.bot_id);
+            os.addAgent(numId, data.palette, data.hueShift);
+            if (data.displayName) displayNameMapRef.current.set(numId, data.displayName);
+          } else if (data.type === 'bot_leave') {
+            const entry = botMapRef.current.get(data.bot_id);
+            if (entry) {
+              os.removeAllSubagents(entry.numericId);
+              os.removeAgent(entry.numericId);
+              displayNameMapRef.current.delete(entry.numericId);
+            }
+          } else if (data.type === 'status') {
+            const entry = botMapRef.current.get(data.bot_id);
+            if (entry) {
+              const numId = entry.numericId;
+              const status = data.status;
+
+              if (status === 'active') {
+                os.setAgentActive(numId, true);
+                os.clearPermissionBubble(numId);
+              } else if (status === 'waiting') {
+                os.setAgentActive(numId, false);
+                os.showWaitingBubble(numId);
+              } else if (status === 'permission') {
+                os.setAgentActive(numId, true);
+                os.showPermissionBubble(numId);
+              } else {
+                // idle
+                os.setAgentActive(numId, false);
+                os.setAgentTool(numId, null);
+                os.clearPermissionBubble(numId);
+              }
+            }
+          }
+        } catch (err) {
+          console.error('[OfficeStream] Error processing state event:', err);
+        }
+      });
+
+      es.addEventListener('tool', (e: MessageEvent) => {
+        try {
+          const data = JSON.parse(e.data) as DeltaToolEvent;
+
+          if (data.seq > expectedSeqRef.current) {
+            console.warn(`[OfficeStream] Seq gap in tool event. Reconnecting.`);
+            scheduleReconnect();
+            return;
+          }
+          expectedSeqRef.current = data.seq + 1;
+
+          const entry = botMapRef.current.get(data.bot_id);
+          if (!entry) return;
+          const numId = entry.numericId;
+
+          if (data.type === 'tool_start') {
+            const toolName = data.tool ? extractToolName(data.tool) : null;
+            os.setAgentTool(numId, toolName);
+            os.setAgentActive(numId, true);
+            os.clearPermissionBubble(numId);
+
+            // Handle subtask spawning
+            if (data.tool?.startsWith('Subtask:') && data.tool_id) {
+              const subAgentId = os.addSubagent(numId, data.tool_id);
+              // Request face-to-face chat if both parent and child are idle
+              const parentCh = os.characters.get(numId);
+              const childCh = os.characters.get(subAgentId);
+              if (parentCh && childCh && !parentCh.isActive && !childCh.isActive) {
+                os.scheduler.requestRealChat(numId, subAgentId);
+              }
+            }
+          } else if (data.type === 'tool_done') {
+            // Tool completed — don't clear agent tool immediately
+            // (another tool may still be active)
+          } else if (data.type === 'tools_clear') {
+            os.setAgentTool(numId, null);
+            os.removeAllSubagents(numId);
+            os.clearPermissionBubble(numId);
+          }
+        } catch (err) {
+          console.error('[OfficeStream] Error processing tool event:', err);
+        }
+      });
+
+      es.addEventListener('subagent', (e: MessageEvent) => {
+        try {
+          const data = JSON.parse(e.data) as {
+            seq: number;
+            type: string;
+            bot_id: string;
+            parent_tool_id: string;
+            tool_id?: string;
+            tool?: string;
+          };
+
+          if (data.seq > expectedSeqRef.current) {
+            scheduleReconnect();
+            return;
+          }
+          expectedSeqRef.current = data.seq + 1;
+
+          const entry = botMapRef.current.get(data.bot_id);
+          if (!entry) return;
+          const numId = entry.numericId;
+
+          if (data.type === 'tool_start') {
+            const subId = os.getSubagentId(numId, data.parent_tool_id);
+            if (subId !== null) {
+              const toolName = data.tool ? extractToolName(data.tool) : null;
+              os.setAgentTool(subId, toolName);
+              os.setAgentActive(subId, true);
+            }
+          } else if (data.type === 'clear') {
+            os.removeSubagent(numId, data.parent_tool_id);
+          }
+        } catch (err) {
+          console.error('[OfficeStream] Error processing subagent event:', err);
+        }
+      });
+
+      es.addEventListener('heartbeat', (e: MessageEvent) => {
+        try {
+          const data = JSON.parse(e.data) as HeartbeatEvent;
+          expectedSeqRef.current = data.seq + 1;
+          reconnectAttemptRef.current = 0;
+        } catch {
+          // Ignore malformed heartbeats
+        }
+      });
+
+      es.onerror = () => {
+        console.warn('[OfficeStream] Connection error. Scheduling reconnect.');
+        scheduleReconnect();
+      };
+    }
+
+    function scheduleReconnect() {
+      if (esRef.current) {
+        esRef.current.close();
+        esRef.current = null;
+      }
+      if (reconnectTimerRef.current) return; // Already scheduled
+
+      const attempt = reconnectAttemptRef.current++;
+      const delay = Math.min(RECONNECT_BASE_MS * Math.pow(2, attempt), RECONNECT_MAX_MS);
+      console.log(`[OfficeStream] Reconnecting in ${delay}ms (attempt ${attempt + 1})`);
+
+      reconnectTimerRef.current = setTimeout(() => {
+        reconnectTimerRef.current = null;
+        connect();
+      }, delay);
+    }
+
+    connect();
+
+    return () => {
+      if (esRef.current) {
+        esRef.current.close();
+        esRef.current = null;
+      }
+      if (reconnectTimerRef.current) {
+        clearTimeout(reconnectTimerRef.current);
+        reconnectTimerRef.current = null;
+      }
+    };
+  }, [officeState, assetsReady, getNumericId]);
+
+  return { getBotNameByNumericId, getDisplayName };
+}