The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import { ProviderDriverKind, type CodexSettings } from "@t3tools/contracts"; |
| 2 | import * as Effect from "effect/Effect"; |
| 3 | import * as FileSystem from "effect/FileSystem"; |
| 4 | import * as Path from "effect/Path"; |
| 5 | import * as Schema from "effect/Schema"; |
| 6 | import * as PlatformError from "effect/PlatformError"; |
| 7 | |
| 8 | import { expandHomePath } from "@t3tools/provider-core/server/pathExpansion"; |
| 9 | import * as HostProcess from "@t3tools/shared/HostProcess"; |
| 10 | |
| 11 | export interface CodexHomeLayout { |
| 12 | readonly mode: "direct" | "authOverlay"; |
| 13 | readonly sharedHomePath: string; |
| 14 | readonly effectiveHomePath: string | undefined; |
| 15 | readonly continuationKey: string; |
| 16 | } |
| 17 | |
| 18 | const KNOWN_SHARED_DIRECTORIES = [ |
| 19 | "sessions", |
| 20 | "archived_sessions", |
| 21 | "sqlite", |
| 22 | "shell_snapshots", |
| 23 | "worktrees", |
| 24 | "skills", |
| 25 | "plugins", |
| 26 | "cache", |
| 27 | "logs", |
| 28 | "mcp-oauth-locks", |
| 29 | "thread-writer-locks", |
| 30 | ] as const; |
| 31 | |
| 32 | // auth.lock guards the shadow home's private auth.json. |
| 33 | const PRIVATE_ENTRY_NAMES = new Set(["auth.json", "auth.lock", "models_cache.json"]); |
| 34 | // Finder maintains metadata separately for each directory, including shadow homes. |
| 35 | const SHADOW_LOCAL_ENTRY_NAMES = new Set(["log", "memories", "tmp", ".DS_Store"]); |
| 36 | // Shadow homes may create local runtime locks first; replace them with shared links because they guard shared state. |
| 37 | const REPLACEABLE_SHARED_RUNTIME_ENTRIES = new Set([ |
| 38 | "mcp-oauth-locks", |
| 39 | "thread-writer-locks", |
| 40 | ".sqlite-maintenance.lock", |
| 41 | ]); |
| 42 | |
| 43 | function resolveHomePath(path: Path.Path, home: string, value: string | undefined): string { |
| 44 | const expanded = |
| 45 | value && value.trim().length > 0 ? expandHomePath(value, home) : path.join(home, ".codex"); |
| 46 | return path.resolve(expanded); |
| 47 | } |
| 48 | |
| 49 | export const resolveCodexHomeLayout = Effect.fn("resolveCodexHomeLayout")(function* ( |
| 50 | config: CodexSettings, |
| 51 | ): Effect.fn.Return<CodexHomeLayout, never, Path.Path> { |
| 52 | const path = yield* Path.Path; |
| 53 | const home = yield* HostProcess.HomeDirectory; |
| 54 | const sharedHomePath = resolveHomePath(path, home, config.homePath); |
| 55 | const shadowHomePath = config.shadowHomePath.trim(); |
| 56 | if (shadowHomePath.length === 0) { |
| 57 | return { |
| 58 | mode: "direct", |
| 59 | sharedHomePath, |
| 60 | effectiveHomePath: config.homePath.trim().length > 0 ? sharedHomePath : undefined, |
| 61 | continuationKey: `codex:home:${sharedHomePath}`, |
| 62 | }; |
| 63 | } |
| 64 | |
| 65 | const effectiveHomePath = path.resolve(expandHomePath(shadowHomePath, home)); |
| 66 | return { |
| 67 | mode: "authOverlay", |
| 68 | sharedHomePath, |
| 69 | effectiveHomePath, |
| 70 | continuationKey: `codex:home:${sharedHomePath}`, |
| 71 | }; |
| 72 | }); |
| 73 | |
| 74 | // Codex accepts bundled plugins only from this path under CODEX_HOME. The shared |
| 75 | // config names the original home, so shadow homes must override it through their .tmp link. |
| 76 | const BUNDLED_MARKETPLACE = "openai-bundled"; |
| 77 | |
| 78 | const quoteCliArg = (value: string) => `"${value.replace(/["\\$`]/g, "\\$&")}"`; |
| 79 | |
| 80 | export function codexHomeLaunchArgs(path: Path.Path, layout: CodexHomeLayout, launchArgs: string) { |
| 81 | const homePath = layout.effectiveHomePath; |
| 82 | if (layout.mode !== "authOverlay" || homePath === undefined) return launchArgs; |
| 83 | const source = path.join(homePath, ".tmp", "bundled-marketplaces", BUNDLED_MARKETPLACE); |
| 84 | const setting = `marketplaces.${BUNDLED_MARKETPLACE}.source=${JSON.stringify(source)}`; |
| 85 | const override = `-c ${quoteCliArg(setting)}`; |
| 86 | // User launch args come last so an explicit source still wins. |
| 87 | return launchArgs.length > 0 ? `${override} ${launchArgs}` : override; |
| 88 | } |
| 89 | |
| 90 | const CodexShadowHomeContext = { |
| 91 | sharedHomePath: Schema.String, |
| 92 | effectiveHomePath: Schema.String, |
| 93 | }; |
| 94 | |
| 95 | export class CodexShadowHomeFileSystemError extends Schema.TaggedError<CodexShadowHomeFileSystemError>()( |
| 96 | "CodexShadowHomeFileSystemError", |
| 97 | { |
| 98 | ...CodexShadowHomeContext, |
| 99 | operation: Schema.Literals(["readLink", "makeDirectory", "readDirectory", "remove", "symlink"]), |
| 100 | path: Schema.String, |
| 101 | targetPath: Schema.optional(Schema.String), |
| 102 | entryName: Schema.optional(Schema.String), |
| 103 | cause: Schema.Defect(), |
| 104 | }, |
| 105 | ) { |
| 106 | override get message(): string { |
| 107 | const target = this.targetPath === undefined ? "" : ` to '${this.targetPath}'`; |
| 108 | return `Codex shadow home filesystem operation '${this.operation}' failed for '${this.path}'${target}.`; |
| 109 | } |
| 110 | } |
| 111 | |
| 112 | export class CodexShadowHomePathConflictError extends Schema.TaggedError<CodexShadowHomePathConflictError>()( |
| 113 | "CodexShadowHomePathConflictError", |
| 114 | CodexShadowHomeContext, |
| 115 | ) { |
| 116 | override get message(): string { |
| 117 | return `Codex shadow home path '${this.effectiveHomePath}' must be different from the shared home path '${this.sharedHomePath}'.`; |
| 118 | } |
| 119 | } |
| 120 | |
| 121 | export class CodexShadowHomeEntryConflictError extends Schema.TaggedError<CodexShadowHomeEntryConflictError>()( |
| 122 | "CodexShadowHomeEntryConflictError", |
| 123 | { |
| 124 | ...CodexShadowHomeContext, |
| 125 | entryName: Schema.String, |
| 126 | linkPath: Schema.String, |
| 127 | targetPath: Schema.String, |
| 128 | }, |
| 129 | ) { |
| 130 | override get message(): string { |
| 131 | return `Cannot create Codex shadow home entry '${this.entryName}' because '${this.linkPath}' already exists and is not a symlink.`; |
| 132 | } |
| 133 | } |
| 134 | |
| 135 | export class CodexShadowHomePrivateEntrySymlinkError extends Schema.TaggedError<CodexShadowHomePrivateEntrySymlinkError>()( |
| 136 | "CodexShadowHomePrivateEntrySymlinkError", |
| 137 | { |
| 138 | ...CodexShadowHomeContext, |
| 139 | entryName: Schema.String, |
| 140 | path: Schema.String, |
| 141 | }, |
| 142 | ) { |
| 143 | override get message(): string { |
| 144 | return `Codex shadow home private entry '${this.entryName}' at '${this.path}' must be a real file, not a symlink.`; |
| 145 | } |
| 146 | } |
| 147 | |
| 148 | export const CodexShadowHomeError = Schema.Union([ |
| 149 | CodexShadowHomeFileSystemError, |
| 150 | CodexShadowHomePathConflictError, |
| 151 | CodexShadowHomeEntryConflictError, |
| 152 | CodexShadowHomePrivateEntrySymlinkError, |
| 153 | ]); |
| 154 | export type CodexShadowHomeError = typeof CodexShadowHomeError.Type; |
| 155 | |
| 156 | type LinkState = |
| 157 | | { |
| 158 | readonly _tag: "Missing"; |
| 159 | } |
| 160 | | { |
| 161 | readonly _tag: "NotSymlink"; |
| 162 | } |
| 163 | | { |
| 164 | readonly _tag: "Symlink"; |
| 165 | readonly target: string; |
| 166 | }; |
| 167 | |
| 168 | function isNotSymlinkError(error: PlatformError.PlatformError): boolean { |
| 169 | const cause = error.reason.cause; |
| 170 | return ( |
| 171 | error.reason._tag === "Unknown" && |
| 172 | typeof cause === "object" && |
| 173 | cause !== null && |
| 174 | "code" in cause && |
| 175 | cause.code === "EINVAL" |
| 176 | ); |
| 177 | } |
| 178 | |
| 179 | const readLinkState = Effect.fn("CodexHomeLayout.readLinkState")(function* (input: { |
| 180 | readonly fileSystem: FileSystem.FileSystem; |
| 181 | readonly sharedHomePath: string; |
| 182 | readonly effectiveHomePath: string; |
| 183 | readonly entryName: string; |
| 184 | readonly linkPath: string; |
| 185 | }): Effect.fn.Return<LinkState, CodexShadowHomeError> { |
| 186 | return yield* input.fileSystem.readLink(input.linkPath).pipe( |
| 187 | Effect.map((target): LinkState => ({ _tag: "Symlink", target })), |
| 188 | Effect.catchTags({ |
| 189 | PlatformError: (cause) => { |
| 190 | if (cause.reason._tag === "NotFound") { |
| 191 | return Effect.succeed<LinkState>({ _tag: "Missing" }); |
| 192 | } |
| 193 | if (isNotSymlinkError(cause)) { |
| 194 | return Effect.succeed<LinkState>({ _tag: "NotSymlink" }); |
| 195 | } |
| 196 | return new CodexShadowHomeFileSystemError({ |
| 197 | sharedHomePath: input.sharedHomePath, |
| 198 | effectiveHomePath: input.effectiveHomePath, |
| 199 | operation: "readLink", |
| 200 | path: input.linkPath, |
| 201 | entryName: input.entryName, |
| 202 | cause, |
| 203 | }); |
| 204 | }, |
| 205 | }), |
| 206 | ); |
| 207 | }); |
| 208 | |
| 209 | const removePrivateSymlink = Effect.fn("CodexHomeLayout.removePrivateSymlink")(function* (input: { |
| 210 | readonly fileSystem: FileSystem.FileSystem; |
| 211 | readonly sharedHomePath: string; |
| 212 | readonly effectiveHomePath: string; |
| 213 | readonly entryName: string; |
| 214 | }): Effect.fn.Return<void, CodexShadowHomeError, Path.Path> { |
| 215 | const path = yield* Path.Path; |
| 216 | const privatePath = path.join(input.effectiveHomePath, input.entryName); |
| 217 | const state = yield* readLinkState({ |
| 218 | ...input, |
| 219 | linkPath: privatePath, |
| 220 | }); |
| 221 | if (state._tag === "Symlink") { |
| 222 | yield* input.fileSystem.remove(privatePath).pipe( |
| 223 | Effect.catchTags({ |
| 224 | PlatformError: (cause) => |
| 225 | new CodexShadowHomeFileSystemError({ |
| 226 | sharedHomePath: input.sharedHomePath, |
| 227 | effectiveHomePath: input.effectiveHomePath, |
| 228 | operation: "remove", |
| 229 | path: privatePath, |
| 230 | entryName: input.entryName, |
| 231 | cause, |
| 232 | }), |
| 233 | }), |
| 234 | ); |
| 235 | } |
| 236 | }); |
| 237 | |
| 238 | const ensureSymlink = Effect.fn("CodexHomeLayout.ensureSymlink")(function* (input: { |
| 239 | readonly fileSystem: FileSystem.FileSystem; |
| 240 | readonly sharedHomePath: string; |
| 241 | readonly effectiveHomePath: string; |
| 242 | readonly entryName: string; |
| 243 | }): Effect.fn.Return<void, CodexShadowHomeError, Path.Path> { |
| 244 | const path = yield* Path.Path; |
| 245 | const target = path.join(input.sharedHomePath, input.entryName); |
| 246 | const link = path.join(input.effectiveHomePath, input.entryName); |
| 247 | const state = yield* readLinkState({ |
| 248 | ...input, |
| 249 | linkPath: link, |
| 250 | }); |
| 251 | |
| 252 | const createLink = input.fileSystem.symlink(target, link).pipe( |
| 253 | Effect.catchTags({ |
| 254 | PlatformError: (cause) => |
| 255 | new CodexShadowHomeFileSystemError({ |
| 256 | sharedHomePath: input.sharedHomePath, |
| 257 | effectiveHomePath: input.effectiveHomePath, |
| 258 | operation: "symlink", |
| 259 | path: link, |
| 260 | targetPath: target, |
| 261 | entryName: input.entryName, |
| 262 | cause, |
| 263 | }), |
| 264 | }), |
| 265 | ); |
| 266 | |
| 267 | if (state._tag === "NotSymlink") { |
| 268 | if (!REPLACEABLE_SHARED_RUNTIME_ENTRIES.has(input.entryName)) { |
| 269 | return yield* new CodexShadowHomeEntryConflictError({ |
| 270 | sharedHomePath: input.sharedHomePath, |
| 271 | effectiveHomePath: input.effectiveHomePath, |
| 272 | entryName: input.entryName, |
| 273 | linkPath: link, |
| 274 | targetPath: target, |
| 275 | }); |
| 276 | } |
| 277 | |
| 278 | if (input.entryName === "thread-writer-locks") { |
| 279 | const lockNames = yield* input.fileSystem.readDirectory(link).pipe( |
| 280 | Effect.catchTags({ |
| 281 | PlatformError: (cause) => |
| 282 | new CodexShadowHomeFileSystemError({ |
| 283 | sharedHomePath: input.sharedHomePath, |
| 284 | effectiveHomePath: input.effectiveHomePath, |
| 285 | operation: "readDirectory", |
| 286 | path: link, |
| 287 | entryName: input.entryName, |
| 288 | cause, |
| 289 | }), |
| 290 | }), |
| 291 | ); |
| 292 | // Codex deletes a thread lock on release, so one that is left may still guard a live |
| 293 | // writer. Keep the local directory until a later setup finds none. |
| 294 | if (lockNames.some((name) => name.endsWith(".lock") && name !== ".coordination.lock")) { |
| 295 | return yield* Effect.logWarning( |
| 296 | "Codex shadow home still has thread writer locks; it will share them on a later setup.", |
| 297 | { path: link }, |
| 298 | ); |
| 299 | } |
| 300 | } |
| 301 | |
| 302 | yield* input.fileSystem.remove(link, { recursive: true }).pipe( |
| 303 | Effect.catchTags({ |
| 304 | PlatformError: (cause) => |
| 305 | new CodexShadowHomeFileSystemError({ |
| 306 | sharedHomePath: input.sharedHomePath, |
| 307 | effectiveHomePath: input.effectiveHomePath, |
| 308 | operation: "remove", |
| 309 | path: link, |
| 310 | entryName: input.entryName, |
| 311 | cause, |
| 312 | }), |
| 313 | }), |
| 314 | ); |
| 315 | return yield* createLink; |
| 316 | } |
| 317 | |
| 318 | if (state._tag === "Missing") { |
| 319 | return yield* createLink; |
| 320 | } |
| 321 | |
| 322 | const resolvedExisting = path.resolve(path.dirname(link), state.target); |
| 323 | if (resolvedExisting !== target) { |
| 324 | yield* input.fileSystem.remove(link).pipe( |
| 325 | Effect.catchTags({ |
| 326 | PlatformError: (cause) => |
| 327 | new CodexShadowHomeFileSystemError({ |
| 328 | sharedHomePath: input.sharedHomePath, |
| 329 | effectiveHomePath: input.effectiveHomePath, |
| 330 | operation: "remove", |
| 331 | path: link, |
| 332 | entryName: input.entryName, |
| 333 | cause, |
| 334 | }), |
| 335 | }), |
| 336 | ); |
| 337 | yield* createLink; |
| 338 | } |
| 339 | }); |
| 340 | |
| 341 | const ensureShadowAuthIsPrivate = Effect.fn("CodexHomeLayout.ensureShadowAuthIsPrivate")( |
| 342 | function* (input: { |
| 343 | readonly fileSystem: FileSystem.FileSystem; |
| 344 | readonly sharedHomePath: string; |
| 345 | readonly effectiveHomePath: string; |
| 346 | }): Effect.fn.Return<void, CodexShadowHomeError, Path.Path> { |
| 347 | const path = yield* Path.Path; |
| 348 | const entryName = "auth.json"; |
| 349 | const authPath = path.join(input.effectiveHomePath, entryName); |
| 350 | const state = yield* readLinkState({ |
| 351 | ...input, |
| 352 | entryName, |
| 353 | linkPath: authPath, |
| 354 | }); |
| 355 | if (state._tag === "Symlink") { |
| 356 | return yield* new CodexShadowHomePrivateEntrySymlinkError({ |
| 357 | sharedHomePath: input.sharedHomePath, |
| 358 | effectiveHomePath: input.effectiveHomePath, |
| 359 | entryName, |
| 360 | path: authPath, |
| 361 | }); |
| 362 | } |
| 363 | }, |
| 364 | ); |
| 365 | |
| 366 | export const materializeCodexShadowHome = Effect.fn("materializeCodexShadowHome")(function* ( |
| 367 | layout: CodexHomeLayout, |
| 368 | ) { |
| 369 | if (layout.mode !== "authOverlay") return; |
| 370 | const effectiveHomePath = layout.effectiveHomePath; |
| 371 | if (!effectiveHomePath) return; |
| 372 | if (layout.sharedHomePath === effectiveHomePath) { |
| 373 | return yield* new CodexShadowHomePathConflictError({ |
| 374 | sharedHomePath: layout.sharedHomePath, |
| 375 | effectiveHomePath, |
| 376 | }); |
| 377 | } |
| 378 | |
| 379 | const fileSystem = yield* FileSystem.FileSystem; |
| 380 | const path = yield* Path.Path; |
| 381 | |
| 382 | const makeDirectory = (directoryPath: string) => |
| 383 | fileSystem.makeDirectory(directoryPath, { recursive: true }).pipe( |
| 384 | Effect.catchTags({ |
| 385 | PlatformError: (cause) => |
| 386 | new CodexShadowHomeFileSystemError({ |
| 387 | sharedHomePath: layout.sharedHomePath, |
| 388 | effectiveHomePath, |
| 389 | operation: "makeDirectory", |
| 390 | path: directoryPath, |
| 391 | cause, |
| 392 | }), |
| 393 | }), |
| 394 | ); |
| 395 | |
| 396 | yield* Effect.all( |
| 397 | [ |
| 398 | makeDirectory(layout.sharedHomePath), |
| 399 | makeDirectory(effectiveHomePath), |
| 400 | ...KNOWN_SHARED_DIRECTORIES.map((directory) => |
| 401 | makeDirectory(path.join(layout.sharedHomePath, directory)), |
| 402 | ), |
| 403 | ], |
| 404 | { concurrency: "unbounded" }, |
| 405 | ); |
| 406 | |
| 407 | const sharedEntryNames = yield* fileSystem.readDirectory(layout.sharedHomePath).pipe( |
| 408 | Effect.catchTags({ |
| 409 | PlatformError: (cause) => |
| 410 | new CodexShadowHomeFileSystemError({ |
| 411 | sharedHomePath: layout.sharedHomePath, |
| 412 | effectiveHomePath, |
| 413 | operation: "readDirectory", |
| 414 | path: layout.sharedHomePath, |
| 415 | cause, |
| 416 | }), |
| 417 | }), |
| 418 | ); |
| 419 | const entries = new Set<string>(KNOWN_SHARED_DIRECTORIES); |
| 420 | for (const entryName of sharedEntryNames) { |
| 421 | if (!PRIVATE_ENTRY_NAMES.has(entryName) && !SHADOW_LOCAL_ENTRY_NAMES.has(entryName)) { |
| 422 | entries.add(entryName); |
| 423 | } |
| 424 | } |
| 425 | |
| 426 | yield* Effect.forEach( |
| 427 | PRIVATE_ENTRY_NAMES, |
| 428 | (entryName) => |
| 429 | entryName === "auth.json" |
| 430 | ? Effect.void |
| 431 | : removePrivateSymlink({ |
| 432 | fileSystem, |
| 433 | sharedHomePath: layout.sharedHomePath, |
| 434 | effectiveHomePath, |
| 435 | entryName, |
| 436 | }), |
| 437 | { discard: true }, |
| 438 | ); |
| 439 | |
| 440 | yield* Effect.forEach( |
| 441 | entries, |
| 442 | (entryName) => { |
| 443 | if (PRIVATE_ENTRY_NAMES.has(entryName)) { |
| 444 | return Effect.void; |
| 445 | } |
| 446 | return ensureSymlink({ |
| 447 | fileSystem, |
| 448 | sharedHomePath: layout.sharedHomePath, |
| 449 | effectiveHomePath, |
| 450 | entryName, |
| 451 | }); |
| 452 | }, |
| 453 | { discard: true }, |
| 454 | ); |
| 455 | |
| 456 | yield* ensureShadowAuthIsPrivate({ |
| 457 | fileSystem, |
| 458 | sharedHomePath: layout.sharedHomePath, |
| 459 | effectiveHomePath, |
| 460 | }); |
| 461 | }); |
| 462 | |
| 463 | export function codexContinuationIdentity(layout: CodexHomeLayout) { |
| 464 | return { |
| 465 | driverKind: ProviderDriverKind.make("codex"), |
| 466 | continuationKey: layout.continuationKey, |
| 467 | }; |
| 468 | } |