Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

22.4 KB
Raw Blame
#!/usr/bin/env python3
"""Private PTYs: real zsh/bash startup, helper protocol, native argv and tty recovery."""
import faulthandler
faulthandler.enable()
faulthandler.dump_traceback_later(120, exit=True)
import base64
import json
import os
from pathlib import Path
import pty
import re
import select
import signal
import tempfile
import time
import urllib.parse

ROOT = Path(__file__).resolve().parents[1]
TOKEN = '8c73ea55-683a-4207-a9aa-ab8a9e813bea'
REQUEST = re.compile(rb'\x1b\]633;hn;([^;]+);([^;]+);([^;]+);([^\x07]*)\x07')
PICKED = b'\x1b]633;picked\x07'
# Removes the progress line's two rows and returns to the row it started on.
ERASE = b'\r\x1b[2K\x1b[1A\x1b[2K\x1b[1A'
AGENTS = ('codex', 'claude', 'cursor-agent', 'opencode', 'pi', 'hermes', 'cmd', 'devin', 'muse', 'amp', 'kilo', 'grok', 'agy', 'copilot')

class Shell:
    def __init__(self, root, shell, custom=False):
        self.root = root
        self.capture = root / 'calls'
        binpath = root / 'bin'
        binpath.mkdir()
        for name in (*AGENTS, 'harness'):
            path = binpath / name
            path.write_text('#!/usr/bin/env python3\nimport os,sys,json\nwith open(os.environ["CALLS"],"a") as f: f.write(json.dumps(sys.argv)+"\\n")\n')
            path.chmod(0o755)
        picker=binpath/'native-picker'
        # With picker-mark, it also marks on the terminal the moment the choice is made.
        picker.write_text('#!/bin/sh\n[ -f "$HOME/picker-choice" ] || exit 130\n'
                          '[ ! -f "$HOME/picker-mark" ] || printf \'\\033]633;picked\\007\' >&2\ncat "$HOME/picker-choice"\n')
        picker.chmod(0o755)
        # With slow-od, making a request id takes a while (a busy machine).
        od=binpath/'od'
        od.write_text('#!/bin/sh\n[ ! -f "$HOME/slow-od" ] || sleep 3\nexec /usr/bin/od "$@"\n')
        od.chmod(0o755)
        for rc in ('.zshenv', '.zprofile', '.zshrc', '.zlogin', '.bashrc'):
            text = f"printf '%s\\n' '{rc}' >> \"$STARTUP\"\n"
            if rc in ('.zshrc', '.bashrc'):
                text += "PS1='READY> '\nPATH=\"$HOME/bin:/usr/bin:/bin:/usr/sbin:/sbin\"\nexport PATH\n"
                # These bindings stand in for existing user/fzf widgets. Harness
                # completion may wrap Tab but must never take over Ctrl-T/Ctrl-R.
                if rc=='.zshrc':
                    text += "_test_ctrl_t() { LBUFFER+='KEPT_T'; }; zle -N _test_ctrl_t; bindkey '^T' _test_ctrl_t\n"
                    text += "_test_ctrl_r() { LBUFFER+='KEPT_R'; }; zle -N _test_ctrl_r; bindkey '^R' _test_ctrl_r\n"
                else:
                    text += "bind '\"\\C-t\": \"KEPT_T\"'\nbind '\"\\C-r\": \"KEPT_R\"'\n"
                if custom:
                    text += "alias codex='printf ALIAS_CODEX\\\\n'\n"
                    text += "claude() { printf '%s\\n' 'FUNCTION_CLAUDE'; }\n"
                    text += "alias pi='printf ALIAS_PI\\\\n'\n"
            (root / rc).write_text(text)
        bootstrap = (ROOT / 'src/shell_bootstrap.sh').read_text().replace('@INTEGRATION@', (ROOT / 'src/shell_integration.sh').read_text())
        self.pid, self.fd = pty.fork()
        if not self.pid:
            # A terminal (tmux too) starts its shell with default signals. A runner
            # started with `&` ignores SIGINT, and a shell can never trap a signal
            # ignored on entry, so Ctrl-C could not cancel anything.
            signal.signal(signal.SIGINT, signal.SIG_DFL)
            signal.signal(signal.SIGQUIT, signal.SIG_DFL)
            os.chdir(root)
            env = {k:v for k,v in os.environ.items() if k in ('LANG','LC_ALL','TZ')}
            env.update(HOME=str(root), SHELL=shell, PATH=str(binpath)+':/usr/bin:/bin:/usr/sbin:/sbin', _HN_CLI=str(binpath/'harness'),
                       TERM='xterm-256color', STARTUP=str(root/'startup'), CALLS=str(self.capture),
                       TMPDIR=str(root), _HN_CONTEXT=TOKEN, _HN_PICKER=str(picker), skip_global_compinit='1')
            os.execve('/bin/sh', ['/bin/sh','-c',bootstrap], env)
        self.data = b''
        self.request_ids = set()
        self.read_until(b'READY> ')
    def send(self, text): os.write(self.fd, text.encode() if isinstance(text,str) else text)
    def read_until(self, pattern, seconds=5):
        end = time.monotonic()+seconds
        while time.monotonic()<end:
            hit = re.search(pattern, self.data) if hasattr(pattern, 'search') else (pattern in self.data)
            if hit:
                got,self.data = self.data,b''
                return got
            if select.select([self.fd],[],[],0.05)[0]:
                try: self.data += os.read(self.fd,65536)
                except OSError: break
        raise AssertionError((pattern,self.data[-6000:]))
    def request(self, command, verb, reply='', code=0):
        print('request',command,flush=True)
        self.send(command+'\r')
        data = self.read_until(REQUEST)
        match = REQUEST.search(data)
        assert match[1].decode()==TOKEN and match[3].decode()==verb, data
        assert match[2] not in self.request_ids, 'successive commands reused a request id'
        self.request_ids.add(match[2])
        self.reply(match, reply, code)
        return self.read_until(b'READY> ')
    def result(self, marker):
        # Bash bind-x may redraw PS1 while a command containing '%' is still
        # being edited. Only the expanded output line proves it ran.
        pattern=re.compile(rb'(?:^|\r?\n)(?:\r|\x1b\[[0-?]*[ -/]*[@-~])*'+re.escape(marker)+rb'\r?\n')
        data=self.read_until(pattern)
        if b'READY> ' not in data[pattern.search(data).end():]: self.read_until(b'READY> ')
        return data
    def reply(self, match, reply='', code=0):
        path = self.root/'.harness/shell-requests'/TOKEN/match[2].decode()
        with path.open('w') as out:
            out.write('HN:'+match[2].decode()+':'+str(code)+':'+base64.b64encode(reply.encode()).decode()+'\n')
    def calls(self): return [json.loads(s) for s in self.capture.read_text().splitlines()] if self.capture.exists() else []
    def close(self):
        self.send('exit\r')
        end=time.monotonic()+2
        while time.monotonic()<end:
            if os.waitpid(self.pid,os.WNOHANG)[0]: break
            if select.select([self.fd],[],[],.02)[0]:
                try: os.read(self.fd,65536)
                except OSError: pass
        else:
            os.close(self.fd)
            os.killpg(self.pid,signal.SIGKILL)
            return
        os.close(self.fd)

