@rivus/agent-kit/discovery

FunctionsCopy Anchor Link

detectAgents()Copy Anchor Link

function detectAgents(platform: DiscoveryPlatform, options?: DetectAgentsOptions): Promise<Installation[]>;

Detects each agent from its probe recipe: its command on PATH, its application, configuration and MCP paths, its version (by running the version probe) and its login state (see authProbe). Agents are probed concurrently; every probe command has a time limit and runs without a shell. A check that fails is reported in the installation's problems, and detection goes on. Throws capability-unsupported when a requested agent has no recipe; an abort rejects with signal.reason and stops the running commands.

ParametersCopy Anchor Link

platformCopy Anchor Link

DiscoveryPlatform

options?Copy Anchor Link

DetectAgentsOptions

ReturnsCopy Anchor Link

Promise<Installation[]>

versionFromOutput()Copy Anchor Link

function versionFromOutput(output: CommandOutput): Version | undefined;

Reads a version from a command that exited with 0 and printed something to standard output. Standard error is ignored, because agents print warnings there.

ParametersCopy Anchor Link

outputCopy Anchor Link

CommandOutput

ReturnsCopy Anchor Link

Version | undefined

InterfacesCopy Anchor Link

AuthReadingCopy Anchor Link

What one login check says. method names how the agent is logged in, such as api-key.

PropertiesCopy Anchor Link

loggedInCopy Anchor Link

readonly loggedIn: boolean;

method?Copy Anchor Link

readonly method?: string;

CommandOutputCopy Anchor Link

What a probe command left behind: its exit code and output. Probes that timed out or did not start have none.

PropertiesCopy Anchor Link

codeCopy Anchor Link

readonly code: number | null;

stderrCopy Anchor Link

readonly stderr: string;

stdoutCopy Anchor Link

readonly stdout: string;

DetectAgentsOptionsCopy Anchor Link

PropertiesCopy Anchor Link

agents?Copy Anchor Link

readonly agents?: readonly string[];

Agents to detect, by id or alias; defaults to every agent in providers.discovery, in table order.

authProbe?Copy Anchor Link

readonly authProbe?: "files" | "commands";

Where login state comes from. files (the default) reads only credential files and environment variables, so it works offline and changes nothing. commands also runs each agent's login status command, whose answer wins; see each recipe's auth.command.sideEffects for what that can do.

providers?Copy Anchor Link

readonly providers?: readonly Provider[];

signal?Copy Anchor Link

readonly signal?: AbortSignal;

timeoutMs?Copy Anchor Link

readonly timeoutMs?: number;

Time limit of each probe command; defaults to 5 seconds.

versionProbe?Copy Anchor Link

readonly versionProbe?: boolean;

Whether to run each agent's version probe; defaults to true. With false nothing is run (unless authProbe is commands), so detection has no side effects, and no agent is runnable: at most found. See each recipe's version.sideEffects for what a probe can do.

InstallationCopy Anchor Link

What detection found out about one agent on this machine.

PropertiesCopy Anchor Link

agentCopy Anchor Link

readonly agent: string;

appPath?Copy Anchor Link

readonly appPath?: string;

The first application path that exists.

authCopy Anchor Link

readonly auth: AuthState;

command?Copy Anchor Link

readonly command?: string;

The resolved path of the agent's command on PATH.

displayNameCopy Anchor Link

readonly displayName: string;

evidenceCopy Anchor Link

readonly evidence: readonly Evidence[];

Every observation behind status, in probe order: command, version, application, configuration, MCP.

kindCopy Anchor Link

readonly kind: InstallationKind;

problemsCopy Anchor Link

readonly problems: readonly ProbeProblem[];

Checks that could not complete.

statusCopy Anchor Link

readonly status: DetectionStatus;

version?Copy Anchor Link

readonly version?: Version;

warningsCopy Anchor Link

readonly warnings: readonly string[];

The recipe's caveats about its own facts, and caveats about this run, such as a Windows shim it did not run.

ProbeRecipeCopy Anchor Link

How discovery detects one agent. A recipe is data plus pure parsers; detectAgents does the IO. Built-in recipes are assembled by the shell; a caller supplies its own through provider descriptors, and /testing has the conformance checks a recipe must pass.

PropertiesCopy Anchor Link

agentCopy Anchor Link

readonly agent: string;

appBundleIds?Copy Anchor Link

readonly appBundleIds?: readonly string[];

macOS bundle ids the application must carry, for an app name another product shares. A bundle whose Contents/Info.plist is XML and names another id does not count; one whose id cannot be read counts by its path.

appPathsCopy Anchor Link

readonly appPaths: readonly ProbePath[];

Application paths; the first that exists is the agent's application.

auth?Copy Anchor Link

readonly auth?: AuthProbe;

commandsCopy Anchor Link

readonly commands: readonly string[];

Executable names looked up on PATH, in order; the first found is the agent's command.

configPathsCopy Anchor Link

readonly configPaths: readonly ProbePath[];

Agent-owned state, session or credential paths; exclude homes and files that installers can create.

displayNameCopy Anchor Link

readonly displayName: string;

For a built-in agent, the display name catalog gives it.

home?Copy Anchor Link

readonly home?: HomeRule;

The home rule of an agent that catalog does not know, for paths under its own AgentHome.

kindCopy Anchor Link

readonly kind: InstallationKind;

mcpConfigPathsCopy Anchor Link

readonly mcpConfigPaths: readonly ProbePath[];

Recipe authors must list only agent-owned MCP state, excluding shared, installer-writable configuration.

specificationVersionCopy Anchor Link

readonly specificationVersion: "discovery-v1";

version?Copy Anchor Link

readonly version?: VersionProbe;

Without a version probe, the agent is at most found.

warningsCopy Anchor Link

readonly warnings: readonly string[];

Caveats about the recipe's facts, such as which of them upstream sources do not confirm.

Type AliasesCopy Anchor Link

ProbePathCopy Anchor Link

type ProbePath = 
  | string
  | {
  agentHome: CodingAgentId;
  path?: string;
};

A path a probe checks: ~ or ~/… under the user's home directory, an absolute path, or path (/-separated, relative) under the AgentHome of agentHome, which follows that agent's override variable.

ProbeProblemCopy Anchor Link

type ProbeProblem = StatFailed | CommandFailed | CredentialFileFailed;

A check that could not complete. Detection goes on; the problem is reported with the installation.

ProbeRecipesCopy Anchor Link

type ProbeRecipes = ServiceTable<ProbeRecipe>;

Probe recipes by agent id; supplied to detectAgents.