agello 0.1.0 → 0.1.4

package/README.md

@@ -38,16 +38,19 @@ Run inside the herdr pane where the agent is running (`$HERDR_PANE_ID` is picked
 
 ```sh
 agello start --open      # start in the background and open the page
-agello status            # list running servers
-agello stop              # stop
+agello status            # list running servers (pane, agent state, screen browser)
+agello stop              # stop this pane's server
 ```
 
 Or target another pane:
 
 ```sh
-agello start --pane w1:p2 --port 8766
+agello start --pane w1:p2
+agello stop --pane w1:p2
 ```
 
+One server per pane. `start` reuses the pane's server if it is already running, and otherwise picks the first free port from 8765 (so servers for different panes never collide). The screen panel only uses the terminal-browser given with `--browser` or the one in the agent's own herdr tab, never another tab's.
+
 Messages sent from the page arrive in the agent as:
 
 ```
@@ -61,11 +64,11 @@ The approve / reject buttons send `action=approve` / `action=reject`.
 | Command | Description |
 |---|---|
 | `agello start [options]` | Start a server in the background |
-| `agello stop [--port N \| --all]` | Stop a server |
-| `agello status [--json]` | List running servers and agent state |
-| `agello open [--port N]` | Open the page in the default browser |
+| `agello stop [--port N \| --pane ID \| --all]` | Stop a server (default: this pane's) |
+| `agello status [--json]` | List running servers, agent state and screen browser |
+| `agello open [--port N \| --pane ID]` | Open the page (default: this pane's server) |
 
-`start` options: `--pane <id>`, `--port <n>` (default 8765), `--session <id>`, `--browser <terminal-browser key>`, `--allow-origin <origin>` (repeatable), `--open`, `--foreground`.
+`start` options: `--pane <id>`, `--port <n>` (default: first free from 8765), `--session <id>`, `--browser <terminal-browser key>`, `--allow-origin <origin>` (repeatable), `--open`, `--foreground`.
 
 State and logs: `~/.local/state/agello/<port>.json`, `<port>.log`.
 

package/bin/agello.ts

@@ -3,6 +3,7 @@
 
 import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, openSync, readdirSync, rmSync } from "node:fs";
+import { createServer } from "node:net";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { parseArgs } from "node:util";
@@ -11,22 +12,23 @@ import { startServer } from "../src/server.ts";
 
 const NAME = "agello";
 const DEFAULT_PORT = 8765;
+const PORT_RANGE_END = 8799; // auto-picked ports: DEFAULT_PORT..PORT_RANGE_END
 const STATE_DIR = join(process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state"), NAME);
 
 const HELP = `${NAME} ${pkg.version}: talk to a coding agent in a herdr pane from the browser
 
 Usage:
-  ${NAME} start [options]      Start a bridge server in the background
-  ${NAME} stop [--port N|--all] Stop a running server
+  ${NAME} start [options]      Start a bridge server for a pane in the background
+  ${NAME} stop [--port N|--pane ID|--all]  Stop a server (default: this pane's)
   ${NAME} status [--json]      List running servers
-  ${NAME} open [--port N]      Open the bridge page in the default browser
+  ${NAME} open [--port N|--pane ID]        Open the page (default: this pane's server)
   ${NAME} help | --version
 
 start options:
   --pane <id>            herdr pane of the agent (default: $HERDR_PANE_ID)
-  --port <n>             port (default: ${DEFAULT_PORT})
+  --port <n>             port (default: first free port from ${DEFAULT_PORT})
   --session <id>         expected agent session id (default: session seen at start)
-  --browser <key>        terminal-browser key for the screen panel (default: same herdr tab)
+  --browser <key>        terminal-browser key for the screen panel (default: the one in the same herdr tab)
   --allow-origin <o>     extra allowed origin for embedding, repeatable ("null" for file://)
   --open                 open the page after starting
   --foreground           run in this process instead of the background
@@ -40,6 +42,7 @@ type Instance = {
   port: number;
   pane: string;
   session?: string;
+  browser?: string; // --browser given at start (unset: same herdr tab)
   url: string;
   log: string;
   startedAt: string;
@@ -89,6 +92,33 @@ async function fetchStatus(url: string): Promise<any | null> {
   }
 }
 
+function portFree(port: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const s = createServer();
+    s.once("error", () => resolve(false));
+    s.listen(port, "127.0.0.1", () => s.close(() => resolve(true)));
+  });
+}
+
+// Which server a stop/open without --all targets: --port, else --pane,
+// else this pane's ($HERDR_PANE_ID), else the only running one.
+async function resolveTarget(o: { port?: string; pane?: string }): Promise<Instance> {
+  const all = await listInstances();
+  if (o.port) {
+    const i = all.find((x) => x.port === Number(o.port));
+    return i ?? fail(`nothing running on port ${o.port}`);
+  }
+  const pane = o.pane ?? process.env.HERDR_PANE_ID;
+  if (pane) {
+    const i = all.find((x) => x.pane === pane);
+    if (i) return i;
+    if (o.pane) fail(`nothing running for pane ${pane}`);
+  }
+  if (all.length === 1) return all[0];
+  if (!all.length) fail(`not running; run \`${NAME} start\``);
+  return fail(`several servers running; pass --port or --pane:\n${all.map((i) => `  ${i.url}  pane=${i.pane}`).join("\n")}`);
+}
+
 function openUrl(url: string) {
   const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
   Bun.spawn([cmd, url], { stdout: "ignore", stderr: "ignore" });
@@ -106,7 +136,7 @@ async function cmdStart(argv: string[]) {
     args: argv,
     options: {
       pane: { type: "string", default: process.env.HERDR_PANE_ID },
-      port: { type: "string", default: String(DEFAULT_PORT) },
+      port: { type: "string" },
       session: { type: "string" },
       browser: { type: "string" },
       "allow-origin": { type: "string", multiple: true, default: [] },
@@ -114,18 +144,33 @@ async function cmdStart(argv: string[]) {
       foreground: { type: "boolean", default: false },
     },
   });
-  const port = Number(o.port);
   if (!o.pane) fail("--pane is required (HERDR_PANE_ID is not set; run inside herdr or pass --pane)");
   if (!Bun.which("herdr")) fail("herdr not found on PATH");
   mkdirSync(STATE_DIR, { recursive: true });
+  const pane = o.pane!;
 
-  const existing = await readInstance(port);
-  if (existing) {
-    console.log(`already running: ${existing.url} (pane ${existing.pane}, pid ${existing.pid})`);
-    if (o.open) openUrl(existing.url);
+  // One server per pane: reuse this pane's server, never another pane's.
+  const all = await listInstances();
+  const mine = all.find((i) => i.pane === pane);
+  if (mine) {
+    console.log(`already running: ${mine.url} (pane ${mine.pane}, pid ${mine.pid})`);
+    if (o.open) openUrl(mine.url);
     return;
   }
 
+  let port: number;
+  if (o.port) {
+    port = Number(o.port);
+    const other = all.find((i) => i.port === port);
+    if (other) fail(`port ${port} is used by the server for pane ${other.pane} (${other.url}); omit --port to pick a free one`);
+    if (!(await portFree(port))) fail(`port ${port} is in use by another program`);
+  } else {
+    let found = 0;
+    for (let p = DEFAULT_PORT; p <= PORT_RANGE_END && !found; p++)
+      if (!all.some((i) => i.port === p) && (await portFree(p))) found = p;
+    port = found || fail(`no free port in ${DEFAULT_PORT}-${PORT_RANGE_END}; pass --port`);
+  }
+
   if (o.foreground) {
     const srv = await startServer({
       port,
@@ -139,6 +184,7 @@ async function cmdStart(argv: string[]) {
       port,
       pane: srv.pane,
       session: srv.session,
+      browser: o.browser,
       url: srv.url,
       log: logPath(port),
       startedAt: new Date().toISOString(),
@@ -157,7 +203,10 @@ async function cmdStart(argv: string[]) {
   }
 
   // Background: re-run this CLI with --foreground, detached, logging to a file.
-  const args = argv.filter((a) => a !== "--open");
+  const args = ["--pane", pane, "--port", String(port)];
+  if (o.session) args.push("--session", o.session);
+  if (o.browser) args.push("--browser", o.browser);
+  for (const origin of o["allow-origin"] as string[]) args.push("--allow-origin", origin);
   const log = openSync(logPath(port), "a");
   const child = spawn(process.execPath, [import.meta.path, "start", "--foreground", ...args], {
     detached: true,
@@ -171,7 +220,7 @@ async function cmdStart(argv: string[]) {
   while (Date.now() < deadline) {
     if (child.exitCode !== null || !isAlive(child.pid!)) fail(`server exited; see ${logPath(port)}`);
     if ((await readInstance(port)) && (await fetchStatus(url))) {
-      console.log(`started: ${url} (pane ${o.pane}, pid ${child.pid})`);
+      console.log(`started: ${url} (pane ${pane}, pid ${child.pid})`);
       console.log(`log: ${logPath(port)}`);
       if (o.open) openUrl(url);
       return;
@@ -184,11 +233,9 @@ async function cmdStart(argv: string[]) {
 async function cmdStop(argv: string[]) {
   const { values: o } = parseArgs({
     args: argv,
-    options: { port: { type: "string" }, all: { type: "boolean", default: false } },
+    options: { port: { type: "string" }, pane: { type: "string" }, all: { type: "boolean", default: false } },
   });
-  const targets = o.all
-    ? await listInstances()
-    : [await readInstance(Number(o.port ?? DEFAULT_PORT))].filter((i): i is Instance => !!i);
+  const targets = o.all ? await listInstances() : [await resolveTarget(o)];
   if (!targets.length) {
     console.log("not running");
     return;
@@ -219,16 +266,17 @@ async function cmdStatus(argv: string[]) {
     const a = r.agent;
     const state = !a ? "unreachable" : a.alive ? a.status : `dead (${a.reason})`;
     const name = a?.label ? `${a.label} (${r.pane})` : r.pane;
-    console.log(`${r.url}  pane=${name}  agent=${state}  pid=${r.pid}`);
+    const scr = a?.screen;
+    const browser = scr?.browser ?? (scr?.reason ? `none (${scr.reason})` : "unknown");
+    console.log(`${r.url}  pane=${name}  agent=${state}  browser=${browser}  pid=${r.pid}`);
   }
 }
 
 async function cmdOpen(argv: string[]) {
-  const { values: o } = parseArgs({ args: argv, options: { port: { type: "string" } } });
-  const inst = await readInstance(Number(o.port ?? DEFAULT_PORT));
-  if (!inst) fail(`not running on port ${o.port ?? DEFAULT_PORT}; run \`${NAME} start\``);
-  openUrl(inst!.url);
-  console.log(inst!.url);
+  const { values: o } = parseArgs({ args: argv, options: { port: { type: "string" }, pane: { type: "string" } } });
+  const inst = await resolveTarget(o);
+  openUrl(inst.url);
+  console.log(inst.url);
 }
 
 // ---------- main ----------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agello",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "description": "Talk to a coding agent in a herdr pane from the browser: chat, live status, and a shared browser screen.",
   "keywords": [
     "herdr",

package/src/screencast.ts

@@ -16,6 +16,7 @@ type Browser = {
 
 export type ScreenMeta = {
   connected: boolean;
+  reason?: "browser_not_found" | "no_browser_in_tab" | "tab_unknown" | "no_active_tab";
   browser?: string;
   url?: string;
   title?: string;
@@ -53,11 +54,20 @@ export function createScreencast(opts: { browserKey?: string; herdrTab?: () => P
     return (await runJson(["terminal-browser", "ls", "--all", "--json"], 3000))?.browsers ?? [];
   }
 
-  async function pickBrowser(): Promise<Browser | undefined> {
+  // Only ever relay (and forward input to) the intended browser: the one given
+  // with --browser, or one in the agent's own herdr tab. Never fall back to
+  // another tab's browser: that would expose another agent's screen and let
+  // "my control" type into it.
+  async function pickBrowser(): Promise<{ browser?: Browser; reason?: ScreenMeta["reason"] }> {
     const all = await listBrowsers();
-    if (opts.browserKey) return all.find((b) => b.key === opts.browserKey);
+    if (opts.browserKey) {
+      const browser = all.find((b) => b.key === opts.browserKey);
+      return browser ? { browser } : { reason: "browser_not_found" };
+    }
     const tab = await opts.herdrTab?.();
-    return all.find((b) => b.pane?.tab === tab) ?? all[0];
+    if (!tab) return { reason: "tab_unknown" };
+    const browser = all.find((b) => b.pane?.tab === tab);
+    return browser ? { browser } : { reason: "no_browser_in_tab" };
   }
 
   function disconnect() {
@@ -107,12 +117,12 @@ export function createScreencast(opts: { browserKey?: string; herdrTab?: () => P
   }
 
   async function syncOnce() {
-    const b = await pickBrowser();
+    const { browser: b, reason } = await pickBrowser();
     const tab = b?.tabs.find((t) => t.active);
     if (!b || !tab) {
       disconnect();
       lastFrame = null;
-      setMeta({ connected: false });
+      setMeta({ connected: false, reason: reason ?? "no_active_tab" });
       return;
     }
     const url = `ws://127.0.0.1:${b.cdpPort}/devtools/page/${tab.targetId}`;
@@ -175,5 +185,12 @@ export function createScreencast(opts: { browserKey?: string; herdrTab?: () => P
     ws.send(JSON.stringify({ id: ++msgId, method: m.method, params: m.params ?? {} }));
   }
 
-  return { handle, input };
+  // Which browser the relay uses (or would use), for status reporting.
+  async function describe(): Promise<ScreenMeta> {
+    if (meta.connected) return meta;
+    const { browser, reason } = await pickBrowser();
+    return browser ? { connected: false, browser: browser.key } : { connected: false, reason };
+  }
+
+  return { handle, input, describe };
 }

package/src/server.ts

@@ -58,6 +58,20 @@ function toolSummary(input: any): string {
   return text.length > 80 ? text.slice(0, 80) + "…" : text;
 }
 
+// Some models emit user-facing narration as a `thinking` block whose signature
+// carries a "narration" marker. Claude Code renders these like normal replies,
+// so treat them as assistant text. Plain (unmarked) thinking stays hidden.
+// The marker is an undocumented detail of the signature; if it changes, these
+// blocks are simply not shown (same as before).
+export function isNarration(b: any): boolean {
+  if (b?.type !== "thinking" || typeof b.thinking !== "string" || !b.thinking.trim()) return false;
+  try {
+    return Buffer.from(String(b.signature ?? "").slice(0, 200), "base64").includes("narration");
+  } catch {
+    return false;
+  }
+}
+
 // Every herdr call is killed after `timeout` ms so a hung herdr cannot pile up processes.
 async function herdr(timeout: number, ...cmd: string[]): Promise<any> {
   return (await runJson(["herdr", ...cmd], timeout)) ?? { error: { code: "herdr_failed" } };
@@ -229,6 +243,8 @@ export async function startServer(opts: ServerOptions) {
       for (const b of content) {
         if (b.type === "text" && b.text.trim()) {
           broadcast("message", { role: "assistant", text: b.text, ts: d.timestamp });
+        } else if (isNarration(b)) {
+          broadcast("message", { role: "assistant", text: b.thinking, ts: d.timestamp, narration: true });
         } else if (b.type === "tool_use") {
           const t = { id: b.id, name: b.name, summary: toolSummary(b.input), ts: d.timestamp };
           pendingTools.set(b.id, t);
@@ -341,7 +357,7 @@ export async function startServer(opts: ServerOptions) {
   async function route(req: Request, url: URL): Promise<Response> {
     switch (url.pathname) {
       case "/status":
-        return Response.json(await checkStatus());
+        return Response.json({ ...(await checkStatus()), browser: opts.browser, screen: await screen.describe() });
       case "/events":
         return events();
       case "/screen":

package/web/agent-bridge.js

@@ -6,7 +6,7 @@
 //
 // Attributes
 //   server       bridge server origin (default: origin this script was loaded from)
-//   heading      header text (default: "Agent Bridge")
+//   heading      header text (default: "agello")
 //   no-header    hide header
 //   no-actions   hide approve/reject buttons
 //   no-history   do not persist chat in localStorage (default: persisted per server + pane)
@@ -47,6 +47,12 @@ const REASONS = {
   session_changed: "다른 세션으로 교체됨",
 };
 const STATES = { idle: "대기 중", working: "작업 중", blocked: "입력 대기", done: "완료", unknown: "상태 불명" };
+const SCREEN_REASONS = {
+  browser_not_found: "지정한 terminal-browser(--browser)를 찾을 수 없음",
+  no_browser_in_tab: "이 herdr 탭에 열린 terminal-browser 없음",
+  tab_unknown: "에이전트의 herdr 탭을 확인할 수 없음",
+  no_active_tab: "브라우저에 활성 탭 없음",
+};
 const ACTIONS = { message: "메시지", approve: "승인", reject: "거절" };
 
 const CSS = `
@@ -298,7 +304,7 @@ class AgentBridge extends HTMLElement {
   }
 
   connectedCallback() {
-    this.$.heading.textContent = this.getAttribute("heading") || "Agent Bridge";
+    this.$.heading.textContent = this.getAttribute("heading") || "agello";
     this.#connect();
     this.#syncScreen();
   }
@@ -310,7 +316,7 @@ class AgentBridge extends HTMLElement {
     this.#setControl(false);
   }
   attributeChangedCallback(name) {
-    if (name === "heading") this.$.heading.textContent = this.getAttribute("heading") || "Agent Bridge";
+    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 === "screen" && this.isConnected) this.#syncScreen();
   }
@@ -519,6 +525,7 @@ class AgentBridge extends HTMLElement {
   #renderScreenMeta(m) {
     const { live, url, viewport } = this.$;
     if (!m.connected) {
+      this.$.viewport.querySelector(".placeholder").textContent = SCREEN_REASONS[m.reason] || "열린 terminal-browser 없음";
       live.hidden = true;
       url.textContent = "";
       viewport.classList.remove("has", "agent");

package/web/embed-example.html

@@ -2,7 +2,7 @@
 <html lang="ko">
 <head>
 <meta charset="utf-8">
-<title>Agent Bridge 임베드 예시</title>
+<title>agello 임베드 예시</title>
 <script type="module" src="http://127.0.0.1:8765/agent-bridge.js"></script>
 <style>
   body { font-family: system-ui, sans-serif; margin: 0; display: grid; grid-template-columns: 1fr 420px;

package/web/index.html

@@ -3,7 +3,7 @@
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<title>Agent Bridge</title>
+<title>agello</title>
 <script type="module" src="/agent-bridge.js"></script>
 <style>
   html, body { height: 100%; margin: 0; }