@phnx-labs/agents-cli 1.20.32 → 1.20.34

package/dist/lib/agent-spec/index.js

@@ -0,0 +1,35 @@
+// Public API for the agent-spec engine. Commands import from here and get the
+// production provider bound automatically; tests import the pure `./resolve.js`
+// core directly and inject a fake provider.
+//
+// One vocabulary, one resolver, reused by every subcommand that accepts
+// `<agent>[@<qualifier>]`. Built for the hot path: exact / @pinned / bare specs
+// resolve with no directory enumeration; only @latest/@oldest/@all enumerate,
+// via the mtime-cached provider.
+import { defaultVersionProvider } from './provider.js';
+import * as core from './resolve.js';
+export * from './types.js';
+export * from './primitives.js';
+/** Shared `--help` epilog so every agent-spec command documents the same grammar. */
+export const AGENT_SPEC_HELP = 'Agent spec: <agent>[@<qualifier>]. Qualifiers: ' +
+    '@latest (highest installed), @oldest (lowest installed), ' +
+    '@pinned / @default (your configured default — synonyms), ' +
+    '@all (every installed version), or an exact @x.y.z. ' +
+    'Bare <agent> uses the resolved default (project pin → global default). ' +
+    'Comma-separate to combine: claude@all,codex@latest.';
+/** Resolve a spec (single or comma-list) into concrete installed targets. */
+export function resolveAgentTargets(spec, opts = {}) {
+    return core.resolveAgentTargets(spec, defaultVersionProvider, opts);
+}
+/** Resolve a spec that must name exactly one installed version. */
+export function resolveSingleAgentTarget(spec, opts = {}) {
+    return core.resolveSingleAgentTarget(spec, defaultVersionProvider, opts);
+}
+/** Resolve a read/list command's version filter (undefined → all, @default → the default, else concrete). */
+export function resolveVersionFilter(agent, qualifier, opts = {}) {
+    return core.resolveVersionFilter(agent, qualifier, defaultVersionProvider, opts);
+}
+/** Concrete version filter for list/display commands (undefined → show all, @default → the default version). */
+export function resolveListFilter(agent, qualifier, opts = {}) {
+    return core.resolveListFilter(agent, qualifier, defaultVersionProvider, opts);
+}

package/dist/lib/agent-spec/primitives.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The only shape a version string may take before it reaches an exec/shim/path
+ * boundary. Accepts the literal `latest` or a 1–64 char run of `[A-Za-z0-9._+-]`
+ * with no `..` traversal. This is THE validation gate — every resolver funnels
+ * exact-version tokens through it.
+ */
+export declare const VERSION_RE: RegExp;
+/** Canonical qualifier set, in help/display order. `pinned` ≡ `default`. */
+export declare const AGENT_QUALIFIERS: readonly ["latest", "oldest", "pinned", "default", "all"];
+export type AgentQualifier = (typeof AGENT_QUALIFIERS)[number];
+/**
+ * Record-filter-only qualifiers. `any` means "no version constraint" for
+ * historical-record queries (sessions/teams resume) — accepted by the filter
+ * path but intentionally kept out of the display vocabulary.
+ */
+export declare const RECORD_ONLY_QUALIFIERS: readonly ["any"];
+/**
+ * Ordering for version strings (ascending).
+ *   1. numeric segment comparison (semver-ish: `2.1.187` > `2.1.143`)
+ *   2. tie → trailing `-N` build suffix, numerically (`2026.2.19-2` > `2026.2.19`)
+ *   3. still tied → 0 (legacy behavior: `1.0` == `1.0.0`, non-numeric tails == 0)
+ *
+ * Deliberately NOT a full semver comparator: OpenClaw's `-N` is a rebuild marker
+ * (higher = newer); a semver comparator would invert it. The `-N` tiebreak is the
+ * only addition over the historical numeric-only compare, so suffix-free versions
+ * (claude/codex semver) are unaffected.
+ */
+export declare function compareVersions(a: string, b: string): number;

package/dist/lib/agent-spec/primitives.js

