The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 23:30 UTC
fix(server): device setup names a missing npm instead of a generic failure (#28258)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Julius Marminge committed
Nov 11, 2026 at 11:53 UTC
1278628870baa7dc88d61f491b7d5a2de20081c5
5 files changed
+161
-20
apps/server/src/device/DeviceService.test.ts
+41
@@ -23,6 +23,7 @@ import * as FileSystem from "effect/FileSystem";
23
import * as SecretResolver from "@t3tools/secret-provider-core/server/SecretResolver";
24
import * as Layer from "effect/Layer";
25
import * as Option from "effect/Option";
26
+import * as PlatformError from "effect/PlatformError";
27
import * as PubSub from "effect/PubSub";
28
import * as Queue from "effect/Queue";
29
import * as Ref from "effect/Ref";
@@ -42,6 +43,7 @@ import { NodeRuntimeUnavailableError } from "@t3tools/shared/nodeRuntime";
43
import * as DeviceService from "./DeviceService.ts";
44
import * as SshDeviceHost from "./SshDeviceHost.ts";
45
import { agentDeviceSession, releaseAgentDeviceSession } from "./AgentDeviceTarget.ts";
46
+import { ensureDeviceHub } from "./DeviceToolchain.ts";
47
48
const decodeJson = Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Unknown));
49
const decodeBootError = Schema.decodeUnknownSync(Schema.fromJsonString(DeviceBootError));
@@ -380,6 +382,45 @@ describe("device setup consent", () => {
382
}).pipe(Effect.scoped),
383
);
384
385
+ it.effect("names the missing npm in the host status when device support cannot install", () =>
386
+ Effect.gen(function* () {
387
+ const fs = yield* FileSystem.FileSystem;
388
+ const baseDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-device-no-npm-" });
389
+ const installError = yield* ensureDeviceHub(baseDir).pipe(
390
+ Effect.provideService(ProcessRunner.ProcessRunner, {
391
+ run: (input) =>
392
+ Effect.fail(
393
+ new ProcessRunner.ProcessSpawnError({
394
+ command: input.command,
395
+ argumentCount: input.args.length,
396
+ cause: PlatformError.systemError({
397
+ _tag: "NotFound",
398
+ module: "ChildProcess",
399
+ method: "spawn",
400
+ description: `spawn ${input.command} ENOENT`,
401
+ }),
402
+ }),
403
+ ),
404
+ }),
405
+ Effect.flip,
406
+ );
407
+ const { service, settings } = yield* fixture(
408
+ Effect.void,
409
+ undefined,
410
+ false,
411
+ new DeviceHost.DeviceHostError({
412
+ hostId: LOCAL_DEVICE_HOST_ID,
413
+ step: "installing device support",
414
+ cause: installError,
415
+ }),
416
+ );
417
+ yield* Ref.update(settings, (current) => ({ ...current, enableDeviceSupport: true }));
418
+ const detail = (yield* service.list).hostStatuses[LOCAL_DEVICE_HOST_ID]?.detail;
419
+ expect(detail).toMatch(/\bnpm\b/);
420
+ expect(detail).toMatch(/Node\.js/);
421
+ }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
422
+ );
423
+
424
it.effect.each([
425
{
426
name: "a Windows host",
apps/server/src/device/DeviceService.ts
+20
-13
@@ -36,7 +36,11 @@ import { SshCommandError } from "@t3tools/ssh/errors";
36
import * as FileSystem from "effect/FileSystem";
37
import { resolveNodeExecutable, nodeRuntimeUnavailableMessage } from "@t3tools/shared/nodeRuntime";
38
import * as Path from "effect/Path";
39
-import { ensureAgentDevice, ensureDeviceHub } from "./DeviceToolchain.ts";
39
+import {
40
+ DeviceToolchainInstallError,
41
+ ensureAgentDevice,
42
+ ensureDeviceHub,
43
+} from "./DeviceToolchain.ts";
44
import {
45
agentDeviceCloseOutcome,
46
bindAgentDeviceLauncher,
@@ -108,6 +112,15 @@ const sshProbeFailureMessage = (error: DeviceHost.DeviceHostError): string => {
112
return `Connected over SSH, but the device host check failed (exit code ${cause.exitCode}).`;
113
};
114
115
+const isToolchainInstallError = Schema.is(DeviceToolchainInstallError);
116
+
117
+const actionableHostFailure = (error: DeviceHost.DeviceHostError): string | undefined => {
118
+ if (error.step === "probe") return sshProbeFailureMessage(error);
119
+ if (isToolchainInstallError(error.cause) && error.cause.reason === "npm_not_found")
120
+ return error.cause.message;
121
+ return undefined;
122
+};
123
+
124
export interface DeviceScreenshot {
125
readonly device: DeviceSummary;
126
readonly png: Uint8Array;
@@ -450,9 +463,7 @@ export const makeWithHosts = Effect.fn("DeviceService.makeWithHosts")(function*
463
setHostStatus(host.id, {
464
status: "failed",
465
detail:
453
- error._tag === "DeviceHostError" && error.step === "probe"
454
- ? sshProbeFailureMessage(error)
455
- : error.message,
466
+ (error._tag === "DeviceHostError" && actionableHostFailure(error)) || error.message,
467
}),
468
),
469
Effect.mapError(
@@ -463,9 +474,8 @@ export const makeWithHosts = Effect.fn("DeviceService.makeWithHosts")(function*
474
reason:
475
error._tag === "NodeRuntimeUnavailableError"
476
? nodeRuntimeUnavailableMessage("Local device support")
466
- : error.step === "probe"
467
- ? sshProbeFailureMessage(error)
468
- : `Device support failed during ${error.step}.`,
477
+ : (actionableHostFailure(error) ??
478
+ `Device support failed during ${error.step}.`),
479
cause: error,
480
}),
481
),
@@ -513,9 +523,7 @@ export const makeWithHosts = Effect.fn("DeviceService.makeWithHosts")(function*
523
setHostStatus(host.id, {
524
status: "failed",
525
detail:
516
- error._tag === "DeviceHostError" && error.step === "probe"
517
- ? sshProbeFailureMessage(error)
518
- : error.message,
526
+ (error._tag === "DeviceHostError" && actionableHostFailure(error)) || error.message,
527
}),
528
),
529
Effect.mapError(
@@ -530,9 +538,8 @@ export const makeWithHosts = Effect.fn("DeviceService.makeWithHosts")(function*
538
? `Agent tools did not start within ${error.timeoutMs} ms.`
539
: error._tag === "AgentDeviceStartError"
540
? error.message
533
- : error.step === "probe"
534
- ? sshProbeFailureMessage(error)
535
- : `Device support failed during ${error.step}.`,
541
+ : (actionableHostFailure(error) ??
542
+ `Device support failed during ${error.step}.`),
543
cause: error,
544
}),
545
),
apps/server/src/device/DeviceToolchain.ts
+19
-3
@@ -37,10 +37,13 @@ export class DeviceToolchainInstallError extends Schema.TaggedError<DeviceToolch
37
tool: Schema.String,
38
step: Schema.String,
39
exitCode: Schema.optional(Schema.Number),
40
+ reason: Schema.optional(Schema.Literal("npm_not_found")),
41
cause: Schema.optional(Schema.Defect()),
42
},
43
) {
44
override get message(): string {
45
+ if (this.reason === "npm_not_found")
46
+ return "Device support needs npm, which is not on the T3 server's PATH. Install npm (it comes with Node.js from nodejs.org), restart T3 Code, then retry.";
47
const suffix = this.exitCode === undefined ? "" : ` (exit code ${this.exitCode})`;
48
return `Installing ${this.tool} failed while ${this.step}${suffix}.`;
49
}
@@ -93,6 +96,11 @@ const isInstalled = Effect.fn("DeviceToolchain.isInstalled")(function* (
96
return entryExists && Option.isSome(sentinel) && sentinel.value.trim() === version;
97
});
98
99
+const isCommandNotFound = (error: ProcessRunner.ProcessRunError) =>
100
+ error._tag === "ProcessSpawnError" &&
101
+ error.cause instanceof PlatformError.PlatformError &&
102
+ error.cause.reason._tag === "NotFound";
103
+
104
const installTool = Effect.fn("DeviceToolchain.installTool")(function* (
105
spec: ToolSpec,
106
paths: DeviceToolPaths,
@@ -130,8 +138,7 @@ const installTool = Effect.fn("DeviceToolchain.installTool")(function* (
138
.pipe(
139
Effect.catchTags({
140
ProcessSpawnError: (error) =>
133
- error.cause instanceof PlatformError.PlatformError &&
134
- error.cause.reason._tag === "NotFound"
141
+ isCommandNotFound(error)
142
? runner.run({
143
command: "pnpm",
144
args: ["--package=npm@11", "dlx", "npm", ...installArgs],
@@ -139,7 +146,16 @@ const installTool = Effect.fn("DeviceToolchain.installTool")(function* (
146
})
147
: Effect.fail(error),
148
}),
142
- Effect.mapError(fail("running npm install")),
149
+ Effect.mapError((cause) =>
150
+ isCommandNotFound(cause)
151
+ ? new DeviceToolchainInstallError({
152
+ tool: spec.name,
153
+ step: "running npm install",
154
+ reason: "npm_not_found",
155
+ cause,
156
+ })
157
+ : fail("running npm install")(cause),
158
+ ),
159
);
160
if (result.code !== 0) {
161
return yield* new DeviceToolchainInstallError({
apps/server/src/mcp/McpDeviceToolkit.test.ts
+52
@@ -285,6 +285,58 @@ it.effect("rejects unavailable agent access before booting or opening a device",
285
);
286
});
287
288
+it.effect("device_open reports a failed host's setup error instead of no devices", () => {
289
+ const failure = "Device support failed: npm was not found. Install Node.js, which includes npm.";
290
+ const failedState = {
291
+ ...state,
292
+ hostStatus: "failed" as const,
293
+ hostStatusDetail: failure,
294
+ hostStatuses: { local: { status: "failed" as const, detail: failure } },
295
+ devices: [],
296
+ };
297
+ const layerFailed = Layer.mock(DeviceService.DeviceService)({
298
+ state: Effect.succeed(failedState),
299
+ list: Effect.succeed(failedState),
300
+ locateDevice: () => Effect.succeedNone,
301
+ open: () => Effect.die("Must not open a device on a host whose setup failed"),
302
+ });
303
+ return Effect.gen(function* () {
304
+ const server = yield* McpServer.McpServer;
305
+ for (const args of [
306
+ { platform: "android" },
307
+ { deviceId: "Pixel_API_35", hostId: "local" },
308
+ { deviceId: "Pixel_API_35" },
309
+ ]) {
310
+ const result = yield* server
311
+ .callTool({ name: "device_open", arguments: args })
312
+ .pipe(
313
+ Effect.provideService(McpInvocationContext.McpInvocationContext, invocation(["device"])),
314
+ Effect.provideService(McpSchema.McpServerClient, client),
315
+ );
316
+ const text = result.content
317
+ .flatMap((entry) => (entry.type === "text" ? [entry.text] : []))
318
+ .join("\n");
319
+ expect(result.isError).toBe(true);
320
+ expect(text).not.toContain("No android devices were found");
321
+ expect(text).toContain(failure);
322
+ }
323
+ }).pipe(
324
+ Effect.scoped,
325
+ Effect.provide(
326
+ McpHttpServer.layerDeviceToolkit.pipe(
327
+ Layer.provideMerge(McpHttpServer.layerInProcessMcpServer),
328
+ Layer.provideMerge(McpToolAccessTestkit.liveThreadsLayer),
329
+ Layer.provide(layerFailed),
330
+ Layer.provide(layerProjectsMock),
331
+ Layer.provide(
332
+ ServerConfig.layerTest(process.cwd(), { prefix: "t3-mcp-device-toolkit-test-" }),
333
+ ),
334
+ Layer.provide(NodeServices.layer),
335
+ ),
336
+ ),
337
+ );
338
+});
339
+
340
describe("device targeting across hosts", () => {
341
const macHost = {
342
id: "mac-mini",
apps/server/src/mcp/toolkits/device/handlers.ts
+29
-4
@@ -4,6 +4,7 @@ import {
4
type DeviceHostSummary,
5
type DeviceId,
6
type DevicePlatform,
7
+ type DeviceServiceState,
8
type DeviceSummary,
9
DeviceToolUnavailableError,
10
LOCAL_DEVICE_HOST_ID,
@@ -143,9 +144,19 @@ const mapLocateErrors = <A, R>(
144
}),
145
);
146
147
+const failedHosts = <H extends { readonly id: DeviceHostId }>(
148
+ state: { readonly hostStatuses: DeviceServiceState["hostStatuses"] },
149
+ hosts: ReadonlyArray<H>,
150
+) =>
151
+ hosts.flatMap((host) => {
152
+ const status = state.hostStatuses[host.id];
153
+ return status?.status === "failed" && status.detail ? [{ host, detail: status.detail }] : [];
154
+ });
155
+
156
const pickDevice = Effect.fn("handlers.pickDevice")(function* (
157
state: {
158
readonly hosts: ReadonlyArray<DeviceHostSummary>;
159
+ readonly hostStatuses: DeviceServiceState["hostStatuses"];
160
readonly devices: ReadonlyArray<DeviceSummary>;
161
},
162
input: {
@@ -159,8 +170,19 @@ const pickDevice = Effect.fn("handlers.pickDevice")(function* (
170
const devices = yield* DeviceService.DeviceService;
171
const located = yield* devices.locateDevice({ deviceId, hostId }).pipe(mapLocateErrors);
172
if (Option.isSome(located)) return located.value;
173
+ const target =
174
+ hostId === undefined
175
+ ? undefined
176
+ : (state.hosts.find((host) => host.id === hostId) ?? { id: hostId });
177
+ const failures = failedHosts(state, target === undefined ? state.hosts : [target]).map(
178
+ ({ host, detail }) => `${hostName(host)} failed to start: ${detail}`,
179
+ );
180
return yield* new DeviceToolUnavailableError({
163
- reason: `No device ${deviceId} on ${hostId === undefined ? "any host" : hostName(state.hosts.find((host) => host.id === hostId) ?? { id: hostId })}. Call device_list for current ids.`,
181
+ reason: [
182
+ `No device ${deviceId} on ${target === undefined ? "any host" : hostName(target)}.`,
183
+ ...failures,
184
+ "Call device_list for current ids.",
185
+ ].join(" "),
186
});
187
}
188
const hostId = input.hostId ?? LOCAL_DEVICE_HOST_ID;
@@ -170,11 +192,14 @@ const pickDevice = Effect.fn("handlers.pickDevice")(function* (
192
(input.platform === undefined || device.platform === input.platform),
193
);
194
if (candidates.length === 0) {
195
+ const [failure] = failedHosts(state, [{ id: hostId }]);
196
return yield* new DeviceToolUnavailableError({
197
reason:
175
- input.platform === undefined
176
- ? "No simulators or emulators were found. Call device_list to see why."
177
- : `No ${input.platform} devices were found on host ${hostId}. Call device_list to see why.`,
198
+ failure !== undefined
199
+ ? failure.detail
200
+ : input.platform === undefined
201
+ ? "No simulators or emulators were found. Call device_list to see why."
202
+ : `No ${input.platform} devices were found on host ${hostId}. Call device_list to see why.`,
203
});
204
}
205
const platforms = new Set(candidates.map((device) => device.platform));