@phnx-labs/agents-cli 1.22.120 → 1.22.121

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

@@ -1,48 +1,17 @@
 import type { AgentConfig, AgentId } from '../types.js';
-/** Represents the installation state of an agent's CLI binary. */
 export interface CliState {
     installed: boolean;
     version: string | null;
     path: string | null;
 }
-/**
- * Minimum Codex CLI version that supports hooks.
- * Mirrored on `AGENTS.codex.capabilities.hooks.since` -- kept exported for
- * legacy import sites that haven't migrated to `supports()` yet.
- */
 export declare const CODEX_HOOKS_MIN_VERSION = "0.116.0";
-/**
- * Synchronous PATH search -- no subprocess. Returns first matching binary path.
- *
- * Skips our own shims dir (`~/.agents/.cache/shims/`) — those shims are
- * dispatch helpers, not real installs. Counting them as installed produced a
- * false positive where agents with NO real binary on the host (e.g. a
- * never-installed Cursor whose only PATH entry was our `cursor-agent` shim
- * dispatcher) showed up under `agents view`'s "Not Managed by Agents CLI"
- * section, even though the user had nothing to import.
- */
 interface NativeBinaryResolutionOptions {
     accept?: (candidate: string) => boolean;
     shimsDir?: string;
     historyDir?: string;
 }
-/**
- * Resolve a PATH candidate to the immutable native executable agents-cli may
- * safely register. An adopted launcher can live outside the shims directory
- * while resolving back into it; in that case its durable adoption record is
- * the source of truth for the original executable.
- */
 export declare function resolveNativeBinaryPath(command: string, candidate: string, options?: NativeBinaryResolutionOptions): string | null;
 export declare function findInPath(command: string, options?: NativeBinaryResolutionOptions): string | null;
-/**
- * Per-harness dispatch data that used to live in `if (agentId === …)` /
- * `switch (agentId)` arms inside this file. These are stable properties of a
- * harness, not per-call-site quirks — a new AgentId must declare every field
- * (the completeness test in agents.test.ts pins that).
- *
- * Left as call-site specials (not registry data): `getAccountInfo` and
- * `readAuthAccountIdentity` — those are parsers, not flags.
- */
 type VersionStdoutMatch = 'semver' | 'openclaw';
 type UnmanagedBinaryResolver = 'path' | 'grok-downloads';
 type McpRegisterPath = 'cli' | 'config';
@@ -50,141 +19,39 @@ type McpAddHttpStyle = 'transport' | 'url';
 type McpAddStdioStyle = 'scope' | 'simple';
 type McpConfigWriteStyle = 'json-mcpServers' | 'yaml-mcp_servers';
 interface AgentRegistryConfig extends AgentConfig {
-    /**
-     * Session-transcript directory as path segments under a HOME root, or null
-     * when this harness has no local session tree `agents` can walk.
-     */
     sessionDir: string[] | null;
-    /** File extension of session transcripts, or null when unknown. */
     sessionFileExt: '.jsonl' | '.json' | null;
-    /** How to parse `cli --version` stdout. */
     versionStdoutMatch: VersionStdoutMatch;
-    /** How to find an unmanaged (non-version-home) binary. */
     unmanagedBinary: UnmanagedBinaryResolver;
-    /**
-     * How `registerMcp` / `unregisterMcp` talk to the harness. `config` writes
-     * the file directly (no `mcp add` CLI); `cli` shells out.
-     */
     mcpRegister: McpRegisterPath;
-    /** Argv shape for `mcp add` over HTTP. */
     mcpAddHttp: McpAddHttpStyle;
-    /** Argv shape for `mcp add` over stdio. */
     mcpAddStdio: McpAddStdioStyle;
-    /** On-disk map key + serialization when writing MCP config directly. */
     mcpConfigWrite: McpConfigWriteStyle;
 }
-/**
- * Master registry of all supported agents keyed by AgentId.
- *
- * Each entry defines the agent's CLI command, npm package, config directory layout,
- * instructions file name, slash-command format, and capability flags. This is the
- * single source of truth for agent metadata consumed throughout the codebase.
- */
 export declare const AGENTS: Record<AgentId, AgentRegistryConfig>;
-/** All current and legacy agent IDs derived from the AGENTS registry. */
 export declare const ALL_AGENT_IDS: AgentId[];