@@ -0,0 +1,57 @@
+// Pure version primitives for the agent-spec engine — zero dependencies, so the
+// whole module (and versions.ts, which re-uses these) stays trivially testable.
+/**
+ * The only shape a version string may take before it reaches an exec/shim/path
+ * boundary. Accepts the literal `latest` or a 1–64 char run of `[A-Za-z0-9._+-]`
+ * with no `..` traversal. This is THE validation gate — every resolver funnels
+ * exact-version tokens through it.
+ */
+export const VERSION_RE = /^(?:latest|(?!.*\.\.)[A-Za-z0-9._+-]{1,64})$/;
+/** Canonical qualifier set, in help/display order. `pinned` ≡ `default`. */
+export const AGENT_QUALIFIERS = ['latest', 'oldest', 'pinned', 'default', 'all'];
+/**
+ * Record-filter-only qualifiers. `any` means "no version constraint" for
+ * historical-record queries (sessions/teams resume) — accepted by the filter
+ * path but intentionally kept out of the display vocabulary.
+ */
+export const RECORD_ONLY_QUALIFIERS = ['any'];
+/** Split a version into numeric `.`-segments (non-numeric tail → 0), e.g. `2026.2.19-2` → [2026,2,19]. */
+function numericParts(v) {
+    return v.split('.').map((n) => parseInt(n, 10) || 0);
+}
+/**
+ * Trailing `-<digits>` build suffix as a number (0 when absent). OpenClaw ships
+ * same-day rebuilds as `2026.2.19-2` where a higher `-N` is NEWER — the opposite
+ * of a semver pre-release. Used only to break exact numeric ties, so semver-style
+ * versions (which carry no `-N`) are unaffected.
+ */
+function buildSuffix(v) {
+    const m = /-(\d+)$/.exec(v);
+    return m ? parseInt(m[1], 10) : 0;
+}
+/**
+ * Ordering for version strings (ascending).
+ *   1. numeric segment comparison (semver-ish: `2.1.187` > `2.1.143`)
+ *   2. tie → trailing `-N` build suffix, numerically (`2026.2.19-2` > `2026.2.19`)
+ *   3. still tied → 0 (legacy behavior: `1.0` == `1.0.0`, non-numeric tails == 0)
+ *
+ * Deliberately NOT a full semver comparator: OpenClaw's `-N` is a rebuild marker
+ * (higher = newer); a semver comparator would invert it. The `-N` tiebreak is the
+ * only addition over the historical numeric-only compare, so suffix-free versions
+ * (claude/codex semver) are unaffected.
+ */
+export function compareVersions(a, b) {
+    const na = numericParts(a);
+    const nb = numericParts(b);
+    for (let i = 0; i < Math.max(na.length, nb.length); i++) {
+        const av = na[i] || 0;
+        const bv = nb[i] || 0;
+        if (av !== bv)
+            return av - bv;
+    }
+    const sa = buildSuffix(a);
+    const sb = buildSuffix(b);
+    if (sa !== sb)
+        return sa - sb;
+    return 0;
+}

package/dist/lib/agent-spec/provider.d.ts

@@ -0,0 +1,2 @@
+import type { VersionProvider } from './types.js';
+export declare const defaultVersionProvider: VersionProvider;

package/dist/lib/agent-spec/provider.js

@@ -0,0 +1,9 @@
+// The production VersionProvider: the only fs/meta-coupled file in the engine.
+// Everything else in this module is pure and testable without it.
+import { listInstalledVersions, getGlobalDefault, getProjectVersion, isVersionInstalled, } from '../versions.js';
+export const defaultVersionProvider = {
+    listInstalled: (agent) => listInstalledVersions(agent),
+    getProjectVersion: (agent, cwd) => getProjectVersion(agent, cwd),
+    getGlobalDefault: (agent) => getGlobalDefault(agent),
+    isInstalled: (agent, version) => isVersionInstalled(agent, version),
+};

package/dist/lib/agent-spec/resolve.d.ts

