ai-agent-detect 0.0.1 → 0.1.0

package/README.md

@@ -1,22 +1,58 @@
 # ai-agent-detect
 
-Detect which AI agent is running your code — structured identity and capabilities.
+Detect which AI agent is running your code — structured identity, not just a boolean.
 
-**Status: name claimed, v0 in development.** This package does not do anything useful yet.
+**Status: working prototype.** The code runs (19 tests, 2 live-probed agents); the API may still shift before `0.1.0`.
 
-## What it will be
+```js
+import { detect, isAgent } from 'ai-agent-detect';
 
-Runtime identification for the agentic era — `isatty()` had fifty years; agents are the third consumer class:
+isAgent();               // boolean — the new isatty()
+isAgent('claude-code');  // assert style: am I running under this one?
 
-- **Structured identity**: `{ name, version, mode, source, confidence }` — parsed, not a raw string. Reads the `AI_AGENT` environment variable standard, the `AGENT` convention (Goose, Amp), and vendor tells (`CLAUDECODE=1`, …).
-- **Signals beyond env vars**: parent-process-tree walking (detect the agent ancestor even with a stripped environment), TTY state (interactive vs headless).
-- **Capability detection**: not just *which* agent, but what it honors — which context files it reads, which skill directories it discovers.
-- **Adaptive-output helpers**: `isAgent()` as the new `isatty()` — emit agent-optimized output when your consumer is an agent.
+detect();
+// {
+//   name: 'claude-code', vendor: 'anthropic',
+//   version: '2.1.205', mode: 'agent',
+//   source: 'env:AI_AGENT', confidence: 'high', corroborated: true,
+//   raw: { AI_AGENT: 'claude-code_2-1-205_agent', CLAUDECODE: '1', ... },
+//   claims: [ ... ]      // every claim the env carries — see below
+// }
+```
 
-## Relationship to `detect-agent`
+## Why claims, not a single winner
 