-/**
- * Agents the routine daemon can fire locally. Lives here (not runner.ts) so
- * routines.ts can import it for schedule-time validation without a circular
- * import (runner.ts already imports from routines.ts).
- *
- * This is a curated subset of AGENT_COMMANDS, not "every harness that can run
- * headlessly". Expanding it is a product change. Argv itself is baked from
- * AGENT_COMMANDS in daemon/runner.ts bakeRoutineArgv — do not reintroduce a
- * second token table.
- */
 export declare const ROUTINE_AGENT_IDS: readonly string[];
-/** Agents that can receive managed installs, imports, and resource sync writes. */
 export declare const MANAGED_AGENT_IDS: AgentId[];
-/**
- * A self-updating agent is a single global binary installed by an official
- * `curl … | sh` / `brew install` script that carries NO version token — the
- * installer can only ever fetch the *current* release, and the binary then keeps
- * itself up to date in place (droid, grok, antigravity, cursor, hermes,
- * goose). There is no semver to pin, so agents-cli must not model these as
- * having multiple installable version-homes the way it does for npm-packaged
- * agents (claude, codex, kimi, …).
- *
- * The predicate is `!npmPackage && installScript && !installScript.includes('VERSION')`:
- *   - `npmPackage` empty       → not installed from npm, so `agents add x@1.2.3`
- *                                can't resolve a registry version.
- *   - `installScript` present  → it IS installed by a script (not unmanaged).
- *   - no `VERSION` placeholder → the script has no slot for a pinned version
- *                                (contrast: an installer templated with `VERSION`
- *                                could pin, and is NOT self-updating).
- *
- * Route every "is this a pinnable, multi-version agent?" decision through here —
- * never a scattered `agent === 'droid'`.
- */
 export declare function isSelfUpdatingAgent(agent: AgentId): boolean;
 export declare function isAgentHardDeprecated(agent: AgentId): boolean;
-/** Get the chalk color function for an agent. Works for any AgentId or SessionAgentId. */
 export declare function colorAgent(agentId: string): (s: string) => string;
-/** Return the agent's display name, colored. */
 export declare function agentLabel(agentId: string): string;
-/** Check whether the given agent's CLI binary is present on PATH. */
 export declare function isCliInstalled(agentId: AgentId): Promise<boolean>;
-/** Return the installed CLI version for the given agent, or null if not found. */
 export declare function getCliVersion(agentId: AgentId): Promise<string | null>;
-/** Return the absolute path to the agent's CLI binary on PATH, or null. */
 export declare function getCliPath(agentId: AgentId): Promise<string | null>;
-/**
- * Resolve the full CLI state for an agent: whether it is installed, its version,
- * and the path to the binary. Checks version-managed installs first, then falls
- * back to a plain PATH lookup.
- */
 export declare function getCliState(agentId: AgentId): Promise<CliState>;
-/**
- * Resolve the agent's OWN install — the one agents-cli does not manage — by plain
- * PATH lookup, ignoring the version dirs entirely.
- *
- * Callers that specifically mean "the user's own globally-installed CLI" must use
- * this rather than `getCliState`, whose managed fast path reports an installed
- * version (any version dir, in readdir order) and would therefore hand back an
- * isolated copy — a copy that is deliberately unreachable from PATH — labelled as
- * the global install.
- */
 export declare function getUnmanagedCliState(agentId: AgentId): Promise<CliState>;
-/** Resolve CLI state for all registered agents in parallel. */
 export declare function getAllCliStates(): Promise<Partial<Record<AgentId, CliState>>>;
-/** Info about an existing unmanaged agent installation. */
 interface UnmanagedInstall {
     agentId: AgentId;
     configDir: string;
     version: string | null;
 }
-/**
- * Agents that `agents setup` probes for pre-existing native installations
- * (i.e., a config dir present before agents-cli took over). Derived from
- * `sessionDir` so a new harness cannot be walkable yet missing from setup.
- */
 export declare const UNMANAGED_DETECTION_CANDIDATES: AgentId[];
-/**
- * Detect existing agent installations that are NOT yet managed by agents-cli.
- * Returns agents whose config dir exists as a real directory (not a symlink).
- */
 export declare function getUnmanagedAgentInstalls(): Promise<UnmanagedInstall[]>;
-/** Create the agent's slash-commands directory if it does not exist. */
 export declare function ensureCommandsDir(agentId: AgentId): void;
