Files, open beside the conversation

A third side panel, built the way the terminal is and filled the way the
inspector is: tabs holding open files. Project files over SFTP in an agent
chat; notes, skills, knowledge documents, this chat's text attachments and its
own scratch document everywhere. Read with pygments, edited in a plain
textarea, saved with a conflict check.

A bug found on the way in, and the reason this needed its own read path.
`ssh.read_file` ends in `clean_output`, which strips ANSI escapes and decodes
with errors="replace" -- right for the output of a command, and fatal for an
editor: open a file containing an escape byte, press Save, and you have
silently rewritten it with the escapes gone and every undecodable byte replaced
by U+FFFD. `read_text`/`write_text` decode strictly, report binary rather than
mangling it, carry an mtime:size token for a file that moved underneath, and
refuse an oversize write rather than truncating -- `write_file` truncates
because a model is told how many bytes it wrote, and somebody pressing Save is
not. The model-facing pair is untouched: what it returns is a contract a model
has been shown. A truncated read opens read-only for the mirror-image reason.

Six sources go through one dispatch table, for the reason tool_labels.py is a
table: six independently written permission checks is how one ends up written
slightly differently, and that failure looks like editing somebody else's note.

A save on a project file bypasses agent/policy.py, which makes it the fourth
documented exception to "the modes do not govern the keyboard" and the first
that writes. Same argument as the terminal panel -- whoever owns the credential
could write the file with scp -- but the consequence is larger and is now said
out loud rather than left to be inferred.

The model opens tabs from the file tools it was already calling, so no new
schema and no tokens. It never brings one to the front: an agent reads forty
files in a long reply, and taking the screen each time would drag somebody
through all of them and lose any edit in progress. Only the strip is streamed,
guarded on truthiness so the frame can never blank itself -- an empty one would
close every open tab, the approval card you could press twice with the sign
reversed. Both halves are settled on the server, which is why canvas.js needs
no guard against a swap at all.

No vendored editor. CodeMirror 6 needs a bundler, which is hard rule 1;
CodeMirror 5 would be a larger payload than xterm on every page, and xterm is
the one heavy dependency precisely because it loads only where it can be used.
So: server-rendered highlighting for reading, a textarea for writing, and the
panel says there is no colour while you type rather than pretending.

Also here: a scratch document per chat, with `scratch_write` at RISK_READ on
plan_update's argument, and a test pinning the three numbers that decide a
panel's width -- LAYOUT_BOUNDS drops an unknown variable silently, so a panel
missing from it has a drag handle that works and forgets.

Driven under a DOM stub and against the running application.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/lembas/services/agent/base.py

@@ -107,6 +107,55 @@ class RemoteEntry:
         return self.name.startswith(".")
 
 
+@dataclass(frozen=True)
+class RemoteFile:
+    """A file as somebody is about to edit it, rather than as a model reads it.
+
+    Separate from what `read_file` returns for the same reason `RemoteEntry` is
+    separate from `list_dir`: the model-facing contract is right for a model and
+    wrong here. `read_file` runs its result through `clean_output`, which strips
+    escape sequences and decodes with errors="replace" -- so a file opened
+    through it and saved back would come out rewritten.
+
+    `binary` means there is nothing safe to put in a textarea, and the tab opens
+    read-only. `truncated` means the same for a different reason: saving back
+    the first 256KB of a larger file is how the rest of it is deleted.
+    """
+
+    text: str
+    size: int = 0
+    mtime: int = 0
+    truncated: bool = False
+    binary: bool = False
+
+    @property
+    def revision(self) -> str:
+        return revision_of(self.mtime, self.size)
+
+
+def revision_of(mtime: int, size: int) -> str:
+    """An opaque token saying which version of a file was read.
+
+    Round-tripped through a hidden field and compared on the way back in. Not a
+    hash: hashing means reading the whole file again on every save, and this
+    catches the case it exists for -- somebody else's editor, a build, a
+    checkout -- without it.
+    """
+    return f"{mtime}:{size}"
+
+
+class Conflict(Exception):
+    """The file moved between being opened and being saved.
+
+    Carries the revision found instead, so the card offering Overwrite has
+    something to compare against.
+    """
+
+    def __init__(self, found: str = "") -> None:
+        super().__init__("That file changed after it was opened.")
+        self.found = found
+
+
 class Executor(Protocol):
     """How a target is acted on. See `ssh.py`; there is no local variant."""
 
