feat(tui): add fleet host adapters

2026-06-12 18:31:29 -07:00
parent e35684efed
commit 9e5688b8c8
4 changed files with 1053 additions and 0 deletions
@@ -0,0 +1,83 @@
+# Agent Fleet
+
+Agent Fleet is the local-first control plane for durable multi-worker runs. The
+initial CLI surface is:
+
+```sh
+codewhale fleet init
+codewhale fleet run tasks.json --max-workers 4
+codewhale fleet status
+codewhale fleet inspect <worker-id>
+codewhale fleet interrupt <worker-id>
+codewhale fleet restart <worker-id>
+codewhale fleet stop --all
+```
+
+Fleet state is stored under the workspace in `.codewhale/fleet.jsonl`. Worker
+logs and adapter logs are stored under `.codewhale/fleet/` and
+`.codewhale/fleet-host/`.
+
+## Task Spec
+
+`codewhale fleet run` accepts JSON or TOML. A minimal JSON spec:
+
+```json
+{
+  "name": "local smoke",
+  "tasks": [
+    {
+      "id": "lint",
+      "name": "Lint",
+      "instructions": "Run the lint check and report failures.",
+      "expected_artifacts": ["log"]
+    }
+  ]
+}
+```
+
+Workers are optional. If omitted, CodeWhale creates local worker slots up to
+`--max-workers`.
+
+## Host Adapters
+
+The host adapter boundary supports local child processes and explicit SSH
+workers. Adapters expose the same operations: start, read status, read bounded
+logs, interrupt, restart, stop, and cleanup.
+
+Local workers run as child processes with stdin closed and stdout/stderr written
+to bounded fleet host logs. They inherit only a small safe base environment
+such as `PATH` and explicitly allowlisted variables.
+
+SSH workers run through the system `ssh` client with `BatchMode=yes` and a
+bounded connect timeout. Remote environment variables are sent with OpenSSH
+`SendEnv`; values are not embedded in the local ssh argv or fleet logs.
+
+Example SSH worker spec:
+
+```json
+{
+  "id": "builder-1",
+  "name": "Builder 1",
+  "host": {
+    "kind": "ssh",
+    "host": "builder.example.com",
+    "user": "codewhale",
+    "port": 22,
+    "identity": "~/.ssh/codewhale_fleet",
+    "working_directory": "/srv/codewhale/work",
+    "env_allowlist": ["CODEWHALE_PROFILE"],
+    "codewhale_binary": "/usr/local/bin/codewhale"
+  },
+  "capabilities": ["local", "linux", "tests"],
+  "max_concurrent_tasks": 1
+}
+```
+
+Defaults are intentionally conservative:
+
+- no hosted control plane or cloud provisioning is enabled;
+- SSH requires an explicit host, working directory, and CodeWhale binary path;
+- secret-like environment names such as `TOKEN`, `SECRET`, `PASSWORD`,
+  `API_KEY`, and `PRIVATE_KEY` are rejected from adapter allowlists;
+- secrets should remain in CodeWhale config providers or remote host config,
+  not in task instructions, argv, or fleet logs.