Merge remote-tracking branch 'origin/main' into screens

# Conflicts:
#	.claude/settings.local.json
#	CLAUDE.md
#	bolt_pet/controller.py

bolt_pet/config.py

@@ -185,6 +185,17 @@ NOTIFICATION_BRIDGE = os.environ.get("NOTIFICATION_BRIDGE", "false").lower() in
 NOTIFICATION_FILTER = os.environ.get("NOTIFICATION_FILTER", "")
 NOTIFICATION_MIN_INTERVAL_SECONDS = float(os.environ.get("NOTIFICATION_MIN_INTERVAL_SECONDS", "60"))
 
+# ── file delivery ────────────────────────────────────────────────────────
+# The server's deliver_files tool (ai/desk_api.py in the main tmn-api repo)
+# queues workspace files on this session — e.g. "send me that report" — for
+# the client to fetch via GET /desk/files. Downloading a file dequeues it
+# server-side, so each one lands here exactly once.
+
+RECEIVE_FILES = os.environ.get("RECEIVE_FILES", "true").lower() in ("1", "true", "yes", "on")
+DELIVERED_FILES_DIR = Path(
+    os.environ.get("DELIVERED_FILES_DIR") or str(Path.home() / "Downloads" / "Bolt")
+).expanduser()
+
 # ── conversation history ────────────────────────────────────────────────────
 
 HISTORY_LIMIT = int(os.environ.get("HISTORY_LIMIT", "100"))

bolt_pet/controller.py

@@ -20,9 +20,9 @@ from typing import Optional
 from PySide6.QtCore import QObject, Signal
 
 from . import (
-    config, history as history_mod, monitors as monitors_mod, notifications,
-    pet_actions, quiet, screen_context, screen_text, server_client,
-    speech_text, updater,
+    config, file_delivery, file_ops, history as history_mod,
+    monitors as monitors_mod, notifications, pet_actions, quiet,
+    screen_context, screen_text, server_client, speech_text, updater,
 )
 from .audio import barge_in, mic, stt, tts, wake_word
 from .state import PetState, PetStateMachine
@@ -259,6 +259,7 @@ class PetController(QObject):
             self._state.transition(PetState.IDLE)
             return
 
+        self._check_deliveries()
         self._speak(reply)
         self._state.transition(PetState.IDLE)
 
