Skip to content

feat(computer): run a computer app's server on Windows - #538

Merged
earakely-scale merged 9 commits into
mainfrom
edgararakelyan/windows-app-runtime
Nov 8, 2026
Merged

earakely-scale merged 9 commits into
mainfrom
edgararakelyan/windows-app-runtime

Conversation

@earakely-scale

@earakely-scale earakely-scale commented Nov 8, 2026 •

Copy link
Copy Markdown
Collaborator

Part of FD-5329.

An app's own server (serve_app) now runs on Windows. Composing apps onto a Windows computer comes in the core PR stacked on this one.

What changes

Transport (served.py). On Linux and macOS, an app's server listens on the Unix socket in its folder, as before. Windows asyncio can't serve a Unix socket, so there the server:

  • listens on a free port of 127.0.0.1;
  • writes the port and a 32-byte token to .agentenv/server.json, atomically;
  • answers only a request or WebSocket carrying exactly one matching x-agentenv-app-token header, and removes the header before the app sees the request.

Everything that reaches an app picks its route the same way: served(folder) checks whether server.json exists. That covers apps, svc forward and relay, launch and the page driver. Clients skip any proxy set in the environment (trust_env=False, websockets proxy=None). svc drops a token header that came from outside, so the token can't be forged.

Session (session.py → _session_posix.py | _session_windows.py). session.py is now a facade that imports the module for the current OS. The POSIX module is the old session.py, moved with git mv; only its exit bookkeeping changed. On Windows:

  • Launch: every app starts through _job.py, a stdlib-only helper (python -I -S). The helper creates a Job object named for its own pid, with KILL_ON_JOB_CLOSE, joins it, and then starts the app, so the app and everything it starts belong to the job. It reports started, or why it couldn't start the app. It exits only when the job holds nothing but itself, and exits with the app's code. As on POSIX, the app outlives the server that launched it, and a restarted server finds the job by its name.
  • Stop: WM_CLOSE goes to the app's visible windows. If they're still there after the timeout, the job is terminated. With no windows to ask, it's terminated at once.
  • Pause (for data/get): NtSuspendProcess on each process in the job except the helper, resumed on the way out, even if the block raises.
  • Windows: EnumWindows, skipping hidden and cloaked windows. Each window is reported by window class, program file name (lowercased) and title, which is what Launch.window matches against on Windows.
  • Menu launcher: a Start Menu .lnk, written with PowerShell's WScript.Shell.

Exit bookkeeping (_reaping.py). The exit-code tracking both session modules use. It reaps with communicate(), so a launch's pipes close together with the process.

Declaring a Windows app (app.py). New @windows(...) decorator and Windows model: files, python, downloads, .ps1 run scripts, services, ports. Windows-only constants: LAUNCHED sits under the temp dir and APPS is C:/agentenv/apps.

Why these choices

These are the six W2.1 decisions, as agreed:

  1. Loopback with a token, because Windows asyncio can't serve a Unix socket.
  2. Suspend the job's processes for data/get, the Windows counterpart of SIGSTOP.
  3. Keep Launch.window's fields and give each one its Windows meaning.
  4. A Job object for what an app starts.
  5. A separate Windows session module.
  6. The notes app goes first.

Tests

  • Protocol suite: 1350 passed, 2 skipped on a Linux box. Ruff is clean.
  • test_computer_served.py:
    • only the token gets in (missing, wrong and duplicated tokens are refused, on HTTP and WebSocket);
    • the app never sees the header;
    • proxy environment variables are ignored;
    • the address file is written whole.
  • test_computer_svc_forward.py runs over both transports and checks that a forged token header is dropped.
  • test_computer_session_windows.py fakes Win32 and checks:
    • stop asks the windows to close and terminates only if they don't;
    • pause and resume, including when the block raises;
    • a job that's gone;
    • the window list;
    • the shortcut;
    • launch, through a stand-in helper;
    • the facade picks the right module for the OS.
  • test_computer_serve.py serves on loopback through the real uvicorn path.
  • The one remaining "Event loop is closed" warning also appears on main, so it isn't from this change.

The real Win32 path (_job.py and _Win32) runs end to end on a Windows computer in the core PR's e2e (notes plus cua-driver: probe, reset, chaos). I'll post the results here.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The PR appears safe to merge with PR #540 providing the required private token-folder permissions.

Summary

