ai-agent-detect 0.0.1 → 0.2.0

package/fixtures/claude-code.json

@@ -0,0 +1,41 @@
+{
+  "agent": "claude-code",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "live: env inside a Claude Code background session (v2.1.205, macOS)",
+      "tier": "probed",
+      "env": {
+        "AI_AGENT": "claude-code_2-1-205_agent",
+        "CLAUDECODE": "1",
+        "CLAUDE_CODE_ENTRYPOINT": "cli",
+        "CLAUDE_CODE_EXECPATH": "/Users/user/.local/share/claude/versions/2.1.205",
+        "CLAUDE_CODE_CHILD_SESSION": "1"
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "claude-code",
+        "version": "2.1.205",
+        "mode": "agent",
+        "claimNames": ["claude-code"]
+      }
+    },
+    {
+      "date": "2026-07-12",
+      "method": "synthetic: AI_AGENT stripped — vendor tells only; version recovered from CLAUDE_CODE_EXECPATH",
+      "tier": "synthetic",
+      "env": {
+        "CLAUDECODE": "1",
+        "CLAUDE_CODE_ENTRYPOINT": "cli",
+        "CLAUDE_CODE_EXECPATH": "/Users/user/.local/share/claude/versions/2.1.205"
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "claude-code",
+        "version": "2.1.205",
+        "mode": null,
+        "claimNames": ["claude-code"]
+      }
+    }
+  ]
+}

package/fixtures/cline.json

@@ -0,0 +1,36 @@
+{
+  "agent": "cline",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "source-derived: VscodeTerminalRegistry.ts:29 \u2014 CLINE_ACTIVE=true injected on VS Code integrated terminals",
+      "tier": "source",
+      "env": {
+        "CLINE_ACTIVE": "true"
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "cline",
+        "claimNames": [
+          "cline"
+        ]
+      }
+    },
+    {
+      "date": "2026-07-12",
+      "method": "source-derived: standalone/CLI path (StandaloneTerminalProcess.ts:104-116) sets only anti-interactivity overrides, NOT the marker \u2014 the coverage gap",
+      "tier": "source",
+      "env": {
+        "TERM": "xterm-256color",
+        "PAGER": "cat",
+        "GIT_PAGER": "cat",
+        "MANPAGER": "cat"
+      },
+      "expect": {
+        "isAgent": false,
+        "primary": null,
+        "claimNames": []
+      }
+    }
+  ]
+}

package/fixtures/codex.json

@@ -0,0 +1,31 @@
+{
+  "agent": "codex",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "source-derived: codex-rs/core/src/spawn.rs — network sandbox on (any OS)",
+      "tier": "source",
+      "env": {
+        "CODEX_SANDBOX_NETWORK_DISABLED": "1"
+      },
+      "expect": { "isAgent": true, "primary": "codex", "claimNames": ["codex"] }
+    },
+    {
+      "date": "2026-07-12",
+      "method": "source-derived: macOS Seatbelt — both sandbox vars present",
+      "tier": "source",
+      "env": {
+        "CODEX_SANDBOX": "seatbelt",
+        "CODEX_SANDBOX_NETWORK_DISABLED": "1"
+      },
+      "expect": { "isAgent": true, "primary": "codex", "claimNames": ["codex"] }
+    },
+    {
+      "date": "2026-07-12",
+      "method": "source-derived: --sandbox danger-full-access — NO env signal exists (the documented hole; ppid walk is the only rung that catches codex here)",
+      "tier": "source",
+      "env": {},
+      "expect": { "isAgent": false, "primary": null, "claimNames": [] }
+    }
+  ]
+}

package/fixtures/continue.json

@@ -0,0 +1,20 @@
+{
+  "agent": "continue",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "source-derived: cn CLI spawns with no env option (runTerminalCommand.ts:192); VS Code path adds only generic color vars. Env-undetectable; upstream ticket candidate (CONTINUE=1)",
+      "tier": "source",
+      "env": {
+        "FORCE_COLOR": "1",
+        "COLORTERM": "truecolor",
+        "CLICOLOR": "1"
+      },
+      "expect": {
+        "isAgent": false,
+        "primary": null,
+        "claimNames": []
+      }
+    }
+  ]
+}

package/fixtures/cowork.json

@@ -0,0 +1,21 @@
+{
+  "agent": "cowork",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "vercel-rules-derived: detect-agent@1.0.1 agents.json (adopted, not independently verified) \u2014 cowork marker atop claude-code vars; claude-code detector defers (specificity wins)",
+      "tier": "vercel-rules",
+      "env": {
+        "CLAUDE_CODE_IS_COWORK": "1",
+        "CLAUDECODE": "1"
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "cowork",
+        "claimNames": [
+          "cowork"
+        ]
+      }
+    }
+  ]
+}

package/fixtures/crush.json