@@ -289,42 +290,57 @@ class PetController(QObject):
 
     def _handle_command(self, command: str) -> str:
         """Server-relayed command. `petctl ...` drives the pet's body and
-        never reaches a shell; everything else is a real command, exactly as
-        before (see the security notes in the README)."""
+        `filectl ...` does local file read/write/edit — neither ever reaches
+        a shell; everything else is a real command, exactly as before (see
+        the security notes in the README)."""
         try:
             action = pet_actions.parse(command)
         except pet_actions.ActionError as exc:
             self.log.emit(f"petctl: {exc}")
             return f"[pet] {exc}"
-        if action is None:
-            return server_client.run_local_command(command)
-        self.log.emit(f"Pet action: {action}")
+        if action is not None:
+            self.log.emit(f"Pet action: {action}")
 
-        # Queries answer from here rather than from pet_actions.describe():
-        # their output *is* the useful part, and it's what the server reads
-        # back off the tool-result relay.
-        kind = action["action"]
-        if kind == "monitors":
-            return monitors_mod.describe(self._monitors, self._pet_monitor)
-        if kind == "read":
-            return self._read_screen(action["target"])
-        if kind == "jump":
+            # Queries answer from here rather than from pet_actions.describe():
+            # their output *is* the useful part, and it's what the server reads
+            # back off the tool-result relay.
+            kind = action["action"]
+            if kind == "monitors":
+                return monitors_mod.describe(self._monitors, self._pet_monitor)
+            if kind == "read":
+                return self._read_screen(action["target"])
+            if kind == "jump":
+                try:
+                    target = monitors_mod.resolve(
+                        self._monitors, action["target"], self._pet_monitor
+                    )
+                except ValueError as exc:
+                    self.log.emit(f"petctl jump: {exc}")
+                    return f"[pet] {exc}"
+                # Hand the window a resolved index, so it can't re-resolve the
+                # spec against a different screen ordering.
+                self.action.emit({"action": "jump", "monitor": target.index})
+                return f"[pet] jumped to monitor {target.label}"
+
+            if kind == "nap":
+                self.set_napping(bool(action["enabled"]))
+            self.action.emit(action)
+            return pet_actions.describe(action)
+
+        try:
+            file_action = file_ops.parse(command)
+        except file_ops.FileOpError as exc:
+            self.log.emit(f"filectl: {exc}")
+            return f"[filectl] {exc}"
+        if file_action is not None:
+            self.log.emit(file_ops.describe(file_action))
             try:
-                target = monitors_mod.resolve(
-                    self._monitors, action["target"], self._pet_monitor
-                )
-            except ValueError as exc:
-                self.log.emit(f"petctl jump: {exc}")
-                return f"[pet] {exc}"
-            # Hand the window a resolved index, so it can't re-resolve the
-            # spec against a different screen ordering.
-            self.action.emit({"action": "jump", "monitor": target.index})
-            return f"[pet] jumped to monitor {target.label}"
+                return file_ops.execute(file_action)
+            except file_ops.FileOpError as exc:
+                self.log.emit(f"filectl: {exc}")
+                return f"[filectl] {exc}"
 
-        if kind == "nap":
-            self.set_napping(bool(action["enabled"]))
-        self.action.emit(action)
-        return pet_actions.describe(action)
+        return server_client.run_local_command(command)
 
     def _read_screen(self, target: str) -> str:
         """`petctl read` — OCR a screen and hand the text back to the server."""
@@ -487,10 +503,39 @@ class PetController(QObject):
             except server_client.ServerError as exc:
                 self.log.emit(f"Couldn't forward notification: {exc}")
                 return
+            self._check_deliveries()
             if reply.strip():
                 self._speak(reply)
                 self._state.transition(PetState.IDLE)
 
+    # ── file delivery ────────────────────────────────────────────────────
+
+    def _check_deliveries(self) -> None:
+        """Download anything the server has queued via deliver_files —
+        called right after a conversation/notification turn (the common
+        case: "send me that file") and once per heartbeat for anything
+        queued out-of-band. Best-effort: a failure here is logged, not
+        raised, so it can't sour a turn that already got its spoken reply."""
+        if not config.RECEIVE_FILES:
+            return
+        try:
+            queued = server_client.list_outbox_files()
+        except server_client.ServerError as exc:
+            self.log.emit(f"Couldn't check for delivered files: {exc}")
+            return
+        for entry in queued:
+            file_id = entry.get("id")
+            name = entry.get("name") or file_id
+            if not file_id:
+                continue
+            try:
+                data = server_client.download_outbox_file(file_id)
+            except server_client.ServerError as exc:
+                self.log.emit(f"Couldn't download {name}: {exc}")
+                continue
+            path = file_delivery.save(config.DELIVERED_FILES_DIR, name, data)
+            self.log.emit(f"Received file: {path}")
+
     # ── auto-update ──────────────────────────────────────────────────────
 
     def _maybe_update(self) -> None:
@@ -546,6 +591,7 @@ class PetController(QObject):
             return
         if self._napping:
             return  # quiet hours: still answers when spoken to, just doesn't start
+        self._check_deliveries()
         self._drain_notifications()
         if self._state.state != PetState.IDLE:
             return

bolt_pet/file_delivery.py