@@ -0,0 +1,33 @@
+import type { AgentId } from '../types.js';
+import { type AgentTarget, type VersionProvider, type VersionSource, type ResolveOptions, type VersionFilter } from './types.js';
+/**
+ * Resolve an agent spec (single or comma-list) into concrete installed targets.
+ * `@latest`/`@oldest`/`@all` range over installed versions.
+ */
+export declare function resolveAgentTargets(spec: string, provider: VersionProvider, opts?: ResolveOptions): AgentTarget[];
+/**
+ * Single-target commands (`run`, `sync`, `inspect`): resolve a spec that must
+ * name exactly one installed version. Rejects `@all` / multi-target specs.
+ */
+export declare function resolveSingleAgentTarget(spec: string, provider: VersionProvider, opts?: ResolveOptions): {
+    agent: AgentId;
+    version: string;
+    source: VersionSource;
+};
+/**
+ * Read/list commands: resolve a qualifier into a version filter.
+ *   undefined / '' / @any → no filter (show all installed versions)
+ *   @default / @pinned    → the literal 'default' sentinel (show the configured default)
+ *   @latest/@oldest/x.y.z → a concrete version (throws if not installed)
+ * Uniform `@default` handling fixes the prior rules-vs-view inconsistency.
+ */
+export declare function resolveVersionFilter(agent: AgentId, qualifier: string | undefined | null, provider: VersionProvider, opts?: ResolveOptions): VersionFilter;
+/**
+ * Concrete version filter for list/display commands whose downstream code
+ * filters by an exact version string (not the `'default'` sentinel `view` uses).
+ *   undefined / '' / @any → undefined  (no filter → show all installed)
+ *   @default / @pinned    → the configured default version, or undefined if none
+ *                           is set (falls back to show-all rather than erroring)
+ *   @latest/@oldest/x.y.z → a concrete version (throws AgentSpecError if bad)
+ */
+export declare function resolveListFilter(agent: AgentId, qualifier: string | undefined | null, provider: VersionProvider, opts?: ResolveOptions): string | undefined;

package/dist/lib/agent-spec/resolve.js

