@ai21/gateway 1.3.1 → 1.5.0

package/README.md

@@ -9,9 +9,13 @@ Ships as the `@ai21/gateway` package.
 npx @ai21/gateway install --agent-id <AGENT_ID>
 ```
 
-Merges `~/.claude/settings.json` so Claude Code routes through the gateway from
-every project on the machine (pass `--repo` to configure only the current one), then
-sends one request to prove it works. With no key stored it signs you in through the
+Configures a coding agent — Claude Code or Codex — so it routes through the
+gateway. Writes the agent's config file (`.claude/settings.json` for Claude Code,
+`config.toml` for Codex), then sends one request to prove it works.
+
+Use `--client codex` for Codex (user-level only; Codex ignores `model_provider`
+and `model_providers` in a project's `.codex/config.toml`). `--client claude-code`
+is the default and also accepts `--repo` for a project-local setup. With no key stored it signs you in through the
 browser first and creates an AI21 key for you, all in the one command — pass `--key`
 only for scripting, since a key in argv stays in your shell history.
 
@@ -25,17 +29,17 @@ and a warning says the key went unchecked.
 `--no-verify` turns off the _post-write_ check — the one that proves end to end that
 Claude Code reaches the gateway. It does not affect the pre-write key check.
 
-The gateway passes your own Claude credential through, so without a Claude login it
-can never answer. When `claude` reports no login — before the write, or when the
-post-write check proves it — the command prints `No Claude subscription detected`,
-leaves `settings.json` as it was before the run, and exits 9. A timeout or any other
-verification failure only warns and keeps the config. `--no-verify` skips this too, for
-machines where Claude Code is signed in later.
+The gateway passes the agent's own login through. Without one it can never answer,
+so `install` checks before the write (with `claude auth status` or `codex login
+status`) and, when verification proves it, undoes the write and exits 9. A timeout
+or any other verification failure only warns and keeps the config. The no-subscription
+check and verification are skipped under `--no-verify`. For Claude Code an Anthropic
+key (`--anthropic-key` or `ANTHROPIC_API_KEY`) can stand in for the login.
 
-The gateway currently supports only the Claude Code CLI. With no `claude` on PATH and
-no Anthropic key (`--anthropic-key` or `ANTHROPIC_API_KEY`), `install` stops before
-signing in, writes nothing, and exits 10, even under `--no-verify`. With an Anthropic
-key it goes ahead and verifies with a direct request instead.
+Without the agent's CLI on PATH, `install` stops before signing in, writes nothing,
+and exits 10, even under `--no-verify` (or, for Claude Code, with neither an Anthropic
+key nor Claude Desktop). For Codex there is no stand-in: only the Codex CLI can send the ChatGPT login
+the gateway forwards.
 
 The dashboard prints this command for you (Add agent, or Reconnect on an existing
 agent) and offers the key as a separate copy.
@@ -95,10 +99,41 @@ derive, so `login` asks for `--app <url>` instead of guessing.
 `--print` renders the config instead of writing it, with the key masked. `--help`
 lists the rest.
 
-`--client <name>` picks which agent to configure. `claude-code` is the default and
-the only one supported so far — an unsupported name is refused rather than
-defaulted, so a `--client` we do not implement never writes Claude Code's file by
-mistake.
+`--client <name>` picks which agent to configure: `claude-code` (the default) or
+`codex`. An unsupported name is refused rather than defaulted, so it never writes
+the wrong agent's file by mistake. `uninstall` also takes `--client` to know whose
+file to revert.
+
+### Claude Desktop
+
+`claude-code` covers every Claude app on the machine: `install` configures the Claude
+Code CLI and Claude Desktop, whichever are installed, in one run, and `uninstall`
+reverts both. It is one setup for analytics, with `agentKind: claude_code`. Desktop
+is configured only for a user-level install; `--repo` leaves it alone.
+
+Desktop uses its own third-party inference mode rather than a patched app: a gateway
+profile in `~/Library/Application Support/Claude-3p/configLibrary/`, applied through
+`_meta.json`, with `deploymentMode: "3p"` in both Desktop configs. Its 1P/3P chooser
+and its telemetry are turned off.
+
+It runs on the user's own Claude subscription. The first install runs `claude
+setup-token`, which opens the browser once and returns a token that lasts about a
+year; if the token cannot be read off the screen, it is pasted into a hidden prompt.
+The token is kept in the login keychain (`ai21-gateway-claude-desktop`), and a helper
+script at `~/.config/ai21-gateway/claude-desktop-credential` hands it to Desktop, which
+sends it as `Authorization: Bearer`. A re-install reuses it, and
+`CLAUDE_CODE_OAUTH_TOKEN` supplies one without the browser step.
+
+Desktop is verified through the gateway before its profile is written. It reads the
+profile only at launch, so `install` quits it if it is running and opens it again;
+run from inside Desktop's own Claude Code, it asks you to reopen it instead.
+
+On Windows the profile lives under `%LOCALAPPDATA%\Claude-3p` (or `Claude Nest-3p`), and
+the token in an owner-only file, `~/.config/ai21-gateway/claude-desktop-token`, which
+Desktop reads by running `cmd.exe /d /c type <file>`: Electron cannot spawn a `.cmd`.
+There is no `script` to record the approval screen, so you paste the token into a hidden
+prompt. Closing Desktop only sends it to the tray, so `install` stops its processes before
+reopening it; a Microsoft Store install is reopened by its app id.
 
 `install` reports onboarding events to AI21's product analytics (Amplitude), so we can
 see where setup fails: when it started, then whether it completed or at which step it

package/dist/agents/claude-code/desktop.d.ts

@@ -0,0 +1,81 @@
+import type { AgentEnv, AgentSurface, SnippetInputs } from "../types.js";
+/** Fixed, so a re-install replaces our profile instead of stacking a second one. */
+export declare const DESKTOP_PROFILE_ID = "00000000-0000-4000-8000-00000000a121";
+export declare const DESKTOP_PROFILE_NAME = "AI21 Gateway";
+export declare const DESKTOP_BUNDLE_ID = "com.anthropic.claudefordesktop";
+/** Where the subscription token lives. Read raw by the helper, so it is not base64 like the login secrets. */
+export declare const TOKEN_SERVICE = "ai21-gateway-claude-desktop";
+export declare const TOKEN_ACCOUNT = "claude-oauth-token";
+/** A subscription token, or undefined: it is quoted into `security -i` and sent as a header, so nothing else may pass. */
+export declare function oauthToken(value: string | undefined): string | undefined;
+export type DesktopPlatform = "darwin" | "win32";
+export interface DesktopPaths {
+    readonly platform: DesktopPlatform;
+    /** The regular Claude profile's config; its `deploymentMode` picks 1P or 3P at launch. */
+    readonly normalConfig: string;
+    readonly thirdPartyConfig: string;
+    readonly meta: string;
+    readonly profile: string;
+    /** What was applied before us, so uninstall can put it back. */
+    readonly restore: string;
+    /** macOS: the helper script over the keychain; Windows: the owner-only token file that `cmd /c type` prints. */
+    readonly helper: string;
+    readonly helperCommand: {
+        readonly path: string;
+        readonly args?: readonly string[];
+    };
+}
+export declare function desktopPaths(home: string, platform?: NodeJS.Platform, env?: Record<string, string | undefined>): DesktopPaths;
+export declare function desktopHeaders({ agentId, ai21Key, userId, client }: SnippetInputs): Record<string, string>;
+export declare function helperScript(): string;
+export declare function desktopProfile(inputs: SnippetInputs, paths: DesktopPaths): Record<string, unknown>;
+export type DesktopOutcome = {
+    readonly kind: "written";
+    readonly path: string;
+} | {
+    readonly kind: "reverted";
+    readonly path: string;
+} | {
+    readonly kind: "not-configured";
+    readonly path: string;
+} | {
+    readonly kind: "malformed";
+    readonly path: string;
+    readonly reason: string;
+} | {
+    readonly kind: "failed";
+    readonly path: string;
+    readonly reason: string;
+};
+/** Every file is parsed before any is written, so a malformed one leaves all untouched. */
+export declare function writeDesktopConfig(paths: DesktopPaths, inputs: SnippetInputs): DesktopOutcome;
+export declare function revertDesktopConfig(paths: DesktopPaths): DesktopOutcome;
+/** Everything outside this process, injected so tests never touch the real app or keychain. */
+export interface DesktopDeps {
+    readonly platform: NodeJS.Platform;
+    readonly installed: () => boolean;
+    readonly isRunning: () => Promise<boolean>;
+    readonly quit: () => Promise<void>;
+    /** For an app that closes to the tray instead of exiting; absent where quit really quits. */
+    readonly forceQuit?: () => Promise<void>;
+    readonly open: () => Promise<void>;
+    readonly sleep: (ms: number) => Promise<void>;
+    readonly readToken: () => Promise<string | undefined>;
+    readonly storeToken: (token: string) => Promise<void>;
+    readonly forgetToken: () => Promise<void>;
+    /** Runs `claude setup-token` in the user's terminal; the token it printed, if one could be read. */
+    readonly setupToken: () => Promise<string | undefined>;
+    readonly pasteToken: () => Promise<string | undefined>;
+}
+export declare function run(file: string, args: readonly string[]): Promise<string>;
+export declare function macDesktopDeps(): DesktopDeps;
+/** Replays a terminal transcript onto a grid: Claude Code draws with cursor moves, so the token is never in one piece. */
+export declare function screenFromTranscript(transcript: string): string;
+/** The token on the final screen, joined across the lines the terminal wrapped it onto. */
+export declare function tokenFromTranscript(transcript: string): string | undefined;
+export declare function promptToken(): Promise<string | undefined>;
+export type LaunchOutcome = "opened" | "restarted" | "still-running" | "open-failed";
+/** Desktop reads the profile only at launch: quit it if running, then open it either way. */
+export declare function relaunchDesktop(deps: DesktopDeps): Promise<LaunchOutcome>;
+/** Tests replace the app and keychain; everything else about the surface is real. */
+export declare function claudeDesktopSurface(desktopDeps?: (env: AgentEnv) => DesktopDeps): AgentSurface;