witbitz-code 1.13.0__tar.gz → 1.15.0__tar.gz

{witbitz_code-1.13.0/src/witbitz_code.egg-info → witbitz_code-1.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: witbitz-code
-Version: 1.13.0
+Version: 1.15.0
 Summary: Reach OpenCode on this computer from the Witbitz Spaces Code section, through an end-to-end sealed relay.
 Author: Witbitz
 License-Expression: MIT

{witbitz_code-1.13.0 → witbitz_code-1.15.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "witbitz-code"
-version = "1.13.0"
+version = "1.15.0"
 description = "Reach OpenCode on this computer from the Witbitz Spaces Code section, through an end-to-end sealed relay."
 readme = "README.md"
 requires-python = ">=3.10"

{witbitz_code-1.13.0 → witbitz_code-1.15.0}/src/witbitz_code/__init__.py

@@ -4,4 +4,4 @@ The Python implementation of tools/witbitz-code.mjs (docs/opencode-relay.md phas
 vectors and cross-implementation tests.
 """
 
-__version__ = "1.13.0"
+__version__ = "1.15.0"

{witbitz_code-1.13.0 → witbitz_code-1.15.0}/src/witbitz_code/connector.py

@@ -39,6 +39,7 @@ from .attachments import (ATTACHMENT_ROUTE, MAX_FILE_BYTES, attachment_rule, def
 from .auto_runner import AutoRunner, detail_of
 from .remind import ReminderClock, seal as seal_remind, valid as valid_remind  # "waiting for your approval" (docs/approval-reminders.md)
 from .outputs import OUTPUT_ROUTE, serve_output
+from .files import FILES_DOWNLOAD_ROUTE, FILES_UPLOAD_ROUTE, download_file, upload_file
 from .plugins import notes_plugin_path as default_notes_plugin, notes_root as default_notes_root, notes_rules
 from .payers import SessionPayers
 from .seen import SEEN_ROUTE, merge_seen, norm_seen
@@ -163,9 +164,11 @@ class PairingServer:
                  notes_plugin_path: Path | None = None, payers: SessionPayers | None = None,
                  model_url: str = "", remind_times: dict | None = None,
                  browse_probe: Callable[[], dict | None] | None = None,
-                 browse_private: Callable[[bool], Awaitable[bool]] | None = None) -> None:
+                 browse_private: Callable[[bool], Awaitable[bool]] | None = None, screens_root: Path | None = None) -> None:
         self.pairing = pairing
         self._browse_private = browse_private  # private browsing on/off (browse.py LocalBrowser.set_private)
+        # the agent's browser_screenshot writes <home>/.witbitz/screens/<session> (browse-cdp.mjs), served beside the session's folder
+        self._screens_root = Path(screens_root) if screens_root else Path.home() / ".witbitz" / "screens"
         # THE AGENT'S BROWSER ON THIS COMPUTER (browse.py): its /status rides the hello; a change is announced within 2 s
         self._browse_probe = browse_probe
         self._browse_said = ""  # the last browse report the page was told, as JSON
@@ -318,7 +321,7 @@ class PairingServer:
         self._browse_said = json.dumps(browse, sort_keys=True)
         # caps: what this connector can do beyond the requests — a page shows the Auto switch only when `auto` is here.
         return self.peer.send({"t": "hello", "ver": VERSION, "name": self.name, "computerId": self.pairing.get("computerId") or "",
-                               "k": self.nonce, "ts": int(time.time() * 1000), "caps": ["auto", "attachments", "outputs", "tools", "seen", "asks", "folders", "remind"], "auto": self.auto.sessions(),
+                               "k": self.nonce, "ts": int(time.time() * 1000), "caps": ["auto", "attachments", "outputs", "tools", "seen", "asks", "folders", "remind", "files"], "auto": self.auto.sessions(),
                                **({"browse": browse} if browse else {})})
 
     def _auth(self) -> dict:
@@ -412,11 +415,45 @@ class PairingServer:
                 await reply(404, {"error": "no such session on this computer"})
                 return
             stat_only = q.get("stat") == "1"
-            st, b = serve_output(directory=session["directory"], path=q.get("path"), stat=stat_only)
+            st, b = serve_output(directory=session["directory"], path=q.get("path"), stat=stat_only,
+                                 shots=(self._screens_root / sid).as_posix())
             self._log_output({"at": int(time.time() * 1000), "session": sid, "digest": hashlib.sha256(q.get("path", "").encode()).hexdigest(),
                               "stat": stat_only, "st": st})
             await reply(st, b)
             return
+        # The Files sheet (files.py ⇄ tools/code-files.mjs): Download any file of the session's folder — nothing secret-looking —
+        # and Upload into it. Answered HERE; the folder is the session's, as OpenCode reports it; logged as a digest of the path.
+        if (m.get("m") == "GET" and bare == FILES_DOWNLOAD_ROUTE) or (m.get("m") == "POST" and bare == FILES_UPLOAD_ROUTE):
+            q = dict(urllib.parse.parse_qsl(query, keep_blank_values=True))
+            sid = q.get("session", "")
+            if not re.fullmatch(r"[A-Za-z0-9_-]{1,128}", sid):
+                await reply(400, {"error": "not a session id"})
+                return
+            dir_query = "directory=" + urllib.parse.quote(q["directory"], safe="!'()*") if q.get("directory") else ""  # encodeURIComponent
+            session = await self._session_for(sid, dir_query)
+            if not session or not isinstance(session.get("directory"), str):
+                await reply(404, {"error": "no such session on this computer"})
+                return
+            now = int(time.time() * 1000)
+            if m.get("m") == "GET":
+                st, b = download_file(directory=session["directory"], path=q.get("path"))
+                self._log_output({"at": now, "session": sid, "digest": hashlib.sha256(q.get("path", "").encode()).hexdigest(),
+                                  "download": True, "st": st})
+                await reply(st, b)
+                return
+            try:
+                f = json.loads(m.get("b") or "null")
+            except ValueError:
+                f = None
+            if not isinstance(f, dict):
+                await reply(400, {"error": "no file"})
+                return
+            st, b = upload_file(directory=session["directory"], dir=f.get("dir"), name=f.get("name"), b64=f.get("b64"),
+                                replace=f.get("replace") is True)
+            self._log_output({"at": now, "session": sid, "digest": hashlib.sha256(f"{f.get('dir')}/{f.get('name')}".encode()).hexdigest(),
+                              "upload": True, "st": st})
+            await reply(st, b)
+            return
         # What the person has seen, shared by their devices (seen.py): answered HERE and kept on this computer.
         if bare == SEEN_ROUTE and m.get("m") in ("GET", "POST"):
             if m.get("m") == "GET":
@@ -973,7 +1010,7 @@ async def start_connector(pairings: list[dict], *, flush_ms: float = 120, log: C
                           notes_plugin_path: Path | None = None, payers: SessionPayers | None = None,
                           model_url: str = "", remind_times: dict | None = None,
                           browse_probe: Callable[[], dict | None] | None = None,
-                          browse_private: Callable[[bool], Awaitable[bool]] | None = None) -> Connector:
+                          browse_private: Callable[[bool], Awaitable[bool]] | None = None, screens_root: Path | None = None) -> Connector:
     """Serve the given pairings until stop()/aclose(). Options exist for tests: flush_ms, log, client, connect,
     request_timeout_ms, max_senders, max_response_bytes, auto_dir, auto_poll_ms."""
     client = client or local_client()
@@ -989,7 +1026,7 @@ async def start_connector(pairings: list[dict], *, flush_ms: float = 120, log: C
                           max_senders=max_senders, max_response_bytes=max_response_bytes, auto_dir=auto_dir, auto_poll_ms=auto_poll_ms,
                           attach_root=attach_root, attach_max_file_bytes=attach_max_file_bytes, asks_reconcile_ms=asks_reconcile_ms,
                           notes_root=notes_root, notes_plugin_path=notes_plugin_path, payers=payers, model_url=model_url, remind_times=remind_times,
-                          browse_probe=browse_probe, browse_private=browse_private)
+                          browse_probe=browse_probe, browse_private=browse_private, screens_root=screens_root)
         await s.start()
         servers.append(s)
     return Connector(servers, client, payers)

witbitz_code-1.15.0/src/witbitz_code/files.py

@@ -0,0 +1,110 @@
+"""The Files sheet in a Code session — tools/code-files.mjs, in Python.
+
+DOWNLOAD (GET /witbitz/download?session=&path=): serve_output with `any_kind` — in the session's folder, no link out, nothing
+secret-looking, 20 MB; any regular file. UPLOAD (POST /witbitz/upload?session=, body {dir, name, b64, replace}): one file
+name (is_upload_name), into a folder whose REAL path is the session's or under it; a name already there is refused (409)
+unless `replace`, and a folder or link under that name is never replaced. Written to a hidden temporary beside it and renamed
+into place. As root, the file takes the uid/gid of the folder it lands in (a cloud computer's connector writing for the agent);
+anyone else is the person, and nothing changes.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import os
+import re
+import secrets
+import stat as stat_mod
+import unicodedata
+from typing import Any
+
+from .attachments import MAX_SERVE_BYTES
+from .auto import posix_normalize
+from .outputs import serve_output, valid_output_path
+
+FILES_DOWNLOAD_ROUTE = "/witbitz/download"
+FILES_UPLOAD_ROUTE = "/witbitz/upload"
+MAX_FILE_TRANSFER = MAX_SERVE_BYTES  # 20 MB: base64 in one relay message stays under its 32 MiB reassembly cap
+_B64 = re.compile(r"[A-Za-z0-9+/]*={0,2}\Z")
+
+
+def is_upload_name(n: Any) -> bool:
+    """A FILE's name (⇄ code-files.mjs isUploadName): no / or \\ or NUL, not hidden, at most 200 characters, nothing
+    invisible (a control or format character — a direction mark, a zero-width space), no surrounding spaces."""
+    s = unicodedata.normalize("NFC", n) if isinstance(n, str) else ""
+    return (bool(s) and len(s) <= 200 and not s.startswith(".") and not re.search(r"[/\\\0]", s)
+            and not any(unicodedata.category(c) in ("Cc", "Cf") for c in s) and s.strip() == s)
+
+
+def _answer(st: int, o: dict) -> tuple[int, str]:
+    return st, json.dumps(o, ensure_ascii=False, separators=(",", ":"))
+
+
+def _as_root() -> bool:
+    return hasattr(os, "geteuid") and os.geteuid() == 0
+
+
+def download_file(*, directory: Any, path: Any, max_bytes: int = MAX_FILE_TRANSFER) -> tuple[int, str]:
+    return serve_output(directory=directory, path=path, max_bytes=max_bytes, any_kind=True)
+
+
+def upload_file(*, directory: Any, dir: Any, name: Any, b64: Any, replace: bool = False,
+                max_bytes: int = MAX_FILE_TRANSFER, as_root: bool | None = None) -> tuple[int, str]:
+    as_root = _as_root() if as_root is None else as_root
+    if isinstance(name, str):
+        name = unicodedata.normalize("NFC", name)
+    if not is_upload_name(name):
+        return _answer(400, {"error": "a file name: no / or \\, not hidden, nothing invisible"})
+    if not isinstance(directory, str) or not directory.startswith("/") or not valid_output_path(dir):
+        return _answer(400, {"error": "not a folder in this session"})
+    root = re.sub(r"/+\Z", "", posix_normalize(directory))
+    where = re.sub(r"/+\Z", "", posix_normalize(dir)) or "/"
+    if not root or not (where == root or where.startswith(root + "/")):
+        return _answer(403, {"error": "that folder is outside the session's folder"})
+    if not isinstance(b64, str) or not _B64.match(b64):
+        return _answer(400, {"error": "not a file's bytes"})
+    try:
+        data = base64.b64decode(b64, validate=True)
+    except (binascii.Error, ValueError):
+        return _answer(400, {"error": "not a file's bytes"})
+    if len(data) > max_bytes:
+        return _answer(413, {"error": f"the file is over {round(max_bytes / 1048576)} MB — too large to send to the computer"})
+    try:
+        real_root = os.path.realpath(root, strict=True)
+    except OSError:
+        return _answer(404, {"error": "the session's folder is not on this computer"})
+    try:
+        real_where = os.path.realpath(where, strict=True)
+    except OSError:
+        return _answer(404, {"error": "that folder is not on the computer (any more)"})
+    if not (real_where == real_root or real_where.startswith(real_root + "/")):
+        return _answer(403, {"error": "that folder leads outside the session's folder"})
+    folder = os.stat(real_where)
+    if not stat_mod.S_ISDIR(folder.st_mode):
+        return _answer(400, {"error": "not a folder"})
+    target = os.path.join(real_where, name)
+    try:
+        there = os.lstat(target)
+    except OSError:
+        there = None
+    if there is not None and not stat_mod.S_ISREG(there.st_mode):
+        return _answer(409, {"error": "a folder or link of that name is there", "exists": True, "replaceable": False})
+    if there is not None and not replace:
+        return _answer(409, {"error": "a file of that name is already there", "exists": True, "replaceable": True})
+    tmp = os.path.join(real_where, f".{name}.upload-{secrets.token_hex(6)}")
+    try:
+        fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o644)
+        with os.fdopen(fd, "wb") as f:
+            f.write(data)
+        if as_root:
+            os.chown(tmp, folder.st_uid, folder.st_gid)
+        os.replace(tmp, target)
+    except OSError as e:
+        try:
+            os.unlink(tmp)
+        except OSError:
+            pass
+        return _answer(500, {"error": f"could not save it here ({str(e)[:120]})"})
+    return _answer(200, {"ok": True, "name": name, "path": target, "size": len(data), "replaced": there is not None})

{witbitz_code-1.13.0 → witbitz_code-1.15.0}/src/witbitz_code/opencode_plugins/witbitz-browse-cdp.mjs

@@ -101,7 +101,24 @@ async function snapshot (c, limit = 120) {
 // The refs are only meaningful next to the snapshot that made them, so they travel with it rather than living in
 // a cache that a page navigation would quietly invalidate.
 const REFS_FILE = (process.env.TMPDIR || '/tmp') + '/wb-browse-refs.json'
-const { writeFileSync, readFileSync } = await import('node:fs')
+const { writeFileSync, readFileSync, mkdirSync, readdirSync, statSync, rmSync } = await import('node:fs')
+const { join } = await import('node:path')
+const { homedir } = await import('node:os')
+
+// THE SCREENSHOTS' FOLDER: <home>/.witbitz/screens/<session> (spaces/public/codeOutputs.js SHOTS_DIR) — the agent's home, as
+// the connector reads it (on a cloud computer /rw/home, on a laptop the person's own). WB_BROWSE_SCREENS moves the root.
+const SHOTS_ROOT = process.env.WB_BROWSE_SCREENS || join(homedir(), '.witbitz', 'screens')
+const shotsDir = (sid) => join(SHOTS_ROOT, sid)
+const SHOT_DAYS = 30
+/** A session's pictures go 30 days after its last one — attachments' rule (tools/code-attachments.mjs). */
+function pruneShots () {
+  try {
+    for (const n of readdirSync(SHOTS_ROOT)) {
+      const d = join(SHOTS_ROOT, n)
+      try { if (Date.now() - statSync(d).mtimeMs > SHOT_DAYS * 86400000) rmSync(d, { recursive: true, force: true }) } catch { /* */ }
+    }
+  } catch { /* none yet */ }
+}
 
 // ★ A MISSING refs file is the SAME situation as a stale ref: the agent has not taken a snapshot yet. Letting
 // readFileSync throw turned that into "ENOENT: no such file or directory", which tells a model nothing it can act
@@ -226,11 +243,22 @@ try {
     await new Promise((r) => setTimeout(r, 400))
   } else if (op === 'screenshot') {
     const { data } = await c.send('Page.captureScreenshot', { format: 'jpeg', quality: 70 })
-    const path = args.path || ((process.env.TMPDIR || '/tmp') + '/wb-browse-' + Date.now() + '.jpg')
-    writeFileSync(path, Buffer.from(data, 'base64'))
+    // ★ INTO WITBITZ'S OWN FOLDER, ONE PER SESSION (the owner, 2026-10-25: "how can I get a screen snapshot in the chat"):
+    //   <home>/.witbitz/screens/<session>/ — the connector serves that folder for that session as well as the session's own
+    //   (tools/code-outputs.mjs), so the picture shows under the agent's answer, and nothing lands in the project. In a temp
+    //   folder the page could never be shown it: the connector serves nothing outside a session's folders.
+    let path = args.path
+    if (!path) {
+      const sid = /^[A-Za-z0-9_-]{1,128}$/.test(String(args.session || '')) ? args.session : 'no-session'
+      const dir = shotsDir(sid)
+      mkdirSync(dir, { recursive: true, mode: 0o700 })
+      pruneShots()
+      path = join(dir, 'screen-' + new Date().toISOString().replace(/[:.]/g, '-') + '.jpg')
+    }
+    writeFileSync(path, Buffer.from(data, 'base64'), { mode: 0o600 })
     const { lines } = await snapshot(c, 0).catch(() => ({ lines: [] }))
     c.close()
-    out({ ok: true, path, note: 'a picture for a person to look at; act from a snapshot, not from this' })
+    out({ ok: true, path, shot: true, note: 'a picture for a person to look at; act from a snapshot, not from this' })
   } else if (op !== 'snapshot') {
     out({ error: 'unknown op: ' + op })
   }

{witbitz_code-1.13.0 → witbitz_code-1.15.0}/src/witbitz_code/opencode_plugins/witbitz-browser.js

@@ -43,6 +43,7 @@ function render (j) {
   if (!j) return 'The browser did not answer.'
   if (j.error) return 'Browser: ' + j.error
   if (j.closed) return 'The browser is closed — its tabs and any sign-ins are gone. browser_open or browser_navigate starts a fresh one.'
+  if (j.shot && j.path) return 'Saved a picture of the page: ' + j.path + ' — the person sees it under your answer.'
   if (j.cleared) return 'Cleared: the browser\'s history, cookies, cache and site data are gone, and a fresh browser is open — browser_navigate to go on.'
   if (j.ok && !j.title && !j.url && !(j.elements && j.elements.length) && !j.path) return 'The browser is open' + (j.headed === false ? ' (headless — see it with browser_screenshot)' : j.headed ? ' (a window on this computer\'s screen)' : '') + '. Navigate to a URL next.' // the open op: nothing on screen yet
   const head = [j.title ? 'Title: ' + j.title : null, j.url ? 'URL: ' + j.url : null].filter(Boolean).join('\n')
@@ -157,7 +158,7 @@ export const WitbitzBrowser = async (ctx = {}) => {
       browser_screenshot: tool({
         description: 'Save a picture of the page for the PERSON to look at, and return its path. Do not use this to decide what to click — use a snapshot.',
         args: {},
-        execute: () => run('screenshot', {}),
+        execute: (args, context) => run('screenshot', { session: (context && context.sessionID) || '' }),
       }),
     },
   }

{witbitz_code-1.13.0 → witbitz_code-1.15.0}/src/witbitz_code/outputs.py

@@ -71,17 +71,23 @@ def _answer(st: int, o: dict) -> tuple[int, str]:
     return st, _js.stringify(o)
 
 
-def serve_output(*, directory: Any, path: Any, stat: bool = False, max_bytes: int = MAX_SERVE_BYTES) -> tuple[int, str]:
-    """One produced file (or its facts, with `stat`) for the page: (status, JSON body) in the connector's reply shape."""
+def serve_output(*, directory: Any, path: Any, stat: bool = False, max_bytes: int = MAX_SERVE_BYTES,
+                 any_kind: bool = False, shots: str = "") -> tuple[int, str]:
+    """One produced file (or its facts, with `stat`) for the page: (status, JSON body) in the connector's reply shape.
+
+    `any_kind`: the Files sheet's Download (files.py) — any regular file, not only a kind the page previews; every other
+    check stays (⇄ tools/code-outputs.mjs). `shots`: the session's screenshots folder (<home>/.witbitz/screens/<session>,
+    browse-cdp.mjs) — served beside its folder with every same check."""
     if not isinstance(directory, str) or not directory.startswith("/") or not valid_output_path(path):
         return _answer(400, {"error": "not a file in this session"})
-    d = re.sub(r"/+\Z", "", posix_normalize(directory))
     a = posix_normalize(path)
+    shot_dir = re.sub(r"/+\Z", "", posix_normalize(shots)) if isinstance(shots, str) and shots.startswith("/") else ""
+    d = shot_dir if shot_dir and a.startswith(shot_dir + "/") else re.sub(r"/+\Z", "", posix_normalize(directory))
     if not d or not a.startswith(d + "/"):
         return _answer(403, {"error": "that file is outside the session's folder"})
     if _sensitive_path(a[len(d):]):
         return _answer(403, {"error": "not shown: the name looks like a secret"})
-    if not output_kind(a):
+    if not any_kind and not output_kind(a):
         return _answer(400, {"error": "not a file the page shows"})
     try:
         real_dir = os.path.realpath(d, strict=True)
@@ -95,7 +101,7 @@ def serve_output(*, directory: Any, path: Any, stat: bool = False, max_bytes: in
         return _answer(403, {"error": "that file leads outside the session's folder"})
     if _sensitive_path(real[len(real_dir):]):
         return _answer(403, {"error": "not shown: the file looks like a secret"})
-    kind = output_kind(real)
+    kind = output_kind(real) or ("file" if any_kind else None)
     if not kind:
         return _answer(400, {"error": "not a file the page shows"})
     try:

{witbitz_code-1.13.0 → witbitz_code-1.15.0/src/witbitz_code.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: witbitz-code
-Version: 1.13.0
+Version: 1.15.0
 Summary: Reach OpenCode on this computer from the Witbitz Spaces Code section, through an end-to-end sealed relay.
 Author: Witbitz
 License-Expression: MIT

{witbitz_code-1.13.0 → witbitz_code-1.15.0}/src/witbitz_code.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ src/witbitz_code/confidential_models.json
 src/witbitz_code/connector.py
 src/witbitz_code/devicelink.py
 src/witbitz_code/dirs.py
+src/witbitz_code/files.py
 src/witbitz_code/folders.py
 src/witbitz_code/gateway.py
 src/witbitz_code/images.py
@@ -89,6 +90,7 @@ tests/test_confidential.py
 tests/test_connector_e2e.py
 tests/test_devicelink.py
 tests/test_dirs.py
+tests/test_files.py
 tests/test_files_and_compress.py
 tests/test_folders.py
 tests/test_images.py

{witbitz_code-1.13.0 → witbitz_code-1.15.0}/tests/test_auto.py

@@ -599,7 +599,7 @@ def test_wiring_the_page_switches_auto_and_the_verdict_comes_back(make, tmp_path
             client = PyClient(rig.secret, rig.relay.url)
             try:
                 await client.start()
-                assert client.hellos()[-1]["caps"] == ["auto", "attachments", "outputs", "tools", "seen", "asks", "folders", "remind"]
+                assert client.hellos()[-1]["caps"] == ["auto", "attachments", "outputs", "tools", "seen", "asks", "folders", "remind", "files"]
                 # a stale nonce cannot switch it: a recording cannot turn Auto on
                 await client.peer.send({"t": "auto", "k": "not-the-nonce", "sid": "ses_main", "dir": DIR, "on": True})
                 await asyncio.sleep(0.3)

{witbitz_code-1.13.0 → witbitz_code-1.15.0}/tests/test_connector_e2e.py

@@ -174,7 +174,7 @@ async def conformance(rig: Rig, connector) -> None:
         await client.start()
         hello = client.hellos()[-1]
         assert set(hello) == {"t", "ver", "name", "computerId", "k", "ts", "caps", "auto"} and hello["ver"] == "1"
-        assert (hello["caps"], hello["auto"]) == (["auto", "attachments", "outputs", "tools", "seen", "asks", "folders", "remind"], []), "both connectors do Auto mode (test_auto.py), save attachments, serve produced files, share what was seen, keep what is waiting (test_asks.py) and allow a folder (test_folders.py)"
+        assert (hello["caps"], hello["auto"]) == (["auto", "attachments", "outputs", "tools", "seen", "asks", "folders", "remind", "files"], []), "both connectors do Auto mode (test_auto.py), save attachments, serve produced files, share what was seen, keep what is waiting (test_asks.py), allow a folder (test_folders.py) and upload/download in the Files sheet (test_files.py)"
         assert (hello["name"], hello["computerId"]) == ("test-box", "cmp_test") and isinstance(hello["ts"], int)
         assert re.fullmatch(r"[A-Za-z0-9_-]{24}", hello["k"]), "18 random bytes, base64url"
 
@@ -345,6 +345,32 @@ async def conformance(rig: Rig, connector) -> None:
         assert (await client.call("POST", mk(), {"name": "..\\escape"}))["st"] == 400
         assert (await client.call("POST", mk(), {"nope": 1}))["st"] == 400
         assert (await client.call("POST", "/witbitz/mkdir?directory=rel&path=.", {"name": "x"}))["st"] == 400
+
+        # FILES (files.py = tools/code-files.mjs; the owner, 2026-10-24: "an upload and download menu"): Download any file of the
+        # session's folder — not a secret, not outside it — and Upload into it, never over a file unasked. The same on both.
+        fw = Path(tempfile.mkdtemp(prefix="wb-conf-files-")) / "proj"
+        (fw / "src").mkdir(parents=True)
+        (fw / "data.bin").write_bytes(b"\x00\x01\x02")
+        (fw / ".env").write_text("TOKEN=x")
+        (fw.parent / "outside.txt").write_text("no")
+        rig.oc.session_dirs["ses_files"] = str(fw)
+        dq = lambda p: f"/witbitz/download?session=ses_files&path={urllib.parse.quote(str(p), safe='')}"  # noqa: E731
+        got = await client.call("GET", dq(fw / "data.bin"))
+        assert got["st"] == 200 and base64.b64decode(json.loads(got["b"])["b64"]) == b"\x00\x01\x02", got
+        assert (await client.call("GET", dq(fw / ".env")))["st"] == 403
+        assert (await client.call("GET", dq(fw.parent / "outside.txt")))["st"] == 403
+        up = lambda body: client.call("POST", "/witbitz/upload?session=ses_files", body)  # noqa: E731
+        b64 = lambda s: base64.b64encode(s).decode()  # noqa: E731
+        made = await up({"dir": str(fw / "src"), "name": "John's notes, v2.md", "b64": b64(b"# hi")})
+        assert made["st"] == 200 and (fw / "src" / "John's notes, v2.md").read_bytes() == b"# hi", made
+        taken = await up({"dir": str(fw), "name": "data.bin", "b64": b64(b"new")})
+        assert taken["st"] == 409 and json.loads(taken["b"])["replaceable"] is True and (fw / "data.bin").read_bytes() == b"\x00\x01\x02"
+        assert (await up({"dir": str(fw), "name": "data.bin", "b64": b64(b"new"), "replace": True}))["st"] == 200
+        assert (fw / "data.bin").read_bytes() == b"new"
+        assert (await up({"dir": str(fw.parent), "name": "x.txt", "b64": b64(b"x")}))["st"] == 403
+        assert (await up({"dir": str(fw), "name": "src", "b64": b64(b"x"), "replace": True}))["st"] == 409
+        assert (await up("not an object"))["st"] == 400
+        assert (await client.call("GET", "/witbitz/download?session=ses_nope&path=%2Fx"))["st"] == 404
         assert not any(h.get("url", "").startswith("/witbitz") for h in rig.oc.seen_copy()), "OpenCode never sees the routes"
     finally:
         await client.peer.aclose()

witbitz_code-1.15.0/tests/test_files.py

@@ -0,0 +1,71 @@
+"""The Files sheet's Download and Upload — files.py, held to tools/code-files.mjs.
+
+The JS module is the reference: the same folder tree and the same requests must get the same answers from both connectors,
+so the sheet behaves the same whichever connector a computer runs.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+
+from conftest import requires_node, run_node
+
+from witbitz_code.files import download_file, is_upload_name, upload_file
+
+NAMES = ["John's report, v2 + notes #1 & more.pdf", "a+b.txt", "שלום.txt", "../x", "a/b", "a\\b", ".hidden", "", "..",
+         "x​.txt", "x‮.txt", " x.txt", "a" * 201]
+
+
+def _tree(tmp_path):
+    d = tmp_path / "proj"
+    out = tmp_path / "elsewhere"
+    (d / "src").mkdir(parents=True)
+    out.mkdir()
+    (d / "report.xlsx").write_bytes(bytes([1, 2, 3, 4]))
+    (d / ".env").write_text("TOKEN=x")
+    (out / "private.txt").write_text("not yours")
+    os.symlink(out, d / "link-out")
+    return str(d), str(out)
+
+
+def _b64(s: str) -> str:
+    return base64.b64encode(s.encode()).decode()
+
+
+def _j(r):
+    return r[0], json.loads(r[1])
+
+
+def test_download_any_file_but_never_a_secret_or_outside(tmp_path):
+    d, out = _tree(tmp_path)
+    st, b = _j(download_file(directory=d, path=f"{d}/report.xlsx"))
+    assert st == 200 and base64.b64decode(b["b64"]) == bytes([1, 2, 3, 4]) and b["kind"] == "file"
+    assert _j(download_file(directory=d, path=f"{d}/.env"))[0] == 403
+    assert _j(download_file(directory=d, path=f"{out}/private.txt"))[0] == 403
+    assert _j(download_file(directory=d, path=f"{d}/link-out/private.txt"))[0] == 403
+
+
+def test_upload_creates_refuses_overwrite_and_replaces_when_asked(tmp_path):
+    d, out = _tree(tmp_path)
+    st, b = _j(upload_file(directory=d, dir=f"{d}/src", name="notes.md", b64=_b64("# hi")))
+    assert st == 200 and (tmp_path / "proj" / "src" / "notes.md").read_text() == "# hi" and b["replaced"] is False
+    st, b = _j(upload_file(directory=d, dir=d, name="report.xlsx", b64=_b64("new")))
+    assert st == 409 and b["replaceable"] is True and (tmp_path / "proj" / "report.xlsx").read_bytes() == bytes([1, 2, 3, 4])
+    assert _j(upload_file(directory=d, dir=d, name="src", b64=_b64("x"), replace=True))[1]["replaceable"] is False
+    assert _j(upload_file(directory=d, dir=d, name="report.xlsx", b64=_b64("new"), replace=True))[0] == 200
+    assert (tmp_path / "proj" / "report.xlsx").read_text() == "new"
+    assert _j(upload_file(directory=d, dir=f"{d}/link-out", name="x.txt", b64=_b64("x")))[0] == 403
+    assert not (tmp_path / "elsewhere" / "x.txt").exists()
+    assert _j(upload_file(directory=d, dir=d, name="x.txt", b64="not base64!"))[0] == 400
+    assert not [f for f in os.listdir(d) if ".upload-" in f], "no temporary left behind"
+
+
+@requires_node
+def test_parity_with_the_js_connector(tmp_path):
+    js = run_node("""
+      import { isUploadName } from '@TOOLS@/code-files.mjs'
+      OUT(INPUT.names.map((n) => isUploadName(n)))
+    """, {"names": NAMES})
+    assert [is_upload_name(n) for n in NAMES] == js

{witbitz_code-1.13.0 → witbitz_code-1.15.0}/tests/test_outputs.py

@@ -67,11 +67,30 @@ def _requests(d: Path, outside: Path, root: Path) -> list[dict]:
              {"directory": str(d), "path": str(d / "out" / "big.pdf"), "stat": False, "maxBytes": 1024},
              {"directory": str(d), "path": str(d / "out" / "big.pdf"), "stat": True, "maxBytes": 1024},
              {"directory": str(d), "path": None, "stat": False}]
+    # the agent's screenshots: <home>/.witbitz/screens/<session>, served for that session only (2026-10-25)
+    mine, theirs = root / "screens" / "ses_A", root / "screens" / "ses_B"
+    reqs += [{"directory": str(d), "path": str(mine / "screen-1.jpg"), "stat": False, "shots": str(mine)},
+             {"directory": str(d), "path": str(theirs / "screen-2.jpg"), "stat": False, "shots": str(mine)},
+             {"directory": str(d), "path": str(mine / "screen-1.jpg"), "stat": False},
+             {"directory": str(d), "path": str(mine / "out.pdf"), "stat": False, "shots": str(mine)},
+             {"directory": str(d), "path": str(d / "out" / "chart.png"), "stat": False, "shots": str(mine)}]
     return reqs
 
 
+def _screens(root: Path, outside: Path) -> None:
+    mine, theirs = root / "screens" / "ses_A", root / "screens" / "ses_B"
+    mine.mkdir(parents=True)
+    theirs.mkdir(parents=True)
+    for p, b in [(mine / "screen-1.jpg", b"JPEGA"), (theirs / "screen-2.jpg", b"JPEGB")]:
+        p.write_bytes(b)
+        os.utime(p, (1789000000, 1789000000))
+    (mine / "out.pdf").symlink_to(outside / "report.pdf")
+
+
 def _py(r: dict) -> list:
     kw = {"max_bytes": r["maxBytes"]} if "maxBytes" in r else {}
+    if "shots" in r:
+        kw["shots"] = r["shots"]
     st, b = serve_output(directory=r["directory"], path=r["path"], stat=r["stat"], **kw)
     return [st, json.loads(b)]
 
@@ -92,12 +111,13 @@ def test_what_the_python_connector_serves(tmp_path):
 @requires_node
 def test_parity_with_the_js_connector(tmp_path):
     d, outside = _tree(tmp_path)
+    _screens(tmp_path, outside)
     reqs = _requests(d, outside, tmp_path)
     js = run_node("""
       import { serveOutput } from '@TOOLS@/code-outputs.mjs'
       import { outputMime } from '@PUBLIC@/codeOutputs.js'
       OUT({
-        served: INPUT.reqs.map((r) => { const o = serveOutput({ directory: r.directory, path: r.path, stat: r.stat, ...(r.maxBytes ? { maxBytes: r.maxBytes } : {}) }); return [o.st, JSON.parse(o.b)] }),
+        served: INPUT.reqs.map((r) => { const o = serveOutput({ directory: r.directory, path: r.path, stat: r.stat, ...(r.maxBytes ? { maxBytes: r.maxBytes } : {}), ...(r.shots ? { shots: r.shots } : {}) }); return [o.st, JSON.parse(o.b)] }),
         mimes: INPUT.exts.map((e) => outputMime('/a/x.' + e)),
       })
     """, {"reqs": reqs, "exts": EXTS})
@@ -108,3 +128,12 @@ def test_parity_with_the_js_connector(tmp_path):
 
 EXTS = ["pdf", "PNG", "jpg", "jpeg", "gif", "webp", "csv", "tsv", "md", "markdown", "txt", "docx", "doc", "xlsx", "xls", "pptx", "ppt",
         "odt", "ods", "odp", "rtf", "zip", "epub", "heic", "svg", "html", "htm", "mp3", "wav", "m4a", "mp4", "mov", "ts", "json", ""]
+
+
+def test_a_screenshot_is_served_for_its_own_session_only(tmp_path):
+    d, outside = _tree(tmp_path)
+    _screens(tmp_path, outside)
+    mine = tmp_path / "screens" / "ses_A"
+    assert _py({"directory": str(d), "path": str(mine / "screen-1.jpg"), "stat": False, "shots": str(mine)})[0] == 200
+    assert _py({"directory": str(d), "path": str(tmp_path / "screens" / "ses_B" / "screen-2.jpg"), "stat": False, "shots": str(mine)})[0] == 403
+    assert _py({"directory": str(d), "path": str(mine / "out.pdf"), "stat": False, "shots": str(mine)})[0] == 403, "a link out"