Skip to content

Commit 156559f

Browse files
fix(devices): reap a device hub left behind by a killed server
Co-Authored-By: Claude Fable 5 <[email protected]> docs(devices): describe the Device panel and its architecture
1 parent fa0d7dc commit 156559f

4 files changed

Lines changed: 198 additions & 0 deletions

File tree

‎apps/server/src/device/LocalDeviceHost.ts‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,20 @@ const DAEMON_POLL_MS = 100;
5858
const HUB_RESTART_STABLE_UPTIME_MS = 60_000;
5959
const HUB_RESTART_MAX_DELAY_MS = 30_000;
6060

61+
/**
62+
* Written beside the agent-device state so a server that dies without running
63+
* its finalizers (SIGKILL, dev-runner restarts) does not leave a hub bound to
64+
* a loopback port forever. The next start reads it, kills only a process that
65+
* is still that hub, and replaces the file.
66+
*/
67+
const HubStateFile = Schema.Struct({
68+
pid: Schema.Int,
69+
port: Schema.Int,
70+
entryPath: Schema.String,
71+
});
72+
const decodeHubStateFile = Schema.decodeUnknownEffect(Schema.fromJsonString(HubStateFile));
73+
const encodeHubStateFile = Schema.encodeUnknownEffect(Schema.fromJsonString(HubStateFile));
74+
6175
const AgentDeviceDaemonFile = Schema.Struct({
6276
httpPort: Schema.Int,
6377
token: Schema.String,
@@ -135,9 +149,75 @@ export const make = Effect.fn("LocalDeviceHost.make")(function* () {
135149
const stopHub = (hub: HubProcess | undefined) =>
136150
hub ? Scope.close(hub.scope, Exit.void).pipe(Effect.ignore) : Effect.void;
137151

152+
const hubStatePath = () => path.join(agentDeviceStateDir(path, config.stateDir), "hub.json");
153+
154+
const isProcessAlive = (pid: number) =>
155+
Effect.sync(() => {
156+
try {
157+
process.kill(pid, 0);
158+
return true;
159+
} catch {
160+
return false;
161+
}
162+
});
163+
164+
/**
165+
* A hub left behind by a previous server is identified by pid plus the
166+
* command line's entry path, so a recycled pid belonging to something else
167+
* is never touched.
168+
*/
169+
const reapStaleHub = Effect.gen(function* () {
170+
const previous = yield* fs
171+
.readFileString(hubStatePath())
172+
.pipe(Effect.flatMap(decodeHubStateFile), Effect.option);
173+
if (previous._tag === "None") return;
174+
const alive = yield* isProcessAlive(previous.value.pid);
175+
if (alive) {
176+
const commandLine = yield* runner
177+
.run({
178+
command: "ps",
179+
args: ["-o", "command=", "-p", String(previous.value.pid)],
180+
timeout: Duration.seconds(5),
181+
timeoutBehavior: "timedOutResult",
182+
})
183+
.pipe(
184+
Effect.map((result) => result.stdout),
185+
Effect.orElseSucceed(() => ""),
186+
);
187+
if (commandLine.includes(previous.value.entryPath)) {
188+
yield* Effect.logWarning("Stopping a device hub left behind by a previous server", {
189+
pid: previous.value.pid,
190+
port: previous.value.port,
191+
});
192+
yield* Effect.sync(() => {
193+
try {
194+
process.kill(previous.value.pid, "SIGTERM");
195+
} catch {
196+
// Already gone.
197+
}
198+
});
199+
}
200+
}
201+
yield* fs.remove(hubStatePath(), { force: true }).pipe(Effect.ignore);
202+
}).pipe(Effect.catchCause(() => Effect.void));
203+
204+
const recordHub = (hub: HubProcess, tools: DeviceToolchainPaths) =>
205+
encodeHubStateFile({
206+
pid: Number(hub.child.pid),
207+
port: Number(new URL(hub.origin).port),
208+
entryPath: tools.hub.entryPath,
209+
}).pipe(
210+
Effect.flatMap((json) => fs.writeFileString(hubStatePath(), json)),
211+
Effect.ignore,
212+
);
213+
138214
const spawnHub = Effect.fn("LocalDeviceHost.spawnHub")(function* (
139215
tools: DeviceToolchainPaths,
140216
): Effect.fn.Return<HubProcess, DeviceHostError> {
217+
yield* reapStaleHub;
218+
yield* fs
219+
.makeDirectory(agentDeviceStateDir(path, config.stateDir), { recursive: true })
220+
.pipe(Effect.ignore);
141221
const port = yield* net.reserveLoopbackPort("127.0.0.1").pipe(
142222
Effect.mapError(
143223
(cause) =>
@@ -203,6 +283,7 @@ export const make = Effect.fn("LocalDeviceHost.make")(function* () {
203283
Effect.provideService(HttpClient.HttpClient, httpClient),
204284
Effect.tapError(() => stopHub(hub)),
205285
);
286+
yield* recordHub(hub, tools);
206287
yield* Effect.logInfo("Device hub started", { pid: Number(child.pid), port });
207288
return hub;
208289
});
@@ -399,6 +480,7 @@ export const make = Effect.fn("LocalDeviceHost.make")(function* () {
399480
Effect.gen(function* () {
400481
const running = yield* Ref.getAndSet(runningRef, null);
401482
yield* stopHub(running?.hub);
483+
yield* fs.remove(hubStatePath(), { force: true }).pipe(Effect.ignore);
402484
yield* stopAgentDeviceDaemon(toolsRef);
403485
}),
404486
);

‎docs/README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
- [Keyboard shortcuts](./user/keybindings.md)
1414
- [SnapShots](./user/snap-shot.md)
1515
- [Import browser sessions](./user/browser-import.md)
16+
- [Devices](./user/devices.md)
1617
- [Usage and limits](./user/usage.md)
1718
- [Product usage data](./user/telemetry.md)
1819
- [Remote access](./user/remote-access.md)
@@ -46,6 +47,7 @@ source alone does not explain. Most code changes do not need an internal documen
4647
- [Mobile navigation](./internals/mobile-navigation.md)
4748
- [Mobile development lifecycle](./internals/mobile-development.md)
4849
- [Terminal runtime](./internals/terminal-runtime.md)
50+
- [Devices](./internals/devices.md)
4951
- [Voice input](./internals/voice-input.md)
5052

5153
### Runbooks

‎docs/internals/devices.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Devices
2+
3+
The environment server owns simulators and emulators the way it owns
4+
terminals: discovery, streaming, and agent access all run there, and every
5+
client reaches them through the environment connection. This is what makes the
6+
Device panel work over Tailscale and T3 Connect, and what will let a device
7+
host on another machine slot in later.
8+
9+
## Two external tools, one seam
10+
11+
[expo-device-hub](../../apps/server/src/device/LocalDeviceHost.ts) streams and
12+
[agent-device](../../apps/server/src/device/AgentDeviceShim.ts) drives. Both
13+
are npm-installed at pinned versions into the T3 home on first use and run with
14+
the server's Node; `npx` would make the first `device_open` after a reboot
15+
depend on the registry. The hub is a supervised child rather than an imported
16+
middleware because serve-sim loads private CoreSimulator frameworks through a
17+
native addon, and a crash there must not take the server down.
18+
19+
Everything platform-specific sits behind
20+
[`DeviceHost`](../../apps/server/src/device/DeviceHost.ts). The service, the
21+
proxy, and the MCP tools only see a hub origin and an agent-device endpoint.
22+
An SSH or cloud host would forward those two things to the server and change
23+
nothing above it.
24+
25+
## The hub is never exposed
26+
27+
serve-sim has a shell-exec route whose token is readable from its own
28+
unauthenticated `/api`, and serve-emu's action routes have no auth at all. The
29+
hub binds loopback and the only way in is the
30+
[proxy](../../apps/server/src/device/DeviceHubProxy.ts), which allowlists the
31+
stream, config, and screenshot routes and authenticates every request as an
32+
environment session. `<img>` and `WebSocket` cannot carry headers, so the proxy
33+
authenticates like the `/ws` upgrade: cookie, or a short-lived `wsTicket` that
34+
bearer and DPoP clients mint over authenticated HTTP. The ticket is stripped
35+
before the request reaches the hub.
36+
37+
Stream responses carry `Cache-Control: no-transform`; the compression
38+
middleware would otherwise buffer an MJPEG body that never ends. In browser dev,
39+
the Vite proxy must forward WebSocket upgrades for `/api`, not only `/ws`.
40+
41+
## Agents drive through the CLI
42+
43+
The `device_*` toolkit is deliberately four tools: list, open, screenshot, and
44+
close. Driving happens through the `agent-device` CLI, which has the semantic
45+
snapshot model agents need and stays current with its own releases. T3 prepends
46+
a shim directory to the provider's PATH and sets
47+
`AGENT_DEVICE_DAEMON_BASE_URL` and `AGENT_DEVICE_DAEMON_AUTH_TOKEN` so the
48+
agent never handles the endpoint or token.
49+
50+
That environment is fixed when the provider subprocess spawns, so
51+
[`prepareMcpSession`](../../apps/server/src/provider/Layers/ProviderService.ts)
52+
starts the device host whenever the session has the `device` capability and
53+
the machine can run at least one platform. Starting it later from
54+
`device_open` would leave the already-running agent without the CLI.
55+
56+
How to drive a device is returned from `device_open`, not kept in an
57+
always-loaded prompt or skill: it costs nothing in threads that never open a
58+
device and cannot drift from the pinned CLI version. The always-on prompt block
59+
is a few lines that point at the tools and forbid raw `simctl` and `adb`.
60+
61+
## The viewer decodes both vendored protocols
62+
63+
The hub vendors two streaming servers with different wire formats. iOS video is
64+
an HTTP body of AVCC envelopes decoded with WebCodecs, with input on a separate
65+
binary WebSocket; Android multiplexes SEMU-framed H.264 and JSON gestures over
66+
one WebSocket. [`deviceStream.ts`](../../apps/web/src/components/device/deviceStream.ts)
67+
speaks both so one panel covers both platforms.
68+
69+
Simulators encode H.264 High 5.1. Hardware decoders on some machines and all
70+
headless browsers reject that profile, and WebCodecs is secure-context only, so
71+
the viewer probes `isConfigSupported` and falls back to the MJPEG endpoint on
72+
iOS. Android has no MJPEG; there the panel reports that it cannot decode.

‎docs/user/devices.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# Devices
2+
3+
The Device panel shows a live iOS Simulator or Android Emulator next to a
4+
thread, so you can watch an agent verify mobile work and tap the device
5+
yourself. Agents get the same device through `device_*` tools and the
6+
`agent-device` command line, which T3 Code sets up for them.
7+
8+
## Open a device
9+
10+
Open the right panel in a project thread and choose **Device**, then pick a
11+
simulator or emulator. A device that is not running boots when you pick it.
12+
The first time, T3 Code installs its device tools on the server; that takes a
13+
minute and happens once.
14+
15+
Simulators run on the machine that hosts the environment server. iOS needs
16+
macOS with Xcode. Android needs the Android SDK with `ANDROID_HOME` set or
17+
`adb` on the path. The panel says which platforms the server can run and why one
18+
cannot.
19+
20+
The screen is interactive: click and drag to touch, type while the screen is
21+
focused, and use the toolbar for Home, Back, and Recents on Android, rotate on
22+
iOS, and power off. Close the tab to stop watching; the device keeps running
23+
unless you power it off.
24+
25+
## Agents and devices
26+
27+
When an agent opens a device, the panel opens in every client connected to the
28+
thread. Agents drive the device through the `agent-device` command line, which
29+
T3 Code preinstalls and connects for them. iOS taps through `agent-device` build
30+
a small test runner on first use, which takes a couple of minutes once per
31+
server.
32+
33+
To keep agents away from simulators, turn off **Agent device access** in
34+
Settings → Projects → Project defaults. This hides the device tools from agents
35+
started from then on; your own Device panel is unaffected.
36+
37+
## Remote connections
38+
39+
The device stream goes through the environment server, so it works over the
40+
local network, Tailscale, and T3 Connect. Live video needs a secure page
41+
(HTTPS or localhost); on a plain-HTTP remote origin iOS falls back to a slower
42+
still-image stream and Android cannot show video.

0 commit comments

Comments
 (0)