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

main
ts 487 lines 17.2 KB
Raw
1 import { EnvironmentId, type ServerConfig, ThreadId, TurnItemId } from "@t3tools/contracts";
2 import type { RelayEnvironmentStatusResponse } from "@t3tools/contracts/relay";
3 import * as Option from "effect/Option";
4 import { describe, expect, it } from "vite-plus/test";
5
6 import { BearerConnectionProfile } from "./connection/catalog.ts";
7 import { BearerConnectionTarget, RelayConnectionTarget } from "./connection/model.ts";
8 import type { EnvironmentPresentation } from "./connection/presentation.ts";
9 import type { RelayDiscoveredEnvironment } from "./relay/discovery.ts";
10 import {
11 ANOTHER_ADDRESS,
12 linkableMachines,
13 linkedEnvironmentNames,
14 linkRequestAnswerInput,
15 linkRequestDisplay,
16 linkRequestFailureMessage,
17 linkRequestInitialMachine,
18 linkRequestTarget,
19 linkRequestTargetName,
20 rankMachinesByHint,
21 } from "./linkRequest.ts";
22
23 const item = {
24 id: TurnItemId.make("turn-item:link-request:1"),
25 threadId: ThreadId.make("thread-1"),
26 };
27 const asked = { url: "https://box.example.ts.net", label: "Box" };
28 const accessLabel = (access: string) => `<${access}>`;
29
30 describe("linkRequestDisplay", () => {
31 it("names the environment linked and the access the user chose", () => {
32 expect(
33 linkRequestDisplay(
34 { ...asked, linkStatus: "linked", linkedLabel: "Box", linkedAccess: "auto" },
35 "local",
36 accessLabel,
37 ),
38 ).toEqual({ kind: "answered", outcome: "linked", label: "Linked Box · <auto>" });
39 });
40
41 it("shows why a link failed, and never offers the actions outside the asking thread", () => {
42 expect(
43 linkRequestDisplay(
44 { ...asked, linkStatus: "failed", failure: "Pairing code expired." },
45 "local",
46 accessLabel,
47 ),
48 ).toMatchObject({ outcome: "failed", label: "Could not link: Pairing code expired." });
49 expect(
50 linkRequestDisplay({ ...asked, linkStatus: "pending" }, "inherited", accessLabel),
51 ).toMatchObject({ kind: "pending-elsewhere" });
52 });
53 });
54
55 describe("linkRequestAnswerInput", () => {
56 const vps = {
57 environmentId: EnvironmentId.make("environment-vps"),
58 label: "VPS",
59 urls: ["https://vps.ts.net", "http://10.0.0.2:3773"],
60 };
61
62 it("answers with the machine picked and every address known for it", () => {
63 expect(
64 linkRequestAnswerInput(item, {
65 type: "link",
66 target: vps,
67 access: "auto",
68 pairingCode: " abc ",
69 }),
70 ).toEqual({
71 threadId: item.threadId,
72 turnItemId: item.id,
73 answer: { type: "link", ...vps, access: "auto", pairingCode: "abc" },
74 });
75 expect(
76 linkRequestAnswerInput(item, {
77 type: "link",
78 target: { url: " https://box.ts.net " },
79 access: "auto",
80 pairingCode: "abc",
81 }),
82 ).toMatchObject({ answer: { urls: ["https://box.ts.net"] } });
83 });
84
85 it("refuses a blank code, a blank address, or a machine with no address", () => {
86 const blank = (target: Parameters<typeof linkRequestAnswerInput>[1] & { type: "link" }) =>
87 linkRequestAnswerInput(item, target);
88 expect(blank({ type: "link", target: vps, access: "auto", pairingCode: " " })).toBeNull();
89 expect(
90 blank({ type: "link", target: { url: " " }, access: "auto", pairingCode: "abc" }),
91 ).toBeNull();
92 expect(
93 blank({ type: "link", target: { ...vps, urls: [] }, access: "auto", pairingCode: "abc" }),
94 ).toBeNull();
95 });
96 });
97
98 const presentation = (
99 id: string,
100 label: string,
101 options: {
102 readonly saved?: ReadonlyArray<string>;
103 readonly reported?: ReadonlyArray<string>;
104 readonly connected?: boolean;
105 } = {},
106 ): EnvironmentPresentation & { readonly environmentId: EnvironmentId } => {
107 const environmentId = EnvironmentId.make(id);
108 const [first, ...rest] = (options.saved ?? []).map((httpBaseUrl, index) => {
109 const connectionId = `${id}-${index}`;
110 return {
111 target: new BearerConnectionTarget({ environmentId, label, connectionId }),
112 profile: Option.some(
113 new BearerConnectionProfile({
114 connectionId,
115 environmentId,
116 label,
117 httpBaseUrl,
118 wsBaseUrl: httpBaseUrl,
119 }),
120 ),
121 };
122 });
123 return {
124 environmentId,
125 entry: {
126 ...(first ?? {
127 target: new RelayConnectionTarget({ environmentId, label }),
128 profile: Option.none(),
129 }),
130 ...(rest.length === 0 ? {} : { alternateRoutes: rest }),
131 enabled: true,
132 },
133 connection: {
134 phase: options.connected === false ? "offline" : "connected",
135 error: null,
136 traceId: null,
137 },
138 serverConfig:
139 options.reported === undefined
140 ? null
141 : ({
142 environment: { platform: { machine: "laptop" } },
143 directEndpoints: options.reported.map((httpBaseUrl) => ({
144 kind: "tailnet",
145 httpBaseUrl,
146 })),
147 } as unknown as ServerConfig),
148 refusedRouteIds: [],
149 };
150 };
151
152 const discovered = (
153 id: string,
154 label: string,
155 machine?: "mac-mini",
156 ): RelayDiscoveredEnvironment => ({
157 environment: {
158 environmentId: EnvironmentId.make(id),
159 label,
160 endpoint: {
161 httpBaseUrl: `https://${id}.t3.example`,
162 wsBaseUrl: `wss://${id}.t3.example`,
163 providerKind: "cloudflare_tunnel",
164 },
165 linkedAt: "2026-10-01T00:00:00.000Z",
166 },
167 availability: "online",
168 status:
169 machine === undefined
170 ? Option.none()
171 : Option.some({
172 environmentId: EnvironmentId.make(id),
173 endpoint: {
174 httpBaseUrl: `https://${id}.t3.example`,
175 wsBaseUrl: `wss://${id}.t3.example`,
176 providerKind: "cloudflare_tunnel",
177 },
178 status: "online",
179 checkedAt: "2026-10-01T00:00:00.000Z",
180 descriptor: {
181 environmentId: EnvironmentId.make(id),
182 label,
183 platform: { os: "darwin", arch: "arm64", machine },
184 serverVersion: "1.0.0",
185 capabilities: {},
186 },
187 } as unknown as RelayEnvironmentStatusResponse),
188 error: Option.none(),
189 });
190
191 describe("linkableMachines", () => {
192 it("lists the other machines with reported addresses before saved ones, once each", () => {
193 const here = presentation("environment-here", "Here", { saved: ["http://localhost:3773"] });
194 // A loopback address would name the linking server itself, so it is no address of the VPS.
195 const vps = presentation("environment-vps", "VPS", {
196 saved: ["https://vps.example.com", "https://vps.ts.net", "http://127.0.0.1:3773"],
197 reported: ["https://vps.ts.net", "http://localhost:3773"],
198 });
199 const mini = presentation("environment-mini", "Mini", { connected: false });
200 expect(
201 linkableMachines({
202 environments: [here, vps, mini],
203 threadEnvironmentId: here.environmentId,
204 links: [{ environmentId: mini.environmentId, status: "unreachable" }],
205 connect: new Map(),
206 }),
207 ).toEqual([
208 {
209 environmentId: vps.environmentId,
210 label: "VPS",
211 machine: "laptop",
212 connected: true,
213 connectOnly: false,
214 linked: false,
215 urls: ["https://vps.ts.net", "https://vps.example.com"],
216 },
217 {
218 environmentId: mini.environmentId,
219 label: "Mini",
220 machine: "server",
221 connected: false,
222 connectOnly: false,
223 linked: true,
224 urls: [],
225 },
226 ]);
227 });
228
229 it("reaches a machine saved only over T3 Connect at its Connect address", () => {
230 const here = presentation("environment-here", "Here", { saved: ["http://localhost:3773"] });
231 const box = presentation("environment-box", "Box");
232 const [listed] = linkableMachines({
233 environments: [here, box],
234 threadEnvironmentId: here.environmentId,
235 links: [],
236 connect: new Map([[box.environmentId, discovered(box.environmentId, "Box")]]),
237 });
238 expect(listed?.urls).toEqual(["https://environment-box.t3.example"]);
239 // Until discovery has found it, there is no address to offer.
240 expect(
241 linkableMachines({
242 environments: [here, box],
243 threadEnvironmentId: here.environmentId,
244 links: [],
245 connect: new Map(),
246 })[0]?.urls,
247 ).toEqual([]);
248 });
249
250 it("also offers the Connect address of a machine saved by direct address, last", () => {
251 const here = presentation("environment-here", "Here", { saved: ["http://localhost:3773"] });
252 const vps = presentation("environment-vps", "VPS", {
253 saved: ["http://192.168.1.20:3773"],
254 reported: ["https://vps.ts.net"],
255 });
256 const [listed] = linkableMachines({
257 environments: [here, vps],
258 threadEnvironmentId: here.environmentId,
259 links: [],
260 connect: new Map([[vps.environmentId, discovered(vps.environmentId, "VPS")]]),
261 });
262 expect(listed?.urls).toEqual([
263 "https://vps.ts.net",
264 "http://192.168.1.20:3773",
265 "https://environment-vps.t3.example",
266 ]);
267 });
268
269 it("no longer counts a machine as linked once its link expired", () => {
270 const here = presentation("environment-here", "Here", { saved: ["http://localhost:3773"] });
271 const vps = presentation("environment-vps", "VPS", { saved: ["https://vps.ts.net"] });
272 const mini = presentation("environment-mini", "Mini", { saved: ["http://mini.local:3773"] });
273 const listed = linkableMachines({
274 environments: [here, vps, mini],
275 threadEnvironmentId: here.environmentId,
276 links: [
277 { environmentId: vps.environmentId, status: "expired" },
278 { environmentId: mini.environmentId, status: "unreachable" },
279 { environmentId: EnvironmentId.make("environment-old"), status: "expired" },
280 ],
281 connect: new Map([["environment-old", discovered("environment-old", "Old box")]]),
282 });
283 expect(listed.map((machine) => [machine.label, machine.linked])).toEqual([
284 ["VPS", false],
285 ["Mini", true],
286 ["Old box", false],
287 ]);
288 });
289
290 it("offers machines only on T3 Connect after the saved ones, at their Connect address", () => {
291 const here = presentation("environment-here", "Here", { saved: ["http://localhost:3773"] });
292 const vps = presentation("environment-vps", "VPS", { saved: ["https://vps.ts.net"] });
293 const listed = linkableMachines({
294 environments: [here, vps],
295 threadEnvironmentId: here.environmentId,
296 links: [{ environmentId: EnvironmentId.make("environment-old"), status: "reachable" }],
297 connect: new Map([
298 // This environment and saved machines are listed once, as saved.
299 [here.environmentId, discovered(here.environmentId, "Here")],
300 [vps.environmentId, discovered(vps.environmentId, "VPS")],
301 ["environment-mini", discovered("environment-mini", "Mac mini", "mac-mini")],
302 ["environment-old", discovered("environment-old", "Old box")],
303 ]),
304 });
305 expect(listed.map((machine) => [machine.label, machine.connectOnly])).toEqual([
306 ["VPS", false],
307 ["Mac mini", true],
308 ["Old box", true],
309 ]);
310 expect(listed[1]).toEqual({
311 environmentId: EnvironmentId.make("environment-mini"),
312 label: "Mac mini",
313 machine: "mac-mini",
314 connected: false,
315 connectOnly: true,
316 linked: false,
317 urls: ["https://environment-mini.t3.example"],
318 });
319 expect(listed[2]).toMatchObject({ machine: "server", linked: true });
320
321 // A Connect record that publishes only a loopback address gives the machine none.
322 const local = discovered("environment-local", "Local");
323 const published = {
324 ...local,
325 environment: {
326 ...local.environment,
327 endpoint: { ...local.environment.endpoint, httpBaseUrl: "http://127.0.0.1:3773/" },
328 },
329 };
330 expect(
331 linkableMachines({
332 environments: [],
333 threadEnvironmentId: EnvironmentId.make("environment-here"),
334 links: [],
335 connect: new Map([["environment-local", published]]),
336 })[0]?.urls,
337 ).toEqual([]);
338 });
339 });
340
341 describe("linkedEnvironmentNames", () => {
342 it("names the links as this client does, else as the link does", () => {
343 const vps = EnvironmentId.make("environment-vps");
344 const mini = EnvironmentId.make("environment-mini");
345 const unsaved = EnvironmentId.make("environment-unsaved");
346 expect(
347 linkedEnvironmentNames({
348 links: [
349 { environmentId: vps, label: "vps-01" },
350 { environmentId: unsaved, label: "Office box" },
351 ],
352 environments: [
353 { environmentId: vps, label: "Hetzner VPS" },
354 { environmentId: mini, label: "Mac mini" },
355 ],
356 }),
357 ).toEqual(
358 new Map([
359 [vps, "Hetzner VPS"],
360 [unsaved, "Office box"],
361 ]),
362 );
363 });
364 });
365
366 describe("rankMachinesByHint", () => {
367 const machines = [
368 { label: "Old vps box" },
369 { label: "VPS-2" },
370 { label: "Mac mini" },
371 { label: "vps" },
372 ];
373
374 it("puts an exact name first, then a prefix, then a substring, keeping order within each", () => {
375 expect(rankMachinesByHint(machines, " VPS ").map((machine) => machine.label)).toEqual([
376 "vps",
377 "VPS-2",
378 "Old vps box",
379 "Mac mini",
380 ]);
381 expect(rankMachinesByHint(machines, undefined)).toBe(machines);
382 });
383
384 it("preselects the card's machine, or the hint's match, and nothing for a hint that matches none", () => {
385 const listed = [
386 { environmentId: EnvironmentId.make("environment-mini"), label: "Mac mini" },
387 { environmentId: EnvironmentId.make("environment-vps"), label: "Hetzner VPS" },
388 ].map(
389 (machine) =>
390 ({
391 ...machine,
392 machine: "server",
393 connected: true,
394 connectOnly: false,
395 linked: false,
396 urls: [],
397 }) as const,
398 );
399 expect(linkRequestInitialMachine({ hint: "vps" }, listed)).toBe("environment-vps");
400 // Agents pass the user's words, which name the machine among others.
401 expect(linkRequestInitialMachine({ hint: "my mac mini" }, listed)).toBe("environment-mini");
402 expect(linkRequestInitialMachine({ hint: "my mac" }, listed)).toBe("environment-mini");
403 expect(linkRequestInitialMachine({ hint: "the hetzner vps box" }, listed)).toBe(
404 "environment-vps",
405 );
406 expect(linkRequestInitialMachine({ hint: "desk" }, listed)).toBeNull();
407 expect(linkRequestInitialMachine({ hint: "minimal" }, listed)).toBeNull();
408 expect(
409 linkRequestInitialMachine(
410 { environmentId: EnvironmentId.make("environment-x"), hint: "vps" },
411 listed,
412 ),
413 ).toBe("environment-x");
414 });
415 });
416
417 describe("linkRequestTarget", () => {
418 const box = {
419 environmentId: EnvironmentId.make("environment-box"),
420 label: "Box",
421 machine: "server",
422 connected: true,
423 connectOnly: false,
424 linked: false,
425 urls: ["http://10.0.0.2:3773", "https://box.t3connect.example/"],
426 } as const;
427
428 it("takes a machine from an address the agent gave only where this app already reaches it", () => {
429 // Anything can answer at an address as the box, so an id beside one is not trusted.
430 const unfamiliar = {
431 url: "https://other.example",
432 environmentId: box.environmentId,
433 label: "Box",
434 };
435 expect(linkRequestTarget(unfamiliar, [box], null)).toEqual({ kind: "address" });
436 expect(linkRequestTarget(unfamiliar, [box], box.environmentId)).toEqual({ kind: "address" });
437 expect(linkRequestTargetName(unfamiliar)).toBe("https://other.example");
438 // A username in the address must not pass for the host the code goes to.
439 expect(linkRequestTargetName({ url: "https://box.t3connect.example@other.example/x" })).toBe(
440 "https://other.example",
441 );
442 // A known address in another spelling is the box, linked at its own addresses only.
443 expect(
444 linkRequestTarget({ url: "https://BOX.t3connect.example:443/mcp" }, [box], null),
445 ).toEqual({
446 kind: "machine",
447 environmentId: box.environmentId,
448 label: "Box",
449 urls: box.urls,
450 linked: false,
451 });
452 expect(linkRequestTarget({ url: "http://box.t3connect.example" }, [box], null)).toEqual({
453 kind: "address",
454 });
455 expect(linkRequestTarget({ url: "not a url" }, [box], null)).toEqual({ kind: "address" });
456 expect(linkRequestTarget({ url: "blob:https://box.t3connect.example/1" }, [box], null)).toEqual(
457 { kind: "address" },
458 );
459 // A private address two machines share names neither.
460 const mini = { ...box, environmentId: EnvironmentId.make("environment-mini") };
461 expect(linkRequestTarget({ url: "http://10.0.0.2:3773" }, [box, mini], null)).toEqual({
462 kind: "address",
463 });
464 });
465
466 it("links the machine the agent named or the user picked, at the addresses this app has", () => {
467 expect(linkRequestTarget({ environmentId: box.environmentId }, [box], null)).toMatchObject({
468 kind: "machine",
469 label: "Box",
470 urls: box.urls,
471 });
472 expect(linkRequestTarget({}, [box], box.environmentId)).toMatchObject({ kind: "machine" });
473 expect(linkRequestTarget({}, [box], ANOTHER_ADDRESS)).toEqual({ kind: "address" });
474 expect(linkRequestTarget({}, [box], null)).toEqual({ kind: "none" });
475 });
476 });
477
478 describe("linkRequestFailureMessage", () => {
479 it("passes through only known user-facing errors", () => {
480 expect(
481 linkRequestFailureMessage({ _tag: "PeerLinkRequestError", message: "Already answered." }),
482 ).toBe("Already answered.");
483 expect(linkRequestFailureMessage({ _tag: "SchemaError", message: "code=abc" })).toBe(
484 "Could not answer the request. Try again.",
485 );
486 });
487 });