@@ -0,0 +1,20 @@
+{
+  "agent": "crush",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "source-derived: full Setenv/cmd.Env sweep of internal/ \u2014 NO self-identity var on shell children; only generic color-forcing on the PTY path. Env-undetectable; upstream ticket candidate (CRUSH=1)",
+      "tier": "source",
+      "env": {
+        "COLORTERM": "truecolor",
+        "CLICOLOR_FORCE": "1",
+        "FORCE_COLOR": "1"
+      },
+      "expect": {
+        "isAgent": false,
+        "primary": null,
+        "claimNames": []
+      }
+    }
+  ]
+}

package/fixtures/cursor.json

@@ -0,0 +1,24 @@
+{
+  "agent": "cursor",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "community/staff-derived: agent shell command env (forum.cursor.com/t/132427, t/37734) — both tells present",
+      "tier": "community",
+      "env": {
+        "CURSOR_AGENT": "1",
+        "CURSOR_TRACE_ID": "0000-fixture-trace-id"
+      },
+      "expect": { "isAgent": true, "primary": "cursor", "claimNames": ["cursor"] }
+    },
+    {
+      "date": "2026-07-12",
+      "method": "community-derived: trace id only (CURSOR_AGENT=1 was once accidentally dropped by a CLI release — the degraded state)",
+      "tier": "community",
+      "env": {
+        "CURSOR_TRACE_ID": "0000-fixture-trace-id"
+      },
+      "expect": { "isAgent": true, "primary": "cursor", "claimNames": ["cursor"] }
+    }
+  ]
+}

package/fixtures/devin.json

@@ -0,0 +1,16 @@
+{
+  "agent": "devin",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "vercel-rules-derived: detect-agent@1.0.1 agents.json (adopted, not independently verified) \u2014 only tell is file_exists /opt/.devin, a disk check outside the edge-safe env core; devin detection belongs to the /node rung",
+      "tier": "vercel-rules",
+      "env": {},
+      "expect": {
+        "isAgent": false,
+        "primary": null,
+        "claimNames": []
+      }
+    }
+  ]
+}

package/fixtures/gemini-cli.json

@@ -0,0 +1,14 @@
+{
+  "agent": "gemini-cli",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "source+doc-derived: shellExecutionService.ts sets GEMINI_CLI=1 on every shell-tool child; documented in docs/tools/shell.md",
+      "tier": "source",
+      "env": {
+        "GEMINI_CLI": "1"
+      },
+      "expect": { "isAgent": true, "primary": "gemini-cli", "claimNames": ["gemini-cli"] }
+    }
+  ]
+}

package/fixtures/github-copilot.json

@@ -0,0 +1,52 @@
+{
+  "agent": "github-copilot",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "doc-derived: vendor changelog:1674 \u2014 COPILOT_CLI=1 is the documented subprocess-detection hook, plus session id (changelog:1128)",
+      "tier": "doc",
+      "env": {
+        "COPILOT_CLI": "1",
+        "COPILOT_AGENT_SESSION_ID": "fixture-session"
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "github-copilot",
+        "claimNames": [
+          "github-copilot"
+        ]
+      }
+    },
+    {
+      "date": "2026-07-12",
+      "method": "vercel-rules-derived: detect-agent@1.0.1 agents.json (adopted, not independently verified) \u2014 COPILOT_MODEL trio, unverified in vendor changelog; weaker fallback",
+      "tier": "vercel-rules",
+      "env": {
+        "COPILOT_MODEL": "gpt-5"
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "github-copilot",
+        "claimNames": [
+          "github-copilot"
+        ]
+      }
+    },
+    {
+      "date": "2026-07-12",
+      "method": "doc-derived: AI_AGENT self-identification (github-copilot-cli dialect via core rung 1)",
+      "tier": "doc",
+      "env": {
+        "AI_AGENT": "github-copilot-cli"
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "github-copilot-cli",
+        "claimNames": [
+          "github-copilot-cli"
+        ],
+        "note": "verbatim rung-1 name; Vercel's scoped pkg normalizes -cli away, we preserve evidence as-is"
+      }
+    }
+  ]
+}

package/fixtures/goose.json

@@ -0,0 +1,22 @@
+{
+  "agent": "goose",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "source-derived: computer-controller / retry path (goose-mcp computercontroller/mod.rs:855-873) — AGENT=goose + GOOSE_TERMINAL=1, corroborating",
+      "tier": "source",
+      "env": {
+        "AGENT": "goose",
+        "GOOSE_TERMINAL": "1"
+      },
+      "expect": { "isAgent": true, "primary": "goose", "claimNames": ["goose"] }
+    },
+    {
+      "date": "2026-07-12",
+      "method": "source-derived: main developer shell tool sets NEITHER var (shell.rs sets only PATH — source contradicts the docs' blanket claim); goose is env-invisible on its most common path",
+      "tier": "source",
+      "env": {},
+      "expect": { "isAgent": false, "primary": null, "claimNames": [] }
+    }
+  ]
+}

