@ai21/gateway 1.4.0 → 1.5.0

package/README.md

@@ -37,8 +37,8 @@ check and verification are skipped under `--no-verify`. For Claude Code an Anthr
 key (`--anthropic-key` or `ANTHROPIC_API_KEY`) can stand in for the login.
 
 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, without an Anthropic
-key). For Codex there is no stand-in: only the Codex CLI can send the ChatGPT login
+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
@@ -104,6 +104,37 @@ lists the rest.
 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
 failed, with your AI21 user id, the CLI version, OS, workspace id and a random per-run

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;