-/** Create the agent's skills directory if it does not exist. */
 export declare function ensureSkillsDir(agentId: AgentId): void;
-/**
- * The agent's config-dir name relative to $HOME — e.g. '.claude',
- * '.gemini/antigravity-cli', '.config/amp', '.kimi-code'.
- *
- * Path segment to join onto a (version) home root when locating an agent's
- * commands/skills/plugins. Do NOT hardcode `.${agentId}`: it is wrong for
- * every agent whose config dir is nested or under ~/.config — antigravity
- * (~/.gemini/antigravity-cli), amp (~/.config/amp), goose (~/.config/goose),
- * kimi (~/.kimi-code). Mirrors the shim configDirName derivation in shims.ts.
- *
- * Relativized against the module-level HOME constant (the same value used to
- * build every `configDir`), NOT a fresh `os.homedir()` — so the result stays a
- * clean relative name even when HOME is overridden after module load (tests,
- * sandboxes). Using `os.homedir()` here would yield `../../real/home/.claude`.
- */
 export declare function agentConfigDirName(agentId: AgentId): string;
-/** Account identity and billing information extracted from an agent's auth config. */
 export interface AccountInfo {
     accountKey: string | null;
     usageKey: string | null;
@@ -203,145 +70,31 @@ export interface AccountInfo {
     organizationType?: string | null;
     organizationName?: string | null;
 }
-/**
- * Human-readable label for a Claude account's organizationType as read from
- * .claude.json's oauthAccount ("claude_team" -> "Team"). Unrecognized values
- * (future tiers) are rendered by stripping the "claude_" prefix and
- * title-casing the rest — an unfamiliar-but-visible label beats silence.
- * Returns null for missing input.
- */
 export declare function formatClaudeOrgLabel(orgType: string | null | undefined): string | null;
-/**
- * Short badge identifying which ORG an account belongs to — "Turing Labs" for a
- * multi-seat Team/Enterprise org, whose name is real identity that disambiguates
- * a Team seat from a same-email personal plan. Returns null for personal plans
- * (Max/Pro/Free): the tier label now lives in the aligned plan column, so a badge
- * would only duplicate it, and a personal org's name is auto-generated boilerplate
- * ("<email>'s Organization"), not identity. Also null when the account carries no
- * organizationType (signed out, non-Claude agents, configs predating the field).
- */
 export declare function accountOrgBadge(info?: Pick<AccountInfo, 'organizationType' | 'organizationName'> | null): string | null;
-/** Agents whose local credential formats expose enough state for account selection. */
 export declare const ACCOUNT_INSPECTION_AGENT_IDS: readonly ["claude", "codex", "cursor", "grok", "antigravity", "kimi", "droid", "opencode", "muse"];
-/** Whether agents-cli can determine this agent's per-version sign-in state. */
 export declare function supportsAccountInspection(agentId: AgentId): boolean;
-/**
- * Human-readable account identity shared by every account-aware surface.
- * Prefer email, append a multi-seat Claude organization name when present,
- * then fall back to a non-secret account id or a generic signed-in label.
- */
 export declare function accountDisplayLabel(info?: Pick<AccountInfo, 'email' | 'accountId' | 'signedIn' | 'organizationType' | 'organizationName'> | null): string;
-/** Return the email address associated with the agent's auth config, or null. */
 export declare function getAccountEmail(agentId: AgentId, home?: string): Promise<string | null>;
-/**
- * Extract full account information (identity, plan, usage status, credits) from
- * the agent's local auth/config files. Supports Claude, Codex, and Gemini.
- */
-/**
- * Resolve a file-auth agent's credential file. Sign-in is account-global, but
- * each installed version gets an isolated home; the credential physically lives
- * only in the home the user logged in under (the one the `~/.<config>` symlink
- * targets). Check the per-version `base` first, then fall back to the active
- * config location under the real HOME so every installed version reflects the
- * true account state (droid/antigravity/kimi all stored login per-version-home
- * and showed non-active versions as "not signed in"). Returns the first
- * existing path, or null.
- */
-/** True when `dir` is under the per-account slot root (`~/.agents/.history/accounts/`). */
 export declare function isAccountSlotDir(dir: string): boolean;
-/** Where an agent's credential file lives, split into the per-version copy and
- *  the active/global copy under the real HOME. */
 export interface CredentialPresence {
-    /** The credential file exists inside the passed version home. */
     perVersion: boolean;
-    /** The credential file exists under the active/global HOME (the one the login
-     *  symlink actually targets), independent of the version home. */
     active: boolean;
-    /** Whether agents-cli knows WHERE this agent's credential lives at all — i.e.
-     *  the agent has an entry in {@link CREDENTIAL_FILE_SEGMENTS}. When false both
-     *  probes are trivially false because there is nothing to look for, so absence
-     *  is NOT evidence of a logout and no caller may treat it as provable.
-     *
-     *  This is deliberately separate from `supportsAccountInspection`: the two
-     *  registries move independently, and an agent has already been added to the
-     *  inspection set without a credential path (cursor), which without this flag
-     *  produced a false "logged out" critical for every installed version. */
     knownLocation: boolean;
 }
-/**
- * File-presence probe for an agent's credential, split by location: whether it
- * exists in a SPECIFIC version home (`perVersion`) and whether it exists under
- * the active/global HOME (`active`). A logged-out claim is only *provable* when
- * BOTH are absent — a version that merely lacks its own copy but shares the
- * global login is signed in, not logged out. Pure file existence; no decrypt,
- * no network, no keychain prompt. Agents with no inspectable identity return
- * `{ perVersion: false, active: false }` and must NEVER yield a provable-logout
- * claim (the caller gates on {@link supportsAccountInspection}).
- */
 export declare function credentialPresence(agentId: AgentId, versionHome: string): CredentialPresence;
-/** Decrypted contents of Droid's auth.v2.file (subset we consume). */
 interface DroidAuthPayload {
     access_token?: string;
     active_organization_id?: string | 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. Every failure (missing key file — e.g. a keyring-v2/legacy
- * login with no on-disk key, a bad GCM tag, or malformed JSON) returns null.
- * Never throws. Shared by account identity below and the Droid usage fetcher
- * in usage.ts.
- */
 export declare function decryptDroidAuthPayload(base: string): DroidAuthPayload | null;
-/**
- * Stable account identity for a *file-auth* agent's credential directory
- * (droid / kimi / antigravity), or null when the directory holds no decodable
- * account claim. Unlike a naive top-level JSON key-scan (which matched NO real
- * credential file), this decrypts / decodes each agent's REAL on-disk format so
- * the identity resolves against production credentials:
- *   - droid: AES-256-GCM auth.v2.file (+ auth.v2.key) -> WorkOS access-token JWT
- *     -> email / org_id / sub.
- *   - kimi: credentials/kimi-code.json -> access-token JWT -> user_id / sub.
- *   - antigravity: antigravity-oauth-token -> token.refresh_token -> JWT sub
- *     when the token is a JWT, else a SHA-256 hash of the raw refresh-token
- *     value (opaque Google consumer tokens are stable per login — hashed so
- *     the identity key, which is persisted as a usage-cache key, never carries
- *     a live credential).
- * Two directories for the SAME account compare equal; two DIFFERENT accounts
- * compare distinct. Used by carryForwardAuthFiles to refuse overwriting one
- * account's login with a credential that belongs to a DIFFERENT account
- * (RUSH-1764). Never throws.
- */
 export declare function readAuthAccountIdentity(agent: AgentId, configDir: string): string | null;
-/**
- * Antigravity (`agy`) stores its OAuth token via the Go keyring library
- * (zalando/go-keyring), which is platform-split:
- *
- *   - macOS: login keychain, service `gemini`, account `antigravity` — no file.
- *   - Linux with Secret Service (libsecret / gnome-keyring): attributes
- *     service=`gemini`, username=`antigravity` (go-keyring's Secret Service
- *     mapping of service+user). Prefer this over the file when a keyring
- *     daemon is running.
- *   - Linux without Secret Service: file fallback at
- *     `~/.gemini/antigravity-cli/antigravity-oauth-token`.
- *
- * Probe the OS keyring for existence after the file check. On macOS,
- * `security find-generic-password` without `-w` is metadata-only (never
- * prompts). On Linux, `secret-tool lookup` exit 0 means the item exists
- * (stdout is the secret — discarded, never logged). Cached per process —
- * the keyring is account-global, so one probe covers every installed version.
- * Returns false when the platform has no probe (Windows) or the tool is
- * missing. Guard with `AGENTS_NO_KEYCHAIN_PROBE=1` for hermetic tests.
- */
 export declare function antigravityOsKeyringProbe(platform?: NodeJS.Platform): {
     cmd: string;
     args: string[];
 } | null;
 /** @internal test hook — clear the per-process keyring probe cache. */
 export declare function __resetAntigravityKeychainCacheForTest(): void;
-/** The XDG base dirs OpenCode reads, and the env var that overrides each. */
 declare const OPENCODE_XDG_DIRS: {
     readonly data: {
         readonly env: "XDG_DATA_HOME";
@@ -352,93 +105,14 @@ declare const OPENCODE_XDG_DIRS: {
         readonly fallback: readonly [".local", "state"];
     };
 };
-/**
- * Resolve one of OpenCode's (sst/opencode) XDG-rooted files.
- *
- * OpenCode keeps provider credentials under `$XDG_DATA_HOME/opencode/` and TUI
- * state under `$XDG_STATE_HOME/opencode/`, defaulting to `~/.local/share` and
- * `~/.local/state` on EVERY platform — its `xdg-basedir` dependency does not
- * special-case macOS, so there is no `~/Library/Application Support` variant.
- * Both roots are account-global (not per-version), matching how
- * `session/discover.ts` already resolves `~/.local/share/opencode/opencode.db`.
- *
- * Resolution order, first existing wins:
- *   1. `<base>/<fallback>/opencode/<file>` — the passed per-version home. This is
- *      primarily a test hook (suites write a hermetic file under a temp home)
- *      but also covers any relocated install.
- *   2. `$XDG_<KIND>_HOME/opencode/<file>` — an explicit XDG override, exactly
- *      what OpenCode itself honours.
- *   3. `<realHome>/<fallback>/opencode/<file>` — the active default, under
- *      `AGENTS_REAL_HOME` or `os.homedir()`, so every installed version reflects
- *      the one account-global state (same fallback shape as
- *      resolveAccountCredentialPath).
- * Returns the first existing path, or null. Never throws.
- */
 export declare function resolveOpenCodeXdgPath(base: string, kind: keyof typeof OPENCODE_XDG_DIRS, file: string): string | null;
-/** OpenCode's signed-in identity, as far as `auth.json` can describe it. */
 export interface OpenCodeIdentity {
-    /** Sorted, "+"-joined provider ids holding a valid credential. */
     providers: string;
-    /** Account email, when some OAuth credential's token carries the claim. */
     email: string | null;
-    /** Plan tier from the same token (e.g. `Pro`), when present. */
     plan: string | null;
 }
-/**
- * OpenCode's account identity, read from `auth.json`.
- *
- * The provider join (`"meta+openai+opencode-go"`) is the stable key: OpenCode is
- * a multi-provider harness, so "which providers are configured" is what actually
- * identifies an install, and `session/discover.ts` indexes sessions by it.
- * Providers that sign in over OAuth additionally hand OpenCode a token with real
- * identity claims, so the email and plan are surfaced alongside it instead of
- * leaving `agents view` showing a bare `id:` key for a login that knows exactly
- * whose it is. Providers are walked in sorted order so a multi-OAuth install
- * resolves to the same email on every machine.
- *
- * This is the ONLY correct source for an OpenCode "account". OpenCode's SQLite
- * `opencode.db` also carries `account`/`account_state`/`control_account` tables,
- * but on a real, actively-used install (yosemite-s1, 1.16.0, 35 applied
- * migrations) all three are permanently empty — no migration ever populates
- * them, and no session has ever written a row. Reading from them instead of
- * `auth.json` always yields `undefined`, credential or not.
- *
- * Sync (`fs.readFileSync`), no network. Returns undefined when `auth.json` is
- * missing, unreadable, or carries no valid credential.
- */
 export declare function resolveOpenCodeIdentity(base: string): OpenCodeIdentity | undefined;
-/**
- * The provider join alone — the value `session/discover.ts` indexes sessions by,
- * kept as its own entry point so callers that only need the key do not have to
- * know about the OAuth claim walk.
- */
 export declare function resolveOpenCodeAccountId(base: string): string | undefined;
-/**
- * Whether a Claude version home's credential file is present but carries no
- * token — the "must have a real credential" floor (see
- * `isValidOpenCodeCredential`) applied to claude.
- *
- * A FAILED OAuth refresh leaves exactly this state behind: Claude Code rewrites
- * `.claude/.credentials.json` with `accessToken: ""`, `refreshToken: ""` and
- * `expiresAt: 0`, keeping only the descriptive fields (`subscriptionType`,
- * `rateLimitTier`, `refreshTokenExpiresAt`). Everything we derive from
- * `.claude.json` — email, plan — still looks healthy, so the install reported
- * `signedIn: true`, `agents view` drew usage bars for it, and balanced rotation
- * (whose `authValid` is just "email present") kept picking it — every pick dying
- * at spawn on "OAuth session expired and could not be refreshed".
- *
- * Only decidable off macOS: there the login Keychain is the canonical store and
- * this file is not authoritative, and probing the Keychain would raise an
- * authorization sheet per installed version on every `agents run` — the reason
- * rotation stopped calling `isClaudeAuthValid` at all. Off macOS the file IS the
- * only store, so a missing or token-less file is proof of signed-out — unless a
- * Linux setup-token (`.claude/.oauth_token`) is present, which the shim exports
- * as `CLAUDE_CODE_OAUTH_TOKEN` and can authenticate the run without
- * `.credentials.json`. `platform` is a parameter so both branches are testable
- * on any host.
- *
- * Sync, no Keychain, no network — safe on the `agents run` hot path.
- */
 export declare function isClaudeCredentialFileBlank(base: string, platform?: NodeJS.Platform): boolean;
 /**
  * Identity of the Claude account a version home is (or was) logged into, read
@@ -457,50 +131,19 @@ export interface ClaudeHomeIdentity {
     organizationId: string | null;
     organizationName: string | null;
     organizationType: string | null;
-    /**
-     * Org-scoped identity — the rate-limit bucket, and the correct key to group by.
-     * Two orgs under one email (a Team seat and a personal Max plan) are separate
-     * buckets and MUST stay distinct; see `candidateIdentity` in lib/rotate.ts.
-     */
     usageKey: string | null;
-    /** Account+org identity, narrower than `usageKey`. */
     accountKey: string | null;
 }
-/** A version home's `.claude.json` plus the identity derived from it. */
 interface ClaudeHomeConfig {
-    /** The config file actually read. */
     path: string;
     config: Record<string, any>;
     identity: ClaudeHomeIdentity;
 }
-/**
- * Read a Claude home's config and account identity. Returns null when the home has
- * no readable `.claude.json`, or has one with no `oauthAccount` (never signed in).
- *
- * Sync because the session scanner calls it once per home on a hot path, and the
- * file is a few KB of local JSON. No Keychain access — see `getAccountInfo`.
- */
 export declare function readClaudeHomeConfig(base: string): ClaudeHomeConfig | null;
 export declare function getAccountInfo(agentId: AgentId, home?: string): Promise<AccountInfo>;
-/**
- * Determine when the agent was last used by checking session file mtimes,
- * falling back to config mtime.
- *
- * The session walk stats every transcript under the home's session dir —
- * thousands of files on long-lived installs — and `agents run` rotation calls
- * this once per installed version on every launch. The walk result is cached
- * on disk for a short window so back-to-back launches skip it entirely.
- * Cache read/write is best-effort: any failure falls back to walking.
- */
 export declare function resolveLastActive(agentId: AgentId, base: string, configPath?: string, cachePath?: string, now?: Date): Date | null;
-/**
- * Quick count of session files for an agent (without full DB scan).
- * Used during init to show approximate session count to user.
- */
 export declare function countSessionFiles(agentId: AgentId): number;
-/** Decode the payload section of a JWT token without verifying its signature. */
 export declare function decodeJwtPayload(token: string): Record<string, any> | null;
-/** Register an MCP server with an agent's CLI via `mcp add`. */
 export declare function registerMcp(agentId: AgentId, name: string, command: string, scope?: 'user' | 'project', transport?: string, options?: {
     home?: string;
     binary?: string;
@@ -509,7 +152,6 @@ export declare function registerMcp(agentId: AgentId, name: string, command: str
     success: boolean;
     error?: string;
 }>;
-/** Unregister (remove) a named MCP server from an agent's CLI config. */
 export declare function unregisterMcp(agentId: AgentId, name: string, options?: {
     home?: string;
     binary?: string;
@@ -517,34 +159,23 @@ export declare function unregisterMcp(agentId: AgentId, name: string, options?:
     success: boolean;
     error?: string;
 }>;
-/** Result of an MCP registration or removal operation targeting a specific agent and optional version. */
 export interface McpTargetOperationResult {
     agentId: AgentId;
     version?: string;
     success: boolean;
     error?: string;
 }
-/**
- * Register an MCP server across multiple agent targets, including both direct
- * (non-version-managed) agents and specific version-managed installs.
- */
 export declare function registerMcpToTargets(targets: {
     directAgents: AgentId[];
     versionSelections: Map<AgentId, string[]>;
 }, name: string, command: string, scope?: 'user' | 'project', transport?: string, options?: {
     headers?: Record<string, string>;
 }): Promise<McpTargetOperationResult[]>;
-/**
- * Unregister an MCP server from multiple agent targets, including both direct
- * agents and specific version-managed installs.
- */
 export declare function unregisterMcpFromTargets(targets: {
     directAgents: AgentId[];
     versionSelections: Map<AgentId, string[]>;
 }, name: string): Promise<McpTargetOperationResult[]>;
-/** Scope at which an MCP server is registered: user-global or per-project. */
 type McpScope = 'user' | 'project';
-/** Describes an MCP server discovered in an agent's config, with its scope and command. */
 interface InstalledMcp {
     name: string;
     scope: McpScope;
@@ -558,62 +189,16 @@ interface McpConfigEntry {
     type?: string;
     url?: string;
 }
-/**
- * Strip JSON comments for JSONC parsing.
- * Only removes comments outside of strings.
- *
- * Exported because the MCP writer needs the SAME parser the reader uses: a
- * naive `//`-to-end-of-line regex eats the `//` inside
- * `"$schema": "https://opencode.ai/config.json"`, which every opencode-generated
- * config carries.
- */
 export declare function stripJsonComments(content: string): string;
-/**
- * Get user-scoped MCP config path for an agent.
- *
- * All three MCP path resolvers read `MCP_TARGETS`, so the file the writer
- * targets, the file the parser reads, and the file the staleness detector
- * watches cannot drift apart. An agent with no MCP target keeps the historical
- * settings.json default so old configs still parse.
- */
 export declare function getUserMcpConfigPath(agentId: AgentId): string;
-/**
- * Get MCP config path for a specific HOME directory (used for version-managed agents).
- */
 export declare function getMcpConfigPathForHome(agentId: AgentId, home: string): string;
-/**
- * Get project-scoped MCP config path for an agent.
- */
 export declare function getProjectMcpConfigPath(agentId: AgentId, cwd?: string): string;
-/**
- * Parse MCP config based on agent type.
- */
 export declare function parseMcpConfig(agentId: AgentId, configPath: string): Record<string, McpConfigEntry>;
-/**
- * List installed MCP servers with scope information.
- * Pass options.home to read from a version-managed agent's home directory.
- */
 export declare function listInstalledMcpsWithScope(agentId: AgentId, cwd?: string, options?: {
     home?: string;
 }): InstalledMcp[];
-/**
- * Resolve a user-provided agent name (alias, shorthand, or canonical) to its AgentId.
- * Tolerates a single typo (insertion/deletion/substitution/transposition) against
- * canonical ids and aliases — `cladue` -> claude, `kim` -> kimi, `codx` -> codex —
- * but only when the correction is unambiguous (all distance-1 candidates agree on
- * one agent). Two-letter shorthands are excluded as fuzzy candidates.
- */
 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;
-/**
- * Split a CLI-provided `<agent>[@<version>][#<label>]` spec into its bare agent
- * id, optional exact version token, and optional account label, the same way
- * `agents run` does — NOT the
- * agent-spec qualifier engine (`@latest`/`@all`), which enumerates installed
- * versions for read/diagnostic commands, not a single launch target. Returns an
- * error message rather than throwing so callers decide exit-vs-continue.
- */
 export declare function parseAgentVersionSpec(raw: string): {
     agent: AgentId;
     version?: string;
@@ -621,20 +206,9 @@ export declare function parseAgentVersionSpec(raw: string): {
 } | {
     error: string;
 };
-/**
- * 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;
 export declare function hardDeprecationNotice(agent: AgentId): string[] | null;
 export declare function hardDeprecationError(agent: AgentId): string;
-/**
- * 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 {};