Adds Windows app servers over token-protected loopback connections and a Windows session backed by Job objects.

  • Windows app servers answer on a guarded loopback port.
  • Windows apps launch and stop with their child processes as a group.
  • App authors can describe Windows installs and launches.
  • Windows computers install and find apps under their own app folder.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Driver[Driver or launcher] --> Route{App server transport}
    Route -->|Linux or macOS| Socket[Unix socket]
    Route -->|Windows| Guard[Loopback token check]
    Guard --> Server[App server]
    Socket --> Server
    Server --> Session{Session}
    Session -->|Windows| Helper[Job helper]
    Helper --> App[App and child processes]
Loading

Reviews (7) · Last reviewed commit: "fix(computer): a Windows app's stop wait..." · Reviewed by Greptile

earakely-scale and others added 3 commits November 7, 2026 23:06
…app servers on loopback

- session.py picks the OS's way: _session_posix (Linux, macOS, as before) or _session_windows, sharing _reaping.
- On Windows an app launches through _job, a standard-library helper that holds a Job object named for its pid: the
  app and all it starts are in it, it outlives the server, and a server finds it by name to stop it (its windows
  asked to close, then the job ended) or pause it (each process suspended). Windows are listed with EnumWindows, by
  program, class and title; the menu launcher is a Start Menu shortcut.
- served.py: an app's server answers on its folder's Unix socket, or on Windows on a loopback port it writes with a
  token, which it checks on every request and WebSocket; the driver's apps and svc, the launcher and the page driver
  reach it either way, through no proxy the environment names.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… reading its pipes to their end

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…nstall under windows

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
earakely-scale and others added 4 commits November 7, 2026 23:25
… name the window buffers' sizes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…, whose pid names its job

A venv's python.exe on Windows is a launcher that runs the interpreter as a child, so the pid a launch held wasn't the
helper's, and pausing, stopping and finding the job found none.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…s no process

Ending a job returns before its processes have, and a reset puts the app's files back once its stop returns, which a
process still holding one open would refuse. The session's windows are listed off the event loop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…not while the job is there

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale

Copy link
Copy Markdown
Collaborator Author

E2E on a real Windows 11 computer: the notes app composed onto windows-11 with cua-driver, through the stacked core PR, on a Linux box with KVM. The first round found three bugs in this PR's Windows session, now fixed:

  1. 40bd73f: The job helper ran on the venv's python.exe. On Windows that's a launcher that runs the interpreter as a child process. The helper named its job after its own pid, but the session held the launcher's, so pause, stop and alive never found the job. The helper now runs on the base interpreter (sys.base_prefix\python.exe).
  2. 89f45b0: TerminateJobObject returns before the processes have exited. A reset restores the app's files right after stop, and a dying process could still hold one open. Stop now waits up to 5 s for a job it ended by force to hold no process. The window list moved off the event loop.
  3. e73ce0f: A job ended by force exists, empty, until its last handle closes. alive now means a process of the job is running, as on POSIX.

With those fixes, running inside the computer as the session user:

  • a launch's exit code is the app's;
  • a pause holds the app and a child it started, and resumes both;
  • a windowless app is ended at once;
  • an app whose window closes when asked stops in 0.2 s;
  • one whose window won't close is ended at the timeout, with nothing of it left running;
  • killing the helper ends the app;
  • a missing program is refused with the reason.

Through the app's server:

  • a reset with the app's window hung takes the 10 s stop timeout, then relaunches the app;
  • data/get returns what data/add wrote;
  • the server returns 403 without its token and 200 with it.

Gate 3's full probe and the deploy, verify, reset, verify task pass. Details are in the core PR.

earakely-scale and others added 2 commits November 8, 2026 05:16
… one module, and key the apps folder by OS

On Windows an app's server is reached on the address it wrote, and one that hasn't written it isn't answering, which
every caller handles; it used to fall back to a Unix socket, which Windows has none of, so a readiness check raised
instead of saying the server hadn't started or why it failed. Served opens an app's WebSocket too, so svc no longer
knows either transport, and app.py keeps the paths, so an app's own code still imports no websockets. apps_folder(os)
says where a computer of each OS keeps its apps, which composing uses for the computer it composes rather than the OS
it runs on. _Win32 names its DLLs, and kernel32's calls are typed in one place.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…o have exited

Its job's list of processes says only that one is no longer in the job; its own handle says it has exited, so none
still writes once a stop returns and a reset puts the app's files back. Once in about 27 windowless stops on a real
Windows computer, a file still grew after the stop returned.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale merged commit a652b20 into main Nov 8, 2026
35 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/windows-app-runtime branch November 8, 2026 16:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant