From b6902eecd328e9f70be4bb458028d429a7da54fc Mon Sep 17 00:00:00 2001 From: dawn <90008@klbr.net> Date: Wed, 30 Sep 2026 21:21:42 +0300 Subject: [PATCH] remote: show remote images with the local cell's result under its limits Signed-off-by: dawn <90008@klbr.net> --- priv/python/albedo_plugins/remote.py | 47 +++++++--- robot-docs/extensions.md | 4 +- .../harness/extensions/remote/extension.gleam | 7 +- test/e2e/image_limits_test.py | 89 ++++++++++++++++++- 4 files changed, 131 insertions(+), 16 deletions(-) diff --git a/priv/python/albedo_plugins/remote.py b/priv/python/albedo_plugins/remote.py index d467b179..7dd8f74f 100644 --- a/priv/python/albedo_plugins/remote.py +++ b/priv/python/albedo_plugins/remote.py @@ -40,12 +40,14 @@ INVOKE_TIMEOUT = 3600 # anti-wedge bound; the cell deadline is the real limit COMMAND_TIMEOUT = 120 # degraded-mode command default MAX_FRAME = 8 * 1024 * 1024 # control-frame ceiling, as in the kernel STDERR_TAIL = 65536 # bytes of ssh diagnostics kept for failures +IMAGE_READ = 5 * 1024 * 1024 + 1 # one past a cell's image bytes, as local reads loop: asyncio.AbstractEventLoop host_call: Any HostErrorType: type[Exception] capture_factory: Any send_frame: Any +attach_image: Any session_modules: list[str] = [] _fallback_live: set[str] = set() # degraded-mode jobs still running over ssh @@ -846,12 +848,36 @@ class RemoteConnection: async def read(self, path: str, *, timeout: float = COMMAND_TIMEOUT) -> str: """A remote file's text over the control connection, not the kernel.""" remote = _remote_path(self, path) - code, stdout, stderr = await ssh_run( - self.host, f"cat {shlex.quote(remote)}", timeout=timeout - ) + data = await self._ssh(f"cat {shlex.quote(remote)}", timeout) + return data.decode(errors="replace") + + async def show_image( + self, + source: bytes | str | os.PathLike[str], + *, + timeout: float = COMMAND_TIMEOUT, + ) -> str: + """Return a remote image to yourself with this cell's result, under the + same limits as local show_image. The remote kernel has no cell of its + own to carry one, so the bytes come here over the control connection.""" + if attach_image is None: + raise RemoteError("this kernel cannot attach images") + if isinstance(source, (bytes, bytearray, memoryview)): + data = bytes(source) + elif isinstance(source, (str, os.PathLike)): + remote = shlex.quote(_remote_path(self, os.fspath(source))) + data = await self._ssh(f"head -c {IMAGE_READ} {remote}", timeout) + else: + raise TypeError( + f"show_image takes image bytes or a remote path, not {type(source).__name__}" + ) + return "attached " + attach_image(data) + + async def _ssh(self, script: str, timeout: float) -> bytes: + code, stdout, stderr = await ssh_run(self.host, script, timeout=timeout) if code != 0: raise RemoteError(f"SSH failed ({code}): {stderr.strip()}") - return stdout.decode(errors="replace") + return stdout async def write( self, path: str, content: str, *, timeout: float = COMMAND_TIMEOUT @@ -859,13 +885,10 @@ class RemoteConnection: """Replace a remote file; bytes travel base64, never as shell text.""" remote = _remote_path(self, path) encoded = base64.b64encode(content.encode()).decode() - code, _, stderr = await ssh_run( - self.host, + await self._ssh( f"printf %s {shlex.quote(encoded)} | base64 -d > {shlex.quote(remote)}", - timeout=timeout, + timeout, ) - if code != 0: - raise RemoteError(f"SSH failed ({code}): {stderr.strip()}") # --- degraded mode --- @@ -1259,7 +1282,8 @@ class Remote: `remote.configure` stored, then `$ALBEDO_SSH`, then the `remote` section of extensions.json. If the host is reachable but the kernel cannot boot, the connection still returns, prints a warning, and - answers `rem.run()`, degraded-only `rem.shell()`, `rem.read`, and `rem.write`. + answers `rem.run()`, degraded-only `rem.shell()`, `rem.read`, `rem.write`, + and `rem.show_image`. """ target = resolve(host, remote_cwd, python) code, _, stderr = await ssh_run( @@ -1315,10 +1339,11 @@ remote = Remote() def setup(api: PythonApi) -> dict[str, object]: global loop, host_call, HostErrorType, capture_factory, send_frame - global session_modules + global attach_image, session_modules loop, host_call = api.loop, api.host HostErrorType, capture_factory = api.HostError, api.capture send_frame = api.send + attach_image = api.attach_image session_modules = list(api.modules) api.on_shutdown(Remote.close_all) return {"remote": remote, "RemoteError": RemoteError} diff --git a/robot-docs/extensions.md b/robot-docs/extensions.md index d94f3cf1..dd890abb 100644 --- a/robot-docs/extensions.md +++ b/robot-docs/extensions.md @@ -149,6 +149,8 @@ the `remote` extension boots this session's Python kernel on a remote host over machine tools run on the remote kernel: `rem.run(program, *args)` starts a supervised job on the host immediately and synchronously, like local run — the handle exists right away, `job.tail()`, `job.id`, `job.exit_code`, `job.duration`, `job.waited`, and `job.timed_out` answer synchronously from the mirrored output stream, `await job` waits for completion, and `await job.stop()` stops it. pipes run entirely on the host, chained before the one await: `job = await rem.run("journalctl", "-u", "nginx", "--no-pager").pipe("rg", "error")`, then `job.tail(lines=40)`. `tail(lines=)` and `exit_code` answer from the mirror; other job methods, like `head(lines=)`, are remote calls to await, and properties such as `job.pipeline` do not cross. session tools run where the daemon runs: `await rem.work.*` and `await rem.skills.*` relay over the connection to the local daemon's ledger and catalog. both kernels load the same content-hashed bundle, so a tool's remote shape matches its local one. every other call returns a reference that settles on its first await: values cross as real objects — dataclasses and list subclasses are rebuilt, so remote output prints exactly like local output — and a result that cannot cross comes back as a live reference whose methods are further remote calls. references passed back into remote calls stay references, not copies, including ones still in flight. one rule remains: a call whose local counterpart is synchronous (`rem.files.read`) still needs `await`, because the value itself crosses the network; handles and their state never do. +images are the exception to "every harness tool runs remotely": a remote call is not a cell, so the remote kernel has no result to carry one. `await rem.show_image(path_or_bytes)` runs locally instead: it reads a remote path over the control connection (at most one byte past the 5 MiB a cell may carry) and attaches the bytes to the local cell through `api.attach_image`, so the image meets the same format, count, size and edge checks as `show_image`. it works in degraded mode too. + the target resolves per call from a `host=` argument, then `remote.configure(host, remote_cwd=None)`, then `$ALBEDO_SSH` (`user@host[:/path]`), then the `remote` section of extensions.json: ```json @@ -157,7 +159,7 @@ the target resolves per call from a `host=` argument, then `remote.configure(hos } ``` -a bare host asks the remote for its `pwd` once. if the host is reachable but its kernel cannot boot (no python, staging failed, bad handshake), `connect()` still returns and prints a warning: the connection is degraded to SSH command mode, where only `rem.run(program, *args, cwd=, env=, stdin=, timeout=300)`, `rem.shell(command, cwd=, env=, stdin=, timeout=300)`, `rem.read(path)`, and `rem.write(path, content)` answer and everything else raises. here `stdin` accepts only text or bytes, not a file or another job, and `.pipe()` is unavailable. The connect warning shows the degraded-only escape hatch `rem.shell('git log --oneline | rg fix')`, which invokes `bash -c` on the host for pipes or other shell syntax. `rem.shell()` does not exist in kernel mode. Neither the quoted-argv `rem.run()` fallback nor `rem.shell()` can offer process-group supervision, so stopping or timing out an ssh client does not prove the remote program stopped. an unreachable host fails `connect()`. connections are scoped: a lost SSH channel invalidates the connection rather than silently reconnecting, and `await rem.close()` ends it. connections run under `BatchMode=yes`, so key-based auth is required. +a bare host asks the remote for its `pwd` once. if the host is reachable but its kernel cannot boot (no python, staging failed, bad handshake), `connect()` still returns and prints a warning: the connection is degraded to SSH command mode, where only `rem.run(program, *args, cwd=, env=, stdin=, timeout=300)`, `rem.shell(command, cwd=, env=, stdin=, timeout=300)`, `rem.read(path)`, `rem.write(path, content)`, and `rem.show_image(path_or_bytes)` answer and everything else raises. here `stdin` accepts only text or bytes, not a file or another job, and `.pipe()` is unavailable. The connect warning shows the degraded-only escape hatch `rem.shell('git log --oneline | rg fix')`, which invokes `bash -c` on the host for pipes or other shell syntax. `rem.shell()` does not exist in kernel mode. Neither the quoted-argv `rem.run()` fallback nor `rem.shell()` can offer process-group supervision, so stopping or timing out an ssh client does not prove the remote program stopped. an unreachable host fails `connect()`. connections are scoped: a lost SSH channel invalidates the connection rather than silently reconnecting, and `await rem.close()` ends it. connections run under `BatchMode=yes`, so key-based auth is required. ## skills diff --git a/src/albedo/harness/extensions/remote/extension.gleam b/src/albedo/harness/extensions/remote/extension.gleam index 819ebddc..5e1ec154 100644 --- a/src/albedo/harness/extensions/remote/extension.gleam +++ b/src/albedo/harness/extensions/remote/extension.gleam @@ -37,15 +37,16 @@ pub fn extension() -> harness_extension.Extension { <> " still needs await, because the value itself crosses the network; handles and" <> " their state never do. await rem.tools() lists what the remote namespace holds;" <> " await rem.read(path) and await rem.write(path, content) move one file's text" - <> " directly. remote.connections() lists open connections (awaiting it also works) and await" + <> " directly, and await rem.show_image(path_or_bytes) returns a remote image with" + <> " this cell's result under the same limits as show_image. remote.connections() lists open connections (awaiting it also works) and await" <> " remote.close_all() ends them all. Failures raise RemoteError." <> " The target resolves per call from a host=" <> " argument, then remote.configure(host, remote_cwd=None), then $ALBEDO_SSH" <> " (user@host[:/path]), or the \"remote\" section of extensions.json (host," <> " remoteCwd, python). If the host is reachable but its kernel cannot boot, the" <> " connection still returns, prints a warning, and answers only rem.run(program," - <> " *args, cwd=None, env=None, stdin=None, timeout=300), rem.read(path), and rem.write(path," - <> " content). The degraded-mode warning gives an explicit rem.shell(command) escape" + <> " *args, cwd=None, env=None, stdin=None, timeout=300), rem.read(path), rem.write(path," + <> " content), and rem.show_image(path_or_bytes). The degraded-mode warning gives an explicit rem.shell(command) escape" <> " hatch for pipes; it is unavailable in kernel mode. Degraded stdin takes only" <> " text or bytes, not a file or job; .pipe() is unavailable, and stopping SSH" <> " cannot prove the remote process stopped. Connections are" diff --git a/test/e2e/image_limits_test.py b/test/e2e/image_limits_test.py index 2f13a11a..1663a531 100644 --- a/test/e2e/image_limits_test.py +++ b/test/e2e/image_limits_test.py @@ -31,6 +31,19 @@ def png(width, height): ) +# An ssh first on the kernel's PATH that runs the command right here, so +# remote.connect boots, stages and talks to a real remote kernel. +LOOPBACK_SSH = """#!/bin/sh +while [ $# -gt 0 ]; do + case "$1" in + -*) shift 2 ;; + *) break ;; + esac +done +shift +exec sh -c "$*" +""" + WIDE = png(1200, 10) WIDE_DATA = base64.b64encode(WIDE).decode() NOTE = "An earlier image was scaled from 1200x10 to 1000x" @@ -42,6 +55,15 @@ def widths(request): return [struct.unpack(">I", base64.b64decode(data)[16:20])[0] for data in found] +def cell_result(output): + """The python tool's result: plain text, or the text part beside images.""" + body = output["output"] + if isinstance(body, str): + return json.loads(body) + [text] = [part["text"] for part in body if part.get("type") == "input_text"] + return json.loads(text) + + class ImageLimitsTest(unittest.TestCase): def test_a_declared_edge_refuses_new_images_and_fits_history(self): def reply(request): @@ -124,7 +146,7 @@ class ImageLimitsTest(unittest.TestCase): if item.get("type") == "function_call_output" ) # show_image refuses it at the call, so the cell fails there. - result = json.loads(output["output"]) + result = cell_result(output) self.assertEqual(result["status"], "error") self.assertIn( "ValueError: 1200x10 image is over this model's 1000px edge limit", @@ -184,6 +206,71 @@ class ImageLimitsTest(unittest.TestCase): finally: provider.close() + def test_a_remote_image_is_shown_under_the_same_limits(self): + cell = ( + """import os +os.makedirs("bin", exist_ok=True) +with open("bin/ssh", "w") as script: + script.write(%r) +os.chmod("bin/ssh", 0o755) +os.environ["PATH"] = os.path.abspath("bin") + os.pathsep + os.environ["PATH"] +rem = await remote.connect("loopback") +try: + print(await rem.show_image("small.png")) + await rem.show_image("wide.png") +finally: + await rem.close() +""" + % LOOPBACK_SSH + ) + + def reply(request): + if request["input"][-1].get("type") == "function_call_output": + return text("done") + return python(cell) + + provider = Provider(reply) + profile = { + "baseUrl": provider.url, + "apiKey": "fixture-key", + "model": "fixture-model", + "protocol": "responses", + "imageEdge": 1000, + } + try: + with Albedo( + provider, + protocol="responses", + providers={f"strict-{provider.route}": profile}, + ) as app: + (app.workspace / "small.png").write_bytes(png(10, 10)) + (app.workspace / "wide.png").write_bytes(WIDE) + session = app.session() + app.prompt(session, "remote").close() + app.idle(session) + [request] = [ + r["request"] + for r in provider.requests + if r["request"]["input"][-1].get("type") == "function_call_output" + ] + output = next( + item + for item in request["input"] + if item.get("type") == "function_call_output" + ) + result = cell_result(output) + # The small image came over the connection and went on to the + # model; the wide one failed the cell at its call. + self.assertIn("attached image/png", result["output"]) + self.assertEqual(result["status"], "error") + self.assertIn( + "ValueError: 1200x10 image is over this model's 1000px edge limit", + result["output"], + ) + self.assertEqual(widths(request), [10]) + finally: + provider.close() + if __name__ == "__main__": unittest.main() -- knotmirror 0.0.1