package/fixtures/grok.json

@@ -0,0 +1,51 @@
+{
+  "agent": "grok",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "live: agent -p child env (grok 0.2.45, macOS), inherited identity vars scrubbed — grok sets no identity var, only a non-interactive hygiene bundle",
+      "tier": "probed",
+      "env": {
+        "CI": "true",
+        "CLICOLOR": "1",
+        "CLICOLOR_FORCE": "1",
+        "PAGER": "cat",
+        "GIT_PAGER": "cat",
+        "GH_PAGER": "cat",
+        "MANPAGER": "cat",
+        "SYSTEMD_PAGER": "cat",
+        "AWS_PAGER": "",
+        "GIT_TERMINAL_PROMPT": "0",
+        "GIT_SEQUENCE_EDITOR": "true",
+        "NPM_CONFIG_PROGRESS": "true",
+        "PIP_PROGRESS_BAR": "on",
+        "CARGO_TERM_PROGRESS_WHEN": "always",
+        "CARGO_TERM_PROGRESS_WIDTH": "80"
+      },
+      "expect": {
+        "isAgent": false,
+        "primary": null,
+        "claimNames": []
+      }
+    },
+    {
+      "date": "2026-07-12",
+      "method": "live: agent -p spawned INSIDE a Claude Code session, unscrubbed — grok passes inherited AI_AGENT through (nested-harness contamination; env-only detection reports the outer layer by design — detectDeep resolves the stack)",
+      "tier": "probed",
+      "env": {
+        "AI_AGENT": "claude-code_2-1-205_agent",
+        "CI": "true",
+        "CLICOLOR": "1",
+        "PAGER": "cat",
+        "GIT_PAGER": "cat",
+        "GIT_TERMINAL_PROMPT": "0"
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "claude-code",
+        "claimNames": ["claude-code"],
+        "note": "honest limitation, not a bug: the inner harness (grok) is env-invisible"
+      }
+    }
+  ]
+}

package/fixtures/junie.json

@@ -0,0 +1,20 @@
+{
+  "agent": "junie",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "vercel-rules-derived: detect-agent@1.0.1 agents.json (adopted, not independently verified)",
+      "tier": "vercel-rules",
+      "env": {
+        "JUNIE_DATA": "/tmp/junie"
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "junie",
+        "claimNames": [
+          "junie"
+        ]
+      }
+    }
+  ]
+}

package/fixtures/kilo.json

@@ -0,0 +1,28 @@
+{
+  "agent": "kilo",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "source-derived: cli/setup.ts:56 + server-manager.ts:113-152 + fork-parent index.ts:111-113 \u2014 the richest emitter surveyed; opencode detector legitimately fires too (kilo IS opencode underneath): the claims model represents it",
+      "tier": "source",
+      "env": {
+        "KILO": "1",
+        "KILO_CLIENT": "vscode",
+        "KILOCODE_FEATURE": "vscode-extension",
+        "KILOCODE_VERSION": "4.99.0",
+        "KILO_PID": "4242",
+        "AGENT": "1",
+        "OPENCODE": "1"
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "kilo",
+        "version": "4.99.0",
+        "claimNames": [
+          "kilo",
+          "opencode"
+        ]
+      }
+    }
+  ]
+}

package/fixtures/kiro.json

@@ -0,0 +1,20 @@
+{
+  "agent": "kiro",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "vercel-rules-derived: detect-agent@1.0.1 agents.json (adopted, not independently verified) \u2014 their rule gates on no_tty which env-only cannot see; low confidence, ambience not identity",
+      "tier": "vercel-rules",
+      "env": {
+        "TERM_PROGRAM": "kiro"
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "kiro",
+        "claimNames": [
+          "kiro"
+        ]
+      }
+    }
+  ]
+}

package/fixtures/opencode.json

@@ -0,0 +1,16 @@
+{
+  "agent": "opencode",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "source-derived: startup middleware (packages/opencode/src/index.ts:75-77) — OPENCODE=1, AGENT=1 (boolean: anonymous claim), OPENCODE_PID",
+      "tier": "source",
+      "env": {
+        "OPENCODE": "1",
+        "AGENT": "1",
+        "OPENCODE_PID": "12345"
+      },
+      "expect": { "isAgent": true, "primary": "opencode", "claimNames": ["opencode"] }
+    }
+  ]
+}

package/fixtures/openhands.json

