/**
 * Import existing unmanaged agent installations into agents-cli.
 *
 * Two flavors:
 *
 *  1. Config-only import — moves an agent's config dir (e.g. ~/.openclaw)
 *     into the version structure and symlinks it back. Used by `agents setup`
 *     on first-run when an agent was previously installed via npm/homebrew.
 *
 *  2. Full import — also registers an existing binary install (e.g. a global
 *     `npm i -g openclaw`) under the managed version path so the shim
 *     resolver can find it. This is what `agents import <agent>` does.
 *
 * The binary side never moves files. It creates a thin symlink farm under
 * `~/.agents/.history/versions/<agent>/<version>/` pointing at the original
 * global install, plus a package.json marker so `isVersionInstalled` returns
 * true.
 */
import type { AgentId } from './types.js';
export interface ImportConfigResult {
    success: boolean;
    skipped?: boolean;
    error?: string;
}
export interface ImportBinaryResult {
    success: boolean;
    skipped?: boolean;
    error?: string;
    resolvedFromPath?: string;
}
export declare function isValidImportVersion(version: string): boolean;
/**
 * Move an agent's config dir into the managed version structure and symlink it
 * back to its original location. Sets the imported version as the global
 * default and refreshes the shim so the user's PATH lookup hits the managed
 * version.
 *
 * No-op (returns skipped=true) if the version's config dir is already created.
 */
export declare function importAgentConfig(agentId: AgentId, version: string): Promise<ImportConfigResult>;
/**
 * Wire an imported version into the rest of the system so it behaves the same
 * as a freshly installed version:
 *
 *   - registered as the global default in agents.yaml (so `agents view`
 *     reports it correctly and resolvers find it),
 *   - main shim refreshed (`~/.agents/.cache/shims/<cli>`),
 *   - versioned alias created (`~/.agents/.cache/shims/<cli>@<version>`),
 *   - home-file symlinks (CLAUDE.md / AGENTS.md / etc.) repointed at this
 *     version's home dir.
 *
 * Without this, the binary-only import path would leave the version stranded:
 * isVersionInstalled returns true, but the resolver never picks it. Safe to
 * call multiple times — each underlying function is idempotent.
 */
export declare function finalizeImport(agentId: AgentId, version: string): void;
/**
 * Agent metadata needed by importAgentBinary. Taking these as explicit
 * inputs (rather than looking up AGENTS internally) decouples the symlink
 * farm from the AGENTS registry, which keeps the function pure and avoids
 * fragile coupling in test setups that stub `lib/agents.ts`.
 */
export interface AgentBinarySpec {
    /** Agent id used in the marker package.json (`agents-{agentId}-{version}`). */
    agentId: string;
    /** npm package name (e.g. `openclaw`) — used as the `node_modules/<name>` dir. */
    npmPackage: string;
    /** Binary name on PATH (e.g. `openclaw`) — used as the `.bin/<name>` entry. */
    cliCommand: string;
}
/**
 * Register an existing global npm package install under the managed version
 * path so the shim resolver finds it.
 *
 * Layout produced (everything is a symlink, nothing is copied):
 *
 *   {versionDir}/
 *     package.json                          # marker so isVersionInstalled() is true
 *     home/                                 # empty isolated $HOME for this version
 *     node_modules/{npmPackage}    -> {globalPath}
 *     node_modules/.bin/{cliCommand} -> {binaryEntry}
 */
export declare function importAgentBinary(spec: AgentBinarySpec, version: string, globalPath: string, versionDir: string): ImportBinaryResult;
/**
 * Register an existing installScript-based binary (Grok, Antigravity, Cursor,
 * etc. — anything with `npmPackage: ''` and a curl/brew installer) under the
 * managed version path. Unlike `importAgentBinary` this skips the npm
 * package.json walk and just symlinks the resolved PATH binary directly into
 * `{versionDir}/node_modules/.bin/{cliCommand}`. The symlink is what makes
 * `listInstalledVersions` consider the version Managed.
 *
 * Layout produced:
 *
 *   {versionDir}/
 *     package.json                              # marker (private, imported, from)
 *     home/                                     # empty isolated $HOME
 *     node_modules/.bin/{cliCommand} -> {binaryPath}
 *
 * For agents whose binary lookup is special-cased elsewhere (e.g. Grok's
 * `~/.grok/downloads/`), the symlink is still created — `getBinaryPath` won't
 * read it for those agents, but it documents provenance and lets a future
 * refactor consolidate the binary-resolution registry.
 */
export declare function importInstallScriptBinary(spec: AgentBinarySpec, version: string, binaryPath: string, versionDir: string): ImportBinaryResult;
/**
 * Resolve the on-disk npm package directory for an agent's CLI binary by
 * walking up from the binary, following any symlinks. Returns null if the
 * package can't be identified.
 *
 * Handles the homebrew/global-npm pattern where:
 *   /opt/homebrew/bin/{cli}  ->  ../lib/node_modules/{pkg}/dist/index.js
 */
export declare function resolvePackageDirFromBinary(binaryPath: string): string | null;
/**
 * Seed an ISOLATED version's home from the user's real `~/.<agent>` — the mirror of
 * {@link importAgentConfig}, which adopts.
 *
 * The difference is the whole point: this COPIES and leaves the original in place,
 * never symlinks it, never sets a default, never creates a shim. So an isolated copy
 * can start from the setup the user already has instead of from nothing, which was
 * the only way to get a working sandbox before.
 *
 * Credentials are skipped by default and reported, not silently included. An isolated
 * copy is a separate principal — `agents add --isolated` already tells the user to
 * sign in on first run — and copying tokens into it should be a choice, not a side
 * effect of wanting your settings. `--with-auth` opts in.
 */
export declare function seedIsolatedConfigFromLocal(agentId: AgentId, version: string, opts?: {
    withAuth?: boolean;
    all?: boolean;
}): {
    seeded: boolean;
    from: string;
    to: string;
    skippedAuth: string[];
    skippedRuntime: string[];
    error?: string;
};
