|
| 1 | +import { determineAgent } from "@vercel/detect-agent"; |
| 2 | + |
| 3 | +/** |
| 4 | + * The `User-Agent` the CLI sends on every API request. |
| 5 | + * |
| 6 | + * Beyond the usual product token, it carries an `agent/<name>` token when a |
| 7 | + * coding agent is driving the CLI. That token is the only thing telling the API |
| 8 | + * apart a command a person typed from one an agent ran on their behalf — the |
| 9 | + * token signing the request is the same either way — and is what lets Argos |
| 10 | + * mark the resulting comment as agent-made. |
| 11 | + */ |
| 12 | + |
| 13 | +/** Product token of the CLI itself, e.g. `argos-cli/6.7.0`. */ |
| 14 | +const PRODUCT = "argos-cli"; |
| 15 | + |
| 16 | +/** |
| 17 | + * Longest agent name we forward. `AI_AGENT` is free-form, so a caller could put |
| 18 | + * anything in it; the API only needs enough to recognize the agent. |
| 19 | + */ |
| 20 | +const MAX_AGENT_LENGTH = 64; |
| 21 | + |
| 22 | +/** |
| 23 | + * Reduce an agent name to a `token` as the HTTP grammar defines it (RFC 9110 |
| 24 | + * §5.6.2), lowercased. |
| 25 | + * |
| 26 | + * `@vercel/detect-agent` returns the `AI_AGENT` environment variable verbatim |
| 27 | + * when it is set, so the value is user input: anything outside the allowed set — |
| 28 | + * spaces, and control characters that would otherwise let it inject a header — |
| 29 | + * becomes a hyphen. Returns `null` when nothing usable is left. |
| 30 | + */ |
| 31 | +function sanitizeAgentName(name: string): string | null { |
| 32 | + const sanitized = name |
| 33 | + .trim() |
| 34 | + .toLowerCase() |
| 35 | + .slice(0, MAX_AGENT_LENGTH) |
| 36 | + .replaceAll(/[^a-z0-9.@_-]+/g, "-") |
| 37 | + .replace(/^-+|-+$/g, ""); |
| 38 | + return sanitized || null; |
| 39 | +} |
| 40 | + |
| 41 | +/** |
| 42 | + * Format the `User-Agent` value, e.g. |
| 43 | + * `argos-cli/6.7.0 node/22.11.0 agent/claude`. |
| 44 | + */ |
| 45 | +export function formatUserAgent(input: { |
| 46 | + version: string; |
| 47 | + agent?: string | null | undefined; |
| 48 | +}): string { |
| 49 | + const tokens = [ |
| 50 | + `${PRODUCT}/${input.version}`, |
| 51 | + `node/${process.versions.node}`, |
| 52 | + ]; |
| 53 | + const agent = input.agent ? sanitizeAgentName(input.agent) : null; |
| 54 | + if (agent) { |
| 55 | + tokens.push(`agent/${agent}`); |
| 56 | + } |
| 57 | + return tokens.join(" "); |
| 58 | +} |
| 59 | + |
| 60 | +let userAgent: string | undefined; |
| 61 | + |
| 62 | +/** |
| 63 | + * Detect the agent driving the CLI and build the `User-Agent` from it, once per |
| 64 | + * process. Called at startup, before any command runs. |
| 65 | + */ |
| 66 | +export async function initUserAgent(version: string): Promise<void> { |
| 67 | + const { agent } = await determineAgent(); |
| 68 | + userAgent = formatUserAgent({ version, agent: agent?.name }); |
| 69 | +} |
| 70 | + |
| 71 | +/** |
| 72 | + * The `User-Agent` for API requests, `undefined` until {@link initUserAgent} has |
| 73 | + * run — the API client then falls back to the runtime's own default rather than |
| 74 | + * claiming a version we do not know. |
| 75 | + */ |
| 76 | +export function getUserAgent(): string | undefined { |
| 77 | + return userAgent; |
| 78 | +} |
0 commit comments