@@ -0,0 +1,174 @@
+// Pure agent-spec resolution — the engine core. Takes a VersionProvider instead
+// of touching the filesystem, so every branch is unit-testable with in-memory
+// fixtures. Domain = installed versions (`add`/install use a separate npm path).
+// Never calls process.exit; throws AgentSpecError on bad input.
+import { AGENTS, ALL_AGENT_IDS, resolveAgentName, formatAgentError } from '../agents.js';
+import { VERSION_RE } from './primitives.js';
+import { AgentSpecError, } from './types.js';
+/**
+ * Resolve an agent spec (single or comma-list) into concrete installed targets.
+ * `@latest`/`@oldest`/`@all` range over installed versions.
+ */
+export function resolveAgentTargets(spec, provider, opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const available = opts.availableAgents ?? ALL_AGENT_IDS;
+    const onAmbiguous = opts.onAmbiguous ?? 'error';
+    const rawEntries = spec.split(',').map((s) => s.trim()).filter(Boolean);
+    if (rawEntries.length === 0) {
+        throw new AgentSpecError('Empty agent spec.', 'empty');
+    }
+    // Expand the bare literal `all` (or `all@all`) into every available agent that
+    // has ≥1 installed version. Lenient: agents with nothing installed are skipped.
+    const entries = [];
+    for (const e of rawEntries) {
+        if (e === 'all' || e === 'all@all') {
+            for (const a of available) {
+                if (provider.listInstalled(a).length > 0)
+                    entries.push(`${a}@all`);
+            }
+        }
+        else {
+            entries.push(e);
+        }
+    }
+    const out = [];
+    const seen = new Set();
+    const push = (agent, version, source) => {
+        const key = `${agent}@${version ?? ''}`;
+        if (!seen.has(key)) {
+            seen.add(key);
+            out.push({ agent, version, source });
+        }
+    };
+    for (const entry of entries) {
+        const at = entry.indexOf('@');
+        const agentToken = (at === -1 ? entry : entry.slice(0, at)).trim();
+        const qualifier = at === -1 ? null : entry.slice(at + 1).trim();
+        if (!agentToken)
+            continue;
+        if (at !== -1 && !qualifier) {
+            throw new AgentSpecError(`Missing version in '${entry}'. Use ${agentToken}@x.y.z, @latest, @oldest, @pinned, @default, or @all.`, 'missing-version');
+        }
+        const agent = resolveAgentName(agentToken);
+        if (!agent || !available.includes(agent)) {
+            throw new AgentSpecError(formatAgentError(agentToken, [...available]), 'unknown-agent');
+        }
+        const name = AGENTS[agent].name;
+        // ----- bare: project pin → global default → sole/ambiguous installed -----
+        if (qualifier === null) {
+            const proj = provider.getProjectVersion(agent, cwd);
+            if (proj) {
+                push(agent, proj, 'project-pin');
+                continue;
+            }
+            const glob = provider.getGlobalDefault(agent);
+            if (glob) {
+                push(agent, glob, 'global-default');
+                continue;
+            }
+            const installed = provider.listInstalled(agent);
+            if (installed.length === 0) {
+                push(agent, null, 'none');
+                continue;
+            }
+            if (installed.length === 1) {
+                push(agent, installed[0], 'sole-installed');
+                continue;
+            }
+            if (onAmbiguous === 'newest') {
+                push(agent, installed[installed.length - 1], 'newest-installed');
+                continue;
+            }
+            throw new AgentSpecError(`No default version set for ${name}. Specify one (${agent}@<version>) or set it: agents use ${agent}@<version>.`, 'no-default', agent, installed);
+        }
+        // ----- @pinned / @default: the configured global default -----
+        if (qualifier === 'pinned' || qualifier === 'default') {
+            const def = provider.getGlobalDefault(agent);
+            if (!def) {
+                throw new AgentSpecError(`No default version set for ${name}. Run: agents use ${agent}@<version>`, 'no-default', agent, provider.listInstalled(agent));
+            }
+            push(agent, def, 'global-default(@pinned)');
+            continue;
+        }
+        // ----- @all: every installed version -----
+        if (qualifier === 'all') {
+            const installed = provider.listInstalled(agent);
+            if (installed.length === 0) {
+                throw new AgentSpecError(`No managed versions are installed for ${name}. Run: agents add ${agent}@latest`, 'none-installed', agent);
+            }
+            for (const v of installed)
+                push(agent, v, 'explicit');
+            continue;
+        }
+        // ----- @latest / @oldest: ends of the installed range -----
+        if (qualifier === 'latest' || qualifier === 'oldest') {
+            const installed = provider.listInstalled(agent);
+            if (installed.length === 0) {
+                throw new AgentSpecError(`No managed versions are installed for ${name}. Run: agents add ${agent}@latest`, 'none-installed', agent);
+            }
+            const isOldest = qualifier === 'oldest';
+            push(agent, isOldest ? installed[0] : installed[installed.length - 1], isOldest ? 'alias-oldest' : 'alias-latest');
+            continue;
+        }
+        // ----- exact version: validate then existence-check (no enumeration) -----
+        if (!VERSION_RE.test(qualifier)) {
+            throw new AgentSpecError(`Invalid version '${qualifier}' for ${name}. Allowed: latest or [A-Za-z0-9._+-]{1,64}.`, 'invalid-version', agent);
+        }
+        if (!provider.isInstalled(agent, qualifier)) {
+            const installed = provider.listInstalled(agent);
+            const hint = installed.length ? ` Installed: ${installed.join(', ')}.` : '';
+            throw new AgentSpecError(`${name}@${qualifier} is not installed.${hint} Install it: agents add ${agent}@${qualifier}`, 'not-installed', agent, installed);
+        }
+        push(agent, qualifier, 'explicit');
+    }
+    return out;
+}
+/**
+ * Single-target commands (`run`, `sync`, `inspect`): resolve a spec that must
+ * name exactly one installed version. Rejects `@all` / multi-target specs.
+ */
+export function resolveSingleAgentTarget(spec, provider, opts = {}) {
+    const targets = resolveAgentTargets(spec, provider, opts);
+    if (targets.length !== 1) {
+        throw new AgentSpecError(`'${spec}' resolves to ${targets.length} targets; this command needs exactly one.`, 'multi-not-allowed');
+    }
+    const t = targets[0];
+    if (t.version === null) {
+        throw new AgentSpecError(`No installed version for ${AGENTS[t.agent].name}. Run: agents add ${t.agent}@latest`, 'none-installed', t.agent);
+    }
+    return { agent: t.agent, version: t.version, source: t.source };
+}
+/**
+ * Read/list commands: resolve a qualifier into a version filter.
+ *   undefined / '' / @any → no filter (show all installed versions)
+ *   @default / @pinned    → the literal 'default' sentinel (show the configured default)
+ *   @latest/@oldest/x.y.z → a concrete version (throws if not installed)
+ * Uniform `@default` handling fixes the prior rules-vs-view inconsistency.
+ */
+export function resolveVersionFilter(agent, qualifier, provider, opts = {}) {
+    const q = qualifier?.trim();
+    if (!q)
+        return { version: null, source: 'all-versions' };
+    if (q === 'default' || q === 'pinned')
+        return { version: 'default', source: 'default' };
+    if (q === 'any')
+        return { version: null, source: 'all-versions' };
+    const { version, source } = resolveSingleAgentTarget(`${agent}@${q}`, provider, { ...opts, availableAgents: [agent] });
+    return { version, source };
+}
+/**
+ * Concrete version filter for list/display commands whose downstream code
+ * filters by an exact version string (not the `'default'` sentinel `view` uses).
+ *   undefined / '' / @any → undefined  (no filter → show all installed)
+ *   @default / @pinned    → the configured default version, or undefined if none
+ *                           is set (falls back to show-all rather than erroring)
+ *   @latest/@oldest/x.y.z → a concrete version (throws AgentSpecError if bad)
+ */
+export function resolveListFilter(agent, qualifier, provider, opts = {}) {
+    const q = qualifier?.trim();
+    if (!q || q === 'any')
+        return undefined;
+    if (q === 'default' || q === 'pinned')
+        return provider.getGlobalDefault(agent) ?? undefined;
+    return resolveSingleAgentTarget(`${agent}@${q}`, provider, { ...opts, availableAgents: [agent] }).version;
+}

