Proposal: separate Windows code and dogfooding

[enyst]

We have a few PRs proposing to add Windows support:

• Add Windows browser path checks to Chromium detection #1014
• Expand Windows tools test coverage in CI workflow #1209
• Add Windows terminal backend support #1012

Proposal:

I think maybe we could we consider implementing this separately, separate from core agent-sdk code. In fact, there are two things here that I feel we could consider:

• separate code / loose coupling
• dogfooding / dedicated maintainer(s).

1. Loose coupling:

• maybe Windows-specific tools
• maybe Windows-specific package
• or better abstractions, at least separate files, initialized per platform
  • if we implement it directly into core.

I'm concerned about code like conditionals with Windows-specific logic in core implementation. Windows is too different IMHO, which means we can expect much more special cases, much more ifs in random places. I do feel Windows support is a much more demanding feature than the current PRs, and I'm concerned that:

• the agent-sdk codebase is becoming more error-prone and harder to understand
• we're starting something we are not able to maintain.

IMHO we could perhaps think how to design and implement Windows support as separated as possible from the rest of the logic... The WindowsTerminal file is a good example: abstraction with platform-specific import. But the if for a tool prompt could be done differently. It's a prompt piece, we could have, for example, different templates/files. Or even subclass the definition, or maybe separate a component with the prompt, and subclass that.

2. Dogfooding:

As I noted in one of these PR, one detail here that seems relevant to me is that usually, it won't be the same people that work regularly on Windows and Linux/Mac. This matters at multiple levels:

• for one, no maintainer is working on Windows. We could test a PR (on a quick Windows), but how deep is that testing? Are we introducing support for something we don't maintain?
• this also means that when any contributor looks at a screen of such code in their editor, they never have at their disposal, in their sight, a screen of code, they have half the screen. This may sound trivial, it's true, but if it's too many times, it affects ease of debugging/readability/maintainability IMHO.

(as it happens, I was re-reading Richard Gabriel's Patterns of Software, and this struck me: "The primary feature for easy maintenance is locality: Locality is that characteristic of source code that enables a programmer to understand that source by looking at only a small portion of it." Now this refers to a different issue, but it is the kind of thing I value when I say the whole screen of code I'm looking at should ideally be meaningful.)

I would suggest that we design it separate, and, publicize support when we have an interested maintainer who actually uses Windows. I'm concerned this is a too error-prone feature to be incidental.

Otherwise, I fear we are looking at a bunch of bug reports and anger, like we had in V0, if not more.

Note:

Please note also that if we start supporting Windows in the SDK, people will of course expect it in the CLI and Web UI too. In V0, Windows had been implemented only in LocalRuntime. But we weren't able to make understandable the distinction, so people expected it in CLI at least... Which hadn't been implemented, but that came across as "full of bugs", instead of "not supported".

I would love to hear some thoughts. I am aware people would like Windows support, and that's fine, I'm just suggesting that how we do it matters IMO. Maybe we can do better this time around. 😅

[enyst]

I just noticed this in the Codex Max announcement thread:

the first Codex model trained to operate in Windows environments.

It’s also better at using Powershell, making it a better collaborator on Windows machines.

I'm not sure if we ever considered evaluating the agent with the same tools, just on Windows? LLMs know Powershell, but I have no idea how well can they use the terminal prompt (which informs it about control chars and stopping pids...)

[SmartManoj]

I would suggest that we design it separate.

This sounds good.

[enyst]

What if we make a windows-tools package, with all clean, Windows-friendly code?

We need CI for Windows, as your recent PR shows. Those workflows should be enabled on Windows tools, and of course releases, but maybe not on the rest.

One thing we noticed on OpenHands, was that the Windows tests were flaky and failing on PRs as harmless as a doc tweak. We need tests, but gating everything else on Windows tests is maybe not necessary?

[neubig]

@enyst I am fully in favor of this proposal, and I think it could be very useful!

[neubig]

It sounds like @ryanhoangt might be able to take a look at some of these PRs on the windows machine.

And @xingyaoww mentioned in our meeting just now that we might want to keep them in this repo, but have conditionally triggered CI that only works when we change something in the directory.

[enyst]

OK, could we do it like

• openhands-sdk
• openhands-tools
• openhands-workspace
• openhands-agent-server
• openhands-windows-tools ?

That would be in this repo, but in its separate directory, and package.

[xingyaoww]

@enyst I'm not sure if it is a good idea to create yet another package for Windows -- i think it will be good to include them along with openhands-tools, but we can figure out some systematic way to get rid of those if/else if we want.

My rationale would be:

Ideally, the same code snippet you wrote for Linux should largely still work when you run the same script in Windows - the SDK should be smart enough to use the available implementation. If we break it down to a different package, it likely means these transitions will be manual.

An alternative I'm willing to consider is adding a class-level attribute to Tool - i.e., indicating whether some tools are "Windows" and others are "Unix".

In case of Windows Terminal, we can implement a new PowerShellTerminal, and in get_default_tools, we automatically detect system version and use PowershellTerminal instead of Terminal when in Windows.
And then we throw an error for people who try to run Terminal in Windows and suggest that them to use PowershellTerminal, or use get_default_tools or get_terminal to retrieve the relavant tool for cross-OS compatibility, wdyt?

[enyst]

An alternative I'm willing to consider is adding a class-level attribute to Tool - i.e., indicating whether some tools are "Windows" and others are "Unix".

I think this would be nice... I hope maybe this means, if there's any Windows-specific implementation, then make it a "Windows" tool?

Though I think that will imply some redundancy for a while, but I personally prefer redundancy to mixing Windows-specific code in the middle of everything else.

Terminal sounds good to me 🤔