@mecha.im/cli 0.3.4

package/agent/dashboard/src/lib/snippet.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from "vitest";
+import { extractSnippet } from "./snippet";
+
+describe("extractSnippet", () => {
+  it("centers snippet around the match", () => {
+    const text = "a".repeat(100) + "NEEDLE" + "b".repeat(100);
+    const result = extractSnippet(text, "needle");
+    expect(result).toContain("NEEDLE");
+    expect(result.startsWith("...")).toBe(true);
+    expect(result.endsWith("...")).toBe(true);
+  });
+
+  it("returns start of text when needle not found", () => {
+    const text = "a".repeat(200);
+    const result = extractSnippet(text, "xyz");
+    expect(result.length).toBe(160); // contextChars * 2
+  });
+
+  it("no ellipsis when match is at the start", () => {
+    const text = "NEEDLE" + "b".repeat(200);
+    const result = extractSnippet(text, "needle");
+    expect(result.startsWith("...")).toBe(false);
+    expect(result.endsWith("...")).toBe(true);
+  });
+
+  it("no ellipsis when match is at the end", () => {
+    const text = "a".repeat(200) + "NEEDLE";
+    const result = extractSnippet(text, "needle");
+    expect(result.startsWith("...")).toBe(true);
+    expect(result.endsWith("...")).toBe(false);
+  });
+
+  it("no ellipsis when text fits within context", () => {
+    const result = extractSnippet("short text with needle here", "needle");
+    expect(result).toBe("short text with needle here");
+  });
+
+  it("replaces newlines with spaces", () => {
+    const result = extractSnippet("line1\nneedle\nline3", "needle");
+    expect(result).not.toContain("\n");
+    expect(result).toContain("line1 needle line3");
+  });
+
+  it("respects custom contextChars", () => {
+    const text = "a".repeat(50) + "NEEDLE" + "b".repeat(50);
+    const result = extractSnippet(text, "needle", 10);
+    // 10 chars before + "NEEDLE" (6) + 10 chars after = ~26, plus "..." on both sides
+    expect(result.length).toBeLessThan(40);
+  });
+});

package/agent/dashboard/src/lib/snippet.ts

@@ -0,0 +1,15 @@
+/**
+ * Extract a text snippet centered around a search needle with surrounding context.
+ * Re-exported from session-history for testability in the dashboard test suite.
+ */
+export function extractSnippet(text: string, needle: string, contextChars = 80): string {
+  const lower = text.toLowerCase();
+  const idx = lower.indexOf(needle.toLowerCase());
+  if (idx === -1) return text.slice(0, contextChars * 2);
+  const start = Math.max(0, idx - contextChars);
+  const end = Math.min(text.length, idx + needle.length + contextChars);
+  let snippet = text.slice(start, end).replace(/\n/g, " ");
+  if (start > 0) snippet = "..." + snippet;
+  if (end < text.length) snippet = snippet + "...";
+  return snippet;
+}

package/agent/dashboard/src/lib/ws-parse.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from "vitest";
+import { parseWsMessage } from "./ws-parse";
+
+describe("parseWsMessage", () => {
+  it("handles ArrayBuffer as binary", () => {
+    const buf = new ArrayBuffer(3);
+    new Uint8Array(buf).set([1, 2, 3]);
+    const result = parseWsMessage(buf);
+    expect(result.kind).toBe("binary");
+    if (result.kind === "binary") {
+      expect(Array.from(result.data)).toEqual([1, 2, 3]);
+    }
+  });
+
+  it("handles plain text", () => {
+    const result = parseWsMessage("hello world");
+    expect(result).toEqual({ kind: "text", data: "hello world" });
+  });
+
+  it("handles text starting with { but not valid JSON", () => {
+    const result = parseWsMessage("{not valid json");
+    expect(result).toEqual({ kind: "text", data: "{not valid json" });
+  });
+
+  it("handles JSON without __mecha flag as plain text", () => {
+    const msg = JSON.stringify({ type: "some_event", data: 123 });
+    const result = parseWsMessage(msg);
+    expect(result).toEqual({ kind: "text", data: msg });
+  });
+
+  it("parses mecha session message", () => {
+    const msg = JSON.stringify({ __mecha: true, type: "session", id: "abc-123" });
+    const result = parseWsMessage(msg);
+    expect(result).toEqual({ kind: "mecha-session", id: "abc-123" });
+  });
+
+  it("parses mecha exit message with code", () => {
+    const msg = JSON.stringify({ __mecha: true, type: "exit", code: 0 });
+    const result = parseWsMessage(msg);
+    expect(result).toEqual({ kind: "mecha-exit", code: 0 });
+  });
+
+  it("parses mecha exit message without code (defaults to -1)", () => {
+    const msg = JSON.stringify({ __mecha: true, type: "exit" });
+    const result = parseWsMessage(msg);
+    expect(result).toEqual({ kind: "mecha-exit", code: -1 });
+  });
+
+  it("parses mecha error message", () => {
+    const msg = JSON.stringify({ __mecha: true, type: "error", message: "something broke" });
+    const result = parseWsMessage(msg);
+    expect(result).toEqual({ kind: "mecha-error", message: "something broke" });
+  });
+
+  it("parses mecha error without message (defaults)", () => {
+    const msg = JSON.stringify({ __mecha: true, type: "error" });
+    const result = parseWsMessage(msg);
+    expect(result).toEqual({ kind: "mecha-error", message: "Unknown error" });
+  });
+
+  it("treats mecha session without id as plain text", () => {
+    const msg = JSON.stringify({ __mecha: true, type: "session" });
+    const result = parseWsMessage(msg);
+    // No id → falls through to plain text since no branch matches
+    expect(result).toEqual({ kind: "text", data: msg });
+  });
+
+  it("handles empty string", () => {
+    const result = parseWsMessage("");
+    expect(result).toEqual({ kind: "text", data: "" });
+  });
+});

package/agent/dashboard/src/lib/ws-parse.ts

@@ -0,0 +1,46 @@
+export interface MechaControlMessage {
+  __mecha: true;
+  type: string;
+  id?: string;
+  code?: number;
+  message?: string;
+}
+
+export type WsParseResult =
+  | { kind: "binary"; data: Uint8Array }
+  | { kind: "text"; data: string }
+  | { kind: "mecha-session"; id: string }
+  | { kind: "mecha-exit"; code: number }
+  | { kind: "mecha-error"; message: string };
+
+/**
+ * Parse a WebSocket message event.data into a typed result.
+ * Expects ws.binaryType = "arraybuffer" so binary arrives as ArrayBuffer.
+ */
+export function parseWsMessage(data: ArrayBuffer | string): WsParseResult {
+  if (data instanceof ArrayBuffer) {
+    return { kind: "binary", data: new Uint8Array(data) };
+  }
+
+  const text = data;
+  if (text.charAt(0) === "{") {
+    try {
+      const msg = JSON.parse(text) as Partial<MechaControlMessage> & { type: string };
+      if (msg.__mecha) {
+        if (msg.type === "session" && msg.id) {
+          return { kind: "mecha-session", id: msg.id };
+        }
+        if (msg.type === "exit") {
+          return { kind: "mecha-exit", code: typeof msg.code === "number" ? msg.code : -1 };
+        }
+        if (msg.type === "error") {
+          return { kind: "mecha-error", message: msg.message ?? "Unknown error" };
+        }
+      }
+    } catch {
+      // not valid JSON — fall through to plain text
+    }
+  }
+
+  return { kind: "text", data: text };
+}

package/agent/dashboard/src/main.tsx

@@ -0,0 +1,25 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import { FleetProvider } from "./lib/fleet-context";
+import LoginGate from "./lib/login-gate";
+import App from "./app";
+import { PixelOffice } from "./pixel-engine/components/PixelOffice";
+import "./index.css";
+
+const isPublicOffice = window.location.pathname === "/office" || window.location.pathname === "/office/";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    {isPublicOffice ? (
+      <div style={{ width: "100vw", height: "100vh", overflow: "hidden", background: "#111" }}>
+        <PixelOffice isActive readOnly />
+      </div>
+    ) : (
+      <LoginGate>
+        <FleetProvider>
+          <App />
+        </FleetProvider>
+      </LoginGate>
+    )}
+  </React.StrictMode>,
+);

package/agent/dashboard/src/pixel-engine/colorize.ts

@@ -0,0 +1,230 @@
+/**
+ * Shared sprite colorization module.
+ *
+ * Two modes:
+ * - Colorize (Photoshop-style): grayscale → fixed HSL. For floor tiles and opt-in furniture.
+ * - Adjust (default for furniture): shift original pixel HSL values.
+ */
+
+import type { FloorColor, SpriteData } from './types.js';
+
+/** Generic colorized sprite cache: arbitrary string key → SpriteData */
+const colorizeCache = new Map<string, SpriteData>();
+
+/** Max entries before evicting oldest (first inserted) */
+const COLORIZE_CACHE_MAX = 500;
+
+/**
+ * Get a color-adjusted sprite from cache, or compute and cache it.
+ * Dispatches to colorize or adjust mode based on `color.colorize`.
+ * Caller provides a unique cache key that must include the colorize flag.
+ */
+export function getColorizedSprite(
+  cacheKey: string,
+  sprite: SpriteData,
+  color: FloorColor,
+): SpriteData {
+  const cached = colorizeCache.get(cacheKey);
+  if (cached) return cached;
+  const result = color.colorize ? colorizeSprite(sprite, color) : adjustSprite(sprite, color);
+  // Evict oldest entry when over limit
+  if (colorizeCache.size >= COLORIZE_CACHE_MAX) {
+    const firstKey = colorizeCache.keys().next().value;
+    if (firstKey !== undefined) colorizeCache.delete(firstKey);
+  }
+  colorizeCache.set(cacheKey, result);
+  return result;
+}
+
+/** Clear all cached colorized sprites (e.g., on tab deactivation or asset reload) */
+export function clearColorizeCache(): void {
+  colorizeCache.clear();
+}
+
+/**
+ * Colorize a sprite using HSL transformation.
+ *
+ * Algorithm (Photoshop Colorize-style):
+ * 1. Parse each pixel's color as perceived luminance (0-1)
+ * 2. Apply contrast: stretch/compress around midpoint 0.5
+ * 3. Apply brightness: shift lightness up/down
+ * 4. Create HSL color with user's hue + saturation
+ * 5. Convert HSL -> RGB -> hex
+ */
+export function colorizeSprite(sprite: SpriteData, color: FloorColor): SpriteData {
+  const { h, s, b, c } = color;
+  const result: SpriteData = [];
+
+  for (const row of sprite) {
+    const newRow: string[] = [];
+    for (const pixel of row) {
+      if (pixel === '') {
+        newRow.push('');
+        continue;
+      }
+
+      // Parse hex to get RGB values
+      const r = parseInt(pixel.slice(1, 3), 16);
+      const g = parseInt(pixel.slice(3, 5), 16);
+      const bv = parseInt(pixel.slice(5, 7), 16);
+      // Use perceived luminance for grayscale
+      let lightness = (0.299 * r + 0.587 * g + 0.114 * bv) / 255;
+
+      // Apply contrast: expand/compress around 0.5
+      if (c !== 0) {
+        const factor = (100 + c) / 100;
+        lightness = 0.5 + (lightness - 0.5) * factor;
+      }
+
+      // Apply brightness: shift up/down
+      if (b !== 0) {
+        lightness = lightness + b / 200;
+      }
+
+      // Clamp
+      lightness = Math.max(0, Math.min(1, lightness));
+
+      // Preserve original alpha
+      const alpha = extractAlpha(pixel);
+
+      // Convert HSL to RGB
+      const satFrac = s / 100;
+      const hex = hslToHex(h, satFrac, lightness);
+      newRow.push(appendAlpha(hex, alpha));
+    }
+    result.push(newRow);
+  }
+
+  return result;
+}
+
+/** Extract alpha from a hex pixel string. Returns 255 for #RRGGBB, parsed value for #RRGGBBAA. */
+function extractAlpha(pixel: string): number {
+  return pixel.length > 7 ? parseInt(pixel.slice(7, 9), 16) : 255;
+}
+
+/** Append alpha to a #RRGGBB hex string, omitting if fully opaque. */
+function appendAlpha(hex: string, alpha: number): string {
+  if (alpha >= 255) return hex;
+  return `${hex}${alpha.toString(16).padStart(2, '0').toUpperCase()}`;
+}
+
+/** Convert HSL (h: 0-360, s: 0-1, l: 0-1) to #RRGGBB hex string */
+function hslToHex(h: number, s: number, l: number): string {
+  const c = (1 - Math.abs(2 * l - 1)) * s;
+  const hp = h / 60;
+  const x = c * (1 - Math.abs((hp % 2) - 1));
+  let r1 = 0,
+    g1 = 0,
+    b1 = 0;
+
+  if (hp < 1) {
+    r1 = c;
+    g1 = x;
+    b1 = 0;
+  } else if (hp < 2) {
+    r1 = x;
+    g1 = c;
+    b1 = 0;
+  } else if (hp < 3) {
+    r1 = 0;
+    g1 = c;
+    b1 = x;
+  } else if (hp < 4) {
+    r1 = 0;
+    g1 = x;
+    b1 = c;
+  } else if (hp < 5) {
+    r1 = x;
+    g1 = 0;
+    b1 = c;
+  } else {
+    r1 = c;
+    g1 = 0;
+    b1 = x;
+  }
+
+  const m = l - c / 2;
+  const r = Math.round((r1 + m) * 255);
+  const g = Math.round((g1 + m) * 255);
+  const bOut = Math.round((b1 + m) * 255);
+
+  return `#${clamp255(r).toString(16).padStart(2, '0')}${clamp255(g).toString(16).padStart(2, '0')}${clamp255(bOut).toString(16).padStart(2, '0')}`.toUpperCase();
+}
+
+function clamp255(v: number): number {
+  return Math.max(0, Math.min(255, v));
+}
+
+/** Convert RGB (0-255 each) to HSL (h: 0-360, s: 0-1, l: 0-1) */
+function rgbToHsl(r: number, g: number, b: number): [number, number, number] {
+  const rf = r / 255,
+    gf = g / 255,
+    bf = b / 255;
+  const max = Math.max(rf, gf, bf),
+    min = Math.min(rf, gf, bf);
+  const l = (max + min) / 2;
+  if (max === min) return [0, 0, l];
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h = 0;
+  if (max === rf) h = ((gf - bf) / d + (gf < bf ? 6 : 0)) * 60;
+  else if (max === gf) h = ((bf - rf) / d + 2) * 60;
+  else h = ((rf - gf) / d + 4) * 60;
+  return [h, s, l];
+}
+
+/**
+ * Adjust a sprite's colors by shifting HSL values (default mode for furniture).
+ *
+ * H slider (-180 to +180): rotates hue
+ * S slider (-100 to +100): shifts saturation
+ * B slider (-100 to 100): shifts lightness
+ * C slider (-100 to 100): adjusts contrast around midpoint
+ */
+export function adjustSprite(sprite: SpriteData, color: FloorColor): SpriteData {
+  const { h: hShift, s: sShift, b, c } = color;
+  const result: SpriteData = [];
+
+  for (const row of sprite) {
+    const newRow: string[] = [];
+    for (const pixel of row) {
+      if (pixel === '') {
+        newRow.push('');
+        continue;
+      }
+
+      const r = parseInt(pixel.slice(1, 3), 16);
+      const g = parseInt(pixel.slice(3, 5), 16);
+      const bv = parseInt(pixel.slice(5, 7), 16);
+      const alpha = extractAlpha(pixel);
+      const [origH, origS, origL] = rgbToHsl(r, g, bv);
+
+      // Shift hue
+      const newH = (((origH + hShift) % 360) + 360) % 360;
+
+      // Shift saturation
+      const newS = Math.max(0, Math.min(1, origS + sShift / 100));
+
+      // Apply contrast: expand/compress around 0.5
+      let lightness = origL;
+      if (c !== 0) {
+        const factor = (100 + c) / 100;
+        lightness = 0.5 + (lightness - 0.5) * factor;
+      }
+
+      // Apply brightness
+      if (b !== 0) {
+        lightness = lightness + b / 200;
+      }
+
+      lightness = Math.max(0, Math.min(1, lightness));
+
+      const hex = hslToHex(newH, newS, lightness);
+      newRow.push(appendAlpha(hex, alpha));
+    }
+    result.push(newRow);
+  }
+
+  return result;
+}

package/agent/dashboard/src/pixel-engine/components/BottomToolbar.tsx

@@ -0,0 +1,83 @@
+import { useState } from 'react';
+
+interface BottomToolbarProps {
+  isEditMode: boolean;
+  onToggleEditMode: () => void;
+  isDebugMode: boolean;
+  onToggleDebugMode: () => void;
+  onOpenSettings: () => void;
+}
+
+const panelStyle: React.CSSProperties = {
+  position: 'absolute',
+  bottom: 10,
+  left: 10,
+  zIndex: 'var(--pixel-controls-z)',
+  display: 'flex',
+  alignItems: 'center',
+  gap: 4,
+  background: 'var(--pixel-bg)',
+  border: '2px solid var(--pixel-border)',
+  borderRadius: 0,
+  padding: '4px 6px',
+  boxShadow: 'var(--pixel-shadow)',
+};
+
+const btnBase: React.CSSProperties = {
+  padding: '5px 10px',
+  fontSize: '24px',
+  color: 'var(--pixel-text)',
+  background: 'var(--pixel-btn-bg)',
+  border: '2px solid transparent',
+  borderRadius: 0,
+  cursor: 'pointer',
+};
+
+const btnActive: React.CSSProperties = {
+  ...btnBase,
+  background: 'var(--pixel-active-bg)',
+  border: '2px solid var(--pixel-accent)',
+};
+
+export function BottomToolbar({
+  isEditMode,
+  onToggleEditMode,
+  isDebugMode: _isDebugMode,
+  onToggleDebugMode: _onToggleDebugMode,
+  onOpenSettings,
+}: BottomToolbarProps) {
+  const [hovered, setHovered] = useState<string | null>(null);
+
+  return (
+    <div style={panelStyle}>
+      <button
+        onClick={onToggleEditMode}
+        onMouseEnter={() => setHovered('edit')}
+        onMouseLeave={() => setHovered(null)}
+        style={
+          isEditMode
+            ? { ...btnActive }
+            : {
+                ...btnBase,
+                background: hovered === 'edit' ? 'var(--pixel-btn-hover-bg)' : btnBase.background,
+              }
+        }
+        title="Edit office layout"
+      >
+        Layout
+      </button>
+      <button
+        onClick={onOpenSettings}
+        onMouseEnter={() => setHovered('settings')}
+        onMouseLeave={() => setHovered(null)}
+        style={{
+          ...btnBase,
+          background: hovered === 'settings' ? 'var(--pixel-btn-hover-bg)' : btnBase.background,
+        }}
+        title="Settings"
+      >
+        Settings
+      </button>
+    </div>
+  );
+}