package/dist/lib/agent-spec/types.d.ts

@@ -0,0 +1,57 @@
+import type { AgentId } from '../types.js';
+/** How a resolved version was arrived at — for provenance, display, and error rendering. */
+export type VersionSource = 'explicit' | 'project-pin' | 'global-default' | 'global-default(@pinned)' | 'sole-installed' | 'newest-installed' | 'alias-latest' | 'alias-oldest' | 'none';
+export interface AgentTarget {
+    agent: AgentId;
+    /** Resolved exact version, or null when the agent has no installed versions yet. */
+    version: string | null;
+    source: VersionSource;
+}
+export type AgentSpecErrorCode = 'empty' | 'unknown-agent' | 'missing-version' | 'invalid-version' | 'not-installed' | 'no-default' | 'none-installed' | 'multi-not-allowed';
+/**
+ * Thrown on any bad spec — never `process.exit`, so the engine is safe on the
+ * hot path and in library contexts. `code` + `installed` let callers render a
+ * consistent message (e.g. the "No default … Specify one:" version list) without
+ * string-matching.
+ */
+export declare class AgentSpecError extends Error {
+    readonly code: AgentSpecErrorCode;
+    readonly agent?: AgentId | undefined;
+    readonly installed?: string[] | undefined;
+    constructor(message: string, code: AgentSpecErrorCode, agent?: AgentId | undefined, installed?: string[] | undefined);
+}
+/**
+ * The filesystem/meta seam. The pure resolver takes this instead of importing
+ * versions.ts, so it is fully unit-testable with in-memory fixtures — no $HOME,
+ * no subprocess. `provider.ts` supplies the production adapter.
+ */
+export interface VersionProvider {
+    /** Installed versions, sorted ascending by `compareVersions`. */
+    listInstalled(agent: AgentId): string[];
+    /** Version pinned by a project-root agents.yaml, or null. */
+    getProjectVersion(agent: AgentId, cwd: string): string | null;
+    /** The configured global default version, or null. */
+    getGlobalDefault(agent: AgentId): string | null;
+    /** Whether an exact version is installed. */
+    isInstalled(agent: AgentId, version: string): boolean;
+}
+export interface ResolveOptions {
+    /** Project dir for a bare spec's project pin. Defaults to process.cwd(). */
+    cwd?: string;
+    /** Restrict which agents a spec may name (e.g. only mcp-capable). Defaults to all. */
+    availableAgents?: readonly AgentId[];
+    /**
+     * Bare spec, >1 installed, no pin/default:
+     *   'error'  (default) → throw AgentSpecError{code:'no-default'} — safe for
+     *                        state-mutating commands (sync/use).
+     *   'newest'          → pick the newest installed (source:'newest-installed');
+     *                        callers should note it. For execution verbs (run/exec).
+     */
+    onAmbiguous?: 'error' | 'newest';
+}
+/** A read/list command's version filter. `null` = show all; `'default'` = show the configured default. */
+export type FilterVersion = string | null | 'default';
+export interface VersionFilter {
+    version: FilterVersion;
+    source: VersionSource | 'all-versions' | 'default';
+}