@@ -0,0 +1,54 @@
+"""Saves files the server queues via its deliver_files tool (ai/desk_api.py
+in the main tmn-api repo) to a local downloads folder.
+
+The server side of this is already generic — any desk client can list
+GET /desk/files and fetch GET /desk/files/<id> (see server_client.
+list_outbox_files / download_outbox_file) — so this module is just the
+filesystem half: turn a server-supplied display name into a safe path and
+write the bytes.
+
+Pure filename/path logic lives here so it's testable without touching a real
+mic/network; the only I/O is the final write in save().
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_FALLBACK_NAME = "delivered_file"
+
+
+def sanitize_filename(name: str) -> str:
+    """Reduce a server-supplied name to a bare filename. Defends against a
+    delivered name that's actually a path (../../etc, an absolute path, ...)
+    — Path(...).name strips every directory component, and anything that
+    collapses to nothing (or "." / "..") falls back to a generic name."""
+    candidate = Path(str(name or "").strip()).name
+    if candidate in ("", ".", ".."):
+        return _FALLBACK_NAME
+    return candidate
+
+
+def unique_path(directory: Path, name: str) -> Path:
+    """*name* under *directory*, suffixed " (1)", " (2)", ... if that name is
+    already taken — a delivered file never overwrites an earlier download."""
+    directory = Path(directory)
+    directory.mkdir(parents=True, exist_ok=True)
+    candidate = directory / name
+    if not candidate.exists():
+        return candidate
+    stem, suffix = candidate.stem, candidate.suffix
+    n = 1
+    while True:
+        candidate = directory / f"{stem} ({n}){suffix}"
+        if not candidate.exists():
+            return candidate
+        n += 1
+
+
+def save(directory: Path, name: str, data: bytes) -> Path:
+    """Write *data* under *directory* as *name* (sanitized + uniquified),
+    returning the path written."""
+    path = unique_path(directory, sanitize_filename(name))
+    path.write_bytes(data)
+    return path

bolt_pet/file_ops.py

@@ -0,0 +1,280 @@
+"""Local file read/edit/write, intercepted from the server-relayed command
+channel the same way pet_actions.py intercepts petctl (see server_client.
+run_local_command / controller._handle_command). Whatever text the server's
+"command" tool sends is just a string this repo is free to interpret before
+it ever reaches subprocess — a `filectl` pseudo-command is one such
+interpretation, giving the model a way to read/write/edit files on this
+machine without constructing a raw shell heredoc, where quoting, `$`,
+backticks, and embedded quotes make anything beyond a one-liner failure-prone.
+
+Executing arbitrary commands already works today (that's exactly what
+run_local_command/subprocess.run does) — filectl doesn't add that ability,
+it only makes the read/write/edit slice of it reliable. It also doesn't
+expand what the server can already do to this machine: a relayed shell
+command could already overwrite any file the desktop user can write (see the
+security notes in CLAUDE.md) — filectl is a safer *path* to the same
+capability, not a new capability.
+
+Wire format: `filectl <json>`, where <json> is a single-line, compact JSON
+object — critically, ONE LINE. The server's "command" tool marker only
+captures the argument up to the next newline (see TOOL_SPECS/
+_extract_all_tool_calls in the main repo's ai/agents/default.py — "command"
+is not declared multiline), so a marker-delimited multi-line payload (this
+module's first design) silently got truncated at the first line no matter
+how the prompt worded it. JSON sidesteps that for free: json.dumps() already
+encodes embedded newlines as the two characters "\n", not an actual line
+break, so arbitrarily multi-line file content still fits on the one physical
+line the extractor captures.
+
+    filectl {"op": "list", "path": "<dir>", "pattern": "<glob>", "recursive": <bool>}
+    filectl {"op": "read", "path": "<path>", "start": <line>, "end": <line>}
+    filectl {"op": "write", "path": "<path>", "content": "<text>"}
+    filectl {"op": "edit", "path": "<path>", "old": "<text>", "new": "<text>"}
+
+"pattern"/"recursive" (list) and "start"/"end" (read) are optional. `list`
+exists even though a real `ls`/`dir` shell command already works, because
+this repo is cross-platform (Windows/macOS/Linux) and the model shouldn't
+have to guess which listing command applies on this machine — one glob-based
+op covers all three. Must be invoked as the argument to the
+ordinary `command` tool marker (e.g. `command: filectl {"op": "write", ...}`)
+— see the pet-only paragraph in the main repo's ai/desk_api.py
+_system_context for the exact instruction the model is given, including the
+"keep it one line" requirement.
+
+Pure parsing (parse) is separated from the filesystem I/O (execute) so the
+syntax is unit-testable without touching disk, matching pet_actions.py's
+parse/describe split.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+_PREFIXES = ("filectl", "file")
+
+# Keeps a runaway read/write/list from blowing up the tool_result relay (and,
+# for read/list, from flooding the model's context with a giant response).
+_MAX_READ_BYTES = 200_000
+_MAX_WRITE_BYTES = 2_000_000
+_MAX_LIST_ENTRIES = 500
+
+HELP = (
+    'filectl {"op": "list", "path": "<dir>", "pattern": "<glob>", "recursive": <bool>}\n'
+    'filectl {"op": "read", "path": "<path>", "start": <line>, "end": <line>}\n'
+    'filectl {"op": "write", "path": "<path>", "content": "<text>"}\n'
+    'filectl {"op": "edit", "path": "<path>", "old": "<text>", "new": "<text>"}\n'
+    "Must be all on one line — this rides the single-line \"command\" marker."
+)
+
+
+class FileOpError(Exception):
+    """Bad filectl syntax or a filesystem error — reported back to the
+    server as command output, exactly like ActionError in pet_actions.py."""
+
+
+def is_file_command(command: str) -> bool:
+    stripped = (command or "").strip()
+    if not stripped:
+        return False
+    first_word = stripped.split(None, 1)[0]
+    return first_word.lower() in _PREFIXES
+
+
+def parse(command: str) -> Optional[dict]:
+    """Parse a `filectl <json>` string into an action dict, or None if this
+    isn't a filectl command at all (caller should try the next handler, or
+    fall back to a real shell command). Raises FileOpError on a filectl
+    command that doesn't make sense."""
+    if not is_file_command(command):
+        return None
+    stripped = command.strip()
+    _, _, rest = stripped.partition(" ")
+    rest = rest.strip()
+    if not rest or rest.lower() in ("help", "-h", "--help"):
+        return {"action": "help"}
+
+    try:
+        payload = json.loads(rest)
+    except json.JSONDecodeError as exc:
+        raise FileOpError(f"couldn't parse filectl JSON ({exc}); usage:\n{HELP}") from exc
+    if not isinstance(payload, dict):
+        raise FileOpError(f"filectl payload must be a JSON object; usage:\n{HELP}")
+
+    op = str(payload.get("op") or "help").lower()
+
+    if op == "help":
+        return {"action": "help"}
+
+    if op == "list":
+        path = _required_str(payload, "path")
+        pattern = payload.get("pattern", "*")
+        if not isinstance(pattern, str) or not pattern:
+            raise FileOpError('"pattern" must be a non-empty string')
+        return {
+            "action": "list", "path": path,
+            "pattern": pattern, "recursive": bool(payload.get("recursive")),
+        }
+
+    if op == "read":
+        path = _required_str(payload, "path")
+        return {
+            "action": "read", "path": path,
+            "start": _line_number(payload.get("start"), "start"),
+            "end": _line_number(payload.get("end"), "end"),
+        }
+
+    if op == "write":
+        path = _required_str(payload, "path")
+        if payload.get("content") is None:
+            raise FileOpError('write needs "content"')
+        return {"action": "write", "path": path, "content": str(payload["content"])}
+
+    if op == "edit":
+        path = _required_str(payload, "path")
+        if payload.get("old") is None or payload.get("new") is None:
+            raise FileOpError('edit needs "old" and "new"')
+        old, new = str(payload["old"]), str(payload["new"])
+        if old == new:
+            raise FileOpError("old and new text are identical — nothing to edit")
+        return {"action": "edit", "path": path, "old": old, "new": new}
+
+    raise FileOpError(f"unknown filectl op {op!r}; usage:\n{HELP}")
+
+
+def _required_str(payload: dict, key: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise FileOpError(f'filectl needs a non-empty "{key}"')
+    return value
+
+
+def _line_number(value, label: str) -> Optional[int]:
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise FileOpError(f"{label} must be an integer line number, got {value!r}")
+    return value
+
+
+def describe(action: dict) -> str:
+    """Text handed back to the server before execute() runs — mirrors
+    pet_actions.describe, used only for the log line."""
+    kind = action.get("action")
+    if kind == "help":
+        return "[filectl] help"
+    return f"[filectl] {kind} {action.get('path', '')}"
+
+
+def execute(action: dict) -> str:
+    """Actually perform a parsed filectl action, returning the text to send
+    back to the server as the command's output. Raises FileOpError on any
+    filesystem problem, same as a bad-syntax parse error."""
+    kind = action.get("action")
+    if kind == "help":
+        return HELP
+    if kind == "list":
+        return _do_list(action)
+    if kind == "read":
+        return _do_read(action)
+    if kind == "write":
+        return _do_write(action)
+    if kind == "edit":
+        return _do_edit(action)
+    return "[filectl] ok"
+
+
+def _resolve(path_str: str) -> Path:
+    return Path(path_str).expanduser()
+
+
+def _do_list(action: dict) -> str:
+    path = _resolve(action["path"])
+    if not path.is_dir():
+        raise FileOpError(f"no such directory: {path}")
+    pattern = action["pattern"]
+    glob = path.rglob if action["recursive"] else path.glob
+    try:
+        entries = sorted(glob(pattern), key=lambda p: str(p).lower())
+    except OSError as exc:
+        raise FileOpError(f"couldn't list {path}: {exc}") from exc
+    if not entries:
+        return f"[no entries matching {pattern!r} in {path}]"
+    truncated = len(entries) > _MAX_LIST_ENTRIES
+    lines = []
+    for entry in entries[:_MAX_LIST_ENTRIES]:
+        rel = entry.relative_to(path)
+        if entry.is_dir():
+            lines.append(f"{rel}/")
+            continue
+        try:
+            size = entry.stat().st_size
+        except OSError:
+            size = -1
+        lines.append(f"{rel}\t{size}B")
+    if truncated:
+        lines.append(f"... truncated at {_MAX_LIST_ENTRIES} entries (of {len(entries)}) — narrow \"pattern\"")
+    return "\n".join(lines)
+
+
+def _do_read(action: dict) -> str:
+    path = _resolve(action["path"])
+    if not path.is_file():
+        raise FileOpError(f"no such file: {path}")
+    try:
+        data = path.read_bytes()
+    except OSError as exc:
+        raise FileOpError(f"couldn't read {path}: {exc}") from exc
+    if len(data) > _MAX_READ_BYTES:
+        raise FileOpError(
+            f"{path} is {len(data)} bytes, over the {_MAX_READ_BYTES}-byte filectl read limit — "
+            'pass "start"/"end" to read a slice instead'
+        )
+    try:
+        text = data.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise FileOpError(f"{path} isn't valid UTF-8 text: {exc}") from exc
+    lines = text.splitlines()
+    start = max(1, action.get("start") or 1)
+    end = min(len(lines), action.get("end") or len(lines))
+    if not lines:
+        return "[empty file]"
+    return "\n".join(f"{i:>6}\t{lines[i - 1]}" for i in range(start, end + 1))
+
+
+def _do_write(action: dict) -> str:
+    path = _resolve(action["path"])
+    content = action["content"]
+    if len(content.encode("utf-8")) > _MAX_WRITE_BYTES:
+        raise FileOpError(f"content is over the {_MAX_WRITE_BYTES}-byte filectl write limit")
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+    except OSError as exc:
+        raise FileOpError(f"couldn't write {path}: {exc}") from exc
+    return f"[filectl] wrote {len(content)} chars to {path}"
+
+
+def _do_edit(action: dict) -> str:
+    path = _resolve(action["path"])
+    old, new = action["old"], action["new"]
+    if not path.is_file():
+        raise FileOpError(f"no such file: {path}")
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise FileOpError(f"couldn't read {path}: {exc}") from exc
+    count = text.count(old)
+    if count == 0:
+        raise FileOpError(f"didn't find that text in {path} — nothing changed")
+    if count > 1:
+        raise FileOpError(
+            f"that text appears {count} times in {path} — filectl edit needs a unique match; "
+            "include more surrounding context"
+        )
+    try:
+        path.write_text(text.replace(old, new, 1), encoding="utf-8")
+    except OSError as exc:
+        raise FileOpError(f"couldn't write {path}: {exc}") from exc
+    return f"[filectl] edited {path}"

bolt_pet/server_client.py

@@ -115,6 +115,37 @@ def converse(
     raise ServerError(str(payload.get("error") or "unknown server response"))
 
 
+def list_outbox_files(timeout: float = 15.0) -> list:
+    """Files the server has queued for this session via its deliver_files
+    tool (e.g. "send me that report" during a conversation) — each entry has
+    id/name/size. Downloading one (download_outbox_file) dequeues it
+    server-side, so a file is only ever handed out once."""
+    try:
+        response = requests.get(
+            f"{config.SERVER_URL}/desk/files",
+            params={"session_id": config.SESSION_ID},
+            headers=_headers(), timeout=timeout,
+        )
+        response.raise_for_status()
+        return list(response.json().get("files") or [])
+    except Exception as exc:
+        raise ServerError(f"couldn't list delivered files: {exc}") from exc
+
+
+def download_outbox_file(file_id: str, timeout: float = 60.0) -> bytes:
+    """Fetches and dequeues one file listed by list_outbox_files()."""
+    try:
+        response = requests.get(
+            f"{config.SERVER_URL}/desk/files/{file_id}",
+            params={"session_id": config.SESSION_ID},
+            headers=_headers(), timeout=timeout,
+        )
+        response.raise_for_status()
+        return response.content
+    except Exception as exc:
+        raise ServerError(f"couldn't download delivered file {file_id!r}: {exc}") from exc
+
+
 def report_status(timeout: float = 15.0) -> Optional[str]:
     """Heartbeat — lets the desk API attach a pending spoken announcement
     (proactive nudges, reminders fired since the last heartbeat) that the pet