-[`detect-agent`](https://www.npmjs.com/package/detect-agent) (Vercel) answers the boolean question — *is* this an agent environment, and its name — via declarative rules. This package aims one level up: structured identity, richer signals than env/file existence checks can express, and capabilities. It will consume the `agents.json` definitions as a compatibility tier.
+Agents run agents. A grok session spawned inside a Claude Code session passes the inherited `AI_AGENT` through to its children (live-probed) — environment variables cannot tell you which *layer* set them. So `detect()` reports **every claim** the env carries and never silently picks between conflicting ones. The env cannot order nesting layers, so `claims[]` doesn't pretend to; genuine stack ordering (via process-tree walk) is `detectDeep()`'s job — planned, `ai-agent-detect/node` subpath.
 
-## Alias
+Every claim carries its evidence: `source` (which signal matched), `raw` (the matched variables), `confidence`. Apply your own trust policy instead of inheriting ours.
+
+## What it reads
+
+1. **`AI_AGENT`** — both value dialects in the wild: `name@version` (Vercel's spec: `devin@1`) and `name_version_mode` (Anthropic ships `claude-code_2-1-205_agent`).
+2. **`AGENT`** — the older convention, value-split: `AGENT=goose` names the agent; `AGENT=1` (opencode) proves agenthood without naming it — `isAgent()` true, every assert form false.
+3. **Vendor tells** — per-agent detector functions. Code, not a condition engine: the claude-code detector recovers the version from `CLAUDE_CODE_EXECPATH` when `AI_AGENT` is stripped; no declarative rule format can express that.
+
+## Supported agents
+
+| agent | signals | evidence |
+|---|---|---|
+| claude-code | `AI_AGENT` triple, `CLAUDECODE=1`, version via `CLAUDE_CODE_EXECPATH` | live-probed 2026-07-12 |
+| grok | **none** — sets no identity variable (and passes inherited `AI_AGENT` through) | live-probed 2026-07-12 |
+
+grok's entry is deliberate: an agent that cannot be detected from env is recorded as such — honesty over reach. Any agent that sets `AI_AGENT` or a name-valued `AGENT` is detected without a registry entry.
+
+## Design
+
+- **Zero runtime dependencies**, ESM, Node ≥ 18.
+- **Edge-safe core**: no `node:` imports; env access is guarded (`globalThis.process?.env`), so Workers/Deno/Bun run it and env-less runtimes return `null`. Anything runtime-specific will live behind subpath exports.
+- **Sync and cheap**: no spawn, no disk, no network. `process.env` is copied once per process (it's a proxy — see `bench.js`); `detect()` ≈ 0.5µs, `isAgent(name)` short-circuits at ≈ 0.15µs.
+- **Fixtures are the ground truth**: every registry entry ships a recorded env snapshot with probe date and method (`fixtures/`). The test matrix runs every fixture against every detector — no false positives is as tested as no false negatives.
+
+## Contributing an agent
+
+One folder, one fixture, one PR:
+
+1. `agents/<name>/index.js` — `{ name, vendor, procNames, pidEnvVar, detect(env) }`, registered in `agents/index.js` (alphabetical).
+2. `fixtures/<name>.json` — a recorded env snapshot from a live session (probe date + method required; the matrix test fails any entry without one).
+3. `npm test`.
 
-`agent-detect` is held as an alias of this package.

package/agents/claude-code/index.js

@@ -0,0 +1,24 @@
+// claude-code (Anthropic) — probed 2026-07-12 (see .kanbento/harnesses/claude-code.md).
+// Sets the full AI_AGENT triple (handled by core rung 1); this detector owns
+// the vendor tells, which also work when AI_AGENT is stripped or inherited-over.
+export default {
+  name: 'claude-code',
+  vendor: 'anthropic',
+  procNames: ['claude'],
+  pidEnvVar: null,
+  detect(env) {
+    if (env.CLAUDECODE !== '1') return null;
+    const raw = {};
+    for (const key of [
+      'CLAUDECODE',
+      'CLAUDE_CODE_ENTRYPOINT',
+      'CLAUDE_CODE_EXECPATH',
+      'CLAUDE_CODE_CHILD_SESSION',
+    ]) {
+      if (env[key] !== undefined) raw[key] = env[key];
+    }
+    // richer than a condition engine: the exec path carries the version
+    const version = env.CLAUDE_CODE_EXECPATH?.match(/\/versions\/(\d[\d.]*)/)?.[1] ?? null;
+    return { confidence: 'high', version, raw };
+  },
+};

package/agents/grok/index.js

@@ -0,0 +1,17 @@
+// grok (xAI) — probed 2026-07-12 (see .kanbento/harnesses/grok.md).
+// Sets NO identity variable (grok 0.2.45, scrubbed-env probe). Its children
+// carry only a non-interactive hygiene bundle (CI=true, pagers off, progress
+// off) — too weak to name an agent; weak-signal use is parked (note:design).
+// It also passes inherited AI_AGENT through — the live proof of nested-harness
+// contamination. Env-undetectable, honestly: this detector never fires.
+export default {
+  name: 'grok',
+  vendor: 'xai',
+  // binary is literally `agent` (~/.grok/bin/agent) — generic name; the ppid
+  // rung must corroborate via the executable path, not the name alone
+  procNames: ['agent'],
+  pidEnvVar: null,
+  detect() {
+    return null;
+  },
+};

package/agents/index.js

@@ -0,0 +1,5 @@
+// One agent = one folder = one easy PR. Keep alphabetical.
+import claudeCode from './claude-code/index.js';
+import grok from './grok/index.js';
+
+export const agents = [claudeCode, grok];

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/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/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;

package/index.js

@@ -1,6 +1,140 @@
-// ai-agent-detect 0.0.1 — name claimed, v0 in development.
-export function detect() {
-  throw new Error(
-    'ai-agent-detect v0 is in development — this 0.0.1 release only claims the name.'
-  );
+// ai-agent-detect — edge-safe core: env-only, sync, zero deps.
+// Detection logic is code; the registry holds facts (see agents/).
+import { agents } from './agents/index.js';
+
+const TRUTHY = new Set(['1', 'true', 'yes', 'on']);
+
+/**
+ * Detect the agent(s) running this process from environment signals.
+ * Returns the primary claim plus `claims[]` — every claim the env carries,
+ * deliberately unordered: env cannot order nesting layers, so it doesn't
+ * pretend to. Genuine stack ordering is detectDeep()'s job (./node).
+ */
+export function detect(opts = {}) {
+  const env = snapshot(opts.env);
+  const claims = [];
+
+  // rung 1 — the AI_AGENT standard (two dialects in the wild)
+  if (env.AI_AGENT) claims.push(parseAiAgent(env.AI_AGENT));
+
+  // rung 2 — the AGENT convention (value-split: name-valued vs boolean)
+  if (env.AGENT) claims.push(parseAgentVar(env.AGENT));
+
+  // rung 3 — per-agent vendor tells (code, richer than any condition engine)
+  for (const agent of agents) {
+    const hit = agent.detect(env);
+    if (hit) {
+      claims.push({
+        name: agent.name,
+        vendor: agent.vendor ?? null,
+        version: null,
+        mode: null,
+        source: 'env:vendor',
+        confidence: 'high',
+        ...hit,
+      });
+    }
+  }
+
+  if (claims.length === 0) return null;
+  return { ...merge(claims), claims };
+}
+
+/**
+ * isAgent()              — am I running under any agent?
+ * isAgent('claude-code') — am I running under this one? (assert style)
+ * An anonymous claim (AGENT=1) proves agenthood without naming the agent:
+ * isAgent() is true, every assert form is false.
+ */
+export function isAgent(name, opts) {
+  if (name !== undefined && typeof name === 'object') {
+    opts = name;
+    name = undefined;
+  }
+  const env = snapshot(opts?.env);
+
+  // Booleans can't get better with more evidence — short-circuit per rung.
+  if (env.AI_AGENT) {
+    if (name === undefined) return true;
+    if (parseAiAgent(env.AI_AGENT).name === name) return true;
+  }
+  if (env.AGENT) {
+    if (name === undefined) return true;
+    if (parseAgentVar(env.AGENT).name === name) return true;
+  }
+  for (const agent of agents) {
+    if (name !== undefined && agent.name !== name) continue;
+    if (agent.detect(env)) return true;
+  }
+  return false;
+}
+
+// process.env is a proxy into libuv — every property read crosses it (~12µs
+// per detect() measured vs ~2µs on a plain object). Copying it per call is
+// worse (~26µs: every var crosses the proxy). So: copy ONCE per process —
+// the agent's env verdict is fixed at spawn time anyway. An injected env
+// (tests, custom sources) bypasses the cache.
+let cached;
+function snapshot(env) {
+  if (env !== undefined) return env;
+  if (cached === undefined) {
+    const source = globalThis.process?.env;
+    cached = source ? { ...source } : {};
+  }
+  return cached;
+}
+
+// AI_AGENT value dialects observed in the wild (2026-07-12):
+//   Anthropic:  name_version_mode   claude-code_2-1-205_agent  (dashes = dots)
+//   Vercel:     name[@version]      devin@1, custom-agent@2.0, v0
+function parseAiAgent(value) {
+  const base = {
+    vendor: null,
+    version: null,
+    mode: null,
+    source: 'env:AI_AGENT',
+    confidence: 'high',
+    raw: { AI_AGENT: value },
+  };
+  if (value.includes('_')) {
+    const [name, version, mode] = value.split('_');
+    return {
+      ...base,
+      name: name || null,
+      version: version ? version.replaceAll('-', '.') : null,
+      mode: mode ?? null,
+      confidence: name ? 'high' : 'low',
+    };
+  }
+  if (value.includes('@')) {
+    const at = value.lastIndexOf('@');
+    return { ...base, name: value.slice(0, at) || null, version: value.slice(at + 1) || null };
+  }
+  return { ...base, name: value };
+}
+
+function parseAgentVar(value) {
+  const base = { vendor: null, version: null, mode: null, source: 'env:AGENT', raw: { AGENT: value } };
+  if (TRUTHY.has(value.toLowerCase())) {
+    // boolean-valued (opencode style): agenthood proven, identity unknown
+    return { ...base, name: null, confidence: 'medium' };
+  }
+  return { ...base, name: value, confidence: 'high' }; // name-valued (goose style)
+}
+
+// Primary = first named claim in rung order, enriched by corroborating
+// same-name claims. Anonymous claims never displace a named one.
+function merge(claims) {
+  const named = claims.filter((c) => c.name);
+  if (named.length === 0) return { ...claims[0] };
+  const primary = { ...named[0] };
+  for (const claim of named.slice(1)) {
+    if (claim.name !== primary.name) continue;
+    primary.version ??= claim.version;
+    primary.mode ??= claim.mode;
+    primary.vendor ??= claim.vendor;
+    primary.raw = { ...primary.raw, ...claim.raw };
+    primary.corroborated = true;
+  }
+  return primary;
 }

package/package.json

@@ -1,22 +1,47 @@
 {
   "name": "ai-agent-detect",
-  "version": "0.0.1",
-  "description": "Detect which AI agent is running your code — structured identity (name, version, mode) and capabilities. Reads the AI_AGENT standard and the signals it misses.",
+  "version": "0.1.0",
+  "description": "Detect which AI agent is running your code — structured identity (name, version, mode) with evidence, not just a boolean. Reads the AI_AGENT standard (both dialects) and the signals it misses.",
   "license": "MIT",
   "author": "George Mihailov",
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "agents/",
+    "fixtures/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "bench": "node bench.js",
+    "prepublishOnly": "npm test"
+  },
   "keywords": [
     "ai-agent",
     "AI_AGENT",
     "agent-detection",
     "detection",
+    "isagent",
     "claude-code",
+    "grok",
     "codex",
     "cursor",
     "gemini-cli",
     "amp",
-    "isagent",
+    "goose",
+    "opencode",
     "agentic"
   ]
 }