package/dist/lib/agent-spec/types.js

@@ -0,0 +1,18 @@
+/**
+ * Thrown on any bad spec — never `process.exit`, so the engine is safe on the
+ * hot path and in library contexts. `code` + `installed` let callers render a
+ * consistent message (e.g. the "No default … Specify one:" version list) without
+ * string-matching.
+ */
+export class AgentSpecError extends Error {
+    code;
+    agent;
+    installed;
+    constructor(message, code, agent, installed) {
+        super(message);
+        this.code = code;
+        this.agent = agent;
+        this.installed = installed;
+        this.name = 'AgentSpecError';
+    }
+}

package/dist/lib/agents.d.ts

@@ -219,6 +219,18 @@ export declare const AGENT_NAME_ALIASES: Record<string, AgentId>;
 export declare function resolveAgentName(input: string): AgentId | null;
 /** Check whether the input string matches any known agent name or alias. */
 export declare function isAgentName(input: string): boolean;
+/**
+ * Build the deprecation notice lines for an agent, or null if it isn't
+ * deprecated. Split from the printer so tests can assert the content without
+ * capturing stdout. Lines are plain (uncolored) text.
+ */
+export declare function deprecationNotice(agent: AgentId): string[] | null;
+/**
+ * Print a deprecation warning (yellow) if the agent's registry entry carries a
+ * `deprecated` marker; no-op otherwise. Call from any user entry point that
+ * acts on a chosen agent — install (`agents add`) and `agents teams add`.
+ */
+export declare function warnAgentDeprecated(agent: AgentId): void;
 /** Format an error message for an unrecognized agent name, listing valid options. */
 export declare function formatAgentError(agentName: string, validAgents?: AgentId[]): string;
 export {};

package/dist/lib/agents.js

@@ -2,7 +2,7 @@
  * Core agent configuration and detection module.
  *
  * Defines the canonical registry of all supported AI coding agents (Claude, Codex,
- * Gemini, Cursor, OpenCode, OpenClaw, Copilot, Amp, Kiro, Goose, Roo, Grok) with their
+ * Gemini, Cursor, OpenCode, OpenClaw, Copilot, Amp, Kiro, Goose, Grok) with their
  * CLI commands, config paths, capability flags, and MCP integration points.
  *
  * Provides functions for detecting installed CLIs, resolving version-managed binaries,
@@ -10,6 +10,7 @@
  */
 import { execFile } from 'child_process';
 import { promisify } from 'util';
+import * as crypto from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -249,6 +250,16 @@ export const AGENTS = {
         variableSyntax: '{{args}}',
         supportsHooks: true,
         nativeAgentsSkillsDir: true,
+        // Google retired the Gemini CLI (announced at Google I/O 2026, May 19); the `gemini`
+        // command stopped serving free/Pro/Ultra requests on June 18, 2026. Antigravity CLI
+        // (`agy`) is the official successor. See warnAgentDeprecated() for the surfaced warning.
+        deprecated: {
+            by: 'Google',
+            date: 'June 18, 2026',
+            reason: 'The Gemini CLI was retired for free, Pro, and Ultra tiers and no longer serves requests (announced at Google I/O 2026 on May 19).',
+            replacement: 'antigravity',
+            url: 'https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/',
+        },
         // gemini hooks: shipped in v0.26.0 (Jan 2026); older binaries silently ignore the `hooks` key.
         capabilities: { hooks: { since: '0.26.0' }, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'GEMINI.md' }, workflows: false, modes: ['plan', 'edit', 'skip'], rulesImports: true },
     },
@@ -375,24 +386,6 @@ export const AGENTS = {
         supportsHooks: false,
         capabilities: { hooks: false, mcp: true, allowlist: false, skills: false, commands: false, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['edit'] },
     },
