The best way to control Claude Code, Codex and more from any computer or phone

main
ts 463 lines 16.2 KB
Raw
1 import {
2 t3ConnectTroubleshootingUrl,
3 type T3ConnectTroubleshootingSection,
4 } from "@t3tools/contracts";
5 import type { RelayEnvironmentStatusResponse } from "@t3tools/contracts/relay";
6 import * as DateTime from "effect/DateTime";
7
8 import type {
9 ConnectionAttemptError,
10 ConnectionFailureCause,
11 ConnectionHop,
12 SupervisorConnectionState,
13 } from "./model.ts";
14 import { mFallback, msg } from "gt-i18n";
15 import type { MFunctionType } from "gt-i18n/types";
16
17 export type ConnectionHopResult = "ok" | "failed" | "unchecked";
18
19 export interface ConnectionDiagnosisHop {
20 readonly hop: ConnectionHop;
21 readonly label: string;
22 readonly result: ConnectionHopResult;
23 }
24
25 export interface ConnectionDiagnosis {
26 /** Names the part that failed, e.g. "Mac mini's tunnel is offline". */
27 readonly headline: string;
28 readonly hops: ReadonlyArray<ConnectionDiagnosisHop>;
29 readonly steps: ReadonlyArray<string>;
30 readonly facts: ReadonlyArray<readonly [label: string, value: string]>;
31 /** The troubleshooting guide section for this failure. Null for direct routes, except a pending T3 Connect sign-in. */
32 readonly moreInfoUrl: string | null;
33 }
34
35 export interface ConnectionDiagnosisInput {
36 readonly hostLabel: string;
37 readonly state: SupervisorConnectionState;
38 /** The environment's usual route, used when the failure does not name one. */
39 readonly via: "relay" | "direct";
40 /** The relay's last health check, which can name a cause before any connect attempt. */
41 readonly relayStatus?: Pick<
42 RelayEnvironmentStatusResponse,
43 "status" | "endpointFailure" | "endpointStatus" | "offlineReason"
44 > | null;
45 readonly clientVersion?: string | undefined;
46 readonly serverVersion?: string | null | undefined;
47 }
48
49 interface Located {
50 readonly hop: ConnectionHop;
51 readonly cause:
52 | ConnectionFailureCause
53 | "offline"
54 | "outdated"
55 | "released"
56 | "session_pending"
57 | null;
58 /** The failure named no hop, so the hops before this one were never probed. */
59 readonly guessed?: true;
60 }
61
62 const NOT_ANSWERING: ReadonlySet<ConnectionFailureCause> = new Set([
63 "origin_unreachable",
64 "invalid_response",
65 ]);
66
67 function locate(input: ConnectionDiagnosisInput): Located | null {
68 const failure = input.state.lastFailure;
69 if (input.state.network === "offline" || input.state.phase === "offline") {
70 return { hop: "device", cause: "offline" };
71 }
72 if (failure?._tag === "ConnectionBlockedError" && failure.serverUpdateRequired) {
73 return { hop: "server", cause: "outdated" };
74 }
75 if (failure?.reason === "session-pending") {
76 return { hop: "device", cause: "session_pending" };
77 }
78 if (failure?.hop !== undefined) {
79 return { hop: failure.hop, cause: failure.failureCause ?? null };
80 }
81 if (failure !== null) {
82 const unreachable =
83 failure.reason === "network" ||
84 failure.reason === "timeout" ||
85 failure.reason === "transport";
86 const via = failure.via ?? input.via;
87 return {
88 hop: unreachable && via === "relay" ? "tunnel" : "server",
89 cause: null,
90 guessed: true,
91 };
92 }
93 const status = input.relayStatus;
94 if (status?.status !== "offline") return null;
95 if (status.offlineReason === "tunnel_released") return { hop: "tunnel", cause: "released" };
96 const cause = status.endpointFailure ?? null;
97 return { hop: cause !== null && NOT_ANSWERING.has(cause) ? "server" : "tunnel", cause };
98 }
99
100 function headline(
101 host: string,
102 located: Located,
103 failure: ConnectionAttemptError | null,
104 resolve: MFunctionType,
105 ): string {
106 switch (located.cause) {
107 case "offline":
108 return resolve(msg("This device is offline"));
109 case "session_pending":
110 return resolve(msg("This device is still loading its T3 Connect sign-in"));
111 case "approval_pending":
112 return resolve(msg("{host} is waiting for someone to approve this device", { host }));
113 case "outdated":
114 return resolve(msg("{host} runs an older T3 Code", { host }));
115 case "clock_skew":
116 return resolve(msg("This device's clock is off"));
117 case "not_linked":
118 return resolve(msg("{host} is not linked to your T3 Connect account", { host }));
119 case "relay_error":
120 return resolve(msg("T3 Connect returned an error"));
121 case "tunnel_pending":
122 return resolve(msg("{host}'s tunnel is still being set up", { host }));
123 case "tunnel_not_enabled":
124 return resolve(msg("T3 Connect is not turned on for {host}", { host }));
125 case "released":
126 case "tunnel_down":
127 return resolve(msg("{host}'s tunnel is offline", { host }));
128 case "origin_unreachable":
129 return resolve(msg("Tunnel works, but T3 Code on {host} did not answer", { host }));
130 case "invalid_response":
131 return resolve(msg("T3 Code on {host} sent an unexpected answer", { host }));
132 case "dns":
133 return resolve(msg("{host}'s tunnel address did not resolve", { host }));
134 case "tls":
135 return resolve(msg("Secure connection to {host}'s tunnel failed", { host }));
136 case "refused":
137 return resolve(msg("{host}'s tunnel refused the connection", { host }));
138 case "timeout":
139 return resolve(msg("{host} did not answer in time", { host }));
140 case "unknown":
141 case null:
142 break;
143 }
144 switch (located.hop) {
145 case "device":
146 return resolve(msg("This device could not prepare the connection"));
147 case "relay":
148 return failure?.reason === "authentication"
149 ? resolve(msg("T3 Connect did not accept this device's sign-in"))
150 : resolve(msg("This device can't reach T3 Connect"));
151 case "tunnel":
152 // The relay already reached the host when this device fails on its own.
153 return failure?.reason === "network" ||
154 failure?.reason === "transport" ||
155 failure?.reason === "timeout"
156 ? resolve(msg("This device can't reach {host}'s tunnel", { host }))
157 : resolve(msg("T3 Connect could not reach {host}'s tunnel", { host }));
158 case "server":
159 return failure?.reason === "authentication" || failure?.reason === "permission"
160 ? resolve(msg("T3 Code on {host} did not accept this device", { host }))
161 : resolve(msg("T3 Code on {host} did not answer", { host }));
162 }
163 }
164
165 function steps(
166 host: string,
167 located: Located,
168 failure: ConnectionAttemptError | null,
169 resolve: MFunctionType,
170 ): string[] {
171 const checkHost = resolve(
172 msg("On {host}, check Settings > Sharing & access or run `t3 connect status`.", { host }),
173 );
174 switch (located.cause) {
175 case "offline":
176 return [resolve(msg("Connect this device to the internet. T3 Code reconnects on its own."))];
177 case "session_pending":
178 return [
179 resolve(msg("Wait a moment. T3 Code retries on its own.")),
180 resolve(msg("If it keeps waiting, reload or restart T3 Code on this device.")),
181 ];
182 case "approval_pending": {
183 const code =
184 failure?._tag === "ConnectionTransientError" ? failure.verificationCode : undefined;
185 return [
186 code
187 ? resolve(
188 msg(
189 "On a device already connected to {host}, open Settings > Sharing & access and approve the device showing {code}.",
190 { host, code },
191 ),
192 )
193 : resolve(
194 msg(
195 "On a device already connected to {host}, open Settings > Sharing & access and approve this device.",
196 { host },
197 ),
198 ),
199 resolve(
200 msg("Or run `t3 auth connect-device approve {code}` on {host}.", {
201 code: code ?? "<code>",
202 host,
203 }),
204 ),
205 ];
206 }
207 case "outdated":
208 return [resolve(msg("Update T3 Code on {host}.", { host }))];
209 case "clock_skew":
210 return [
211 resolve(
212 msg("Turn on automatic date and time on this device and on {host}, then retry.", {
213 host,
214 }),
215 ),
216 ];
217 case "not_linked":
218 return [
219 resolve(
220 msg("Check that this device is signed in to the same T3 Connect account as the host."),
221 ),
222 resolve(
223 msg("On {host}, open Settings > Sharing & access and turn T3 Connect on.", { host }),
224 ),
225 ];
226 case "tunnel_pending":
227 return [resolve(msg("Wait a minute. T3 Code retries on its own.")), checkHost];
228 case "relay_error":
229 return [
230 resolve(msg("Wait a few minutes. T3 Code retries on its own.")),
231 resolve(msg("If it keeps failing, copy the diagnostics and report it.")),
232 ];
233 case "tunnel_not_enabled":
234 return [
235 resolve(
236 msg("On {host}, open Settings > Sharing & access and turn T3 Connect on.", { host }),
237 ),
238 ];
239 case "released":
240 case "tunnel_down":
241 return [
242 resolve(msg("Make sure {host} is awake and T3 Code is running on it.", { host })),
243 checkHost,
244 resolve(
245 msg(
246 "A VPN or Tailscale exit node on {host} can block the tunnel (port 7844). Turn it off or allow the tunnel.",
247 { host },
248 ),
249 ),
250 ];
251 case "origin_unreachable":
252 case "invalid_response":
253 return [resolve(msg("Open or restart T3 Code on {host}.", { host })), checkHost];
254 // The relay saw these on its way to the host, so the fix is on the host.
255 case "dns":
256 case "tls":
257 case "refused":
258 case "timeout":
259 case "unknown":
260 return [resolve(msg("Make sure {host} is awake and online.", { host })), checkHost];
261 case null:
262 break;
263 }
264 switch (located.hop) {
265 case "device":
266 return [
267 resolve(msg("Restart T3 Code on this device.")),
268 resolve(
269 msg("If it keeps failing, remove {host} from this device and add it again.", { host }),
270 ),
271 ];
272 case "relay":
273 return failure?.reason === "authentication"
274 ? [resolve(msg("Sign out of T3 Connect and sign in again."))]
275 : [
276 resolve(msg("Check this device's internet connection.")),
277 resolve(msg("A VPN, firewall, or ad blocker on this device can block T3 Connect.")),
278 ];
279 case "tunnel":
280 return failure?.reason === "network" ||
281 failure?.reason === "transport" ||
282 failure?.reason === "timeout"
283 ? [
284 resolve(msg("A VPN, firewall, or DNS filter on this device can block the tunnel.")),
285 resolve(msg("Try another network, or add a direct route such as a Tailscale address.")),
286 ]
287 : [resolve(msg("Make sure {host} is awake and online.", { host })), checkHost];
288 case "server":
289 return failure?.reason === "authentication"
290 ? [
291 resolve(
292 msg(
293 "This device's sign-in to {host} expired or was revoked. Pair it again with a new pairing link from {host}.",
294 { host },
295 ),
296 ),
297 ]
298 : [
299 resolve(msg("Make sure T3 Code is running on {host}.", { host })),
300 resolve(msg("Retry. If it keeps failing, copy the diagnostics.")),
301 ];
302 }
303 }
304
305 function helpSection(
306 located: Located,
307 failure: ConnectionAttemptError | null,
308 ): T3ConnectTroubleshootingSection {
309 switch (located.cause) {
310 case "offline":
311 return "this-device-cant-reach-t3-connect";
312 case "outdated":
313 return "the-host-runs-an-older-t3-code";
314 case "clock_skew":
315 return "the-clock-is-off";
316 case "session_pending":
317 case "approval_pending":
318 case "not_linked":
319 case "tunnel_not_enabled":
320 return "sign-in-account-or-link-problems";
321 case "relay_error":
322 return "t3-connect-returned-an-error";
323 case "released":
324 case "tunnel_down":
325 case "tunnel_pending":
326 return "the-hosts-tunnel-is-offline";
327 case "origin_unreachable":
328 case "invalid_response":
329 return "the-tunnel-works-but-t3-code-does-not-answer";
330 case "dns":
331 case "tls":
332 case "refused":
333 case "timeout":
334 case "unknown":
335 return "the-t3-connect-address-does-not-resolve-or-answer";
336 case null:
337 break;
338 }
339 const onThisDevice =
340 failure?.reason === "network" ||
341 failure?.reason === "transport" ||
342 failure?.reason === "timeout";
343 switch (located.hop) {
344 case "device":
345 return "this-device-cant-reach-t3-connect";
346 case "relay":
347 return failure?.reason === "authentication"
348 ? "sign-in-account-or-link-problems"
349 : "this-device-cant-reach-t3-connect";
350 case "tunnel":
351 return onThisDevice ? "this-device-cant-reach-t3-connect" : "the-hosts-tunnel-is-offline";
352 case "server":
353 return failure?.reason === "authentication" || failure?.reason === "permission"
354 ? "sign-in-account-or-link-problems"
355 : "the-tunnel-works-but-t3-code-does-not-answer";
356 }
357 }
358
359 const T3_CONNECT_NAME = "T3 Connect";
360
361 const HOP_ORDER = {
362 relay: ["device", "relay", "tunnel", "server"],
363 direct: ["device", "server"],
364 } as const;
365
366 function hopLabel(hop: ConnectionHop, host: string, resolve: MFunctionType): string {
367 switch (hop) {
368 case "device":
369 return resolve(msg("This device"));
370 case "relay":
371 return T3_CONNECT_NAME;
372 case "tunnel":
373 return resolve(msg("{host} tunnel", { host }));
374 case "server":
375 return resolve(msg("T3 Code on {host}", { host }));
376 }
377 }
378
379 /**
380 * Turns a connection state into what failed, in order, and what to try. Returns
381 * null when nothing has failed. Web and mobile render this same model.
382 */
383 export function presentConnectionDiagnosis(
384 input: ConnectionDiagnosisInput,
385 resolve: MFunctionType = mFallback,
386 ): ConnectionDiagnosis | null {
387 const located = locate(input);
388 if (located === null) return null;
389 const host = input.hostLabel;
390 const failure = input.state.lastFailure;
391 const relayPath =
392 located.hop === "relay" ||
393 located.hop === "tunnel" ||
394 (failure === null && input.relayStatus?.status === "offline") ||
395 (failure?.via ?? input.via) === "relay";
396 const order: ReadonlyArray<ConnectionHop> = HOP_ORDER[relayPath ? "relay" : "direct"];
397 const failedIndex = order.indexOf(located.hop);
398 const hops = order.map((hop, index): ConnectionDiagnosisHop => ({
399 hop,
400 label: hopLabel(hop, host, resolve),
401 result:
402 index === failedIndex
403 ? "failed"
404 : index < failedIndex && located.guessed !== true
405 ? "ok"
406 : "unchecked",
407 }));
408
409 // The relay health check only explains the state when no attempt has failed yet.
410 const httpStatus = failure !== null ? failure.httpStatus : input.relayStatus?.endpointStatus;
411 const facts: Array<readonly [string, string]> = [];
412 const add = (label: string, value: string | number | null | undefined) => {
413 if (value !== null && value !== undefined && value !== "") facts.push([label, String(value)]);
414 };
415 add(
416 resolve(msg("Cause", { $context: "diagnostics field label" })),
417 located.cause ?? failure?.reason,
418 );
419 add(resolve(msg("HTTP status")), httpStatus);
420 add(
421 resolve(msg("Attempts", { $context: "diagnostics field label" })),
422 input.state.attempt > 0 ? input.state.attempt : null,
423 );
424 add(
425 resolve(msg("Next retry")),
426 input.state.retryAt === null
427 ? null
428 : DateTime.formatIso(DateTime.makeUnsafe(input.state.retryAt)),
429 );
430 add(
431 resolve(msg("Route", { $context: "diagnostics field label" })),
432 relayPath ? "T3 Connect" : resolve(msg("Direct", { $context: "connection route" })),
433 );
434 add(resolve(msg("App version")), input.clientVersion);
435 add(resolve(msg("Host version")), input.serverVersion);
436 add(resolve(msg("Error", { $context: "diagnostics field label" })), failure?.detail);
437 add(resolve(msg("Trace ID")), failure?.traceId);
438
439 return {
440 headline: headline(host, located, failure, resolve),
441 hops,
442 steps: steps(host, located, failure, resolve),
443 facts,
444 moreInfoUrl:
445 relayPath || located.cause === "session_pending"
446 ? t3ConnectTroubleshootingUrl(helpSection(located, failure))
447 : null,
448 };
449 }
450
451 const HOP_MARK = { ok: "ok", failed: "FAILED", unchecked: "not checked" } as const;
452
453 /** One plain-text block for bug reports. */
454 export function connectionDiagnosisText(hostLabel: string, diagnosis: ConnectionDiagnosis): string {
455 return [
456 `T3 Code connection to ${hostLabel}: ${diagnosis.headline}`,
457 "",
458 ...diagnosis.hops.map((hop) => `${hop.label}: ${HOP_MARK[hop.result]}`),
459 "",
460 ...diagnosis.facts.map(([label, value]) => `${label}: ${value}`),
461 ...(diagnosis.moreInfoUrl ? ["", `More info: ${diagnosis.moreInfoUrl}`] : []),
462 ].join("\n");
463 }