@@ -116,6 +165,10 @@ class Executor(Protocol):
 
     async def write_file(self, path: str, text: str) -> int: ...
 
+    async def read_text(self, path: str, *, max_bytes: int) -> RemoteFile: ...
+
+    async def write_text(self, path: str, text: str, *, if_unchanged: str) -> RemoteFile: ...
+
     async def list_dir(self, path: str) -> list[str]: ...
 
     async def scan_dir(self, path: str) -> list[RemoteEntry]: ...

src/lembas/services/agent/ssh.py

@@ -26,17 +26,21 @@ forgot to install it gets a sentence rather than an ImportError at startup.
 
 from __future__ import annotations
 
+import contextlib
 import logging
 import time
 from typing import Any
 
 from lembas.db.models import AUTH_PASSWORD, SshProfile
 from lembas.services.agent.base import (
+    Conflict,
     ExecError,
     ExecRequest,
     ExecResult,
     RemoteEntry,
+    RemoteFile,
     clean_output,
+    revision_of,
 )
 from lembas.services.crypto import decrypt
 
@@ -284,6 +288,111 @@ class SshExecutor:
             raise self._wrap(exc) from exc
         return len(payload)
 
+    # --- The same files, for somebody about to edit them ---------------------
+    # Deliberately not `read_file`/`write_file`, and those two are deliberately
+    # left exactly as they are: what they return is a contract a model has been
+    # shown, and it is the right contract for a model.
+    #
+    # It is the wrong one for an editor. `read_file` ends in `clean_output`,
+    # which strips ANSI escape sequences and decodes with errors="replace" --
+    # correct for the output of a command, and for a file it means that opening
+    # one containing an escape byte and pressing Save rewrites it with the
+    # escapes gone and every undecodable byte replaced by U+FFFD. `write_file`
+    # truncates at MAX_WRITE_BYTES, which a model is told about and a person
+    # pressing Save is not.
+    async def read_text(self, path: str, *, max_bytes: int = MAX_READ_BYTES) -> RemoteFile:
+        """A file as somebody is about to edit it.
+
+        Strict decoding, so a file this cannot represent faithfully is reported
+        as binary rather than silently mangled into something that would be
+        saved back. The stat and the read share one connection: connections are
+        per call, so doing it in two is two handshakes and two authentications
+        to open one file.
+        """
+        import asyncssh
+
+        try:
+            async with (
+                self._connect() as conn,
+                conn.start_sftp_client() as sftp,
+                sftp.open(self._resolve(path), "rb") as handle,
+            ):
+                attrs = await handle.stat()
+                data = await handle.read(max_bytes + 1)
+        except asyncssh.SFTPNoSuchFile as exc:
+            raise ExecError(f"There is no file at {path}.") from exc
+        except asyncssh.SFTPPermissionDenied as exc:
+            raise ExecError(f"Not allowed to read {path}.") from exc
+        except (OSError, asyncssh.Error) as exc:
+            raise self._wrap(exc) from exc
+
+        truncated = len(data) > max_bytes
+        data = data[:max_bytes]
+        size = int(getattr(attrs, "size", None) or len(data))
+        mtime = int(getattr(attrs, "mtime", None) or 0)
+
+        # A NUL in the first few kilobytes, or anything that will not decode.
+        # Either way there is nothing safe to put in a textarea.
+        if b"\0" in data[:8192]:
+            return RemoteFile("", size, mtime, truncated, binary=True)
+        try:
+            text = data.decode("utf-8")
+        except UnicodeDecodeError:
+            return RemoteFile("", size, mtime, truncated, binary=True)
+        return RemoteFile(text, size, mtime, truncated, binary=False)
+
+    async def write_text(self, path: str, text: str, *, if_unchanged: str = "") -> RemoteFile:
+        """Write a file, refusing if it moved under the editor.
+
+        `if_unchanged` is the token `read_text` handed out. The re-stat and the
+        write happen on one connection, which is the narrowest window SFTP
+        allows; there is no compare-and-swap here and this does not pretend to
+        be atomic. It catches what it exists for -- another editor, a build, a
+        checkout between opening a tab and pressing Save -- and not a race
+        measured in milliseconds.
+
+        Oversize is refused rather than truncated. `write_file` truncates
+        because a model is told how many bytes it wrote; somebody pressing Save
+        would lose the tail of their file with nothing said.
+        """
+        import asyncssh
+
+        payload = text.encode("utf-8")
+        if len(payload) > MAX_WRITE_BYTES:
+            raise ExecError(
+                f"That is {len(payload) // 1024}KB and the limit is "
+                f"{MAX_WRITE_BYTES // 1024}KB. Nothing was written."
+            )
+
+        target = self._resolve(path)
+        try:
+            async with self._connect() as conn, conn.start_sftp_client() as sftp:
+                if if_unchanged:
+                    current = ""
+                    with contextlib.suppress(asyncssh.SFTPNoSuchFile):
+                        attrs = await sftp.stat(target)
+                        current = revision_of(
+                            int(getattr(attrs, "mtime", None) or 0),
+                            int(getattr(attrs, "size", None) or 0),
+                        )
+                    if current and current != if_unchanged:
+                        raise Conflict(current)
+                async with sftp.open(target, "wb") as handle:
+                    await handle.write(payload)
+                attrs = await sftp.stat(target)
+        except asyncssh.SFTPPermissionDenied as exc:
+            raise ExecError(f"Not allowed to write {path}.") from exc
+        except (OSError, asyncssh.Error) as exc:
+            raise self._wrap(exc) from exc
+
+        return RemoteFile(
+            text,
+            len(payload),
+            int(getattr(attrs, "mtime", None) or 0),
+            truncated=False,
+            binary=False,
+        )
+
     async def list_dir(self, path: str = "") -> list[str]:
         import asyncssh
 

