Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ Apache-2.0 · Default branch: `master`.
| `internal/client` | Protocol client (calls, notifications, events, handshake) and starting a local server |
| `internal/tui` | The TUI: tree, tabs/splits/scoping, keys, mouse, views (changes, sessions, setup), dialogs, settings, brain bar, updates |
| `internal/remote` | How a machine is reached (`Transport`: ssh, a sandbox through its provider's ssh gateway with a fresh token, or a local command), ssh config and commands, remote install, bridging, machine catalog, release downloads, cross builds |
| `internal/sandbox` | Hosted sandbox providers (Daytona, boat.dev, Devin Cloud, Tensorlake): create, start, stop, delete, list conch's own, ssh access — a fresh token, or a key of your own authorized in the sandbox. And providers conch has no code for, described by a file (`custom.go`, `providerfile.md` the format): `$CONCH_HOME/providers/NAME.toml` says which call does what and how ssh gets in, read by one provider of conch's own — a description, never generated code, so a wrong file fails rather than does something else. `conch sandbox adapt` (`cmd/conch/adapt.go`) has an agent draft one from the provider's API docs in a pane of its own; the key stays conch's. Format 2 (`format = 2`: a wrapped reply's `[get] item`, `{public_key}` in a create body via `sandbox.PublicKey`, which `internal/remote` sets, and `list[key=value]` selectors in paths) is refused by older conches as an unknown key, which is the point. `registry.go` is the provider registry (github.com/Amitgb14/conch-sandbox-providers, its index on Pages, `CONCH_PROVIDERS_URL` to point elsewhere): install checks the file's hash against the index and records it in `providers/registry.json`, so update can leave an edited file alone and asks again when a file's hosts change — a provider file sends the person's key to its `api` host. Publishing (`cmd/conch/registry.go`) is a pull request through `gh api`, after a live check with the key; tests never reach the real registry (`TestMain` points it at a dead address) |
| `internal/sandbox` | Hosted sandbox providers (Daytona, boat.dev, Devin Cloud, Tensorlake): create, start, stop, delete, list conch's own, ssh access — a fresh token, or a key of your own authorized in the sandbox. And providers conch has no code for, described by a file (`custom.go`, `providerfile.md` the format): `$CONCH_HOME/providers/NAME.toml` says which call does what and how ssh gets in, read by one provider of conch's own — a description, never generated code, so a wrong file fails rather than does something else. `conch sandbox adapt` (`cmd/conch/adapt.go`) has an agent draft one from the provider's API docs in a pane of its own; the key stays conch's. Format 2 (`format = 2`: a wrapped reply's `[get] item`, `{public_key}` in a create body via `sandbox.PublicKey`, which `internal/remote` sets, and `list[key=value]` selectors in paths) and format 3 (`headers`, top-level and per call, with `{uuid}` new for each request — an `Idempotency-Key`, a delete's confirmation; never the key, never a header conch sets) and `[ssh] port = "{reply.PATH}"` (`SSHPort`, a gateway that names its port per connection) are refused by older conches as an unknown key, which is the point. `registry.go` is the provider registry (github.com/Amitgb14/conch-sandbox-providers, its index on Pages, `CONCH_PROVIDERS_URL` to point elsewhere): install checks the file's hash against the index and records it in `providers/registry.json`, so update can leave an edited file alone and asks again when a file's hosts change — a provider file sends the person's key to its `api` host. Publishing (`cmd/conch/registry.go`) is a pull request through `gh api`, after a live check with the key; tests never reach the real registry (`TestMain` points it at a dead address) |
| `internal/phone` | The gateway `conch web` runs for a phone: HTTP and a WebSocket in front of every machine's server (a client of each, as the TUI is — `machines.go` keeps one per machine, reached in the background so a phone never waits on ssh, and a pane is addressed `machine:pane`; capabilities are asked of *each* machine, since every one runs its own conch — `phoneNeeds` against that machine's handshake, said in its `Behind` before anything is tried, and refused by `lacks` with that machine named and `conch machine upgrade` rather than "reload the server", which is the wrong advice about a machine nobody is sitting at), pairing codes, per-device tokens kept hashed in `phone.json`, the socket deflated with the window kept across messages (`CompressionContextTakeover`), since a frame is the screen and the next frame is that screen slightly changed — measured 14.9× fewer bytes end to end and *less* processor time a frame than compressing each alone, for a 32 KB window and a flate writer a socket; `view`/`reply`/`full` checked on every route and socket message — and *where*, since the gateway reaches every machine with the person's credentials: a device reaches this computer and the machines named for it (`Device.Machines`, `Reaches`), which is why `machinesFor`, `machineFor`, `paneOn`, `everyAgent`, `everyPane` and the socket's own `paneOn` all take the device, a machine it was not given is left out of every list rather than merely refused, pushes about one are not sent, and an older `phone.json` loads as this computer alone, reading a waiting agent's choices off its screen — each socket holds its *own* connection per machine, since frames come from its own subscriptions and one phone's subscribing would otherwise decide another's, so a message naming a machine this socket has not joined dials it and waits (`machineReady`) rather than refusing: refusing meant the agent a phone had just been shown would not open for the first seconds after the app started, which is how it was found — and the phone's app (`ui/`: plain HTML, CSS and ES modules embedded as they are, no build step — each file deflated once at first use and served that way to a phone that takes it (`uiDeflated`, 102 KB of shell as 34 KB), since nothing in `ui/` can change while conch runs; its logic in `ui/lib.mjs`, tested with node from `uitest/` through `TestUILogic`, which skips without node). Its shapes are a contract (`api.go`) a test pins |
| `internal/relay` | How a phone reaches conch web without Tailscale: `conch relay` (`relay.go`, the server — rooms keyed by a hash of a secret only the gateway holds, a phone's WebSocket spliced to one the gateway opens for it, nothing stored), the gateway's link out to it (`link.go`), and the tunnel inside (`tunnel.go`): a Noise NK session (`Noise_NK_25519_AESGCM_SHA256`, flynn/noise) keyed by the gateway's key, which the pairing QR code carries in its fragment past the relay; the phone's calls and its socket carried as length-prefixed JSON frames and served by the gateway's own handler through an in-memory listener, the gateway's direction deflated before it is encrypted. The phone's end is `internal/phone/ui/tunnel.mjs` in WebCrypto, run against this Go end by `TestTunnelJSAgainstGo`; `phone.go` is the same end in Go, for tests. A test taps the relay's bytes and fails if any plaintext is among them. **The relay is trusted all the same**: it serves the phone's app — the code that makes the session and keeps the device's token in `localStorage` — so it could serve one that reads everything; the docs say to run one of your own, and nothing here may claim more. A device paired through the tunnel is marked (`Device.Relay`, from `relay.Through`, which only the in-memory connection can set) so `conch web relay reset` revokes it with the key |
| `internal/preview` | The phones a mobile app is tried on, on this computer: iOS simulators through `xcrun simctl`, Android emulators and phones through `adb` and `emulator` (found in the SDK where Android Studio puts it, not only on `PATH`), and AXe (else `idb`) for touching an iOS simulator, which simctl cannot — in points, the screenshot's pixels divided by the device type's `mainScreenScale`. Xcode is found in `/Applications` when `xcode-select` points at the Command Line Tools (`DEVELOPER_DIR` is set for every tool, AXe included, which asks `xcode-select -p` itself); `[preview]` in config.toml names it otherwise. Lists, boots, screenshots, taps, types, presses home or back, and says what kind of mobile app a folder is. `conch preview` (`cmd/conch/preview.go`) is the command over it, asking no server; Conch.app's **Mobile Preview** tab (`MobilePreviewView.swift`, the testable part in `ConchKit/MobilePreview.swift`) runs that command a few times a second while on screen, and an agent looks at its own work with `conch preview shot`. Tests answer from a table of command lines and never reach a real simulator |
Expand Down
Loading
Loading