agello 0.3.0 → 0.4.2

package/README.md

@@ -5,16 +5,17 @@
 - Chat with the agent from a web page; terminal input, browser input and agent replies are shown as separate bubbles
 - Live session status, tool activity, and prompts queued while the agent is busy (same order as the terminal)
 - Conversation saved per pane in the browser, kept across reloads
+- Interactive terminal view of the existing herdr pane: live cursor, keyboard input, and automatic resize
 - Optional live view of a `terminal-browser` screen, with an on/off switch to control it yourself
 - Annotate: point at an element on that screen and send a request about it, with its CSS selector
 - Embeddable `<agent-bridge>` web component
 
-Currently supports **Claude Code** sessions.
+Chat currently supports **Claude Code** sessions. The terminal view connects directly to the pane, including ordinary shells and other terminal applications.
 
 ## Requirements
 
 - [Bun](https://bun.sh) >= 1.1
-- [herdr](https://herdr.dev) (the agent must run inside a herdr pane)
+- [herdr](https://herdr.dev) (the agent must run inside a herdr pane); interactive terminal view requires `herdr terminal session control`
 - Optional: `terminal-browser` for the screen panel
 
 ## Install
@@ -89,6 +90,20 @@ Selector: nearest unique `id` / `data-testid` ancestor, then `tag:nth-of-type` s
 
 State and logs: `~/.local/state/agello/<port>.json`, `<port>.log`.
 
+### Pane picker
+
+Click the status in the header to open a drawer with herdr's workspace -> tab -> pane tree (the current pane's workspace is expanded; a workspace with a single tab lists its panes directly). Search filters by workspace, title, folder, or agent. Picking a pane switches the page to that pane's server, starting it if needed (`?server=` keeps the choice across reloads). Panes without Claude Code open as a terminal, since chat supports Claude Code only.
+
+`+` adds a workspace (top), a tab (workspace row), or splits a pane (pane row); new panes open as a terminal. Nothing can be closed from the page: closing a herdr pane ends its processes.
+
+### Interactive terminal
+
+Click the terminal icon in the header to replace the chat with the pane's live terminal (the screen panel stays). Keyboard input (including Korean text, arrow keys, and Ctrl+C) goes directly to that terminal. The viewport follows the browser size, and the mouse wheel scrolls through Herdr. Click the icon again or close the page to release control; the pane and its process keep running. If disconnected, use **다시 연결** to restore the current screen.
+
+Only one browser connection can control a pane through this server at a time. Agello never forcibly takes over another Herdr controller. While connected, resizing the browser also changes the source terminal size. Terminal input is raw input, without the chat's `[browser]` prefix.
+
+The xterm.js renderer and its styles are served locally; no terminal CDN is required. Herdr sends an initial ANSI screen and subsequent frame updates over the WebSocket, including cursor state. Terminal frames are not stored in browser chat history.
+
 ### Presentation mode
 
 `agello present x,y,w,h` (CSS px of the browser's visible viewport; omit for the whole screen):
@@ -142,11 +157,17 @@ See `web/embed-example.html`.
 - **Send**: `herdr agent prompt <pane> "<text>"` (kept to 3 lines so Claude Code does not treat it as a paste)
 - **Status**: `herdr agent get` / `herdr pane get`, polled every 1.5s
 - **Chat**: tails the Claude Code transcript (`$CLAUDE_CONFIG_DIR/projects/*/<session>.jsonl`) and streams it over SSE
+- **Panes**: `GET /panes` (`herdr workspace/tab/pane list`), `POST /panes/connect` (`agello start --pane`), `POST /panes/create` (`herdr workspace create`, `tab create`, `pane split`, always `--no-focus`)
+- **Terminal**: `/terminal` WebSocket relays `herdr terminal session control <pane>` ANSI frames and validated input, resize, and scroll commands to xterm.js
 - **Screen**: finds the terminal-browser CDP port via `terminal-browser ls --json` and relays `Page.startScreencast` frames; user control forwards `Input.*` events only
 
 ## Security
 
-The server listens on `127.0.0.1` only. Data and input endpoints accept requests from the same origin and `localhost` pages only; other origins get `403` unless added with `--allow-origin`. Anything allowed to post to `/send` can type into your agent session, so keep the allow list short.
+The server listens on `127.0.0.1` only. Data and input endpoints accept requests from the same origin and `localhost` pages only; other origins get `403` unless added with `--allow-origin`. Allowed origins can send chat prompts and connect to `/terminal` to type directly into the pane, so keep the allow list short.
+
+## Development
+
+Run `bun install` and `bun test`. Tests cover the pane tree and creation (against a mock herdr), local terminal assets, origin rejection, ANSI frames, keyboard bytes, resize, exclusive control, and reconnect.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agello",
-  "version": "0.3.0",
+  "version": "0.4.2",
   "description": "Talk to a coding agent in a herdr pane from the browser: chat, live status, and a shared browser screen.",
   "keywords": [
     "herdr",
@@ -31,5 +31,9 @@
   "engines": {
     "bun": ">=1.1"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "@xterm/addon-fit": "0.11.0",
+    "@xterm/xterm": "6.0.0"
+  }
 }

package/src/panes.ts

@@ -0,0 +1,86 @@
+// herdr workspace -> tab -> pane tree, creation, and switching to a pane's own
+// agello server (one server per pane; started on demand through the CLI).
+// Deliberately no close/delete: closing a herdr pane kills its processes.
+
+import { join } from "node:path";
+import { run, runJson } from "./run.ts";
+
+const CLI = join(import.meta.dir, "..", "bin", "agello.ts");
+const ID = /^[A-Za-z0-9]+:[A-Za-z0-9]+$/; // herdr ids: w23, w23:t1, w23:p3
+const WS_ID = /^[A-Za-z0-9]+$/;
+
+// Resolve herdr on the current PATH (Bun.spawn uses the PATH from process start).
+const bin = () => Bun.which("herdr", { PATH: process.env.PATH }) ?? "herdr";
+const herdr = async (...cmd: string[]) => (await runJson([bin(), ...cmd], 5000)) ?? { error: { code: "herdr_failed" } };
+
+export type TreePane = { id: string; agent?: string; status: string; title?: string; cwd?: string; focused: boolean };
+export type TreeTab = { id: string; label: string; number: number; panes: TreePane[] };
+export type TreeWorkspace = { id: string; label: string; number: number; tabs: TreeTab[] };
+
+export async function paneTree(): Promise<TreeWorkspace[] | null> {
+  const [w, t, p] = await Promise.all([herdr("workspace", "list"), herdr("tab", "list"), herdr("pane", "list")]);
+  if (!w.result || !t.result || !p.result) return null;
+  const tabs = new Map<string, TreeTab>();
+  for (const tab of t.result.tabs)
+    tabs.set(tab.tab_id, { id: tab.tab_id, label: tab.label, number: tab.number, panes: [] });
+  for (const pane of p.result.panes)
+    tabs.get(pane.tab_id)?.panes.push({
+      id: pane.pane_id,
+      agent: pane.agent,
+      status: pane.agent_status,
+      title: pane.terminal_title_stripped || undefined,
+      cwd: pane.foreground_cwd || pane.cwd,
+      focused: pane.focused,
+    });
+  return w.result.workspaces.map((ws: any) => ({
+    id: ws.workspace_id,
+    label: ws.label,
+    number: ws.number,
+    tabs: t.result.tabs
+      .filter((tab: any) => tab.workspace_id === ws.workspace_id)
+      .map((tab: any) => tabs.get(tab.tab_id)!),
+  }));
+}
+
+const text = (v: unknown, max = 200) => (typeof v === "string" && v.trim() && v.length <= max ? v.trim() : undefined);
+const fail = (error: string, status = 400) => Response.json({ ok: false, error }, { status });
+
+// POST /panes/connect {pane} -> {ok, url}: the pane's server, started if needed.
+async function connect(pane: unknown): Promise<Response> {
+  if (typeof pane !== "string" || !ID.test(pane)) return fail("invalid_pane");
+  if (!(await herdr("pane", "get", pane)).result) return fail("pane_not_found", 404);
+  const out = await run([process.execPath, CLI, "start", "--pane", pane], 20000);
+  const url = out?.match(/https?:\/\/127\.0\.0\.1:\d+/)?.[0];
+  return url ? Response.json({ ok: true, pane, url }) : fail("server_start_failed", 502);
+}
+
+// POST /panes/create {kind: workspace|tab|pane, ...} -> {ok, pane}: the new root pane.
+async function create(d: any): Promise<Response> {
+  const cwd = text(d.cwd, 1024);
+  if (cwd && !cwd.startsWith("/")) return fail("invalid_cwd");
+  const label = text(d.label, 80);
+  const opt = [...(cwd ? ["--cwd", cwd] : []), ...(label ? ["--label", label] : []), "--no-focus"];
+  let res: any;
+  if (d.kind === "workspace") res = await herdr("workspace", "create", ...opt);
+  else if (d.kind === "tab") {
+    if (typeof d.workspace !== "string" || !WS_ID.test(d.workspace)) return fail("invalid_workspace");
+    res = await herdr("tab", "create", "--workspace", d.workspace, ...opt);
+  } else if (d.kind === "pane") {
+    if (typeof d.pane !== "string" || !ID.test(d.pane)) return fail("invalid_pane");
+    if (d.direction !== "right" && d.direction !== "down") return fail("invalid_direction");
+    res = await herdr("pane", "split", d.pane, "--direction", d.direction, ...(cwd ? ["--cwd", cwd] : []), "--no-focus");
+  } else return fail("invalid_kind");
+  const pane = res.result?.root_pane?.pane_id ?? res.result?.pane?.pane_id;
+  return pane ? Response.json({ ok: true, pane }) : fail(res.error?.code ?? "herdr_failed", 502);
+}
+
+export async function panesRoute(req: Request, path: string, current: string): Promise<Response | null> {
+  if (path === "/panes" && req.method === "GET") {
+    const tree = await paneTree();
+    return tree ? Response.json({ ok: true, current, workspaces: tree }) : fail("herdr_failed", 502);
+  }
+  if (req.method !== "POST" || (path !== "/panes/connect" && path !== "/panes/create")) return null;
+  const d = (await req.json().catch(() => null)) as any;
+  if (!d || typeof d !== "object") return fail("invalid_body");
+  return path === "/panes/connect" ? connect(d.pane) : create(d);
+}

package/src/server.ts

@@ -4,9 +4,15 @@
 // GET  /agent-bridge.js  <agent-bridge> web component
 // GET  /status           session liveness (herdr agent get + pane get)
 // GET  /events           SSE: status, chat messages, tool start/end (from transcript JSONL)
-// POST /send             {action, text} -> herdr agent prompt
+// POST /send             {action, text, images?: [{type, data(base64)}]} -> herdr agent prompt
+//                        (images are saved to $TMPDIR/agello-uploads and sent as [image: <path>])
 //                        (action "annotate": + target {selector, label, rect, text?, url?} from inspect)
 // GET  /screen           SSE: terminal-browser screen frames (CDP screencast)
+// POST /upload           {images: [{type, data(base64)}]} -> {paths}: terminal image paste
+// WS   /terminal         interactive herdr terminal frames, keyboard input, resize
+// GET  /panes            herdr workspace -> tab -> pane tree
+// POST /panes/connect    {pane} -> url of that pane's server (started if needed)
+// POST /panes/create     {kind: workspace|tab|pane, cwd?, label?, workspace?, pane?, direction?}
 // WS   /input            user control: CDP Input.* commands forwarded to the page;
 //                        {id, inspect: {x, y} | {selector}, full?} -> {id, result}: element at a point (annotation)
 // GET  /present          presentation state
@@ -17,7 +23,10 @@
 // POST /script           {script: {rect?, steps: [{go?, say: string[], hold?}]}} load (keeps position)
 // POST /player           {cmd: "resume" | "pause" | "goto", at?: "3" | "3.2"}
 
-import { homedir } from "node:os";
+import { createTerminal, type SocketData } from "./terminal.ts";
+import { panesRoute } from "./panes.ts";
+import { mkdir } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
 import { join } from "node:path";
 import { runJson } from "./run.ts";
 import { createPlayer, parsePos, parseScript, type PlayerInfo } from "./player.ts";
@@ -32,6 +41,30 @@ export type ServerOptions = {
 };
 
 export const BROWSER_PREFIX = "[browser]";
+const UPLOAD_DIR = join(tmpdir(), "agello-uploads");
+const IMAGE_EXT: Record<string, string> = { "image/png": "png", "image/jpeg": "jpg", "image/gif": "gif", "image/webp": "webp" };
+const MAX_IMAGES = 5;
+const MAX_IMAGE_BYTES = 10 * 1024 * 1024;
+
+// Save pasted/dropped chat images so the agent can open them by path
+// (herdr agent prompt carries text only). null: invalid input.
+export async function saveImages(list: unknown): Promise<string[] | null> {
+  if (list === undefined) return [];
+  if (!Array.isArray(list) || list.length > MAX_IMAGES) return null;
+  const files = list.map((img: any) => {
+    const ext = IMAGE_EXT[img?.type];
+    if (!ext || typeof img.data !== "string") return null;
+    const bytes = Buffer.from(img.data, "base64");
+    return bytes.length && bytes.length <= MAX_IMAGE_BYTES ? { ext, bytes } : null;
+  });
+  if (files.includes(null)) return null;
+  await mkdir(UPLOAD_DIR, { recursive: true, mode: 0o700 });
+  return Promise.all(files.map(async (f) => {
+    const path = join(UPLOAD_DIR, `${crypto.randomUUID()}.${f!.ext}`);
+    await Bun.write(path, f!.bytes);
+    return path;
+  }));
+}
 const WEB_DIR = join(import.meta.dir, "..", "web");
 
 // ---------- pure helpers ----------
@@ -125,6 +158,12 @@ export async function startServer(opts: ServerOptions) {
   const HTML = Bun.file(join(WEB_DIR, "index.html"));
   const COMPONENT = Bun.file(join(WEB_DIR, "agent-bridge.js"));
 
+  const terminal = createTerminal(PANE);
+  const bundle = await Bun.build({ entrypoints: [join(WEB_DIR, "terminal.js")], target: "browser", minify: true });
+  if (!bundle.success) throw new Error(`Terminal bundle failed: ${bundle.logs.join("\n")}`);
+  const terminalJS = await bundle.outputs[0].text();
+  const terminalCSS = Bun.file(new URL(import.meta.resolve("@xterm/xterm/css/xterm.css")));
+
   const agentInfo = async (): Promise<any | null> =>
     (await herdr(3000, "agent", "get", PANE))?.result?.agent ?? null;
 
@@ -324,7 +363,8 @@ export async function startServer(opts: ServerOptions) {
 
   const screen = createScreencast({
     browserKey: opts.browser,
-    herdrTab: async () => (await agentInfo())?.tab_id,
+    // shell panes have no agent: fall back to the pane's own tab
+    herdrTab: async () => (await agentInfo())?.tab_id ?? (await herdr(3000, "pane", "get", PANE))?.result?.pane?.tab_id,
   });
 
   // ----- presentation mode -----
@@ -482,7 +522,7 @@ export async function startServer(opts: ServerOptions) {
   }
 
   async function sendPrompt(req: Request): Promise<Response> {
-    const data = (await req.json().catch(() => ({}))) as { action?: string; text?: string; target?: Inspected };
+    const data = (await req.json().catch(() => ({}))) as { action?: string; text?: string; images?: unknown; target?: Inspected };
     const action = /^[\w-]{1,32}$/.test(data.action ?? "") ? data.action! : "message";
     let text = data.text ?? "";
     if (action === "annotate") {
@@ -497,11 +537,18 @@ export async function startServer(opts: ServerOptions) {
       const at = where();
       if (at) text += ` (대본 정지: ${at})`;
     }
+    const images = await saveImages(data.images);
+    if (!images) return Response.json({ ok: false, error: "invalid_images" }, { status: 400 });
+    text = [text, ...images.map((p) => `[image: ${p}]`)].join("\n");
     const r = await promptAgent(action, text);
     return r.ok ? Response.json({ ok: true }) : Response.json({ ok: false, error: r.error }, { status: r.status });
   }
 
   async function route(req: Request, url: URL): Promise<Response> {
+    if (url.pathname.startsWith("/panes")) {
+      const res = await panesRoute(req, url.pathname, PANE);
+      if (res) return res;
+    }
     switch (url.pathname) {
       case "/status":
         return Response.json({
@@ -514,6 +561,10 @@ export async function startServer(opts: ServerOptions) {
         return events();
       case "/screen":
         return screen.handle();
+      case "/terminal.js":
+        return new Response(terminalJS, { headers: { "Content-Type": "text/javascript; charset=utf-8" } });
+      case "/terminal.css":
+        return new Response(terminalCSS, { headers: { "Content-Type": "text/css; charset=utf-8" } });
       case "/agent-bridge.js":
         return new Response(COMPONENT, {
           headers: { "Content-Type": "text/javascript; charset=utf-8", "Cache-Control": "no-store" },
@@ -521,6 +572,13 @@ export async function startServer(opts: ServerOptions) {
       case "/send":
         if (req.method === "POST") return sendPrompt(req);
         break;
+      case "/upload":
+        if (req.method === "POST") {
+          const data = (await req.json().catch(() => ({}))) as { images?: unknown };
+          const paths = data.images === undefined ? null : await saveImages(data.images);
+          return paths ? Response.json({ ok: true, paths }) : Response.json({ ok: false, error: "invalid_images" }, { status: 400 });
+        }
+        break;
       case "/present":
         return req.method === "POST" ? presentRequest(req) : Response.json(presentView());
       case "/script":
@@ -532,13 +590,16 @@ export async function startServer(opts: ServerOptions) {
     return new Response(HTML, { headers: { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-store" } });
   }
 
-  const server = Bun.serve({
+  const server = Bun.serve<SocketData>({
     hostname: "127.0.0.1",
     port: opts.port,
     idleTimeout: 0, // keep SSE open
     websocket: {
+      maxPayloadLength: 128 * 1024,
+      open(ws) { if (ws.data.kind === "terminal") terminal.open(ws); },
       async message(ws, msg) {
         const raw = String(msg);
+        if (ws.data.kind === "terminal") return terminal.message(ws, raw);
         let m: any;
         try {
           m = JSON.parse(raw);
@@ -556,11 +617,12 @@ export async function startServer(opts: ServerOptions) {
         }
         screen.input(raw);
       },
+      close(ws) { if (ws.data.kind === "terminal") terminal.close(ws); },
     },
     async fetch(req, server) {
       const url = new URL(req.url);
       const origin = req.headers.get("Origin");
-      const isScript = url.pathname === "/agent-bridge.js";
+      const isScript = ["/agent-bridge.js", "/terminal.js", "/terminal.css"].includes(url.pathname);
 
       // The component script itself is public; data and input endpoints are origin-checked.
       if (!isScript && !originAllowed(origin, url.origin))
@@ -579,8 +641,9 @@ export async function startServer(opts: ServerOptions) {
           origin,
         );
 
-      if (url.pathname === "/input")
-        return server.upgrade(req) ? undefined : new Response("websocket required", { status: 426 });
+      if (url.pathname === "/input" || url.pathname === "/terminal")
+        return server.upgrade(req, { data: { kind: url.pathname === "/terminal" ? "terminal" : "screen" } })
+          ? undefined : new Response("websocket required", { status: 426 });
 
       const res = await route(req, url);
       return isScript ? (res.headers.set("Access-Control-Allow-Origin", "*"), res) : withCors(res, origin);
@@ -593,6 +656,7 @@ export async function startServer(opts: ServerOptions) {
     session: SESSION,
     transcript,
     stop() {
+      terminal.stop();
       timers.forEach(clearInterval);
       server.stop(true);
     },

package/src/terminal.ts

@@ -0,0 +1,122 @@
+import type { ServerWebSocket } from "bun";
+
+export type SocketData = { kind: "screen" | "terminal" };
+type Socket = ServerWebSocket<SocketData>;
+const MAX_MESSAGE = 128 * 1024;
+
+// The CLI owns Herdr's socket handshake and emits ordered ANSI frame envelopes.
+// Never use --takeover: another controller must release its session first.
+export function createTerminal(pane: string) {
+  let owner: Socket | null = null;
+  let childProcess: ReturnType<typeof Bun.spawn> | null = null;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  function close(ws: Socket) {
+    if (owner !== ws) return;
+    owner = null;
+    clearTimeout(timer);
+    const child = childProcess;
+    childProcess = null;
+    if (child) {
+      try { (child.stdin as any).end(); } catch {}
+      child.kill(); // Disconnect only; Herdr keeps the underlying pane alive.
+    }
+  }
+
+  function fail(ws: Socket, message: string) {
+    ws.send(JSON.stringify({ type: "terminal.error", message }));
+    close(ws);
+    ws.close(1011, "Terminal disconnected");
+  }
+
+  function send(ws: Socket, frame: unknown) {
+    if (owner !== ws) return;
+    if (ws.getBufferedAmount() > 4 * 1024 * 1024) {
+      fail(ws, "연결이 느려 터미널을 닫았습니다. 다시 연결해 주세요.");
+      return;
+    }
+    ws.send(JSON.stringify(frame));
+  }
+
+  async function pump(ws: Socket, child: ReturnType<typeof Bun.spawn>) {
+    let pending = "";
+    let stderr = "";
+    let received = false;
+    const readError = (async () => {
+      for await (const chunk of child.stderr as ReadableStream<Uint8Array>) {
+        stderr = (stderr + new TextDecoder().decode(chunk)).slice(-2000);
+      }
+    })();
+    try {
+      const decoder = new TextDecoder();
+      for await (const chunk of child.stdout as ReadableStream<Uint8Array>) {
+        if (owner !== ws) break;
+        pending += decoder.decode(chunk, { stream: true });
+        if (pending.length > 8 * 1024 * 1024) throw new Error("Terminal frame too large");
+        let end: number;
+        while ((end = pending.indexOf("\n")) >= 0) {
+          const line = pending.slice(0, end);
+          pending = pending.slice(end + 1);
+          if (!line.trim()) continue;
+          const frame = JSON.parse(line);
+          if (frame.type === "terminal.frame" && frame.encoding === "ansi") {
+            if (!received) { received = true; clearTimeout(timer); }
+            send(ws, frame);
+          } else if (frame.type === "terminal.closed") {
+            fail(ws, frame.reason || "터미널 연결이 종료되었습니다.");
+          }
+        }
+      }
+      await child.exited;
+      await readError;
+      if (owner === ws) fail(ws, stderr.trim() || "터미널 연결이 종료되었습니다. 다시 연결해 주세요.");
+    } catch {
+      if (owner === ws) fail(ws, "터미널 스트림을 읽을 수 없습니다.");
+    }
+  }
+
+  return {
+    open(ws: Socket) {
+      if (owner) {
+        ws.send(JSON.stringify({ type: "terminal.error", message: "다른 브라우저가 터미널을 사용 중입니다." }));
+        ws.close(1008, "Terminal busy");
+        return;
+      }
+      owner = ws;
+      timer = setTimeout(() => fail(ws, "터미널 연결 시간이 초과되었습니다."), 10000);
+    },
+    message(ws: Socket, raw: string) {
+      if (owner !== ws) return;
+      try {
+        if (raw.length > MAX_MESSAGE) throw new Error("Message too large");
+        const msg = JSON.parse(raw);
+        const size = () => Number.isInteger(msg.cols) && Number.isInteger(msg.rows)
+          && msg.cols >= 2 && msg.cols <= 500 && msg.rows >= 2 && msg.rows <= 300;
+        if (msg.type === "terminal.start" && !childProcess && size()) {
+          childProcess = Bun.spawn([Bun.which("herdr", { PATH: process.env.PATH }) ?? "herdr", "terminal", "session", "control", pane,
+            "--cols", String(msg.cols), "--rows", String(msg.rows)],
+          { stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+          void pump(ws, childProcess);
+          return;
+        }
+        if (!childProcess) throw new Error("Terminal not started");
+        let command: object;
+        if (msg.type === "terminal.input" && typeof msg.text === "string" && msg.text.length <= 65536) {
+          command = { type: msg.type, text: msg.text };
+        } else if (msg.type === "terminal.resize" && size()) {
+          command = { type: msg.type, cols: msg.cols, rows: msg.rows };
+        } else if (msg.type === "terminal.scroll" && ["up", "down"].includes(msg.direction)
+            && Number.isInteger(msg.lines) && msg.lines > 0 && msg.lines <= 100) {
+          command = { type: msg.type, direction: msg.direction, lines: msg.lines };
+        } else throw new Error("Invalid terminal message");
+        const input = childProcess.stdin as Bun.FileSink;
+        if (input.write(JSON.stringify(command) + "\n") > 1024 * 1024) throw new Error("Input overflow");
+        input.flush();
+      } catch {
+        fail(ws, "터미널 요청을 처리할 수 없습니다.");
+      }
+    },
+    close,
+    stop() { if (owner) close(owner); },
+  };
+}

package/web/agent-bridge.js

@@ -27,6 +27,12 @@
 //                  (tool calls are also kept in the conversation as one-line rows, like the terminal)
 //   agent-screen   detail: { connected, browser?, url?, title?, agentControlled? }
 //   agent-present  detail: { on, rect?: {x,y,w,h}, since? }
+//   agent-pane     detail: { pane, server }  another pane was picked in the drawer (server attribute changed)
+//
+// Pane picker
+//   Clicking the status in the header opens a drawer with herdr's workspace -> tab -> pane tree.
+//   Picking a pane switches to that pane's own server (started on demand). Workspaces, tabs and
+//   panes can be added there; nothing is closed from the page (closing kills the pane's processes).
 //
 // Presentation mode (started by the agent: `agello present [x,y,w,h]`)
 //   The screen panel expands to fill the window and shows only the given
@@ -44,7 +50,7 @@
 //   is working (e.g. answering a question), a small loader is shown.
 //
 // Methods
-//   el.send(text, action = 'message', extra) -> Promise<{ok, error?}>  (extra: e.g. {target} for annotate)
+//   el.send(text, action = 'message', extra) -> Promise<{ok, error?}>  (extra: {images: [{type, data (base64)}]}, {target} for annotate)
 //   el.clearHistory()                  clear saved chat for the current pane
 //   el.stopPresent()                   end presentation mode, tell the agent -> Promise<{ok, error?, notified?}>
 
@@ -79,6 +85,57 @@ const ACTIONS = {
 };
 
 const CSS = `
+.pane-btn { display: inline-flex; align-items: center; gap: 7px; padding: 3px 10px; border-radius: 999px; font-size: 12px;
+            color: var(--_muted); max-width: 46cqi; }
+.pane-btn .state { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.pane-btn .dot { flex: none; }
+.drawer-backdrop { display: none; position: absolute; inset: 0; z-index: 20; background: rgb(0 0 0 / .25); }
+.drawer { position: absolute; top: 0; right: 0; bottom: 0; z-index: 21; width: min(360px, 92%); display: flex;
+          flex-direction: column; background: var(--_panel); border-left: 1px solid var(--_line);
+          box-shadow: -8px 0 24px rgb(0 0 0 / .18); transform: translateX(100%); visibility: hidden;
+          transition: transform .18s ease, visibility 0s .18s; }
+:host([panes-open]) .drawer { transform: none; visibility: visible; transition: transform .18s ease; }
+:host([panes-open]) .drawer-backdrop { display: block; }
+.drawer-head { display: flex; gap: 6px; align-items: center; padding: 10px 12px; border-bottom: 1px solid var(--_line); }
+.drawer-head strong { font-size: 13px; margin-right: auto; }
+.icon-btn { padding: 1px 8px; border-radius: 6px; font-size: 14px; line-height: 1.5; }
+.pane-filter { width: 100%; padding: 5px 9px; font: inherit; font-size: 12px; border: 1px solid var(--_line);
+               border-radius: 7px; background: var(--_bg); color: var(--_text); }
+.drawer-search { padding: 8px 12px; border-bottom: 1px solid var(--_line); }
+.add-form { display: grid; gap: 6px; padding: 10px 12px; border-bottom: 1px solid var(--_line); font-size: 12px; }
+.add-form[hidden] { display: none; }
+.add-form .add-title { font-weight: 600; }
+.add-form input, .add-form select { padding: 4px 8px; font: inherit; border: 1px solid var(--_line); border-radius: 6px;
+                                    background: var(--_bg); color: var(--_text); }
+.add-form .add-row { display: flex; gap: 6px; justify-content: flex-end; }
+.tree { flex: 1; overflow: auto; padding: 6px 0; font-size: 13px; }
+.tree-row { display: flex; align-items: center; gap: 6px; padding: 4px 10px; cursor: pointer; min-width: 0; }
+.tree-row:hover { background: var(--_user); }
+.tree-row .name { flex: 1; min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.tree-row .meta { font-size: 11px; color: var(--_muted); flex: none; }
+.tree-row .caret { width: 12px; flex: none; color: var(--_muted); font-size: 10px; }
+.tree-row .row-add { visibility: hidden; padding: 0 6px; font-size: 12px; border-radius: 5px; flex: none; }
+.tree-row:hover .row-add, .tree-row:focus-within .row-add { visibility: visible; }
+.tree-row.ws .name { font-weight: 600; }
+.tree-row.tab { padding-left: 26px; color: var(--_muted); }
+.tree-row.pane { padding-left: 30px; }
+.tree-row.pane.nested { padding-left: 46px; }
+.tree-row.pane.current { background: color-mix(in srgb, var(--_accent) 16%, transparent); }
+.tree-row .badge { font-size: 10px; padding: 0 6px; border-radius: 999px; border: 1px solid var(--_line); color: var(--_muted); flex: none; }
+.tree-empty, .drawer-hint { padding: 8px 12px; font-size: 12px; color: var(--_muted); }
+.drawer-hint:empty { display: none; }
+.term-btn { display: inline-flex; align-items: center; justify-content: center; padding: 3px 7px; border-radius: 999px; }
+.term-btn svg { width: 14px; height: 14px; }
+.term-btn[aria-pressed="true"] { background: var(--_accent); border-color: var(--_accent); color: white; }
+.terminal-panel { display: none; flex: 1; min-height: 0; flex-direction: column; background: #101114; }
+:host([terminal-open]) .chat > .stage, :host([terminal-open]) .chat > footer { display: none; }
+:host([terminal-open]) .terminal-panel { display: flex; }
+.terminal-bar { display: flex; gap: 8px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #26272b; }
+.terminal-status { flex: 1; font-size: 12px; color: #a1a1aa; overflow-wrap: anywhere; }
+.terminal-retry { font-size: 11px; padding: 2px 9px; border-radius: 999px; }
+.terminal-host { flex: 1; min-height: 0; padding: 8px 12px; overflow: hidden; }
+.terminal-host textarea { min-height: 0; border: 0; padding: 0; resize: none; }
+
 :host {
   --_bg: var(--ab-bg, #f6f6f4); --_panel: var(--ab-panel, #fff); --_text: var(--ab-text, #1f1f1f);
   --_muted: var(--ab-muted, #6b6b6b); --_line: var(--ab-line, #e4e4e0); --_accent: var(--ab-accent, #2f6fed);
@@ -103,7 +160,6 @@ header { display: flex; align-items: center; gap: 10px; padding: 10px 16px; bord
          background: var(--_panel); }
 :host([no-header]) header { display: none; }
 h1 { font-size: 14px; margin: 0; font-weight: 600; }
-.clear-btn { font-size: 11px; padding: 2px 9px; border-radius: 999px; }
 .session { margin-left: auto; display: flex; align-items: center; gap: 8px; font-size: 12px; color: var(--_muted); }
 .dot { width: 9px; height: 9px; border-radius: 50%; background: var(--_muted); }
 .dot.idle, .dot.done { background: var(--_ok); } .dot.working { background: var(--_busy); }
@@ -341,18 +397,38 @@ button.primary { background: var(--_accent); border-color: var(--_accent); color
 button:disabled { cursor: not-allowed; opacity: .45; }
 :host([no-actions]) .secondary { display: none; }
 .hint { font-size: 12px; color: var(--_muted); }
+.attachments { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 8px; }
+.attachments:empty { display: none; }
+.attachment { position: relative; width: 64px; height: 64px; border: 1px solid var(--_line); border-radius: 8px; overflow: hidden; }
+.attachment img { width: 100%; height: 100%; object-fit: cover; display: block; }
+.attachment button { position: absolute; top: 2px; right: 2px; padding: 0 6px; font-size: 12px; line-height: 1.5;
+                     border-radius: 999px; background: rgb(0 0 0 / .6); border: 0; color: #fff; }
+.composer.dragover textarea { outline: 2px dashed var(--_accent); outline-offset: -1px; }
 `;
 
 const TEMPLATE = `
-<header><h1 part="heading"></h1><div class="session"><button class="clear-btn" title="이 pane의 저장된 대화 삭제">기록 지우기</button><span class="dot"></span><span class="state">연결 중</span></div></header>
+<header><h1 part="heading"></h1><div class="session"><button class="term-btn" aria-pressed="false" title="터미널에서 실행 중인 세션 보기 (다시 누르면 채팅)" aria-label="터미널"><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><rect x="1.5" y="2.5" width="13" height="11" rx="2"/><path d="M4.5 6l2 2-2 2M8.5 10.5h3"/></svg></button><button class="pane-btn" aria-haspopup="dialog" aria-expanded="false" title="pane 선택"><span class="dot"></span><span class="state">연결 중</span><span aria-hidden="true">▾</span></button></div></header>
+<div class="drawer-backdrop"></div>
+<aside class="drawer" role="dialog" aria-label="pane 선택">
+  <div class="drawer-head"><strong>pane 선택</strong><button class="icon-btn ws-add" title="workspace 추가" aria-label="workspace 추가">+</button><button class="icon-btn panes-refresh" title="새로고침" aria-label="새로고침">↻</button><button class="icon-btn drawer-close" title="닫기 (Esc)" aria-label="닫기">×</button></div>
+  <div class="drawer-search"><input class="pane-filter" type="search" placeholder="workspace, 제목, 폴더 검색" aria-label="pane 검색"></div>
+  <form class="add-form" hidden><span class="add-title"></span>
+    <input name="label" placeholder="이름 (선택)" maxlength="80">
+    <input name="cwd" placeholder="폴더 경로 (선택, 절대 경로)">
+    <select name="direction" aria-label="분할 방향"><option value="right">오른쪽으로 분할</option><option value="down">아래로 분할</option></select>
+    <div class="add-row"><button type="button" class="add-cancel">취소</button><button type="submit" class="primary">추가</button></div></form>
+  <div class="tree" role="tree"></div><div class="drawer-hint" role="status"></div>
+</aside>
 <div class="body"><section class="chat">
+<div class="terminal-panel" aria-label="터미널"><div class="terminal-bar"><span class="terminal-status" role="status"></span><button class="terminal-retry">다시 연결</button></div><div class="terminal-host"></div></div>
 <div class="stage">
 <div class="log" part="log"><div class="inner"><div class="empty">이 pane의 대화가 브라우저에 저장돼요.</div></div><div class="inner queue" part="queue"></div></div>
 <div class="activity" part="activity"></div>
 </div>
 <footer part="composer"><div class="composer">
   <div class="grip" role="separator" aria-orientation="horizontal" aria-label="입력창 높이 조절 (위아래 방향키)" tabindex="0" title="끌어서 입력창 높이 조절"></div>
-  <textarea placeholder="에이전트에게 보낼 메시지 (Enter 전송, Shift+Enter 줄바꿈)"></textarea>
+  <textarea placeholder="에이전트에게 보낼 메시지 (Enter 전송, Shift+Enter 줄바꿈, 이미지 붙여넣기·끌어놓기)"></textarea>
+  <div class="attachments" aria-label="첨부 이미지"></div>
   <div class="row">
     <button class="secondary" data-action="approve">승인</button>
     <button class="secondary" data-action="reject">거절</button>
@@ -396,6 +472,15 @@ class AgentBridge extends HTMLElement {
   #sel = null; // selected element (annotate)
   #inspectId = 0;
   #inspectWait = new Map();
+  #terminalCleanup = null;
+  #terminalVersion = 0;
+  #terminalStyles = null;
+  #panes = null; // {current, workspaces}
+  #expanded = new Set();
+  #adding = null; // {kind, workspace?, pane?}
+  #images = []; // chat attachments: {type, data (base64), url (preview)}
+  static IMAGE_MAX = 5;
+  static IMAGE_BYTES = 10 * 1024 * 1024;
   #frame = { w: 0, h: 0 };
   #moveQueued = null;
   #status = null;
@@ -417,7 +502,7 @@ class AgentBridge extends HTMLElement {
       activity: q(".activity"), box: q("textarea"), hint: q(".hint"),
       buttons: this.#root.querySelectorAll("button[data-action]"),
       live: q(".live"), url: q(".screen-bar .url"), viewport: q(".viewport"), img: q(".viewport img"),
-      controlBtn: q(".control-btn"), kbd: q(".kbd"), clearBtn: q(".clear-btn"),
+      controlBtn: q(".control-btn"), kbd: q(".kbd"),
       body: q(".body"), screen: q(".screen"), captions: q(".captions"),
       busy: q(".busy"), hand: q(".hand"), end: q(".end"), ask: q(".ask"), askBox: q(".ask textarea"), askHint: q(".ask-hint"),
       annotBtn: q(".annot-btn"), hlHover: q(".hl.hover"), hlSel: q(".hl.sel"), hlLabel: q(".hl-label"),
@@ -435,7 +520,10 @@ class AgentBridge extends HTMLElement {
     this.#bindControl();
     this.#bindAnnotate();
     this.#bindHand();
-    this.$.clearBtn.addEventListener("click", () => this.clearHistory());
+    q(".term-btn").addEventListener("click", () => this.#showTerminal(!this.hasAttribute("terminal-open")));
+    q(".terminal-retry").addEventListener("click", () => this.#showTerminal(true));
+    this.#bindPanes();
+    this.#bindImages();
   }
 
   get server() {
@@ -448,6 +536,7 @@ class AgentBridge extends HTMLElement {
     this.#syncScreen();
   }
   disconnectedCallback() {
+    this.#showTerminal(false);
     this.#es?.close();
     this.#es = null;
     this.#screenEs?.close();
@@ -457,10 +546,286 @@ class AgentBridge extends HTMLElement {
   }
   attributeChangedCallback(name) {
     if (name === "heading") this.$.heading.textContent = this.getAttribute("heading") || "agello";
-    if (name === "server" && this.isConnected) { this.#connect(); this.#screenEs?.close(); this.#screenEs = null; this.#syncScreen(); }
+    if (name === "server" && this.isConnected) { this.#showTerminal(false); this.#openPanes(false); this.#connect(); this.#screenEs?.close(); this.#screenEs = null; this.#syncScreen(); }
     if (name === "screen" && this.isConnected) this.#syncScreen();
   }
 
+  async #showTerminal(on) {
+    const version = ++this.#terminalVersion;
+    this.#terminalCleanup?.();
+    this.#terminalCleanup = null;
+    this.toggleAttribute("terminal-open", on);
+    const q = (s) => this.#root.querySelector(s);
+    q(".term-btn").setAttribute("aria-pressed", String(on));
+    if (!on) return;
+    this.#setControl(false);
+    this.#setAnnotate(false);
+    q(".terminal-status").textContent = "터미널 로딩 중…";
+    try {
+      if (!this.#terminalStyles) {
+        const link = document.createElement("link");
+        link.rel = "stylesheet";
+        link.href = `${SCRIPT_ORIGIN}/terminal.css`;
+        link.dataset.terminalCss = "";
+        this.#terminalStyles = new Promise((resolve, reject) => {
+          link.onload = resolve;
+          link.onerror = () => { this.#terminalStyles = null; link.remove(); reject(new Error("Stylesheet failed")); };
+        });
+        this.#root.append(link);
+      }
+      await this.#terminalStyles;
+      const { mountTerminal } = await import(`${SCRIPT_ORIGIN}/terminal.js`);
+      if (version !== this.#terminalVersion || !this.isConnected) return;
+      this.#terminalCleanup = mountTerminal(q(".terminal-host"), q(".terminal-status"), this.server);
+    } catch {
+      if (version === this.#terminalVersion) q(".terminal-status").textContent = "터미널을 불러오지 못했습니다. 다시 연결해 주세요.";
+    }
+  }
+
+  // ---------- pane picker (herdr workspace -> tab -> pane) ----------
+
+  #bindPanes() {
+    const q = (s) => this.#root.querySelector(s);
+    q(".pane-btn").addEventListener("click", () => this.#openPanes(!this.hasAttribute("panes-open")));
+    q(".drawer-close").addEventListener("click", () => this.#openPanes(false));
+    q(".drawer-backdrop").addEventListener("click", () => this.#openPanes(false));
+    q(".panes-refresh").addEventListener("click", () => this.#loadPanes());
+    q(".ws-add").addEventListener("click", () => this.#startAdd({ kind: "workspace" }));
+    q(".pane-filter").addEventListener("input", () => this.#renderPanes());
+    q(".add-cancel").addEventListener("click", () => this.#startAdd(null));
+    q(".add-form").addEventListener("submit", (e) => { e.preventDefault(); this.#submitAdd(); });
+    q(".drawer").addEventListener("keydown", (e) => {
+      if (e.key === "Escape") { e.stopPropagation(); this.#adding ? this.#startAdd(null) : this.#openPanes(false); }
+    });
+    q(".tree").addEventListener("click", (e) => {
+      const add = e.target.closest(".row-add");
+      const row = e.target.closest(".tree-row");
+      if (!row) return;
+      const { kind, id, ws } = row.dataset;
+      if (add) return this.#startAdd(kind === "ws" ? { kind: "tab", workspace: id } : { kind: "pane", pane: id, workspace: ws });
+      if (kind === "pane") return this.#selectPane(id);
+      this.#expanded.has(id) ? this.#expanded.delete(id) : this.#expanded.add(id);
+      this.#renderPanes();
+    });
+    q(".tree").addEventListener("keydown", (e) => {
+      if ((e.key === "Enter" || e.key === " ") && e.target.classList.contains("tree-row")) { e.preventDefault(); e.target.click(); }
+    });
+  }
+
+  #openPanes(on) {
+    if (on === this.hasAttribute("panes-open")) return;
+    this.toggleAttribute("panes-open", on);
+    const q = (s) => this.#root.querySelector(s);
+    q(".pane-btn").setAttribute("aria-expanded", String(on));
+    if (!on) { this.#startAdd(null); q(".pane-btn").focus(); return; }
+    q(".pane-filter").value = "";
+    this.#loadPanes(true);
+    q(".pane-filter").focus();
+  }
+
+  async #loadPanes(expandCurrent = false) {
+    const hint = this.#root.querySelector(".drawer-hint");
+    hint.textContent = "불러오는 중…";
+    try {
+      const res = await fetch(`${this.server}/panes`);
+      const d = await res.json();
+      if (!d.ok) throw new Error(d.error);
+      this.#panes = d;
+      hint.textContent = "";
+      if (expandCurrent) {
+        const ws = d.workspaces.find((w) => w.tabs.some((t) => t.panes.some((p) => p.id === d.current)));
+        const tab = ws?.tabs.find((t) => t.panes.some((p) => p.id === d.current));
+        if (ws) this.#expanded.add(ws.id);
+        if (tab) this.#expanded.add(tab.id);
+      }
+    } catch {
+      hint.textContent = "pane 목록을 불러오지 못했습니다.";
+    }
+    this.#renderPanes();
+  }
+
+  #renderPanes() {
+    const tree = this.#root.querySelector(".tree");
+    const d = this.#panes;
+    if (!d) { tree.replaceChildren(); return; }
+    const filter = this.#root.querySelector(".pane-filter").value.trim().toLowerCase();
+    const hit = (...xs) => !filter || xs.some((x) => String(x ?? "").toLowerCase().includes(filter));
+    const el = (tag, cls, text) => { const e = document.createElement(tag); if (cls) e.className = cls; if (text != null) e.textContent = text; return e; };
+    const row = (kind, id, cls, level, expanded) => {
+      const r = el("div", `tree-row ${cls}`);
+      Object.assign(r.dataset, { kind, id });
+      r.tabIndex = 0;
+      r.setAttribute("role", "treeitem");
+      r.setAttribute("aria-level", String(level));
+      if (expanded !== undefined) r.setAttribute("aria-expanded", String(expanded));
+      return r;
+    };
+    const addBtn = (label) => { const b = el("button", "row-add", "+"); b.type = "button"; b.title = label; b.setAttribute("aria-label", label); return b; };
+    const base = (p) => p.cwd?.split("/").filter(Boolean).pop();
+    const rows = [];
+    for (const ws of d.workspaces) {
+      const tabs = ws.tabs.map((t) => ({ ...t, panes: t.panes.filter((p) => hit(ws.label, t.label, p.id, p.agent, p.title, p.cwd)) }))
+        .filter((t) => t.panes.length);
+      if (filter && !tabs.length) continue;
+      const open = !!filter || this.#expanded.has(ws.id);
+      const r = row("ws", ws.id, "ws", 1, open);
+      const count = ws.tabs.reduce((n, t) => n + t.panes.length, 0);
+      r.append(el("span", "caret", open ? "▾" : "▸"), el("span", "name", ws.label || ws.id), el("span", "meta", String(count)), addBtn("tab 추가"));
+      rows.push(r);
+      if (!open) continue;
+      const single = ws.tabs.length === 1; // D5: a lone tab adds no information
+      for (const t of tabs) {
+        const tabOpen = single || !!filter || this.#expanded.has(t.id);
+        if (!single) {
+          const tr = row("tab", t.id, "tab", 2, tabOpen);
+          tr.append(el("span", "caret", tabOpen ? "▾" : "▸"), el("span", "name", `tab ${t.label}`), el("span", "meta", String(t.panes.length)));
+          rows.push(tr);
+        }
+        if (!tabOpen) continue;
+        for (const p of t.panes) {
+          const pr = row("pane", p.id, `pane${single ? "" : " nested"}${p.id === d.current ? " current" : ""}`, single ? 2 : 3);
+          pr.dataset.ws = ws.id;
+          if (p.id === d.current) pr.setAttribute("aria-current", "true");
+          const dot = el("span", `dot ${p.status}`);
+          dot.title = STATES[p.status] || p.status;
+          const name = el("span", "name", p.title || base(p) || p.id);
+          name.title = [p.title, p.cwd, p.id].filter(Boolean).join("\n");
+          const badge = el("span", "badge", p.agent || "셸");
+          if (p.agent !== "claude") badge.title = "채팅 미지원: 터미널로 연결";
+          pr.append(dot, name, badge, addBtn("pane 분할"));
+          rows.push(pr);
+        }
+      }
+    }
+    tree.replaceChildren(...rows);
+    if (!rows.length) tree.append(el("div", "tree-empty", filter ? "검색 결과 없음" : "pane 없음"));
+  }
+
+  #startAdd(target) {
+    this.#adding = target;
+    const form = this.#root.querySelector(".add-form");
+    form.hidden = !target;
+    if (!target) return;
+    form.reset();
+    const titles = { workspace: "새 workspace", tab: "새 tab", pane: "pane 분할" };
+    form.querySelector(".add-title").textContent = titles[target.kind];
+    form.elements.label.hidden = target.kind === "pane";
+    form.elements.direction.hidden = target.kind !== "pane";
+    (target.kind === "pane" ? form.elements.direction : form.elements.label).focus();
+  }
+
+  async #submitAdd() {
+    const target = this.#adding;
+    if (!target) return;
+    const f = this.#root.querySelector(".add-form").elements;
+    const hint = this.#root.querySelector(".drawer-hint");
+    const body = { ...target, cwd: f.cwd.value.trim() || undefined };
+    if (target.kind === "pane") body.direction = f.direction.value;
+    else body.label = f.label.value.trim() || undefined;
+    if (body.cwd && !body.cwd.startsWith("/")) { hint.textContent = "폴더 경로는 /로 시작하는 절대 경로여야 합니다."; return; }
+    hint.textContent = "만드는 중…";
+    try {
+      const res = await fetch(`${this.server}/panes/create`, {
+        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body),
+      });
+      const d = await res.json();
+      if (!d.ok) throw new Error(d.error);
+      this.#startAdd(null);
+      if (target.workspace) this.#expanded.add(target.workspace);
+      await this.#selectPane(d.pane, { terminal: true }); // a new pane is a plain shell: show it as a terminal
+    } catch (e) {
+      hint.textContent = `추가 실패: ${e.message || "server_unreachable"}`;
+    }
+  }
+
+  async #selectPane(pane, { terminal = false } = {}) {
+    const hint = this.#root.querySelector(".drawer-hint");
+    if (pane === this.#panes?.current && !terminal) { this.#openPanes(false); return; }
+    hint.textContent = "연결 중…";
+    try {
+      const res = await fetch(`${this.server}/panes/connect`, {
+        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ pane }),
+      });
+      const d = await res.json();
+      if (!d.ok) throw new Error(d.error);
+      const info = this.#panes?.workspaces.flatMap((w) => w.tabs.flatMap((t) => t.panes)).find((p) => p.id === pane);
+      hint.textContent = "";
+      this.#openPanes(false);
+      if (d.url !== this.server) this.setAttribute("server", d.url);
+      this.#emit("agent-pane", { pane, server: d.url });
+      if (terminal || (info && info.agent !== "claude")) this.#showTerminal(true); // D8: chat is Claude-only
+    } catch (e) {
+      hint.textContent = `연결 실패: ${e.message || "server_unreachable"}`;
+    }
+  }
+
+  // ---------- image attachments (paste / drop into the chat box) ----------
+
+  #bindImages() {
+    const composer = this.#root.querySelector(".composer");
+    const images = (list) => [...(list ?? [])].filter((f) => f.type?.startsWith("image/"));
+    this.$.box.addEventListener("paste", (e) => {
+      const files = images([...(e.clipboardData?.items ?? [])].filter((i) => i.kind === "file").map((i) => i.getAsFile()));
+      if (!files.length) return;
+      if (!e.clipboardData.getData("text/plain")) e.preventDefault();
+      this.#addImages(files);
+    });
+    composer.addEventListener("dragover", (e) => {
+      if (![...(e.dataTransfer?.items ?? [])].some((i) => i.kind === "file")) return;
+      e.preventDefault();
+      composer.classList.add("dragover");
+    });
+    composer.addEventListener("dragleave", (e) => { if (!composer.contains(e.relatedTarget)) composer.classList.remove("dragover"); });
+    composer.addEventListener("drop", (e) => {
+      composer.classList.remove("dragover");
+      const files = images(e.dataTransfer?.files);
+      if (!files.length) return;
+      e.preventDefault();
+      this.#addImages(files);
+    });
+    this.#root.querySelector(".attachments").addEventListener("click", (e) => {
+      const i = e.target.closest("[data-remove]")?.dataset.remove;
+      if (i === undefined) return;
+      URL.revokeObjectURL(this.#images[i].url);
+      this.#images.splice(Number(i), 1);
+      this.#renderImages();
+    });
+  }
+
+  async #addImages(files) {
+    const ok = ["image/png", "image/jpeg", "image/gif", "image/webp"];
+    for (const f of files) {
+      if (this.#images.length >= AgentBridge.IMAGE_MAX) { this.$.hint.textContent = `이미지는 최대 ${AgentBridge.IMAGE_MAX}개`; break; }
+      if (!ok.includes(f.type)) { this.$.hint.textContent = "PNG, JPEG, GIF, WebP만 첨부 가능"; continue; }
+      if (f.size > AgentBridge.IMAGE_BYTES) { this.$.hint.textContent = "이미지 1개당 최대 10MB"; continue; }
+      const data = await new Promise((resolve, reject) => {
+        const r = new FileReader();
+        r.onload = () => resolve(String(r.result).split(",")[1]);
+        r.onerror = reject;
+        r.readAsDataURL(f);
+      });
+      this.#images.push({ type: f.type, data, url: URL.createObjectURL(f) });
+    }
+    this.#renderImages();
+  }
+
+  #renderImages() {
+    this.#root.querySelector(".attachments").replaceChildren(...this.#images.map((img, i) => {
+      const wrap = document.createElement("div");
+      wrap.className = "attachment";
+      const pic = document.createElement("img");
+      pic.src = img.url;
+      pic.alt = `첨부 이미지 ${i + 1}`;
+      const rm = document.createElement("button");
+      rm.type = "button";
+      rm.textContent = "×";
+      rm.dataset.remove = String(i);
+      rm.setAttribute("aria-label", `첨부 이미지 ${i + 1} 삭제`);
+      wrap.append(pic, rm);
+      return wrap;
+    }));
+  }
+
   async send(text, action = "message", extra = {}) {
     try {
       const res = await fetch(`${this.server}/send`, {
@@ -555,7 +920,7 @@ class AgentBridge extends HTMLElement {
     this.#emit("agent-present", this.#present);
     this.#renderBusy();
     if (on === was) return;
-    if (on) { this.#setControl(false); this.#setAnnotate(false); }
+    if (on) { this.#showTerminal(false); this.#setControl(false); this.#setAnnotate(false); }
     else { this.$.captions.replaceChildren(); this.#openAsk(false); this.#handUp = false; }
     this.#syncScreen();
     // FLIP: grow from (or shrink back to) the side panel
@@ -1191,10 +1556,17 @@ class AgentBridge extends HTMLElement {
 
   async #submit(action) {
     const text = this.$.box.value.trim();
-    if (action === "message" && !text) return;
+    const images = this.#images.map(({ type, data }) => ({ type, data }));
+    if (action === "message" && !text && !images.length) return;
     this.$.buttons.forEach((b) => (b.disabled = true));
-    const res = await this.send(text, action);
-    if (res.ok) { this.$.box.value = ""; this.$.hint.textContent = ""; }
+    const res = await this.send(text, action, { images: images.length ? images : undefined });
+    if (res.ok) {
+      this.$.box.value = "";
+      this.$.hint.textContent = "";
+      this.#images.forEach((img) => URL.revokeObjectURL(img.url));
+      this.#images = [];
+      this.#renderImages();
+    }
     else this.$.hint.textContent = `전송 실패: ${res.error}`;
     this.#renderStatus(this.#status);
     this.$.box.focus();

package/web/index.html

@@ -12,5 +12,17 @@
 </head>
 <body>
   <agent-bridge screen></agent-bridge>
+  <script>
+    // Keep the pane picked in the drawer across reloads (?server=http://127.0.0.1:<port>).
+    const bridge = document.querySelector("agent-bridge");
+    const saved = new URLSearchParams(location.search).get("server");
+    if (saved && /^http:\/\/127\.0\.0\.1:\d+$/.test(saved)) bridge.setAttribute("server", saved);
+    bridge.addEventListener("agent-pane", (e) => {
+      const url = new URL(location.href);
+      if (e.detail.server === location.origin) url.searchParams.delete("server");
+      else url.searchParams.set("server", e.detail.server);
+      history.replaceState(null, "", url);
+    });
+  </script>
 </body>
 </html>

package/web/terminal.js

@@ -0,0 +1,121 @@
+import { Terminal } from "@xterm/xterm";
+import { FitAddon } from "@xterm/addon-fit";
+
+export function mountTerminal(host, status, server) {
+  const term = new Terminal({ fontSize: 14, fontFamily: 'Menlo, Consolas, monospace',
+    cursorBlink: true, scrollback: 0, disableStdin: true,
+    theme: { background: '#101114', foreground: '#e4e4e7' } });
+  const fit = new FitAddon();
+  term.loadAddon(fit);
+  term.open(host);
+  fit.fit();
+  const ws = new WebSocket(`${server.replace(/^http/, "ws")}/terminal`);
+  let active = true, ready = false, failed = false, queued = 0;
+  let resizeTimer;
+  const send = (msg) => {
+    if (active && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(msg));
+  };
+  const dimensions = () => ({ cols: Math.max(2, Math.min(500, term.cols)), rows: Math.max(2, Math.min(300, term.rows)) });
+  status.textContent = "터미널 연결 중…";
+  ws.onopen = () => send({ type: "terminal.start", ...dimensions() });
+  ws.onmessage = (event) => {
+    if (!active) return;
+    try {
+      const frame = JSON.parse(event.data);
+      if (frame.type === "terminal.error") {
+        failed = true;
+        status.textContent = frame.message;
+      } else if (frame.type === "terminal.frame") {
+        const data = Uint8Array.from(atob(frame.bytes), (c) => c.charCodeAt(0));
+        queued += data.length;
+        if (queued > 4 * 1024 * 1024) {
+          failed = true;
+          status.textContent = "화면 처리가 지연되었습니다. 다시 연결해 주세요.";
+          ws.close();
+          return;
+        }
+        if (term.cols !== frame.width || term.rows !== frame.height) term.resize(frame.width, frame.height);
+        term.write(data, () => { queued -= data.length; });
+        if (!ready) {
+          ready = true;
+          term.options.disableStdin = false;
+          status.textContent = "터미널 연결됨 · 키보드 입력 가능";
+          term.focus();
+        }
+      }
+    } catch {
+      failed = true;
+      status.textContent = "터미널 화면을 읽을 수 없습니다. 다시 연결해 주세요.";
+      ws.close();
+    }
+  };
+  ws.onclose = () => {
+    if (!active) return;
+    ready = false;
+    term.options.disableStdin = true;
+    if (!failed) status.textContent = "연결이 종료되었습니다. 다시 연결해 주세요.";
+  };
+  ws.onerror = () => { failed = true; status.textContent = "터미널 서버에 연결할 수 없습니다."; };
+  term.onData((text) => { if (ready) send({ type: "terminal.input", text }); });
+  // Herdr renders viewport frames; scroll the source viewport rather than an
+  // xterm scrollback buffer. Herdr routes wheel events to alternate-screen apps.
+  const wheel = (event) => {
+    if (!ready || !event.deltaY || event.ctrlKey) return;
+    event.preventDefault();
+    event.stopPropagation();
+    send({ type: "terminal.scroll", direction: event.deltaY < 0 ? "up" : "down",
+      lines: Math.min(100, Math.max(1, Math.ceil(Math.abs(event.deltaY) / 40))) });
+  };
+  host.addEventListener("wheel", wheel, { passive: false, capture: true });
+  // xterm pastes text only. For images (a Finder file copy or a screenshot),
+  // upload the file the browser received and paste its path, as a local
+  // terminal does for a dropped file: Claude Code attaches image paths.
+  // (Sending Ctrl+V instead would make Claude Code read the system clipboard,
+  // which for a Finder copy holds the file icon, not the image.)
+  const paste = async (event) => {
+    const data = event.clipboardData;
+    if (!ready || !data) return;
+    const files = [...data.items].filter((i) => i.kind === "file" && i.type.startsWith("image/")).map((i) => i.getAsFile());
+    if (!files.length) return;
+    event.preventDefault();
+    event.stopPropagation();
+    status.textContent = "이미지 올리는 중…";
+    try {
+      const images = await Promise.all(files.slice(0, 5).map((f) => new Promise((resolve, reject) => {
+        const r = new FileReader();
+        r.onload = () => resolve({ type: f.type, data: String(r.result).split(",")[1] });
+        r.onerror = reject;
+        r.readAsDataURL(f);
+      })));
+      const res = await fetch(`${server}/upload`, {
+        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ images }),
+      });
+      const d = await res.json();
+      if (!d.ok) throw new Error(d.error);
+      send({ type: "terminal.input", text: `\x1b[200~${d.paths.join(" ")}\x1b[201~` });
+      status.textContent = "터미널 연결됨 · 키보드 입력 가능";
+    } catch {
+      status.textContent = "이미지를 올리지 못했습니다. (PNG·JPEG·GIF·WebP, 10MB 이하)";
+    }
+  };
+  host.addEventListener("paste", paste, true);
+  const observer = new ResizeObserver(() => {
+    clearTimeout(resizeTimer);
+    resizeTimer = setTimeout(() => {
+      if (!active || !host.clientWidth || !host.clientHeight) return;
+      fit.fit();
+      if (ready) send({ type: "terminal.resize", ...dimensions() });
+    }, 100);
+  });
+  observer.observe(host);
+  return () => {
+    active = false;
+    clearTimeout(resizeTimer);
+    observer.disconnect();
+    host.removeEventListener("wheel", wheel, true);
+    host.removeEventListener("paste", paste, true);
+    ws.close();
+    term.dispose();
+    host.replaceChildren();
+  };
+}