src/lembas/services/agent/tools.py

@@ -343,6 +343,27 @@ def _path_key(agent: AgentContext, path: str) -> str:
     return posixpath.normpath(path)
 
 
+def _canvas(agent: AgentContext, path: str) -> dict[str, str]:
+    """"This file should be on screen."
+
+    Written onto the event because a runner cannot write the message row --
+    `_persist` is the single writer -- so the generation loop carries it, in
+    exactly the way it carries a merged plan.
+
+    The key comes from `_path_key`, the same normaliser the read-path set uses,
+    so a tab a model opened and a tab a person opened are one tab rather than
+    two spellings of the same file.
+
+    It never brings the tab to the front; see `canvas.open_tab`. This rides on
+    calls the model was already making, so it costs no schema and no tokens.
+    """
+    return {
+        "key": f"agent:{_path_key(agent, path)}",
+        "title": posixpath.basename(path) or path,
+        "source": "agent",
+    }
+
+
 def _forget_instructions(agent: AgentContext, path: str) -> None:
     """Drop the cached AGENTS.md when the thing just written *is* it.
 
@@ -395,7 +416,14 @@ async def _run_read(context: ToolContext, args: dict[str, Any]) -> ToolOutcome:
 
     return ToolOutcome(
         text or "(the file is empty)",
-        _event("file_read", agent, path, status="ok", text=text[:MAX_EVENT_CHARS]),
+        _event(
+            "file_read",
+            agent,
+            path,
+            status="ok",
+            text=text[:MAX_EVENT_CHARS],
+            canvas=_canvas(agent, path),
+        ),
     )
 
 
@@ -436,7 +464,14 @@ async def _run_write(context: ToolContext, args: dict[str, Any]) -> ToolOutcome:
         index.forget_dir(agent.profile_id, agent.project_dir)
         _forget_instructions(agent, path)
 
-    event = _event("file_write", agent, path, status="ok", text=f"{written} bytes")
+    event = _event(
+        "file_write",
+        agent,
+        path,
+        status="ok",
+        text=f"{written} bytes",
+        canvas=_canvas(agent, path),
+    )
     if diffable and before != content:
         event["diff"] = patch.render(before, content, path, max_lines=MAX_DIFF_LINES)
 
@@ -508,7 +543,14 @@ async def _run_edit(context: ToolContext, args: dict[str, Any]) -> ToolOutcome:
     # cares that it exists, that cache is a copy of what is in it.
     _forget_instructions(agent, path)
 
-    event = _event("file_edit", agent, path, status="ok", text=f"{written} bytes")
+    event = _event(
+        "file_edit",
+        agent,
+        path,
+        status="ok",
+        text=f"{written} bytes",
+        canvas=_canvas(agent, path),
+    )
     if diffable:
         event["diff"] = patch.render(before, after, path, max_lines=MAX_DIFF_LINES)