From a5cd5d36ed7ddc01f581aaa0606f4a10223c7ef7 Mon Sep 17 00:00:00 2001 From: Ollie Agent Date: Tue, 18 Aug 2026 13:28:30 +0200 Subject: [PATCH] document compatibility roadmap --- doc/compatibility-roadmap.md | 90 ++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 doc/compatibility-roadmap.md diff --git a/doc/compatibility-roadmap.md b/doc/compatibility-roadmap.md new file mode 100644 index 0000000..e7c5b81 --- /dev/null +++ b/doc/compatibility-roadmap.md @@ -0,0 +1,90 @@ +# Compatibility roadmap + +This document records compatibility observations and possible future work. It is not an implementation plan. The current Linux-first behavior remains acceptable; these items can be prioritized when broader host support becomes useful. + +## Target architecture + +```text +olliesrv + agent runtime, orchestration, and 9P service + preferably host-neutral + │ + └── toolsrv + host-dependent tool execution boundary + execution, filesystem, process, networking, sandbox +``` + +`toolsrv` should be extensible to other host systems so Ollie tools remain useful to as many people as possible. `olliesrv` may remain Linux-specific if that keeps the agent runtime simpler, but its current implementation has only a small set of host-specific assumptions and may be portable with limited work. + +## olliesrv + +### Current status + +`olliesrv` is primarily implemented with portable Go facilities: + +- 9P protocol handling over `net.Conn`. +- Unix and TCP listeners. +- Filesystem persistence and configuration. +- Context cancellation, goroutines, and process supervision. +- Provider and agent runtime logic. + +The Plan 9 client dependency is a Go 9P implementation. `olliesrv` does not directly require the plan9port plumber. The default namespace lookup follows plan9port-style conventions (`$NAMESPACE`, then a derived `/tmp/ns...` path), but this can be replaced or made explicit later. + +### Compatibility observations + +- `cmd/olliesrv/internal/toolclient/spawn.go` sets `syscall.SysProcAttr.Pdeathsig` for local toolsrv and remote SSH processes. +- `Pdeathsig` is available on Linux and FreeBSD but not macOS. Its use currently prevents builds on macOS and other systems whose `SysProcAttr` lacks that field. +- The same file uses `Setpgid` for remote SSH process management. This is also OS-specific and should be isolated if process-group behavior is retained. +- Existing context cancellation, explicit process killing, waiting, and toolsrv idle timeouts already provide most lifecycle management. Removing `Pdeathsig` is therefore a viable future option. +- A portable parent-death pipe is another possible option if orphan cleanup must remain consistent across hosts. +- Local session metadata hard-codes `Platform: "linux"` in session setup and local process metadata. It should eventually use `runtime.GOOS` or host-provided metadata. +- Remote deployment currently assumes `bash`, `tar`, `ssh`, and a Linux toolsrv binary. Remote host detection and platform-specific toolsrv artifacts will be needed for non-Linux remote hosts. +- D-Bus desktop notifications are optional at runtime, but the dependency is currently compiled into `olliesrv`. The notification integration could later be isolated or replaced with a host/frontend-specific notifier. + +### Possible future directions + +1. Remove `Pdeathsig` and `Setpgid` from common code and rely on existing lifecycle cleanup. +2. Keep stronger process attributes in OS-specific files for Linux and FreeBSD. +3. Add a portable parent-death pipe when consistent orphan cleanup is required. +4. Add explicit socket/listen configuration so the service does not depend on an implicit Plan 9 namespace directory. +5. Detect and propagate local and remote platform metadata. +6. Separate remote deployment from the assumption that the host runs Linux. + +## toolsrv + +### Current status + +`toolsrv` is currently Linux-specific. Restricted execution uses native Landlock system calls in a short-lived helper process. The installed sandbox policy and execution path assume Linux Landlock semantics. + +The toolsrv protocol and namespace are more portable than the execution implementation. `olliesrv` communicates with toolsrv through authenticated 9P over a Unix socket, and remote execution already treats toolsrv as a separately deployed process. + +### Compatibility areas + +Supporting other hosts will require platform-specific implementations for more than sandboxing: + +- Tool process creation and lifecycle. +- Process groups, signals, and cancellation. +- Filesystem policy enforcement. +- Network policy enforcement. +- Environment and path handling. +- Resource limits and process supervision. +- Host metadata and capability reporting. +- Local and remote binary deployment. + +Possible sandbox mechanisms include Capsicum and jails on FreeBSD, and the platform sandbox facilities on macOS. These mechanisms do not necessarily express the same path-based policy as Landlock, so each backend must declare its enforcement limits rather than silently weakening policy. + +### Possible future directions + +1. Keep the generic sandbox interface and add OS-specific implementations behind it. +2. Define a host capability model for filesystem, process, network, and sandbox features. +3. Make tool execution report unsupported or degraded policy enforcement explicitly. +4. Build and deploy toolsrv artifacts per target host and architecture. +5. Add host-specific tests without making Linux behavior conditional at runtime. + +## WSL2 + +WSL2 provides a Linux kernel in a VM. It should use the existing Linux `olliesrv` and `toolsrv` implementations, subject to the kernel and distribution providing the required Linux features, including Landlock support. + +## Decision status + +No compatibility work is scheduled now. This roadmap records the design boundary and observations for later prioritization.