package/agent/dashboard/src/pixel-engine/components/DebugView.tsx

@@ -0,0 +1,175 @@
+import type { ToolActivity } from '../types.js';
+
+interface DebugViewProps {
+  agents: number[];
+  selectedAgent: number | null;
+  agentTools: Record<number, ToolActivity[]>;
+  agentStatuses: Record<number, string>;
+  subagentTools: Record<number, Record<string, ToolActivity[]>>;
+  onSelectAgent: (id: number) => void;
+}
+
+/** Z-index just below the floating toolbar (50) so the toolbar stays on top */
+const DEBUG_Z = 40;
+
+function ToolDot({ tool }: { tool: ToolActivity }) {
+  return (
+    <span
+      className={tool.done ? undefined : 'pixel-agents-pulse'}
+      style={{
+        width: 6,
+        height: 6,
+        borderRadius: '50%',
+        background: tool.done
+          ? '#89d185'
+          : tool.permissionWait
+            ? '#cca700'
+            : '#3794ff',
+        display: 'inline-block',
+        flexShrink: 0,
+      }}
+    />
+  );
+}
+
+function ToolLine({ tool }: { tool: ToolActivity }) {
+  return (
+    <span
+      style={{
+        fontSize: '22px',
+        opacity: tool.done ? 0.5 : 0.8,
+        display: 'flex',
+        alignItems: 'center',
+        gap: 5,
+      }}
+    >
+      <ToolDot tool={tool} />
+      {tool.permissionWait && !tool.done ? 'Needs approval' : tool.status}
+    </span>
+  );
+}
+
+export function DebugView({
+  agents,
+  selectedAgent,
+  agentTools,
+  agentStatuses,
+  subagentTools,
+  onSelectAgent,
+}: DebugViewProps) {
+  const renderAgentCard = (id: number) => {
+    const isSelected = selectedAgent === id;
+    const tools = agentTools[id] || [];
+    const subs = subagentTools[id] || {};
+    const status = agentStatuses[id];
+    const hasActiveTools = tools.some((t) => !t.done);
+    return (
+      <div
+        key={id}
+        style={{
+          border: `2px solid ${isSelected ? '#5a8cff' : '#4a4a6a'}`,
+          borderRadius: 0,
+          padding: '6px 8px',
+          background: isSelected
+            ? 'rgba(255,255,255,0.04)'
+            : undefined,
+        }}
+      >
+        <span style={{ display: 'inline-flex', alignItems: 'center', gap: 0 }}>
+          <button
+            onClick={() => onSelectAgent(id)}
+            style={{
+              borderRadius: 0,
+              padding: '6px 10px',
+              fontSize: '26px',
+              background: isSelected ? 'rgba(90, 140, 255, 0.25)' : undefined,
+              color: isSelected ? '#fff' : undefined,
+              fontWeight: isSelected ? 'bold' : undefined,
+            }}
+          >
+            Agent #{id}
+          </button>
+        </span>
+        {(tools.length > 0 || status === 'waiting') && (
+          <div
+            style={{
+              display: 'flex',
+              flexDirection: 'column',
+              gap: 1,
+              marginTop: 4,
+              paddingLeft: 4,
+            }}
+          >
+            {tools.map((tool) => (
+              <div key={tool.toolId}>
+                <ToolLine tool={tool} />
+                {subs[tool.toolId] && subs[tool.toolId].length > 0 && (
+                  <div
+                    style={{
+                      borderLeft: '2px solid rgba(255,255,255,0.12)',
+                      marginLeft: 3,
+                      paddingLeft: 8,
+                      marginTop: 1,
+                      display: 'flex',
+                      flexDirection: 'column',
+                      gap: 1,
+                    }}
+                  >
+                    {subs[tool.toolId].map((subTool) => (
+                      <ToolLine key={subTool.toolId} tool={subTool} />
+                    ))}
+                  </div>
+                )}
+              </div>
+            ))}
+            {status === 'waiting' && !hasActiveTools && (
+              <span
+                style={{
+                  fontSize: '22px',
+                  opacity: 0.85,
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 5,
+                }}
+              >
+                <span
+                  style={{
+                    width: 6,
+                    height: 6,
+                    borderRadius: '50%',
+                    background: '#cca700',
+                    display: 'inline-block',
+                    flexShrink: 0,
+                  }}
+                />
+                Might be waiting for input
+              </span>
+            )}
+          </div>
+        )}
+      </div>
+    );
+  };
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        top: 0,
+        left: 0,
+        width: '100%',
+        height: '100%',
+        background: 'var(--pixel-bg)',
+        zIndex: DEBUG_Z,
+        overflow: 'auto',
+      }}
+    >
+      {/* Top padding so cards don't overlap the floating toolbar */}
+      <div style={{ padding: '12px 12px 12px', fontSize: '28px' }}>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 6 }}>
+          {agents.map(renderAgentCard)}
+        </div>
+      </div>
+    </div>
+  );
+}