with tempfile.TemporaryDirectory(prefix='hn-shell-test-') as tmp:
    # An empty HN_SHELL_TEST_ZSH skips zsh (a machine with only a bash 5).
    for shell in filter(None,(os.environ.get('HN_SHELL_TEST_ZSH','/bin/zsh'),os.environ.get('HN_SHELL_TEST_BASH','/bin/bash'))):
        for custom in (False,True):
            root=Path(tmp)/(Path(shell).name+str(custom)); root.mkdir()
            print('starting',shell,custom,flush=True)
            s=Shell(root,shell,custom)
            try:
                expected=['.zshenv','.zprofile','.zshrc','.zlogin'] if shell.endswith('zsh') else ['.bashrc']
                assert (root/'startup').read_text().splitlines()==expected
                assert not list(root.glob('hn-shell.*')), 'rc overlay leaked'
                # Cancelling either picker returns without swallowing the next command.
                s.send('ch\r'); s.read_until(b'READY> ')
                s.send('cm\r'); s.read_until(b'READY> ')
                s.send("printf 'AFTER_CANCEL\\n'\r"); s.read_until(b'READY> ')
                # A direct shortcut opens from the middle of a draft. Selecting
                # a context sends one literal request; it must never execute or
                # replace the draft, and the editor keeps its cursor position.
                for kind,verb,value in [('model','model-inline','default'),
                                        ('host','host-inline',"office ' ; $(touch SHORTCUT_EVAL); # 日本語"),
                                        ('sessions','session-inline','external:local:saved')]:
                    (root/'picker-choice').write_text(kind+'\n'+value+'\n')
                    s.send("printf 'DRAFT_%s\\n' LRIGHT")
                    s.send('\x02'*5+'\x10')
                    match=REQUEST.search(s.read_until(REQUEST))
                    assert match[3].decode()==verb and base64.b64decode(match[4]).decode()==value
                    assert not (root/'SHORTCUT_EVAL').exists()
                    s.reply(match,'Changed.\n')
                    s.read_until(b'READY> ')
                    s.send('M\r')
                    s.result(b'DRAFT_LMRIGHT')
                # A computer that never answers: the widget says at once what it waits
                # for, Ctrl-C gives the prompt back with the line unchanged, and the
                # next pick is served.
                # The wait starts once the choice is made, not while the picker starts.
                (root/'picker-choice').write_text('host\nGone\n')
                (root/'picker-mark').touch()
                s.send("printf 'GONE_%s\\n' LRIGHT")
                s.send('\x02'*5+'\x10')
                seen=s.read_until(PICKED).split(PICKED,1)[1]
                t0=time.monotonic()
                (root/'picker-mark').unlink()
                if not REQUEST.search(seen): seen+=s.read_until(REQUEST)
                first=REQUEST.search(seen)
                assert first[3]==b'host-inline' and base64.b64decode(first[4])==b'Gone'
                progress='Opening a shell on Gone… Ctrl-C to cancel'.encode()
                if progress not in seen: seen+=s.read_until(progress,seconds=1)
                assert time.monotonic()-t0<1,'the progress line came too late'
                time.sleep(.3)    # nobody answers: the line must stay as it is meanwhile
                s.send('\x03')
                t0=time.monotonic()
                said=s.read_until(b'READY> ',seconds=1)
                assert time.monotonic()-t0<1,'Ctrl-C did not give the prompt back within 1 s'
                assert re.search(rb'633;hn;'+TOKEN.encode()+b';'+re.escape(first[2])+b';cancel;',said),'the request was not cancelled'
                # The rows the progress line added are gone again: only the prompt is left.
                assert ERASE in said.split(b'cancel;',1)[1],('the progress line was left behind',said)
                s.send('M\r')
                s.result(b'GONE_LMRIGHT')       # the line is exactly what it was
                # Right after it, another choice is served (the TUI freed the picker),
                # and the progress line names this computer as such.
                (root/'picker-choice').write_text('host\nlocal\n')
                s.send('\x10')
                seen=s.read_until(REQUEST)
                match=REQUEST.search(seen)
                assert match[3]==b'host-inline' and match[2]!=first[2]
                if b'Ctrl-C to cancel' not in seen: seen+=s.read_until(b'Ctrl-C to cancel')
                assert 'Opening a shell on this computer… Ctrl-C to cancel'.encode() in seen,seen
                s.reply(match); done=s.read_until(b'READY> ')
                assert ERASE in done,('the progress line was left behind',done)
                if shell.endswith('zsh'):
                    # The widget's localtraps ends with it: a user function's trap still holds after it.
                    s.send("[[ -o localtraps ]] && printf 'LT_%s\\n' ON || printf 'LT_%s\\n' OFF\r")
                    said=s.read_until(LT:=re.compile(rb'[\r\n]LT_(ON|OFF)\r?\n'))
                    assert LT.search(said)[1]==b'OFF',('LOCAL_TRAPS leaked into the shell',said)
                    if b'READY> ' not in said[LT.search(said).end():]: s.read_until(b'READY> ')
                # The widget keeps its saved trap to itself.
                s.send("[ -z \"${_hn_saved_int+x}\" ] && printf 'SV_%s\\n' CLEAN || printf 'SV_%s\\n' LEAKED\r")
                said=s.read_until(SV:=re.compile(rb'[\r\n]SV_(CLEAN|LEAKED)\r?\n'))
                assert SV.search(said)[1]==b'CLEAN',('the widget left _hn_saved_int behind',said)
                if b'READY> ' not in said[SV.search(said).end():]: s.read_until(b'READY> ')
                # Ctrl-C while the request is still being made says Cancelled, not a failure.
                (root/'slow-od').touch()
                (root/'picker-choice').write_text('host\nGone\n')
                s.send('\x10')
                s.read_until(b'Ctrl-C to cancel')
                time.sleep(.3)    # od is running now
                s.send('\x03')
                said=s.read_until(b'Cancelled.',seconds=2)
                assert b'Could not create' not in said,said
                # zsh draws the prompt before its message; bash after it.
                if shell.endswith('bash') and b'READY> ' not in said.split(b'Cancelled.',1)[1]: s.read_until(b'READY> ')
                (root/'slow-od').unlink()
                if not custom:
                    # An answer that comes just as the shell gives up is used, not
                    # reported as missing. (picker-ready gives up after 5 s.)
                    s.send("_hn_request picker-ready; printf 'RC_%s\\n' $?\r")
                    late=REQUEST.search(s.read_until(REQUEST))
                    assert late[3]==b'picker-ready'
                    s.read_until(re.compile(rb'633;hn;'+TOKEN.encode()+b';'+re.escape(late[2])+b';cancel;'),seconds=8)
                    s.reply(late,'JUST_IN_TIME\n')
                    said=s.read_until(RC:=re.compile(rb'[\r\n]RC_(\d+)\r?\n'),seconds=3)
                    assert b'JUST_IN_TIME' in said and RC.search(said)[1]==b'0' and b'did not answer' not in said,said
                    if b'READY> ' not in said[RC.search(said).end():]: s.read_until(b'READY> ')
                # The widget's own Ctrl-C guard must not drop the user's INT trap.
                s.send("trap 'echo MINE' INT\r"); s.read_until(b'READY> ')
                s.send('\x10')
                match=REQUEST.search(s.read_until(REQUEST))
                s.reply(match); s.read_until(b'READY> ')
                show='trap' if shell.endswith('zsh') else 'trap -p INT'
                s.send("printf 'TRAP_%s\\n' BEGIN; "+show+"; printf 'TRAP_%s\\n' END\r")
                kept=s.read_until(re.compile(rb'\nTRAP_END'))
                assert b'echo MINE' in kept.split(b'TRAP_BEGIN',2)[-1],('the INT trap was lost',kept)
                if b'READY> ' not in kept.rsplit(b'TRAP_END',1)[1]: s.read_until(b'READY> ')
                s.send("trap - INT\r"); s.read_until(b'READY> ')
                (root/'picker-choice').unlink()
                (root/'picker-choice').write_text('sessions\nexternal:local:missing\n')
                s.send('\x10')
                match=REQUEST.search(s.read_until(REQUEST))
                assert match[3]==b'session-inline'
                s.reply(match,'Could not open it: fixture folder is unavailable.',code=1)
                failed=s.read_until(b'Could not open it: fixture folder is unavailable.')
                # Bash prints the explanation before bind-x returns to Readline.
                # Wait for that redraw before cancelling; an old prompt must not
                # acknowledge Ctrl-C and race the next draft's first characters.
                if shell.endswith('bash') and b'READY> ' not in failed.split(b'Could not open it: fixture folder is unavailable.',1)[1]:
                    s.read_until(b'READY> ')
                s.send('\x03');s.read_until(b'READY> ')
                (root/'picker-choice').unlink()
                s.send("printf 'CANCEL_DRAFT_%s\\n' LRIGHT")
                s.send('\x02'*5+'\x10')
                s.read_until(b'READY> ')
                s.send('M\r')
                # A bind-x redraw can leave an earlier prompt in the PTY. Wait
                # for the command's actual result, not that pending redraw.
                s.result(b'CANCEL_DRAFT_LMRIGHT')
                # Tab selects INTO the current shell line, without taking the
                # action. Shell quoting must preserve every byte as literal data.
                malicious="office ' ; $(touch SHOULD_NOT_EXIST); # 日本語"
                (root/'picker-choice').write_text(malicious+'\n')
                s.send('ch \t')
                ready=s.read_until(b'office')
                assert not REQUEST.search(ready), 'completion executed instead of editing the draft'
                s.send('\r')
                match=REQUEST.search(s.read_until(REQUEST))
                assert match[3]==b'host-inline' and base64.b64decode(match[4]).decode()==malicious
                assert not (root/'SHOULD_NOT_EXIST').exists(), 'completion evaluated selected text'
                s.reply(match);s.read_until(b'READY> ')
                (root/'picker-choice').write_text('grid one :: model/test\n')
                s.send('cm \t');s.read_until(b'model/test');s.send('\r')
                match=REQUEST.search(s.read_until(REQUEST))
                assert match[3]==b'model-inline' and base64.b64decode(match[4])==b'grid one :: model/test'
                s.reply(match);s.read_until(b'READY> ')
                (root/'picker-choice').write_text('external:local:chosen\n')
                s.send('hn sessions \t');s.read_until(b'external');s.send('\r')
                match=REQUEST.search(s.read_until(REQUEST))
                assert match[3]==b'session-inline' and base64.b64decode(match[4])==b'external:local:chosen'
                s.reply(match);s.read_until(b'READY> ')
                (root/'picker-choice').unlink()
                # Cancellation retains a draft; a normal subsequent space/Enter
                # takes the same text, with no fallback filename completion.
                s.send('ch local\t');time.sleep(.08);s.send('\r')
                match=REQUEST.search(s.read_until(REQUEST))
                assert match[3]==b'host-inline' and base64.b64decode(match[4])==b'local'
                s.reply(match);s.read_until(b'READY> ')
                s.send("printf '%s\\n' \x14\x12\r")
                s.result(b'KEPT_TKEPT_R')
                s.send('ch local\r')
                match = REQUEST.search(s.read_until(REQUEST))
                s.send("printf 'TYPEAHEAD_%s\\n' OK\r")
                s.reply(match)
                # Zsh may enable bracketed paste after drawing PS1. Check the
                # result line and its following prompt, not the buffer suffix.
                s.result(b'TYPEAHEAD_OK')
                s.request('cm default','model-inline','Using defaults.\n')
                # A reattach may drop the initial output event. Retrying keeps the
                # same id, leaves typeahead alone, and cleans up the response FIFO.
                s.send('cm default\r')
                first = REQUEST.search(s.read_until(REQUEST))
                retry = REQUEST.search(s.read_until(REQUEST))
                assert first.groups() == retry.groups()
                s.reply(retry, code=1)
                s.read_until(b'READY> ')
                assert not list((root/'.harness/shell-requests').glob('*/*'))
                (root/'picker-choice').write_text('external:local:old-task\n')
                s.request('hn sessions old task','session-inline')
                (root/'picker-choice').unlink()
                if custom:
                    s.send('codex\r'); assert b'ALIAS_CODEX' in s.read_until(b'READY> ')
                    s.send('claude\r'); assert b'FUNCTION_CLAUDE' in s.read_until(b'READY> ')
                    s.send('pi\r'); assert b'ALIAS_PI' in s.read_until(b'READY> ')
                    s.request('hn run codex "a task"','route','grid one\nmodel/test')
                else:
                    for agent in AGENTS:
                        s.request(agent+' "native task"','route')
                        assert Path(s.calls()[-1][0]).name == agent
                        assert s.calls()[-1][1:] == ['native task']
                    before = len(s.calls())
                    result = s.request('pi','route','grid one\nmodel/test')
                    assert b'cm routing is not supported for pi' in result
                    assert len(s.calls()) == before, 'Pi must not silently use a different model'
                    s.send('command pi --version\r'); s.read_until(b'READY> ')
                    assert Path(s.calls()[-1][0]).name == 'pi' and s.calls()[-1][1:] == ['--version']
                    s.request('codex "a task with spaces"','route')
                    assert s.calls()[-1][1:]==['a task with spaces']
                    s.request('claude "say $HOME literally"','route','grid one\nmodel/test')
                    assert s.calls()[-1][1:5]==['shell-launch','claude','grid one','model/test']
                    for command in ['claude -p "print a task"', 'codex exec "run a task"', 'printf input | claude -p']:
                        s.request(command,'route','grid one\nmodel/test')
                        assert s.calls()[-1][1]=='shell-launch', 'inference flags must not silently bypass cm'
                    before=len(s.calls())
                    s.request('codex','route',code=1)
                    assert len(s.calls())==before, 'cancel fell through to native login'
                    for command,args in [('codex --model chosen "my task"',['--model','chosen','my task']),('codex resume saved',['resume','saved']),('claude --resume saved',['--resume','saved'])]:
                        s.send(command+'\r'); s.read_until(b'READY> ')
                        assert s.calls()[-1][1:]==args
                if not custom:
                    for agent in AGENTS:
                        (root/'bin'/agent).unlink()
                        s.request(agent+' "fresh user"','route')
                        engine = {'cursor-agent':'cursor', 'cmd':'commandcode'}.get(agent,agent)
                        assert s.calls()[-1][1:]==['shell-launch',engine,'--native','--','fresh user']
                # Helpers restore echo and do not alter the user's prompt or cwd.
                weird=root/'folder ü % #'; weird.mkdir()
                s.send("cd '"+str(weird)+"'\r")
                # The '%' binding can redraw the prompt while cd is still being
                # edited. OSC 7, rather than that redraw, proves cd has finished.
                result=s.read_until(re.compile(rb'\x1b\]7;file://localhost[^\x07]+\x07'))
                if b'READY> ' not in result.rsplit(b'\x07',1)[-1]: s.read_until(b'READY> ')
                paths=re.findall(rb'\x1b\]7;file://localhost([^\x07]+)\x07',result)
                assert paths and urllib.parse.unquote(paths[-1].decode())==str(weird), result
                s.send("stty -a\r"); result=s.read_until(b'READY> ')
                assert re.search(rb'(?<!-)\becho\b',result), result
            finally: s.close()
            print('PASS',Path(shell).name,'custom aliases' if custom else 'native agents')