@devries-cameron20 / t3code Mirror · read-only / commits / 1278628870
Fork 0

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));