-    roo: {
-        id: 'roo',
-        name: 'Roo Code',
-        color: 'cyanBright',
-        cliCommand: 'roo',
-        npmPackage: '',
-        installScript: 'curl -fsSL https://raw.githubusercontent.com/RooCodeInc/Roo-Code/main/apps/cli/install.sh | sh',
-        configDir: path.join(HOME, '.roo'),
-        commandsDir: path.join(HOME, '.roo', 'commands'),
-        commandsSubdir: 'commands',
-        skillsDir: path.join(HOME, '.roo', 'skills'),
-        hooksDir: 'hooks',
-        instructionsFile: 'AGENTS.md',
-        format: 'markdown',
-        variableSyntax: '$ARGUMENTS',
-        supportsHooks: false,
-        capabilities: { hooks: false, mcp: true, allowlist: false, skills: true, commands: true, plugins: false, subagents: false, rules: { file: 'AGENTS.md' }, workflows: false, modes: ['plan', 'edit'] },
-    },
     // Google Antigravity CLI (`agy`) — official replacement for Gemini CLI as of IO 2026.
     // configDir nests inside `~/.gemini/` since agy shares the parent dir with the Gemini
     // CLI but isolates its own state in the `antigravity-cli/` subdir. Per-version HOME
@@ -802,6 +795,52 @@ function resolveAccountCredentialPath(base, ...segments) {
     }
     return null;
 }
