Upgrade xterm to v6 with improved React integration and configurable database path

.oxlintrc.json

@@ -31,7 +31,10 @@
  // Unicorn — disable noisy ones
  "unicorn/filename-case": "off",
  "unicorn/no-null": "off",
- "unicorn/no-array-for-each": "off"
+ "unicorn/no-array-for-each": "off",
+
+ // Side-effect imports (CSS, polyfills) are intentional
+ "import/no-unassigned-import": "off"
  },
  "ignorePatterns": ["dist/", "node_modules/", "out/", ".agentforge/"]
 }

package.json

@@ -29,9 +29,13 @@
  "@dnd-kit/core": "^6.1.0",
  "@dnd-kit/sortable": "^8.0.0",
  "@dnd-kit/utilities": "^3.2.2",
+ "@fontsource/jetbrains-mono": "^5.2.8",
  "@icons-pack/react-simple-icons": "^13.13.0",
  "@pierre/diffs": "^1.1.15",
  "@tailwindcss/vite": "^4.2.2",
+ "@xterm/addon-attach": "^0.12.0",
+ "@xterm/addon-fit": "^0.11.0",
+ "@xterm/xterm": "^6.0.0",
  "bun": "1.3.11",
  "clsx": "^2.1.1",
  "date-fns": "^3.6.0",
@@ -42,8 +46,7 @@
  "react-router-dom": "^7.14.1",
  "simple-git": "^3.36.0",
  "tailwindcss": "^4.2.2",
