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

main
ts 230 lines 6.67 KB
Raw
1 import { EnvironmentId, type ExecutionEnvironmentDescriptor } from "@t3tools/contracts";
2 import { RelayEnvironmentEndpointFailure } from "@t3tools/contracts/relay";
3 import * as Schema from "effect/Schema";
4
5 import { MarkedText } from "../errors/translatable.ts";
6
7 const ConnectionTargetBase = {
8 environmentId: EnvironmentId,
9 label: Schema.String,
10 };
11
12 export class PrimaryConnectionTarget extends Schema.TaggedClass<PrimaryConnectionTarget>()(
13 "PrimaryConnectionTarget",
14 {
15 ...ConnectionTargetBase,
16 httpBaseUrl: Schema.String,
17 wsBaseUrl: Schema.String,
18 },
19 ) {}
20
21 export class BearerConnectionTarget extends Schema.TaggedClass<BearerConnectionTarget>()(
22 "BearerConnectionTarget",
23 {
24 ...ConnectionTargetBase,
25 connectionId: Schema.String,
26 },
27 ) {}
28
29 export class RelayConnectionTarget extends Schema.TaggedClass<RelayConnectionTarget>()(
30 "RelayConnectionTarget",
31 {
32 ...ConnectionTargetBase,
33 },
34 ) {}
35
36 export class SshConnectionTarget extends Schema.TaggedClass<SshConnectionTarget>()(
37 "SshConnectionTarget",
38 {
39 ...ConnectionTargetBase,
40 connectionId: Schema.String,
41 },
42 ) {}
43
44 export const ConnectionTarget = Schema.Union([
45 PrimaryConnectionTarget,
46 BearerConnectionTarget,
47 RelayConnectionTarget,
48 SshConnectionTarget,
49 ]);
50 export type ConnectionTarget = typeof ConnectionTarget.Type;
51
52 export const PersistedConnectionTarget = Schema.Union([
53 BearerConnectionTarget,
54 RelayConnectionTarget,
55 SshConnectionTarget,
56 ]);
57 export type PersistedConnectionTarget = typeof PersistedConnectionTarget.Type;
58
59 export type NetworkStatus = "unknown" | "offline" | "online";
60
61 export const ConnectionTransientReason = Schema.Literals([
62 "network",
63 "timeout",
64 "transport",
65 "endpoint-unavailable",
66 "relay-unavailable",
67 "remote-unavailable",
68 "session-pending",
69 "approval-pending",
70 ]);
71 export type ConnectionTransientReason = typeof ConnectionTransientReason.Type;
72
73 export const ConnectionBlockedReason = Schema.Literals([
74 "authentication",
75 "configuration",
76 "permission",
77 "unsupported",
78 ]);
79 export type ConnectionBlockedReason = typeof ConnectionBlockedReason.Type;
80
81 /** A part of the path to an environment: this device, T3 Connect, the host's tunnel, or T3 Code on the host. */
82 export const ConnectionHop = Schema.Literals(["device", "relay", "tunnel", "server"]);
83 export type ConnectionHop = typeof ConnectionHop.Type;
84
85 /** The relay's endpoint failures plus the causes the client can name from other errors. */
86 export const ConnectionFailureCause = Schema.Literals([
87 ...RelayEnvironmentEndpointFailure.literals,
88 "clock_skew",
89 "not_linked",
90 "relay_error",
91 "tunnel_pending",
92 "tunnel_not_enabled",
93 "approval_pending",
94 ]);
95 export type ConnectionFailureCause = typeof ConnectionFailureCause.Type;
96
97 /**
98 * Where and why a failure happened, when the code that saw it knows. See
99 * `presentConnectionDiagnosis`. `via` names the route when the hop alone does
100 * not: T3 Code on the host can fail behind the tunnel or on a direct route.
101 */
102 const ConnectionFailureFields = {
103 hop: Schema.optionalKey(ConnectionHop),
104 via: Schema.optionalKey(Schema.Literals(["relay", "direct"])),
105 failureCause: Schema.optionalKey(ConnectionFailureCause),
106 httpStatus: Schema.optionalKey(Schema.Number),
107 };
108
109 export class ConnectionTransientError extends Schema.TaggedError<ConnectionTransientError>()(
110 "ConnectionTransientError",
111 {
112 reason: ConnectionTransientReason,
113 detail: Schema.String,
114 i18nMessage: Schema.optionalKey(MarkedText),
115 traceId: Schema.optionalKey(Schema.String),
116 /** The code this device shows while the host decides whether to trust it. */
117 verificationCode: Schema.optionalKey(Schema.String),
118 ...ConnectionFailureFields,
119 },
120 ) {
121 override get message(): string {
122 return this.detail;
123 }
124 }
125
126 export class ConnectionBlockedError extends Schema.TaggedError<ConnectionBlockedError>()(
127 "ConnectionBlockedError",
128 {
129 reason: ConnectionBlockedReason,
130 detail: Schema.String,
131 i18nMessage: Schema.optionalKey(MarkedText),
132 traceId: Schema.optionalKey(Schema.String),
133 ...ConnectionFailureFields,
134
135 serverUpdateRequired: Schema.optionalKey(Schema.Boolean),
136 },
137 ) {
138 override get message(): string {
139 return this.detail;
140 }
141 }
142
143 export type ConnectionAttemptError = ConnectionTransientError | ConnectionBlockedError;
144
145 export const DPOP_ACCESS_TOKEN_REFRESH_SKEW_MS = 60_000;
146
147 export type PreparedHttpAuthorization =
148 | {
149 readonly _tag: "Bearer";
150 readonly token: string;
151 }
152 | {
153 readonly _tag: "Dpop";
154 readonly accessToken: string;
155 readonly expiresAtEpochMs: number;
156 /** Set when the token renews directly with the host instead of through T3 Connect. */
157 readonly directConnection?: DirectDpopConnection;
158 };
159
160 export interface DirectDpopConnection {
161 /** The credential store key. */
162 readonly connectionId: string;
163 readonly httpBaseUrl: string;
164 }
165
166 export interface PreparedConnection {
167 readonly environmentId: EnvironmentId;
168 readonly label: string;
169 readonly httpBaseUrl: string;
170 readonly socketUrl: string;
171 readonly httpAuthorization: PreparedHttpAuthorization | null;
172 readonly target: ConnectionTarget;
173 /** What the server said about itself while this connection was prepared. */
174 readonly descriptor?: ExecutionEnvironmentDescriptor;
175 }
176
177 export type SupervisorConnectionPhase =
178 | "available"
179 | "offline"
180 | "connecting"
181 | "backoff"
182 | "connected"
183 | "blocked";
184
185 export type ConnectionAttemptStage = "preparing" | "opening" | "synchronizing";
186
187 export interface SupervisorConnectionState {
188 readonly desired: boolean;
189 readonly network: NetworkStatus;
190 readonly phase: SupervisorConnectionPhase;
191 readonly stage: ConnectionAttemptStage | null;
192 readonly attempt: number;
193 readonly generation: number;
194 readonly lastFailure: ConnectionAttemptError | null;
195 readonly retryAt: number | null;
196 /** While connected: saved routes whose host refused this device's credential on the way. */
197 readonly refusedRouteIds: ReadonlyArray<string>;
198 }
199
200 export const NO_REFUSED_ROUTES: ReadonlyArray<string> = Object.freeze([]);
201
202 export type ConnectionProjectionPhase = "disconnected" | "synchronizing" | "ready";
203
204 export function connectionProjectionPhase(
205 state: SupervisorConnectionState,
206 ): ConnectionProjectionPhase {
207 switch (state.phase) {
208 case "connecting":
209 return "synchronizing";
210 case "connected":
211 return "ready";
212 case "available":
213 case "offline":
214 case "backoff":
215 case "blocked":
216 return "disconnected";
217 }
218 }
219
220 export const AVAILABLE_CONNECTION_STATE: SupervisorConnectionState = Object.freeze({
221 desired: false,
222 network: "unknown",
223 phase: "available",
224 stage: null,
225 attempt: 0,
226 generation: 0,
227 lastFailure: null,
228 retryAt: null,
229 refusedRouteIds: NO_REFUSED_ROUTES,
230 });