agentus 0.1.0 → 0.2.0

package/packages/server/src/index.ts

@@ -15,7 +15,7 @@ import { SessionManager, SessionUnavailable } from "./acp/session-manager.js";
 import { describeAcpError } from "./acp/errors.js";
 import { BACKENDS } from "./acp/backends.js";
 import { classifyError, checkedHealth, coerceRow, inspectRow, planFor, seedRows, startupCheck } from "./acp/registry.js";
-import { FsError, listDirs, readTextFile } from "./fs.js";
+import { ChangedOnDiskError, FsError, listDirs, readTextFile, statFile, writeTextFile } from "./fs.js";
 import { terms } from "./term.js";
 import { VoiceError, listVoiceModels, setHotwordSource, synthesize, transcribe, voiceCapabilities } from "./voice.js";
 import { hotwordsFor, vocabularyOf } from "./hotwords.js";
@@ -740,6 +740,79 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
         throw e;
       }
     }
+    // What IS this file? The panel asks before reading: an image or a PDF should not be pulled
+    // through the text endpoint to learn that it is not text, and `kind` decides which renderer
+    // and whether an editor is offered. Cheap: a stat plus a hash, no bytes decoded.
+    if (url.pathname === "/api/fs/stat" && req.method === "GET") {
+      try {
+        return send(res, 200, statFile(url.searchParams.get("path")));
+      } catch (e) {
+        if (e instanceof FsError) {
+          return send(res, e.code === "not_found" ? 404 : 400, { error: e.message, code: e.code });
+        }
+        throw e;
+      }
+    }
+    // The file's RAW BYTES, for the renderers that need the real thing: an <img> in a reply,
+    // a PDF in the preview panel, an audio/video tag. Before this existed there was no way to
+    // show a local image at all (the read endpoint decodes utf-8 text and calls binary files
+    // "binary file"), so every `![shot](/Users/…/shot.png)` an agent wrote was a broken image.
+    //
+    // Same trust model as the endpoints above: any path the server process can read, because
+    // the operator can already point an agent at any directory and browse it via /api/fs/dirs.
+    // Behind the same auth gate. `inline` on purpose — a preview must not turn into a download.
+    if (url.pathname === "/api/fs/raw" && req.method === "GET") {
+      try {
+        const req0 = url.searchParams.get("path");
+        if (!req0) return send(res, 400, { error: "path is required", code: "bad_path" });
+        const info = statFile(req0);
+        res.writeHead(200, {
+          "content-type": info.contentType,
+          "content-length": String(info.size),
+          "cache-control": "no-store",
+          "content-disposition": "inline",
+        });
+        const stream = fs.createReadStream(info.path);
+        stream.on("error", () => res.destroy());
+        // The operator may close the panel mid-stream; an unhandled 'error' on the response
+        // would crash the process for a click that is not an error.
+        res.on("close", () => stream.destroy());
+        return stream.pipe(res);
+      } catch (e) {
+        if (e instanceof FsError) {
+          return send(res, e.code === "not_found" ? 404 : 400, { error: e.message, code: e.code });
+        }
+        throw e;
+      }
+    }
+    // Save an edit made in the panel. 409 carries the CURRENT bytes when the file changed on
+    // disk while the operator was typing, so the UI can offer to reload instead of choosing
+    // silently whose work to lose (see writeTextFile).
+    if (url.pathname === "/api/fs/file" && (req.method === "PUT" || req.method === "POST")) {
+      const body = await readJson(req);
+      try {
+        const path0 = typeof body.path === "string" ? body.path : "";
+        if (!path0) return send(res, 400, { error: "path is required", code: "bad_path" });
+        const content = typeof body.content === "string" ? body.content : "";
+        const ifHash = typeof body.ifHash === "string" ? body.ifHash : undefined;
+        return send(res, 200, { ok: true, ...writeTextFile(path0, content, { ifHash }) });
+      } catch (e) {
+        if (e instanceof ChangedOnDiskError) {
+          return send(res, 409, {
+            error: "changed_on_disk",
+            path: e.target,
+            hash: e.currentHash,
+            content: e.currentContent,
+            truncated: e.truncated,
+            hint: "the file changed on disk since you opened it",
+          });
+        }
+        if (e instanceof FsError) {
+          return send(res, e.code === "not_found" ? 404 : 400, { error: e.message, code: e.code });
+        }
+        throw e;
+      }
+    }
     // The windows remembered per model (the settings page and scripts read this).
     if (url.pathname === "/api/context-limits" && req.method === "GET") {
       return send(res, 200, { limits: store.listModelLimits() });
@@ -1226,7 +1299,11 @@ termWss.on("connection", (ws: WebSocket, _req: IncomingMessage, url: URL) => {
   }
   let term: ReturnType<typeof terms.start> | null = null;
   try {
-    term = terms.start(root.path);
+    // The client sends its viewport size on the socket URL: the pty must be born at the right size
+    // (the shell reads it when it paints the first prompt). Later changes arrive as term-resize.
+    const cols = Number(url.searchParams.get("cols") || 0);
+    const rows = Number(url.searchParams.get("rows") || 0);
+    term = terms.start(root.path, cols && rows ? { cols, rows } : undefined);
   } catch (e) {
     ws.send(JSON.stringify({ t: "term-error", error: String((e as Error)?.message ?? e) }));
     ws.close();
@@ -1236,12 +1313,15 @@ termWss.on("connection", (ws: WebSocket, _req: IncomingMessage, url: URL) => {
   const send = (msg: unknown): void => {
     if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(msg));
   };
-  send({ t: "term-ready", id: session.id, cwd: session.cwd, pid: session.pid });
+  // The buffered tail goes out first, so a reconnect (or a second tab) lands on the scrollback the
+  // way ttyd's RESUME does instead of a blank screen.
+  if (session.buffer) send({ t: "term-data", id: session.id, data: session.buffer });
+  send({ t: "term-ready", id: session.id, cwd: session.cwd, pid: session.pid, tty: session.tty });
   const onData = (chunk: string): void => send({ t: "term-data", id: session.id, data: chunk });
   session.subscribers.add(onData);
   session.child.on("exit", () => send({ t: "term-exit", id: session.id }));
   ws.on("message", (data) => {
-    let cmd: { t?: string; data?: string };
+    let cmd: { t?: string; data?: string; cols?: number; rows?: number };
     try {
       cmd = JSON.parse(String(data));
     } catch {
@@ -1249,10 +1329,12 @@ termWss.on("connection", (ws: WebSocket, _req: IncomingMessage, url: URL) => {
     }
     if (cmd.t === "term-input" && typeof cmd.data === "string") {
       try {
-        session.child.stdin.write(cmd.data);
+        session.child.stdin?.write(cmd.data);
       } catch (e) {
         send({ t: "term-error", error: `write failed: ${String((e as Error)?.message ?? e)}` });
       }
+    } else if (cmd.t === "term-resize" && typeof cmd.cols === "number" && typeof cmd.rows === "number") {
+      session.resize(cmd.cols, cmd.rows);
     } else if (cmd.t === "term-close") {
       terms.kill(session.id);
       ws.close();

package/packages/server/src/pty-helper.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Run one command on a REAL pseudo-terminal and shovel bytes between it and stdio.
+
+This is the whole trick behind a web terminal (ttyd does the same thing in C): `forkpty` gives the
+child a controlling terminal, so the shell believes a human is at the keyboard — line editing,
+prompts, colours, job control, full-screen programs (vim, top) all work. Without it (pipe stdio)
+the shell is in non-interactive mode: no prompt on screen, no echo, no cursor, SIGWINCH meaningless,
+and any terminal emulator in front of it is a lie.
+
+Why a Python helper instead of node-pty: node-pty is a build-time native module and this project
+stays dependency-free on install. Python 3 is present on macOS and essentially every Linux; its
+stdlib already has forkpty + termios, which is all a PTY needs. If python3 is missing the server
+falls back to pipes and says so in the panel.
+
+Wire format, all raw bytes:
+    stdin  (fd 0)  -> keystrokes from the browser, written straight to the PTY master
+    stdout (fd 1)  <- everything the PTY produces, written straight out (no filtering, no ANSI
+                      stripping: a terminal emulator consumes the escape sequences, a <pre> cannot)
+    fd 3           <- control channel, one command per line: "resize <cols> <rows>"
+
+Sizing: the initial size comes from AGENTUS_PTY_COLS / AGENTUS_PTY_ROWS, and `resize` applies
+TIOCSWINSZ to the master — the kernel then signals the child's foreground process group (SIGWINCH),
+which is what makes vim redraw at the new width.
+
+Exit: when the child exits we exit with its status; when stdin hits EOF (the socket closed) or we
+are signalled, we kill the child's process group first so no shell is orphaned.
+"""
+import errno
+import fcntl
+import os
+import pty
+import select
+import signal
+import struct
+import sys
+import termios
+
+CTL_FD = 3
+
+
+def set_winsize(fd: int, cols: int, rows: int) -> None:
+    cols = max(1, min(cols, 1000))
+    rows = max(1, min(rows, 1000))
+    fcntl.ioctl(fd, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
+
+
+def main() -> int:
+    argv = sys.argv[1:] or [os.environ.get("SHELL") or "/bin/sh"]
+    try:
+        cols = int(os.environ.get("AGENTUS_PTY_COLS") or 80)
+        rows = int(os.environ.get("AGENTUS_PTY_ROWS") or 24)
+    except ValueError:
+        cols, rows = 80, 24
+
+    pid, master = pty.fork()
+    if pid == 0:  # child: this IS the shell now
+        os.environ["TERM"] = os.environ.get("TERM") or "xterm-256color"
+        try:
+            os.execvp(argv[0], argv)
+        except Exception as exc:  # noqa: BLE001 - report it on the terminal rather than dying mute
+            os.write(2, f"cannot start {argv[0]}: {exc}\r\n".encode())
+            os._exit(127)
+
+    set_winsize(master, cols, rows)
+
+    ctl = None
+    try:
+        ctl = os.fdopen(CTL_FD, "r", buffering=1)
+    except OSError:
+        ctl = None  # no control channel: a fixed-size terminal is still a terminal
+
+    stdin_fd = 0
+    running = True
+    while running:
+        watch = [master, stdin_fd] + ([CTL_FD] if ctl else [])
+        try:
+            ready, _, _ = select.select(watch, [], [])
+        except OSError as exc:
+            if exc.errno == errno.EINTR:
+                continue
+            break
+
+        if master in ready:
+            try:
+                data = os.read(master, 65536)
+            except OSError:
+                data = b""
+            if not data:
+                break  # the child closed the pty: it is gone
+            os.write(1, data)
+
+        if stdin_fd in ready:
+            try:
+                data = os.read(stdin_fd, 65536)
+            except OSError:
+                data = b""
+            if not data:
+                break  # EOF: the browser went away, take the shell with us
+            os.write(master, data)
+
+        if ctl and CTL_FD in ready:
+            line = ctl.readline()
+            if line == "":
+                ctl.close()
+                ctl = None
+                continue
+            parts = line.split()
+            if parts and parts[0] == "resize" and len(parts) == 3 and parts[1].isdigit() and parts[2].isdigit():
+                set_winsize(master, int(parts[1]), int(parts[2]))
+
+    # Reap the child, then leave with its status so the server can report a real exit code.
+    status = 0
+    try:
+        _, raw = os.waitpid(pid, 0)
+        status = os.waitstatus_to_exitcode(raw) if hasattr(os, "waitstatus_to_exitcode") else 0
+    except ChildProcessError:
+        pass
+    except KeyboardInterrupt:
+        pass
+    return 0 if status is None else status
+
+
+def _terminate(_signum, _frame):  # noqa: ANN001 - signal handler
+    # The server kills our process group; this is the polite path when only we are signalled.
+    try:
+        os.kill(0, signal.SIGKILL)
+    except OSError:
+        pass
+    raise SystemExit(0)
+
+
+if __name__ == "__main__":
+    signal.signal(signal.SIGTERM, _terminate)
+    signal.signal(signal.SIGHUP, _terminate)
+    sys.exit(main())

package/packages/server/src/term.ts

@@ -19,10 +19,11 @@
 //    because that is the directory the operator pointed this slot at. It is not
 //    a sandbox and does not pretend to be: the person running the cockpit already
 //    owns the machine (same trust model as the agent processes).
-import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+import { spawn, type ChildProcess } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
 
 export interface TermSession {
   id: string;
@@ -30,31 +31,53 @@ export interface TermSession {
   pid: number | null;
   /** bytes of output kept for a late joiner / a reconnect */
   buffer: string;
-  child: ChildProcessWithoutNullStreams;
+  child: ChildProcess;
   subscribers: Set<(chunk: string) => void>;
   exited: { code: number | null; signal: string | null } | null;
+  /** true when the child has a real tty (see shellCommand). The panel says which it got, because
+   *  a pipe shell and a tty look nothing alike and the operator should not have to guess. */
+  tty: boolean;
+  /** Resize the tty (no-op on a pipe shell). The kernel then SIGWINCHes the child's foreground
+   *  process group, which is what makes a full-screen program redraw at the new width. */
+  resize: (cols: number, rows: number) => void;
 }
 
 const MAX_BUFFER = 256 * 1024;
 
-/** How to start the shell. Default: pipes (no native deps). PTY on request. */
-function shellCommand(shell: string): { cmd: string; args: string[] } {
+/** The PTY helper that ships with the server. */
+function ptyHelperPath(): string | null {
+  for (const rel of ["./pty-helper.py", "../src/pty-helper.py"]) {
+    try {
+      const p = fileURLToPath(new URL(rel, import.meta.url));
+      if (fs.existsSync(p)) return p;
+    } catch {
+      /* not this layout */
+    }
+  }
+  return null;
+}
+
+/** How to start the shell.
+ *
+ *  Default is a REAL pty via `pty-helper.py` (python3 stdlib `forkpty`): the shell gets a controlling
+ *  terminal, so prompts, echo, colours, job control and full-screen programs behave. That is the
+ *  whole point of the panel — a terminal emulator in front of a pipe shell is a lie (no prompt lands
+ *  on screen, keystrokes are never echoed, resize means nothing).
+ *
+ *  Escapes: `AGENTUS_TERM_CMD` runs an arbitrary command line instead (pipes), `AGENTUS_TERM_PTY=0`
+ *  forces the old pipe shell, and a machine without python3 degrades to it automatically. Whoever
+ *  gets a pipe shell is told so in the panel rather than being shown a fake terminal. */
+function shellCommand(shell: string): { cmd: string; args: string[]; tty: boolean } {
   const override = (process.env.AGENTUS_TERM_CMD || "").trim();
   if (override) {
     const parts = override.split(/\s+/);
-    return { cmd: parts[0], args: parts.slice(1) };
+    return { cmd: parts[0], args: parts.slice(1), tty: false };
   }
-  if (process.env.AGENTUS_TERM_PTY === "1") {
-    // python3's stdlib pty module is the one pty allocation available without a
-    // native build step. Missing python3 fails loudly in the panel (the child
-    // prints the interpreter error into the terminal), which is better than
-    // silently degrading to a pipe shell that claims to be a tty.
-    return {
-      cmd: "python3",
-      args: ["-u", "-c", `import pty,sys; pty.spawn(${JSON.stringify([shell, "-i"])})`],
-    };
+  if (process.env.AGENTUS_TERM_PTY !== "0") {
+    const helper = ptyHelperPath();
+    if (helper) return { cmd: "python3", args: [helper, shell, "-i"], tty: true };
   }
-  return { cmd: shell, args: ["-i"] };
+  return { cmd: shell, args: ["-i"], tty: false };
 }
 
 function pickShell(): string {
@@ -69,9 +92,11 @@ function pickShell(): string {
 export class TermService {
   #sessions = new Map<string, TermSession>();
 
-  start(cwd: string): TermSession {
+  start(cwd: string, size?: { cols: number; rows: number }): TermSession {
     const shell = pickShell();
-    const { cmd, args } = shellCommand(shell);
+    const { cmd, args, tty } = shellCommand(shell);
+    const cols = Math.max(20, Math.min(size?.cols ?? 80, 1000));
+    const rows = Math.max(5, Math.min(size?.rows ?? 24, 1000));
     const child = spawn(cmd, args, {
       cwd: fs.existsSync(cwd) ? cwd : homedir(),
       env: {
@@ -80,13 +105,19 @@ export class TermService {
         PYTHONUNBUFFERED: "1",
         // Let the shell know a machine is driving, so prompts stay plain.
         AGENTUS_TERMINAL: "1",
+        // The pty is sized at start because the shell reads its size when it draws the first
+        // prompt — resizing afterwards still works, but a 80x24 flash on every open is not free.
+        AGENTUS_PTY_COLS: String(cols),
+        AGENTUS_PTY_ROWS: String(rows),
       },
-      stdio: ["pipe", "pipe", "pipe"],
-      // own process group: `script` wraps the shell, so only a group kill reliably
-      // takes both down (see kill()).
+      // fd 3 is the PTY helper's control channel (resize). A pipe shell has no use for it.
+      stdio: tty ? ["pipe", "pipe", "pipe", "pipe"] : ["pipe", "pipe", "pipe"],
+      // own process group: the shell (or the pty helper wrapping it) is killed as a group, never
+      // one process at a time (see kill()).
       detached: true,
-    }) as ChildProcessWithoutNullStreams;
+    }) as ChildProcess;
 
+    const ctl = tty ? ((child.stdio[3] ?? null) as NodeJS.WritableStream | null) : null;
     const session: TermSession = {
       id: randomUUID(),
       cwd,
@@ -95,6 +126,15 @@ export class TermService {
       child,
       subscribers: new Set(),
       exited: null,
+      tty,
+      resize: (c: number, r: number): void => {
+        if (!ctl) return;
+        try {
+          ctl.write(`resize ${Math.max(1, Math.min(c, 1000))} ${Math.max(1, Math.min(r, 1000))}\n`);
+        } catch {
+          /* the helper is gone; the exit event says so */
+        }
+      },
     };
     const push = (chunk: string): void => {
       session.buffer = (session.buffer + chunk).slice(-MAX_BUFFER);
@@ -106,17 +146,18 @@ export class TermService {
         }
       }
     };
-    child.stdout.setEncoding("utf8");
-    child.stderr.setEncoding("utf8");
-    // stderr is part of the terminal picture (a missing command prints there)
-    child.stdout.on("data", (d: string) => push(d));
-    child.stderr.on("data", (d: string) => push(d));
-    child.on("exit", (code, signal) => {
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    // stderr is part of the terminal picture (a missing command prints there). With a pty both
+    // streams are already merged into the pty master, so only stdout carries them — harmless.
+    child.stdout?.on("data", (d: string) => push(d));
+    child.stderr?.on("data", (d: string) => push(d));
+    child.on("exit", (code: number | null, signal: string | null) => {
       session.exited = { code, signal };
       push(`\r\n[process exited${code != null ? ` with code ${code}` : ""}${signal ? ` (${signal})` : ""}]\r\n`);
       this.#sessions.delete(session.id);
     });
-    child.on("error", (err) => push(`\r\n[cannot start shell: ${err.message}]\r\n`));
+    child.on("error", (err: Error) => push(`\r\n[cannot start shell: ${err.message}]\r\n`));
     this.#sessions.set(session.id, session);
     return session;
   }