- "xterm": "^5.3.0",
- "xterm-addon-fit": "^0.8.0",
+ "zod": "^4.3.6",
  "zustand": "^4.5.5"
  },
  "devDependencies": {

src/backend/db/database.ts

@@ -5,8 +5,9 @@ import { MigrationRunner, SqliteAdapter } from "./migrator.ts";
 import { migrations } from "./migrations/index.ts";
 import type { Agent, RemoteConfig, Ticket } from "../../common/types.ts";
 
-const DB_PATH = join(process.cwd(), ".agentforge/data/agentforge.db");
-mkdirSync(join(process.cwd(), ".agentforge/data"), { recursive: true });
+const BASE_PATH = process.env.REPO_PATH ?? process.cwd();
+const DB_PATH = join(BASE_PATH, ".agentforge/data/agentforge.db");
+mkdirSync(join(BASE_PATH, ".agentforge/data"), { recursive: true });
 
 export const db = new Database(DB_PATH, { create: true });
 

src/backend/ws/hub.ts

@@ -1,9 +1,17 @@
 import type { ServerWebSocket } from "bun";
+import { z } from "zod";
 import { agentStmts } from "../db/index.ts";
 import { agentProcessManager } from "../services/AgentProcessManager.ts";
 import { shellSessionManager } from "../services/ShellSessionManager.ts";
 import { errorMeta, logger } from "../lib/logger.ts";
 
+const sessionResizeSchema = z.object({
+ type: z.literal("resize"),
+ agentId: z.string().min(1),
+ cols: z.number().int().positive(),
+ rows: z.number().int().positive(),
+});
+
 const log = logger.child("ws");
 
 // Global notification subscribers
@@ -50,7 +58,7 @@ export const wsHandlers = {
  open(ws: ServerWebSocket<{ channel: string; agentId?: string }>) {
  const { channel, agentId } = ws.data;
 
- if (channel === "notifications" || channel === "kanban") {
+ if (channel === "notifications" || channel === "kanban" || channel === "session") {
  notificationClients.add(ws);
  return;
  }
@@ -146,48 +154,36 @@ export const wsHandlers = {
  message(ws: ServerWebSocket<{ channel: string; agentId?: string }>, raw: string | Buffer) {
  const { channel, agentId } = ws.data;
 
- if (channel === "shell" && agentId) {
+ if (channel === "agent" && agentId) {
+ agentProcessManager.write(agentId, String(raw));
+ } else if (channel === "shell" && agentId) {
+ shellSessionManager.write(agentId, String(raw));
+ } else if (channel === "session") {
+ let parsed: unknown;
  try {
- const msg = JSON.parse(String(raw)) as {
- type: string;
- data?: string;
- cols?: number;
- rows?: number;
- };
- if (msg.type === "input" && msg.data) {
- shellSessionManager.write(agentId, msg.data);
- } else if (msg.type === "resize" && msg.cols && msg.rows) {
- shellSessionManager.resize(agentId, msg.cols, msg.rows);
- }
+ parsed = JSON.parse(String(raw));
  } catch {
- shellSessionManager.write(agentId, String(raw));
+ log.warn("session: invalid JSON in message", { raw: String(raw) });
+ return;
  }
- return;
- }
-
- if (channel !== "agent" || !agentId) return;
-
- try {
- const msg = JSON.parse(String(raw)) as {
- type: string;
- data?: string;
- cols?: number;
- rows?: number;
- };
- if (msg.type === "input" && msg.data) {
- agentProcessManager.write(agentId, msg.data);
- } else if (msg.type === "resize" && msg.cols && msg.rows) {
- agentProcessManager.resize(agentId, msg.cols, msg.rows);
+ const result = sessionResizeSchema.safeParse(parsed);
+ if (!result.success) {
+ log.warn("session: invalid resize payload", {
+ raw: String(raw),
+ errors: result.error.issues,
+ });
+ return;
  }
- } catch {
- agentProcessManager.write(agentId, String(raw));
+ const { agentId: targetId, cols, rows } = result.data;
+ agentProcessManager.resize(targetId, cols, rows);
+ shellSessionManager.resize(targetId, cols, rows);
  }
  },
 
  close(ws: ServerWebSocket<{ channel: string; agentId?: string }>) {
  const { channel, agentId } = ws.data;
 
- if (channel === "notifications" || channel === "kanban") {
+ if (channel === "notifications" || channel === "kanban" || channel === "session") {
  notificationClients.delete(ws);
  return;
  }

src/frontend/App.tsx

@@ -6,7 +6,7 @@ import { KanbanBoard } from "./components/kanban-board/KanbanBoard";
 import { ShellTerminal } from "./components/ShellTerminal";
 import { Header } from "./components/layout/Header";
 import { NotificationToast } from "./components/NotificationToast";
-import { useNotificationWebSocket } from "./hooks/useWebSocket";
+import { SessionSocketProvider } from "./hooks/useSessionSocket";
 import { AgentPage } from "./pages/AgentPage";
 import { registerNavigate, useStore } from "./store";
 
@@ -43,8 +43,6 @@ function KanbanPage() {
 export function App() {
  const { fetchTickets } = useStore();
 
- useNotificationWebSocket();
-
  useEffect(() => {
  fetchTickets();
  }, [fetchTickets]);
@@ -53,12 +51,12 @@ export function App() {
  const agentElement = useMemo(() => <AgentPage />, []);
 
  return (
- <>
+ <SessionSocketProvider>
  <NavigateFnRegistrar />
  <Routes>
  <Route path="/" element={kanbanElement} />
  <Route path="/agent/:ticketId" element={agentElement} />
  </Routes>
- </>
+ </SessionSocketProvider>
  );
 }

src/frontend/components/AgentTerminalPanel.tsx

@@ -1,20 +1,19 @@
 import { Terminal as TerminalIcon } from "lucide-react";
-import { useXTerm } from "../hooks/useXTerm";
+import { useForgeTerminal } from "../hooks/useForgeTerminal";
 
 interface AgentTerminalPanelProps {
  agentId: string;
 }
 
 export function AgentTerminalPanel({ agentId }: AgentTerminalPanelProps) {
- const { containerRef } = useXTerm(`/ws/agent/${agentId}`);
+ const { containerRef } = useForgeTerminal(`/ws/agent/${agentId}`);
 
  return (
  <div className="flex flex-col flex-1">
  <div className="px-3 py-1.5 border-b border-r border-forge-border flex items-center gap-2 flex-shrink-0 bg-forge-panel">
  <TerminalIcon size={11} className="text-forge-text-muted" />
  <span className="text-forge-text-muted text-xs uppercase tracking-widest">TERMINAL</span>
  </div>
-
  <div className="flex-1 overflow-hidden border-r border-forge-border bg-forge-black p-1">
  <div ref={containerRef} className="w-full h-full" />
  </div>

src/frontend/components/ShellTerminal.tsx

@@ -1,7 +1,7 @@
 import { useEffect, useState } from "react";
 import { X, TerminalSquare, FolderOpen } from "lucide-react";
 import { api } from "../lib/api";
-import { useXTerm } from "../hooks/useXTerm";
+import { useForgeTerminal } from "../hooks/useForgeTerminal";
 
 interface ShellTerminalProps {
  onClose: () => void;
@@ -10,7 +10,7 @@ interface ShellTerminalProps {
 export function ShellTerminal({ onClose }: ShellTerminalProps) {
  const [wsUrl, setWsUrl] = useState<string | null>(null);
  const [cwd, setCwd] = useState("");
- const { containerRef } = useXTerm(wsUrl);
+ const { containerRef } = useForgeTerminal(wsUrl);
 
  useEffect(() => {
  let cancelled = false;
@@ -35,14 +35,12 @@ export function ShellTerminal({ onClose }: ShellTerminalProps) {
  };
  }, []);
 
- // Shorten the cwd for display — show last 2 path segments
  const displayCwd = cwd
  ? cwd.replace(/^.*?\/([^/]+\/[^/]+)\/?$/, "$1").replace(/^.*\/([^/]+)\/?$/, "$1") || cwd
  : "";
 
  return (
  <div className="fixed bottom-0 left-0 right-0 h-[42vh] min-h-[200px] bg-forge-black border-t-2 border-forge-accent z-50 flex flex-col animate-slide-in-bottom shadow-[0_-8px_32px_rgba(0,0,0,0.8)]">
- {/* Drag handle / header */}
  <div className="flex items-center justify-between px-4 h-8 flex-shrink-0 bg-forge-panel border-b border-forge-border select-none">
  <div className="flex items-center gap-2.5 min-w-0">
  <TerminalSquare size={13} className="text-forge-accent flex-shrink-0" />
@@ -69,8 +67,6 @@ export function ShellTerminal({ onClose }: ShellTerminalProps) {
  <X size={13} />
  </button>
  </div>
-
- {/* Terminal container */}
  <div className="flex-1 overflow-hidden bg-forge-black p-1">
  <div ref={containerRef} className="w-full h-full" />
  </div>

src/frontend/hooks/useForgeTerminal.ts

@@ -0,0 +1,88 @@
+import { useEffect, useMemo, type RefObject } from "react";
+import { AttachAddon } from "@xterm/addon-attach";
+import { FitAddon } from "@xterm/addon-fit";
+import { useXTerm } from "./useXTerm";
+import { useSessionSocket } from "./useSessionSocket";
+import { TERMINAL_OPTIONS } from "../lib/terminalConfig";
+
+export function useForgeTerminal(wsUrl: string | null): {
+ containerRef: RefObject<HTMLDivElement>;
+} {
+ const fitAddon = useMemo(() => new FitAddon(), []);
+ const { ref, instance } = useXTerm(TERMINAL_OPTIONS);
+ const { send } = useSessionSocket();
+
+ // terminalId is the last path segment: /ws/agent/<id> or /ws/shell/<id>
+ const parts = wsUrl?.split("/");
+ const terminalId = parts ? parts[parts.length - 1] : null;
+
+ // Load FitAddon once when terminal is ready
+ useEffect(() => {
+ if (!instance) return;
+ instance.loadAddon(fitAddon);
+ }, [instance, fitAddon]);
+
+ // ResizeObserver → fit + send resize over session channel
+ useEffect(() => {
+ if (!instance || !ref.current) return;
+ const container = ref.current;
+ const safeFit = () => {
+ try {
+ fitAddon.fit();
+ } catch {}
+ };
+ const observer = new ResizeObserver(() => {
+ safeFit();
+ if (terminalId) {
+ send({ type: "resize", agentId: terminalId, cols: instance.cols, rows: instance.rows });
+ }
+ });
+ observer.observe(container);
+ requestAnimationFrame(safeFit);
+ return () => observer.disconnect();
+ }, [instance, ref, fitAddon, send, terminalId]);
+
+ // Data WS — AttachAddon owns it entirely (pure raw PTY)
+ useEffect(() => {
+ if (!wsUrl || !instance) return;
+ let disposed = false;
+ let attachAddon: AttachAddon | null = null;
+ let dataSocket: WebSocket | null = null;
+ let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+ const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
+
+ const connect = () => {
+ if (disposed) return;
+ const ws = new WebSocket(`${protocol}//${window.location.host}${wsUrl}`);
+ dataSocket = ws;
+
+ ws.addEventListener("open", () => {
+ instance.clear();
+ attachAddon?.dispose();
+ attachAddon = new AttachAddon(ws);
+ instance.loadAddon(attachAddon);
+ });
+ ws.addEventListener("close", () => {
+ attachAddon?.dispose();
+ attachAddon = null;
+ instance.write("\r\n\x1b[33m[disconnected]\x1b[0m\r\n");
+ if (!disposed) reconnectTimer = setTimeout(connect, 3000);
+ });
+ ws.addEventListener("error", () => {
+ instance.write("\r\n\x1b[31m[connection error]\x1b[0m\r\n");
+ });
+ };
+
+ connect();
+
+ return () => {
+ disposed = true;
+ if (reconnectTimer !== null) clearTimeout(reconnectTimer);
+ attachAddon?.dispose();
+ dataSocket?.close();
+ };
+ }, [wsUrl, instance]);
+
+ return { containerRef: ref as RefObject<HTMLDivElement> };
+}