+/**
+ * Factory Droid stores its OAuth credential encrypted at ~/.factory/auth.v2.file
+ * (AES-256-GCM, format `ivB64:tagB64:ctB64`) with the 32-byte key base64-stored
+ * in ~/.factory/auth.v2.key. On the keyfile-v2 source there is no OS-keychain /
+ * device binding — the key is on disk — so we can decrypt locally with no
+ * network call. The decrypted JSON credential's `access_token` is a WorkOS JWT
+ * carrying an `email` claim (plus org_id / role). We decode the claim WITHOUT
+ * verifying `exp`: the email is stable identity for display, not an
+ * authorization decision, so an expired token still yields the right address.
+ * Every failure (missing key file — e.g. a keyring-v2/legacy login with no
+ * on-disk key, a bad GCM tag, malformed JSON, or no email claim) returns null so
+ * the caller falls back to the file-presence signed-in signal. Never throws.
+ */
+function decryptDroidCredential(base) {
+    const filePath = resolveAccountCredentialPath(base, '.factory', 'auth.v2.file');
+    const keyPath = resolveAccountCredentialPath(base, '.factory', 'auth.v2.key');
+    if (!filePath || !keyPath)
+        return null;
+    try {
+        const blob = fs.readFileSync(filePath, 'utf-8').trim();
+        const key = Buffer.from(fs.readFileSync(keyPath, 'utf-8').trim(), 'base64');
+        if (key.length !== 32)
+            return null;
+        const [ivB64, tagB64, ctB64] = blob.split(':');
+        if (!ivB64 || !tagB64 || !ctB64)
+            return null;
+        const decipher = crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(ivB64, 'base64'));
+        decipher.setAuthTag(Buffer.from(tagB64, 'base64'));
+        const plaintext = Buffer.concat([
+            decipher.update(Buffer.from(ctB64, 'base64')),
+            decipher.final(),
+        ]).toString('utf-8');
+        const cred = JSON.parse(plaintext);
+        const claims = typeof cred?.access_token === 'string' ? decodeJwtPayload(cred.access_token) : null;
+        if (!claims)
+            return null;
+        return {
+            email: typeof claims.email === 'string' ? claims.email : null,
+            orgId: normalizeIdentityPart(claims.org_id ?? cred.active_organization_id),
+            role: typeof claims.role === 'string' ? claims.role : null,
+        };
+    }
+    catch {
+        return null;
+    }
+}
 let cachedAgyKeychainSignedIn;
 /**
  * Antigravity (`agy`, a Codeium/Windsurf-based CLI) stores its OAuth token in
@@ -1034,12 +1073,29 @@ export async function getAccountInfo(agentId, home) {
                 return { ...empty, signedIn: true, accountId: userId, accountKey, lastActive };
             }
             case 'droid': {
-                // Factory Droid stores auth at ~/.factory/auth.v2.file (+ auth.v2.key,
-                // an encrypted blob). No email/JWT is readable locally, so presence of
-                // the auth file is the only signed-in signal we can derive without a
-                // network call — same pattern as antigravity/kimi. `.factory` is the
-                // config dir on every platform (macOS/Linux ~/.factory, Windows
-                // %USERPROFILE%\.factory), so path.join keeps this cross-platform.
+                // Factory Droid stores auth at ~/.factory/auth.v2.file (AES-256-GCM,
+                // decrypted with the on-disk ~/.factory/auth.v2.key). We decrypt locally
+                // — no network — and surface the email/org/role from the WorkOS
+                // access-token JWT, same as claude/codex/grok. If the credential can't be
+                // decrypted (a keyring-v2/legacy login with no on-disk key, or a decrypt
+                // failure) we fall back to the file-presence signed-in signal so the row
+                // still reads as logged in — the conservative floor antigravity/kimi use.
+                // `.factory` is the config dir on every platform (macOS/Linux
+                // ~/.factory, Windows %USERPROFILE%\.factory).
+                const decoded = decryptDroidCredential(base);
+                if (decoded?.email) {
+                    const organizationId = decoded.orgId;
+                    const accountKey = buildIdentityKey(agentId, [['org', organizationId]]);
+                    return {
+                        ...empty,
+                        email: decoded.email,
+                        organizationId,
+                        accountId: organizationId,
+                        accountKey,
+                        signedIn: true,
+                        lastActive,
+                    };
+                }
                 const authPath = resolveAccountCredentialPath(base, '.factory', 'auth.v2.file');
                 if (!authPath)
                     return { ...empty, lastActive };
@@ -1574,8 +1630,6 @@ export function getMcpConfigPathForHome(agentId, home) {
             return path.join(home, '.kiro', 'settings', 'mcp.json');
         case 'goose':
             return path.join(home, '.config', 'goose', 'config.yaml');
-        case 'roo':
-            return path.join(home, '.roo', 'mcp.json');
         case 'antigravity':
             return path.join(home, '.gemini', 'antigravity-cli', 'mcp_config.json');
         case 'grok':
@@ -1612,8 +1666,6 @@ function getProjectMcpConfigPath(agentId, cwd = process.cwd()) {
             return path.join(cwd, '.kiro', 'settings', 'mcp.json');
         case 'goose':
             return path.join(cwd, '.goose', 'config.yaml');
-        case 'roo':
-            return path.join(cwd, '.roo', 'mcp.json');
         case 'antigravity':
             return path.join(cwd, '.gemini', 'antigravity-cli', 'mcp_config.json');
         case 'grok':
@@ -1746,9 +1798,6 @@ export const AGENT_NAME_ALIASES = {
     'kiro-cli': 'kiro',
     goose: 'goose',
     'block-goose': 'goose',
-    roo: 'roo',
-    'roo-code': 'roo',
-    roocode: 'roo',
     antigravity: 'antigravity',
     'google-antigravity': 'antigravity',
     agy: 'antigravity',
@@ -1789,6 +1838,40 @@ export function resolveAgentName(input) {
 export function isAgentName(input) {
     return resolveAgentName(input) !== null;
 }
+/**
+ * Build the deprecation notice lines for an agent, or null if it isn't
+ * deprecated. Split from the printer so tests can assert the content without
+ * capturing stdout. Lines are plain (uncolored) text.
+ */
+export function deprecationNotice(agent) {
+    const dep = AGENTS[agent].deprecated;
+    if (!dep)
+        return null;
+    const name = AGENTS[agent].name;
+    const lines = [
+        `Warning: ${name} was deprecated by ${dep.by} (${dep.date}).`,
+        `  ${dep.reason}`,
+    ];
+    if (dep.replacement) {
+        const rep = AGENTS[dep.replacement];
+        lines.push(`  Consider using ${rep.name} instead:  agents add ${rep.id}`);
+    }
+    if (dep.url)
+        lines.push(`  ${dep.url}`);
+    return lines;
+}
+/**
+ * Print a deprecation warning (yellow) if the agent's registry entry carries a
+ * `deprecated` marker; no-op otherwise. Call from any user entry point that
+ * acts on a chosen agent — install (`agents add`) and `agents teams add`.
+ */
+export function warnAgentDeprecated(agent) {
+    const lines = deprecationNotice(agent);
+    if (!lines)
+        return;
+    for (const line of lines)
+        console.log(chalk.yellow(line));
+}
 /** Format an error message for an unrecognized agent name, listing valid options. */
 export function formatAgentError(agentName, validAgents = ALL_AGENT_IDS) {
     return `Unknown agent '${agentName}'. Valid agents: ${validAgents.join(', ')}`;