feat(operator): Phase 2 — sandbox drive (exec/write/get) + keystroke relay
Co-located mode: the operator launches its own podman/docker container and execs into it out-of-band (argv-identical to the native harness), exposed as `sbx launch|status|down`, `exec`, `write`, `get`. When granted, it can also drive the room's broker-owned container directly on the same host. Relay mode primitive: `keys` injects raw bytes into the shared PTY via the same `_sbx:input` frame a human driver emits — full keyboard control incl. the stop-vocabulary (ctrl-c/ctrl-d/ctrl-z/ctrl-\, esc, arrows, pager q). A compact per-session cheat-sheet (`sandbox.KEYS_HELP`, `keys --help-keys`) documents what each inject does and how to end a stuck program, token-efficiently. Gating: exec/write/get refuse a host (`local`) inherited from the room; the room sandbox is only driven when `granted`. Keystrokes are inert until granted. 17 offline tests green; e2e verified against real podman (launch→exec→write→ get round-trip→teardown) and through the CLI socket. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
leetcrypt
@@ -58,6 +58,36 @@ def _build_parser() -> argparse.ArgumentParser:
|
||||
s.add_argument("text", nargs="+")
|
||||
s.add_argument("--session", default=None)
|
||||
|
||||
# ── sandbox drive ───────────────────────────────────────────────────
|
||||
sb = sub.add_parser("sbx", help="manage the operator's own container")
|
||||
sb.add_argument("action", choices=["launch", "status", "down"], nargs="?",
|
||||
default="status")
|
||||
sb.add_argument("--engine", default=None, help="podman|docker (default: auto)")
|
||||
sb.add_argument("--image", default=None, help="container image (default per engine)")
|
||||
sb.add_argument("--name", default=None, help="container name (default: hh-op-<user>)")
|
||||
sb.add_argument("--session", default=None)
|
||||
|
||||
ex = sub.add_parser("exec", help="run a shell command in the sandbox")
|
||||
ex.add_argument("cmd", nargs="+")
|
||||
ex.add_argument("--session", default=None)
|
||||
|
||||
wr = sub.add_parser("write", help="write a file in the sandbox (content from stdin or --text)")
|
||||
wr.add_argument("path")
|
||||
wr.add_argument("--text", default=None, help="inline content (else read stdin)")
|
||||
wr.add_argument("--session", default=None)
|
||||
|
||||
gt = sub.add_parser("get", help="read a file out of the sandbox")
|
||||
gt.add_argument("path")
|
||||
gt.add_argument("--out", default=None, help="write to this local path (else stdout)")
|
||||
gt.add_argument("--session", default=None)
|
||||
|
||||
ky = sub.add_parser("keys", help="inject keystrokes into the room's shared PTY")
|
||||
ky.add_argument("keys", nargs="*",
|
||||
help="tokens: literal text, named keys (enter, ctrl-c, esc, "
|
||||
"up…), text:<verbatim>, hex:<bytes>")
|
||||
ky.add_argument("--help-keys", action="store_true", help="print the key vocabulary")
|
||||
ky.add_argument("--session", default=None)
|
||||
|
||||
for v in ("roster", "status", "down"):
|
||||
sub.add_parser(v).add_argument("--session", default=None)
|
||||
return ap
|
||||
@@ -191,6 +221,67 @@ def _run_say(args) -> int:
|
||||
return 0
|
||||
|
||||
|
||||
def _run_sbx(args) -> int:
|
||||
resp = _client_request(args, {"op": "sbx", "action": args.action,
|
||||
"engine": args.engine, "image": args.image,
|
||||
"name": args.name})
|
||||
print(json.dumps(resp))
|
||||
return 0 if resp.get("ok") else 1
|
||||
|
||||
|
||||
def _run_exec(args) -> int:
|
||||
cmd = " ".join(args.cmd)
|
||||
resp = _client_request(args, {"op": "exec", "cmd": cmd})
|
||||
out = resp.get("output", "")
|
||||
if out:
|
||||
sys.stdout.write(out if out.endswith("\n") else out + "\n")
|
||||
if not resp.get("ok"):
|
||||
if "error" in resp:
|
||||
print(resp["error"], file=sys.stderr)
|
||||
return resp.get("rc", 1) or 1
|
||||
return 0
|
||||
|
||||
|
||||
def _run_write(args) -> int:
|
||||
text = args.text if args.text is not None else sys.stdin.read()
|
||||
resp = _client_request(args, {"op": "write", "path": args.path, "content": text})
|
||||
if not resp.get("ok"):
|
||||
print(resp.get("error", "write failed"), file=sys.stderr)
|
||||
return 1
|
||||
print(f"wrote {resp.get('path')} ({resp.get('bytes')} bytes)", file=sys.stderr)
|
||||
return 0
|
||||
|
||||
|
||||
def _run_get(args) -> int:
|
||||
import base64
|
||||
resp = _client_request(args, {"op": "get", "path": args.path})
|
||||
if not resp.get("ok"):
|
||||
print(resp.get("error", "get failed"), file=sys.stderr)
|
||||
return 1
|
||||
raw = base64.b64decode(resp.get("b64", ""))
|
||||
if args.out:
|
||||
Path(args.out).write_bytes(raw)
|
||||
print(f"wrote {args.out} ({len(raw)} bytes)", file=sys.stderr)
|
||||
else:
|
||||
sys.stdout.buffer.write(raw)
|
||||
return 0
|
||||
|
||||
|
||||
def _run_keys(args) -> int:
|
||||
from . import sandbox as sbx
|
||||
if args.help_keys:
|
||||
print(sbx.KEYS_HELP)
|
||||
return 0
|
||||
if not args.keys:
|
||||
print("no keys given (try --help-keys)", file=sys.stderr)
|
||||
return 2
|
||||
resp = _client_request(args, {"op": "keys", "keys": args.keys})
|
||||
if not resp.get("ok"):
|
||||
print(resp.get("error", "keys failed"), file=sys.stderr)
|
||||
return 1
|
||||
return 0
|
||||
|
||||
|
||||
def _run_simple(args, op: str) -> int:
|
||||
resp = _client_request(args, {"op": op})
|
||||
print(json.dumps(resp))
|
||||
@@ -208,6 +299,16 @@ def main(argv: list[str] | None = None) -> int:
|
||||
return _run_read(args)
|
||||
if verb == "say":
|
||||
return _run_say(args)
|
||||
if verb == "sbx":
|
||||
return _run_sbx(args)
|
||||
if verb == "exec":
|
||||
return _run_exec(args)
|
||||
if verb == "write":
|
||||
return _run_write(args)
|
||||
if verb == "get":
|
||||
return _run_get(args)
|
||||
if verb == "keys":
|
||||
return _run_keys(args)
|
||||
if verb in ("roster", "status", "down"):
|
||||
return _run_simple(args, verb)
|
||||
return 2
|
||||
|
||||
@@ -25,6 +25,7 @@ import time
|
||||
import websockets
|
||||
|
||||
from ..client.client import Client
|
||||
from . import sandbox as sbx
|
||||
from .session import Session
|
||||
|
||||
|
||||
@@ -56,6 +57,12 @@ class OperatorBridge(Client):
|
||||
self.sbx_engine: str | None = None
|
||||
self.sbx_name: str = ""
|
||||
|
||||
# Co-located sandbox the operator launched itself (Phase 2). When set we
|
||||
# exec straight into it (out-of-band); independent of the room's broker
|
||||
# sandbox, which we can also drive when co-located + granted.
|
||||
self._own_engine: str | None = None
|
||||
self._own_name: str = ""
|
||||
|
||||
# Live websocket (None while reconnecting); set in _connect_and_serve.
|
||||
self._ws = None
|
||||
self._stop = asyncio.Event()
|
||||
@@ -285,6 +292,16 @@ class OperatorBridge(Client):
|
||||
return await self._op_read(req)
|
||||
if op == "say":
|
||||
return await self._op_say(req)
|
||||
if op == "sbx":
|
||||
return await self._op_sbx(req)
|
||||
if op == "exec":
|
||||
return await self._op_exec(req)
|
||||
if op == "write":
|
||||
return await self._op_write(req)
|
||||
if op == "get":
|
||||
return await self._op_get(req)
|
||||
if op == "keys":
|
||||
return await self._op_keys(req)
|
||||
if op == "down":
|
||||
asyncio.get_running_loop().call_soon(self._begin_shutdown)
|
||||
return {"ok": True, "stopping": True}
|
||||
@@ -317,6 +334,141 @@ class OperatorBridge(Client):
|
||||
await self._emit("sent", **{"from": self.name}, text=text, addressed=False)
|
||||
return {"ok": True}
|
||||
|
||||
# ── sandbox drive (Phase 2) ──────────────────────────────────────────
|
||||
def _target(self) -> tuple[str | None, str, str | None]:
|
||||
"""Pick the sandbox to exec into and report why.
|
||||
|
||||
Returns ``(engine, name, error)``. Prefer the operator's *own* container
|
||||
(always ours to drive). Else, if the room granted us drive AND its broker
|
||||
sandbox is a kind we can exec directly (we're co-located on this host),
|
||||
target that. ``local`` is refused here — execing on the host is opt-in
|
||||
only via our own `local` launch, never inherited from the room."""
|
||||
if self._own_engine:
|
||||
return self._own_engine, self._own_name, None
|
||||
if self.granted and self.sbx_engine in ("docker", "podman", "multipass") \
|
||||
and self.sbx_name:
|
||||
return self.sbx_engine, self.sbx_name, None
|
||||
if self.sbx_engine and not self.granted:
|
||||
return None, "", "not a granted driver (owner must `/grant`)"
|
||||
return None, "", "no sandbox — `sbx launch` one or join a room with one"
|
||||
|
||||
async def _op_sbx(self, req: dict) -> dict:
|
||||
"""Manage the operator's own co-located container: launch / status / down."""
|
||||
action = req.get("action", "status")
|
||||
if action == "launch":
|
||||
engine = req.get("engine") or sbx.pick_engine()
|
||||
if not engine:
|
||||
return {"ok": False, "error": "no container engine (need podman or docker)"}
|
||||
image = req.get("image") or sbx.default_image(engine)
|
||||
name = req.get("name") or f"hh-op-{self.name}"
|
||||
ok, msg = await sbx.launch_container(engine, name, image)
|
||||
if ok:
|
||||
self._own_engine, self._own_name = engine, name
|
||||
await self._emit("sandbox", state="own-ready", engine=engine,
|
||||
name=name, image=image)
|
||||
return {"ok": ok, "engine": engine, "name": name, "image": image,
|
||||
"message": msg}
|
||||
if action == "down":
|
||||
if not self._own_engine:
|
||||
return {"ok": False, "error": "no own sandbox to tear down"}
|
||||
ok, msg = await sbx.teardown_container(self._own_engine, self._own_name)
|
||||
if ok:
|
||||
await self._emit("sandbox", state="own-down",
|
||||
engine=self._own_engine, name=self._own_name)
|
||||
self._own_engine, self._own_name = None, ""
|
||||
return {"ok": ok, "message": msg}
|
||||
# status
|
||||
engine, name, err = self._target()
|
||||
return {"ok": True, "target_engine": engine, "target_name": name,
|
||||
"reason": err, "own_engine": self._own_engine,
|
||||
"own_name": self._own_name, "room_engine": self.sbx_engine,
|
||||
"room_name": self.sbx_name, "granted": self.granted}
|
||||
|
||||
async def _op_exec(self, req: dict) -> dict:
|
||||
"""Run a shell command in the target sandbox, capture combined output +
|
||||
exit code. The command runs under `sh -c` (a real shell, intended) inside
|
||||
the container — the container is the blast radius."""
|
||||
cmd = str(req.get("cmd", ""))
|
||||
if not cmd:
|
||||
return {"ok": False, "error": "empty cmd"}
|
||||
engine, name, err = self._target()
|
||||
if err:
|
||||
return {"ok": False, "error": err}
|
||||
prefix = sbx.exec_prefix(engine, name)
|
||||
if prefix is None:
|
||||
return {"ok": False, "error": f"can't address {engine}/{name}"}
|
||||
out, rc = await sbx.exec_capture(prefix + ["sh", "-c", cmd])
|
||||
await self._emit("exec", engine=engine, name=name, cmd=cmd, rc=rc)
|
||||
return {"ok": rc == 0, "rc": rc, "output": out, "engine": engine, "name": name}
|
||||
|
||||
async def _op_write(self, req: dict) -> dict:
|
||||
"""Write a file in the target sandbox. Content arrives on stdin (never
|
||||
shell-parsed); the path is a positional arg. `mkdir -p` the parent first
|
||||
so an absolute path into a new dir works. Mirrors the native harness."""
|
||||
path = str(req.get("path", "")).strip()
|
||||
if not path:
|
||||
return {"ok": False, "error": "missing path"}
|
||||
content = req.get("content", "")
|
||||
data = content.encode() if isinstance(content, str) else bytes(content)
|
||||
engine, name, err = self._target()
|
||||
if err:
|
||||
return {"ok": False, "error": err}
|
||||
prefix = sbx.exec_prefix(engine, name)
|
||||
if prefix is None:
|
||||
return {"ok": False, "error": f"can't address {engine}/{name}"}
|
||||
out, rc = await sbx.exec_capture(
|
||||
prefix + ["sh", "-c", 'mkdir -p "$(dirname "$1")" && cat > "$1"',
|
||||
"hh-write", path],
|
||||
stdin=data)
|
||||
await self._emit("write", engine=engine, name=name, path=path, rc=rc)
|
||||
return {"ok": rc == 0, "rc": rc, "path": path, "bytes": len(data),
|
||||
"output": out if (out or "").strip() else ""}
|
||||
|
||||
async def _op_get(self, req: dict) -> dict:
|
||||
"""Read a file out of the target sandbox. Returns base64 (binary-safe);
|
||||
the content is plumbing, so it's uncapped (unlike exec output)."""
|
||||
path = str(req.get("path", "")).strip()
|
||||
if not path:
|
||||
return {"ok": False, "error": "missing path"}
|
||||
engine, name, err = self._target()
|
||||
if err:
|
||||
return {"ok": False, "error": err}
|
||||
prefix = sbx.exec_prefix(engine, name)
|
||||
if prefix is None:
|
||||
return {"ok": False, "error": f"can't address {engine}/{name}"}
|
||||
raw, rc = await sbx.exec_capture(prefix + ["cat", "--", path], text=False)
|
||||
if rc != 0:
|
||||
return {"ok": False, "rc": rc,
|
||||
"error": f"read failed (exit={rc}): {raw.decode(errors='replace')[:200]}"}
|
||||
return {"ok": True, "rc": 0, "path": path,
|
||||
"b64": base64.b64encode(raw).decode(), "bytes": len(raw)}
|
||||
|
||||
async def _op_keys(self, req: dict) -> dict:
|
||||
"""Relay raw keystrokes into the room's *shared* PTY — the same
|
||||
`_sbx:input` frame a human driver's terminal emits. The broker writes our
|
||||
bytes to the shared shell iff we're a granted driver, so this is how the
|
||||
operator drives a broker-owned sandbox (and tests interactive programs:
|
||||
ctrl-c to stop, q to quit a pager, esc to leave vim). See
|
||||
`sandbox.KEYS_HELP` for the byte vocabulary."""
|
||||
if self._ws is None:
|
||||
return {"ok": False, "error": "not connected to room"}
|
||||
if not self.granted:
|
||||
return {"ok": False, "error": "not a granted driver — keystrokes inert until `/grant`"}
|
||||
spec = req.get("keys")
|
||||
if spec in (None, "", []):
|
||||
return {"ok": False, "error": "no keys", "help": sbx.KEYS_HELP}
|
||||
try:
|
||||
data = sbx.encode_keys(spec)
|
||||
except ValueError as e:
|
||||
return {"ok": False, "error": f"bad key spec: {e}"}
|
||||
frame = json.dumps({"_sbx": "input", "b64": base64.b64encode(data).decode()})
|
||||
try:
|
||||
await self._ws.send(self.room_fernet.encrypt(frame.encode()).decode())
|
||||
except Exception as e: # noqa: BLE001
|
||||
return {"ok": False, "error": f"send failed: {type(e).__name__}: {e}"}
|
||||
await self._emit("keys", bytes=len(data))
|
||||
return {"ok": True, "bytes": len(data)}
|
||||
|
||||
def _begin_shutdown(self) -> None:
|
||||
self._stop.set()
|
||||
self.running = False
|
||||
|
||||
@@ -0,0 +1,187 @@
|
||||
"""Sandbox primitives for the operator bridge — pure, dependency-light helpers.
|
||||
|
||||
Two ways the operator touches a sandbox:
|
||||
|
||||
1. **Co-located exec** (this module's `exec_*` / `launch_*`): the daemon owns a
|
||||
container it started itself (`podman`/`docker run -d … sleep infinity`) and
|
||||
runs commands *out-of-band* with `engine exec -i`. Output is captured and
|
||||
returned — clean, scriptable, invisible to the room. Mirrors the native
|
||||
harness's exec path (cmd_chat/agent/bridge.py:640-676) argv-for-argv so the
|
||||
blast radius and quoting rules are identical.
|
||||
|
||||
2. **Relay keystrokes** (`encode_keys`): when the *room's* shared sandbox is
|
||||
owned by the Rust broker, the only way in is the same `_sbx:input` keystroke
|
||||
frame a human driver's terminal emits. The broker writes our bytes to the
|
||||
shared PTY iff we're a granted driver. That path needs a precise byte
|
||||
vocabulary — including how to *stop* a running program — which lives here so
|
||||
it's one tested table, reused by the bridge and documented once per session.
|
||||
|
||||
Nothing here opens a websocket or holds state; the bridge wires these in.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
|
||||
# Match the native harness so behaviour is identical across both drivers.
|
||||
EXEC_TIMEOUT = 60.0 # NATIVE_TOOL_TIMEOUT
|
||||
OUTPUT_CAP = 4096 # NATIVE_OUTPUT_CAP (bytes of combined stdout+stderr)
|
||||
|
||||
|
||||
# ── engine / image selection ───────────────────────────────────────────────
|
||||
def pick_engine() -> str | None:
|
||||
"""Prefer podman (rootless, daemonless, no sudo) then docker. None if neither
|
||||
is on PATH — the caller surfaces that as a clear 'no engine' error."""
|
||||
import shutil
|
||||
|
||||
for eng in ("podman", "docker"):
|
||||
if shutil.which(eng):
|
||||
return eng
|
||||
return None
|
||||
|
||||
|
||||
def default_image(engine: str) -> str:
|
||||
"""Match the Rust/agent defaults: Podman→Kali, Docker→Parrot."""
|
||||
return "kalilinux/kali-rolling" if engine == "podman" else "parrotsec/core"
|
||||
|
||||
|
||||
# ── co-located exec ─────────────────────────────────────────────────────────
|
||||
def exec_prefix(engine: str | None, name: str | None) -> list[str] | None:
|
||||
"""argv prefix that runs a program *inside* the named sandbox, or None if we
|
||||
can't address it. The real program + args are appended as separate argv
|
||||
elements (never a shell-interpolated string), so untrusted room text can't
|
||||
inject shell metacharacters outside an explicit `sh -c`. `-i` keeps stdin
|
||||
open so `write` can pipe file content in. Identical shape to the native
|
||||
harness (bridge.py:640)."""
|
||||
if engine in ("docker", "podman"):
|
||||
return [engine, "exec", "-i", name] if name else None
|
||||
if engine == "multipass":
|
||||
return ["multipass", "exec", name, "--"] if name else None
|
||||
if engine == "local":
|
||||
return [] # host shell — explicit, opt-in exception
|
||||
return None
|
||||
|
||||
|
||||
async def exec_capture(argv: list[str], stdin: bytes | None = None,
|
||||
text: bool = True) -> tuple[str | bytes, int]:
|
||||
"""Run an exec argv, capture combined stdout+stderr and the exit code,
|
||||
time-bounded. `text=True` decodes + byte-caps for display; `text=False`
|
||||
returns raw bytes uncapped (for `get`, where truncation would corrupt the
|
||||
file). The container/VM is the blast radius; `local` is the host by choice."""
|
||||
try:
|
||||
proc = await asyncio.create_subprocess_exec(
|
||||
*argv,
|
||||
stdin=asyncio.subprocess.PIPE if stdin is not None else asyncio.subprocess.DEVNULL,
|
||||
stdout=asyncio.subprocess.PIPE,
|
||||
stderr=asyncio.subprocess.STDOUT,
|
||||
)
|
||||
except (FileNotFoundError, OSError) as e:
|
||||
return (f"[exec failed: {e}]" if text else b""), 127
|
||||
try:
|
||||
out, _ = await asyncio.wait_for(proc.communicate(input=stdin), timeout=EXEC_TIMEOUT)
|
||||
except asyncio.TimeoutError:
|
||||
proc.kill()
|
||||
return ("[command timed out]" if text else b""), 124
|
||||
rc = proc.returncode if proc.returncode is not None else -1
|
||||
if not text:
|
||||
return out, rc
|
||||
s = out.decode(errors="replace")
|
||||
if len(s) > OUTPUT_CAP:
|
||||
s = s[:OUTPUT_CAP] + "\n[output truncated]"
|
||||
return s, rc
|
||||
|
||||
|
||||
async def launch_container(engine: str, name: str, image: str) -> tuple[bool, str]:
|
||||
"""Start a persistent throwaway container we can exec into: remove any stale
|
||||
one, then `run -d --name … --hostname … -w /root <image> sleep infinity`
|
||||
(argv-identical to hh/src/sbx.rs:779). Returns (ok, message)."""
|
||||
await exec_capture([engine, "rm", "-f", name]) # ignore "no such container"
|
||||
out, rc = await exec_capture(
|
||||
[engine, "run", "-d", "--name", name, "--hostname", name,
|
||||
"-w", "/root", image, "sleep", "infinity"])
|
||||
if rc != 0:
|
||||
tail = (out or "").strip().splitlines()[-1:] or [""]
|
||||
return False, f"{engine} run failed (exit={rc}): {tail[0]}"
|
||||
return True, f"launched {engine} container '{name}' from {image}"
|
||||
|
||||
|
||||
async def teardown_container(engine: str, name: str) -> tuple[bool, str]:
|
||||
out, rc = await exec_capture([engine, "rm", "-f", name])
|
||||
if rc != 0:
|
||||
return False, f"{engine} rm failed (exit={rc}): {(out or '').strip()[:200]}"
|
||||
return True, f"removed {engine} container '{name}'"
|
||||
|
||||
|
||||
# ── relay keystrokes (shared-PTY drive) ─────────────────────────────────────
|
||||
#
|
||||
# A terminal is just a byte stream. Named keys below are the bytes a real
|
||||
# keyboard sends; the bridge base64-wraps them into a `{"_sbx":"input"}` frame.
|
||||
# The control characters are the *how to stop things* vocabulary — being able to
|
||||
# interrupt a hung program is as essential as starting one, especially in tests.
|
||||
NAMED_KEYS: dict[str, bytes] = {
|
||||
# line endings / whitespace
|
||||
"enter": b"\r", "return": b"\r", "newline": b"\n", "tab": b"\t",
|
||||
"space": b" ", "backspace": b"\x7f",
|
||||
# the stop/exit family — the most important keys for staying unstuck
|
||||
"ctrl-c": b"\x03", # SIGINT — interrupt the foreground program
|
||||
"ctrl-d": b"\x04", # EOF — end stdin / exit an empty shell
|
||||
"ctrl-z": b"\x1a", # SIGTSTP — suspend to the background (then `fg`/`bg`)
|
||||
"ctrl-\\": b"\x1c", # SIGQUIT — hard quit + core dump when SIGINT is ignored
|
||||
"esc": b"\x1b", # leave vim insert-mode, dismiss menus, abort readline
|
||||
# screen / job control niceties
|
||||
"ctrl-l": b"\x0c", # clear/redraw the screen
|
||||
"ctrl-u": b"\x15", # kill the input line (clear a half-typed command)
|
||||
"ctrl-a": b"\x01", # start-of-line (also tmux/screen prefix)
|
||||
"ctrl-e": b"\x05", # end-of-line
|
||||
"ctrl-k": b"\x0b", # kill to end-of-line
|
||||
"ctrl-w": b"\x17", # delete the previous word
|
||||
# arrows / paging — ANSI sequences (history, menus, pagers)
|
||||
"up": b"\x1b[A", "down": b"\x1b[B", "right": b"\x1b[C", "left": b"\x1b[D",
|
||||
"home": b"\x1b[H", "end": b"\x1b[F",
|
||||
"pageup": b"\x1b[5~", "pagedown": b"\x1b[6~",
|
||||
"delete": b"\x1b[3~",
|
||||
}
|
||||
|
||||
# Token-efficient cheat-sheet the skill/status surfaces once per session, so a
|
||||
# Claude operator knows the stop-vocabulary without re-deriving it every turn.
|
||||
KEYS_HELP = (
|
||||
"send-keys vocabulary (bytes → shared PTY; granted drivers only):\n"
|
||||
" literal text types it verbatim (no trailing newline)\n"
|
||||
" enter/tab/space/esc \\r \\t ' ' \\x1b\n"
|
||||
" ctrl-c interrupt the running program (SIGINT) — your main 'stop'\n"
|
||||
" ctrl-d EOF: end stdin / exit an empty shell\n"
|
||||
" ctrl-z suspend to background (resume with `fg`); ctrl-\\ = SIGQUIT\n"
|
||||
" ctrl-u clear a half-typed line; ctrl-l clears the screen\n"
|
||||
" up/down/left/right home end pageup pagedown delete backspace\n"
|
||||
" q quits most pagers (less/man); :q<enter> quits vim\n"
|
||||
"End a stuck command with ctrl-c; if that's ignored, ctrl-\\ then ctrl-c again."
|
||||
)
|
||||
|
||||
|
||||
def encode_keys(spec) -> bytes:
|
||||
"""Resolve a key spec into the raw bytes to inject.
|
||||
|
||||
Accepts either a list of tokens or a single string:
|
||||
- a NAMED_KEYS name (case-insensitive) → that control sequence
|
||||
- 'text:...' → the rest, verbatim (preserves a
|
||||
literal name like 'enter')
|
||||
- 'hex:1b5b41' / '\\x1b' → raw bytes from hex
|
||||
- anything else → typed verbatim as UTF-8
|
||||
|
||||
A bare string with no recognised token is typed as-is, so the common case
|
||||
(`send-keys "ls -la" enter`) is one obvious call. Naming is explicit on
|
||||
purpose: nothing here guesses, so an operator always knows what it sent."""
|
||||
tokens = spec if isinstance(spec, (list, tuple)) else [spec]
|
||||
out = bytearray()
|
||||
for tok in tokens:
|
||||
s = "" if tok is None else str(tok)
|
||||
low = s.lower()
|
||||
if low in NAMED_KEYS:
|
||||
out += NAMED_KEYS[low]
|
||||
elif s.startswith("text:"):
|
||||
out += s[5:].encode()
|
||||
elif low.startswith("hex:"):
|
||||
out += bytes.fromhex(s[4:])
|
||||
else:
|
||||
out += s.encode()
|
||||
return bytes(out)
|
||||
Reference in New Issue
Block a user