@@ -0,0 +1,23 @@
+{
+  "agent": "openhands",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "source-derived: docker_sandbox_spec_service.py:38-52 + subprocess_terminal.py:150 \u2014 sandbox container furniture + PS1 markers; environment fingerprint, not identity by intent",
+      "tier": "source",
+      "env": {
+        "OH_CONVERSATIONS_PATH": "/workspace/conversations",
+        "OH_BASH_EVENTS_DIR": "/workspace/bash_events",
+        "OPENVSCODE_SERVER_ROOT": "/openhands/.openvscode-server",
+        "PS1": "###PS1JSON###{}###PS1END###"
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "openhands",
+        "claimNames": [
+          "openhands"
+        ]
+      }
+    }
+  ]
+}

package/fixtures/pi.json

@@ -0,0 +1,20 @@
+{
+  "agent": "pi",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "vercel-rules-derived: detect-agent@1.0.1 agents.json (adopted, not independently verified) \u2014 PATH fingerprint, weak-signal class",
+      "tier": "vercel-rules",
+      "env": {
+        "PATH": "/usr/bin:/home/u/.pi/agent/bin"
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "pi",
+        "claimNames": [
+          "pi"
+        ]
+      }
+    }
+  ]
+}

package/fixtures/qwen-code.json

@@ -0,0 +1,23 @@
+{
+  "agent": "qwen-code",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "source-derived: shellExecutionService.ts:723 + shellContextEnv.ts:41-55 \u2014 QWEN_CODE=1 with session-id family on every shell child; renamed from Gemini's GEMINI_CLI (fork, zero GEMINI_CLI hits)",
+      "tier": "source",
+      "env": {
+        "QWEN_CODE": "1",
+        "QWEN_CODE_SESSION_ID": "fixture-uuid",
+        "QWEN_CODE_AGENT_ID": "",
+        "QWEN_CODE_PROMPT_ID": ""
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "qwen-code",
+        "claimNames": [
+          "qwen-code"
+        ]
+      }
+    }
+  ]
+}

package/fixtures/replit.json

@@ -0,0 +1,20 @@
+{
+  "agent": "replit",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "vercel-rules-derived: detect-agent@1.0.1 agents.json (adopted, not independently verified) \u2014 REPL_ID marks the Replit environment, not specifically its agent",
+      "tier": "vercel-rules",
+      "env": {
+        "REPL_ID": "fixture-repl"
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "replit",
+        "claimNames": [
+          "replit"
+        ]
+      }
+    }
+  ]
+}

package/fixtures/roo.json

@@ -0,0 +1,38 @@
+{
+  "agent": "roo",
+  "probes": [
+    {
+      "date": "2026-07-12",
+      "method": "source-derived: Terminal.ts:153-161 \u2014 ROO_ACTIVE=true on VS Code terminals",
+      "tier": "source",
+      "env": {
+        "ROO_ACTIVE": "true",
+        "PAGER": "cat",
+        "VTE_VERSION": "0"
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "roo",
+        "claimNames": [
+          "roo"
+        ]
+      }
+    },
+    {
+      "date": "2026-07-12",
+      "method": "source-derived: extension-host.ts:182 \u2014 ROO_CLI_RUNTIME=1 process-wide in the headless CLI",
+      "tier": "source",
+      "env": {
+        "ROO_CLI_RUNTIME": "1"
+      },
+      "expect": {
+        "isAgent": true,
+        "primary": "roo",
+        "mode": "agent",
+        "claimNames": [
+          "roo"
+        ]
+      }
+    }
+  ]
+}

package/index.d.ts

@@ -0,0 +1,37 @@
+// Hand-written declarations — no build step for a zero-dep package.
+
+export interface AgentClaim {
+  /** Canonical agent slug, or null when agenthood is proven but unnamed (e.g. AGENT=1). */
+  name: string | null;
+  vendor: string | null;
+  version: string | null;
+  mode: string | null;
+  /** Which rung produced this claim. */
+  source: 'env:AI_AGENT' | 'env:AGENT' | 'env:vendor';
+  confidence: 'high' | 'medium' | 'low';
+  /** The matched evidence — the env vars this claim rests on. */
+  raw: Record<string, string>;
+}
+
+export interface AgentInfo extends AgentClaim {
+  /** Set when an independent signal confirmed the primary claim. */
+  corroborated?: boolean;
+  /**
+   * Every claim the environment carries, deliberately unordered — env cannot
+   * order nesting layers (an outer harness's vars pass through inner ones).
+   */
+  claims: AgentClaim[];
+}
+
+export interface DetectOptions {
+  /** Inject an env (tests, snapshots). Defaults to process.env, copied once per process. */
+  env?: Record<string, string | undefined>;
+}
+
+/** Structured detection: primary claim + all claims, or null when nothing matches. */
+export function detect(opts?: DetectOptions): AgentInfo | null;
+
+/** Am I running under any agent? */
+export function isAgent(opts?: DetectOptions): boolean;
+/** Assert style: am I running under this specific agent? */
+export function isAgent(name: string, opts?: DetectOptions): boolean;