#Module: install

#Interfaces

#DoctorDurableStateReport

#Properties

#diagnostics

readonly diagnostics: readonly Diagnostic[]

#directory

readonly directory: string

#exists

readonly exists: boolean

#findings

readonly findings: readonly DoctorDurableStateStore[]

#ownership

readonly ownership: "derived" | "marker" | "unowned" | "unrecorded"

#ownershipReason?

readonly optional ownershipReason?: string

#purgeable

readonly purgeable: boolean

#servers

readonly servers: readonly string[]

#stateSource

readonly stateSource: "native" | "derived"

#status

readonly status: "warnings" | "known"

#summary

readonly summary: object

#bytes

readonly bytes: number

#stores

readonly stores: number

#writable

readonly writable: boolean

---

#DoctorDurableStateStore

#Properties

#bytes

readonly bytes: number

Main database plus any present -wal and -shm sidecars.

#file

readonly file: string

#mtime

readonly mtime: string

#path

readonly path: string

---

#DoctorEndpointReport

#Properties

#diagnostics

readonly diagnostics: readonly Diagnostic[]

#directory

readonly directory: string

#findings

readonly findings: readonly DoctorFinding[]

#status

readonly status: "failed" | "skipped" | "warnings" | "healthy"

#summary

readonly summary: object

#live

readonly live: number

#staleLocks

readonly staleLocks: number

#staleSockets

readonly staleSockets: number

---

#DoctorFinding

#Properties

#commit?

readonly optional commit?: string

Git commit of a staged Cursor marketplace repository.

#durableState?

readonly optional durableState?: DoctorDurableStateReport

#durableStates?

readonly optional durableStates?: readonly DoctorDurableStateReport[]

Every current per-server state root, deduplicated by directory.

#enabled?

readonly optional enabled?: boolean

Claude only: the row's enabled flag from claude plugin list --json. false sets state: 'disabled' — the copy is installed but switched off, so none of it reaches a session until claude plugin enable runs.

#entry?

readonly optional entry?: string

#errors?

readonly optional errors?: readonly string[]

The host's own load errors, verbatim (claude plugin list --json errors); present only when the host refused to load this plugin, which also sets state: 'failed'.

#hooks?

readonly optional hooks?: CursorHooksRegistration

Cursor plugin hook registration proof (.cursor-plugin/plugin.json installs only).

#launch?

readonly optional launch?: CursorAgentPluginsLaunch

Agent Plugins stdio launch proof for Cursor (root plugin.json installs with stdio servers only).

#manifest?

readonly optional manifest?: string

#marketplace?

readonly optional marketplace?: string

#name?

readonly optional name?: string

#operatorEnv?

readonly optional operatorEnv?: DoctorOperatorEnvReport

The operator .env layer the installed pack's shells read at launch (#469); names and counts only, never values.

#path?

readonly optional path?: string

#pluginId?

readonly optional pluginId?: string

Grok Bot only: the server-assigned plugin id from Grok Bot's skill index.

#receipt?

readonly optional receipt?: DoctorReceiptSummary

The in-tree install receipt of a Cursor local copy, when it carries one.

#runtime?

readonly optional runtime?: DoctorRuntimeStatus

#state

readonly state: DoctorFindingState

#version?

readonly optional version?: string

---

#DoctorGrokBotSideload

grokbot receipts: what install grokbot sideloaded and which parts Grok Bot still has (AB7335).

#Extends

• GrokBotSideloadInspection

#Properties

#cacheCopy

readonly cacheCopy: boolean

#Inherited from

GrokBotSideloadInspection.cacheCopy

#cachePath

readonly cachePath: string

#cloneActive

readonly cloneActive: boolean

#Inherited from

GrokBotSideloadInspection.cloneActive

#commit

readonly commit: string

#listed

readonly listed: boolean

#Inherited from

GrokBotSideloadInspection.listed

#loaded

readonly loaded: boolean

Grok Bot's plugin index names the cache copy: the account lists the plugin and Grok Bot loaded this copy.

#Inherited from

GrokBotSideloadInspection.loaded

#manifest

readonly manifest: string

#pluginFolder

readonly pluginFolder: boolean

#Inherited from

GrokBotSideloadInspection.pluginFolder

#pluginPath

readonly pluginPath: string

#repo

readonly repo: string

#slug

readonly slug: string

---

#DoctorHostProbe

#Properties

#evidence?

readonly optional evidence?: "directory"

#status

readonly status: DoctorHostProbeStatus

#version?

readonly optional version?: string

---

#DoctorHostReport

#Properties

#bundle?

readonly optional bundle?: DoctorFinding & object

#Type Declaration

#bundleRoot?

readonly optional bundleRoot?: string

#comparison?

readonly optional comparison?: DoctorInstallComparison

#hostValidation?

readonly optional hostValidation?: readonly DoctorHostValidation[]

Claude only: host validator reports for the bundle and every installed copy, when claude is available.

#lifecycle?

readonly optional lifecycle?: DoctorLifecycle

#marketplace?

readonly optional marketplace?: string

#diagnostics

readonly diagnostics: readonly Diagnostic[]

#host

readonly host: "grokbot" | DoctorHost

#inventory

readonly inventory: DoctorInventory

#probe

readonly probe: DoctorHostProbe

#receipts

readonly receipts: readonly DoctorReceiptFinding[]

Agent Bundle store receipts under the host root, cross-checked against the host's inventory.

---

#DoctorHostValidation

One claude plugin validate pass (the same runner validate --artifact uses: plugin.json then marketplace.json, --strict, --json on 2.1.259+) over the built bundle or one installed copy of it.

#Extends

• ClaudePluginValidationReport

#Properties

#copy

readonly copy: "installed" | "bundle"

bundle: the --from bundle root; installed: a copy the host lists for this plugin.

#diagnostics

readonly diagnostics: readonly Diagnostic[]

#Inherited from

ClaudePluginValidationReport.diagnostics

#host

readonly host: "claude"

#Inherited from

ClaudePluginValidationReport.host

#load?

readonly optional load?: ClaudePluginLoadCheck

The load check that follows the validation runs. Absent when the CLI was unavailable, a validation run itself failed (AB6022), the caller opted out, or the bundle has no readable .claude-plugin/plugin.json name to look for in the listing.

#Inherited from

ClaudePluginValidationReport.load

#pluginDirectory

readonly pluginDirectory: string

#scope?

readonly optional scope?: string

Claude install scope of an installed copy.

#status

readonly status: ClaudePluginValidationStatus

#Inherited from

ClaudePluginValidationReport.status

#target

readonly target: string

#Inherited from

ClaudePluginValidationReport.target

#version?

readonly optional version?: string

#Inherited from

ClaudePluginValidationReport.version

---

#DoctorInstallComparison

Installed copy versus the built artifact: current (same content), stale (same version, different content), version-mismatch, foreign (a directory at the install path that is not an agent-bundle install of this plugin), load-failed (the host lists the copy but refused to load it; errors carries its message), not-installed, or unknown when the host inventory could not be read.

#Properties

#artifactContentHash

readonly artifactContentHash: string

#enabled?

readonly optional enabled?: boolean

Claude only: false when the host lists the compared copy as disabled (AB7327).

#errors?

readonly optional errors?: readonly string[]

Host load errors for a load-failed copy, verbatim from claude plugin list --json.

#installedContentHash?

readonly optional installedContentHash?: string

#installedPath?

readonly optional installedPath?: string

#installedVersion?

readonly optional installedVersion?: string

#ownership?

readonly optional ownership?: InstalledTreeOwnership | "host"

Who owns the installed copy: an agent-bundle receipt, a foreign directory, or the host's own cache.

#status

readonly status: DoctorInstallComparisonStatus

---

#DoctorInventory

#Properties

#findings

readonly findings: readonly DoctorFinding[]

#status

readonly status: DoctorInventoryStatus

---

#DoctorLifecycle

placed (bytes at the host's install location) → registered (the host's registry names the plugin) → enabled (the host reports it enabled/trusted) → active (loaded by a live host process), each observed or typed unavailable per host (#101).

#Properties

#active

readonly active: DoctorLifecycleObservation

#enabled

readonly enabled: DoctorLifecycleObservation

#placed

readonly placed: DoctorLifecycleObservation

#registered

readonly registered: DoctorLifecycleObservation

#stage

readonly stage: DoctorLifecycleStage

---

#DoctorOperatorEnvFile

One operator env file of an installed pack: present (with its variable count) or absent.

#Properties

#path

readonly path: string

#state

readonly state: "absent" | "unreadable" | "present"

#variables?

readonly optional variables?: number

The number of variables the file declares; never their names or values.

---

#DoctorOperatorEnvReport

#Properties

#diagnostics

readonly diagnostics: readonly Diagnostic[]

#files

readonly files: readonly DoctorOperatorEnvFile[]

#status

readonly status: "absent" | "present" | "warnings"

---

#DoctorOptions

#Properties

#commandRunner?

readonly optional commandRunner?: DoctorCommandRunner

#endpointDirectory?

readonly optional endpointDirectory?: string

#environment?

readonly optional environment?: Readonly<ProcessEnv>

Process environment consulted for host cache roots (CODEX_HOME); defaults to process.env.

#from?

readonly optional from?: string

#home?

readonly optional home?: string

#hosts?

readonly optional hosts?: readonly ("grokbot" | DoctorHost)[]

#platform?

readonly optional platform?: Platform

---

#DoctorReceiptFinding

#Properties

#contentHash

readonly contentHash: string

#format

readonly format: string

#installedAt

readonly installedAt: string

#mode

readonly mode: InstallReceiptMode

#path

readonly path: string

#plugin

readonly plugin: string

#registrations

readonly registrations: readonly InstallRegistration[]

#scope

readonly scope: InstallReceiptScope

#sideload?

readonly optional sideload?: DoctorGrokBotSideload

#state

readonly state: "unknown" | "consistent" | "orphaned"

#updatedAt

readonly updatedAt: string

#version

readonly version: string

---

#DoctorReceiptSummary

The install receipt an inventoried Cursor local copy carries, as read.

#Properties

#contentHash

readonly contentHash: string

#format

readonly format: string

#installedAt

readonly installedAt: string

#mode

readonly mode: InstallReceiptMode

#scope

readonly scope: InstallReceiptScope

#updatedAt

readonly updatedAt: string

---

#DoctorReport

#Properties

#diagnostics

readonly diagnostics: readonly Diagnostic[]

#endpoints

readonly endpoints: DoctorEndpointReport

#hosts

readonly hosts: readonly DoctorHostReport[]

#summary

readonly summary: object

#errors

readonly errors: number

#infos

readonly infos: number

#warnings

readonly warnings: number

#web?

readonly optional web?: DoctorWebSurface

Present when --from points at a bundle whose agent-bundle.manifest.json has a web section.

---

#DoctorWebSurface

#Properties

#apps

readonly apps: number

#line

readonly line: string

web: <n> App(s) exposed — run <plugin> web

#plugin

readonly plugin: string

---

#InstallBundleOptions

sideload, sideloadRepo, and sideloadSlug apply to the grokbot host only (install/grokbot-sideload.ts).

#Extends

• GrokBotSideloadOptions

#Properties

#commandRunner?

readonly optional commandRunner?: InstallCommandRunner

#environment?

readonly optional environment?: Readonly<ProcessEnv>

Process environment consulted for host cache roots (CODEX_HOME); defaults to process.env.

#from

readonly from: string

#home?

readonly optional home?: string

#host

readonly host: InstallHost

#mode?

readonly optional mode?: InstallMode

Cursor only; defaults to local. Other hosts reject an explicit mode.

#projectRoot?

readonly optional projectRoot?: string

Amp project-scope destination; defaults to the calling process cwd.

#replace?

readonly optional replace?: boolean

Replace an existing agent-bundle install of this plugin even when its version differs (--replace). Same-version content drift is replaced automatically; foreign directories are always refused.

#scope?

readonly optional scope?: InstallScope

#sideload?

readonly optional sideload?: boolean

false skips the sideload (--no-sideload); defaults to on unless GROK_BOT_SIDELOAD=0.

#Inherited from

GrokBotSideloadOptions.sideload

#sideloadRepo?

readonly optional sideloadRepo?: string

<owner>/<repo> of the marketplace clone (--sideload-repo, GROK_BOT_SIDELOAD_REPO).

#Inherited from

GrokBotSideloadOptions.sideloadRepo

#sideloadSlug?

readonly optional sideloadSlug?: string

Grok Bot's cache partition for it (--sideload-slug, GROK_BOT_SIDELOAD_SLUG); defaults to <owner>-<repo>.

#Inherited from

GrokBotSideloadOptions.sideloadSlug

---

#InstallCliOptions

A package-bound lifecycle CLI (#724): the agent-bundle CLI's own install, uninstall, and doctor commands with the bundle root pinned to the package that ships the bin, so a published plugin can offer <name> install <host> without bundling the framework's installer source or parsing argv itself.

#Properties

#from

readonly from: string

The bundle root the bin binds: the package root of an npm-root layout (new URL('..', import.meta.url) from bin/).

#name?

readonly optional name?: string

The bin name shown in --help; defaults to install.

#stderr?

readonly optional stderr?: (text) => void

#Parameters

#text

string

#Returns

void

#stdout?

readonly optional stdout?: (text) => void

#Parameters

#text

string

#Returns

void

#version?

readonly optional version?: string

The version --version prints; omitted when absent.

---

#InstallCommandResult

#Properties

#code

readonly code: number

#stderr

readonly stderr: string

#stdout

readonly stdout: string

---

#InstallCommandRunner

#Methods

#run()

run(command, args, options): Promise<InstallCommandResult>

#Parameters

#command

string

#args

readonly string[]

#options

#cwd

string

#environment?

Readonly<ProcessEnv>

#Returns

Promise<InstallCommandResult>

---

#InstallResult

#Properties

#bundleRoot

readonly bundleRoot: string

#commit?

readonly optional commit?: string

Git commit of the staged marketplace repository (mode: 'marketplace').

#contentHash?

readonly optional contentHash?: string

sha256 over the artifact tree that was installed or found already installed.

#destination?

readonly optional destination?: string

#host

readonly host: InstallHost

#marketplace?

readonly optional marketplace?: string

#mode?

readonly optional mode?: InstallMode

#nextSteps?

readonly optional nextSteps?: readonly string[]

Remaining host-owned steps the installer cannot perform non-interactively.

#plugin

readonly plugin: string

#previousContentHash?

readonly optional previousContentHash?: string

Content hash of the copy a replaced install superseded.

#receipt?

readonly optional receipt?: string

The install receipt this run wrote or confirmed: inside the plugin root for Cursor/Amp local copies, in the host root's agent-bundle/receipts store for host-CLI and marketplace deliveries (#101).

#sideload?

readonly optional sideload?: GrokBotSideloadResult

grokbot only: what was sideloaded into Grok Bot's marketplace clone and plugin cache, or why it was skipped.

#state

readonly state: InstallResultState

staged means the marketplace repository is ready and Cursor's import step is still pending (mode: 'marketplace').

#version

readonly version: string

---

#PublicHostInstalledEntry

#Properties

#enabled?

readonly optional enabled?: boolean

The row's enabled flag (Claude and Codex both carry one). false means the copy is installed but switched off (claude plugin disable), so none of it reaches a session until claude plugin enable runs; absent when the row carries no boolean.

#errors?

readonly optional errors?: readonly string[]

Claude only: the host's own load errors for this copy, verbatim from the row's errors array (present and nonempty only when Claude Code refused the plugin, e.g. "Hook load failed: Duplicate hooks file detected ..."). A refused copy is installed but contributes no hooks, MCP servers, or skills to a session, so callers must not report it as healthy.

#installPath

readonly installPath: string

#scope?

readonly optional scope?: string

Claude only: the scope this copy is installed at.

#version

readonly version: string

---

#PublicHostMarketplaceEntry

#Properties

#name

readonly name: string

#root?

readonly optional root?: string

---

#UninstallBundleOptions

#Properties

#commandRunner?

readonly optional commandRunner?: InstallCommandRunner

#confirmPurge?

readonly optional confirmPurge?: boolean

Required with purgeData: the explicit confirmation that durable state may be deleted.

#environment?

readonly optional environment?: Readonly<ProcessEnv>

#force?

readonly optional force?: boolean

Proceed when a host-registered copy has no store receipt, or when owned content no longer matches the receipt. Directories without a receipt naming this plugin are foreign and refused regardless, and a copy without a store receipt is never purged: purgeData is refused (AB7009).

#from

readonly from: string

#home?

readonly optional home?: string

#host

readonly host: InstallHost

#keepData?

readonly optional keepData?: boolean

Explicitly keep durable runtime state (the default).

#mode?

readonly optional mode?: InstallMode

Cursor only; defaults to local.

#plan?

readonly optional plan?: boolean

Compute and report the exact plan without changing anything.

#projectRoot?

readonly optional projectRoot?: string

Amp project-scope destination; defaults to the calling process cwd.

#purgeData?

readonly optional purgeData?: boolean

Remove durable runtime state too; refused without confirmPurge.

#scope?

readonly optional scope?: InstallScope

---

#UninstallDataReport

#Properties

#detail

readonly detail: string

#outcome

readonly outcome: UninstallDataOutcome

#paths

readonly paths: readonly string[]

The durable-state paths the decision applied to (absolute).

#policy

readonly policy: UninstallDataPolicy

#retained?

readonly optional retained?: readonly object[]

Recorded state roots retained because this installation lacks valid deletion authority.

---

#UninstallReceiptReport

#Properties

#contentHash?

readonly optional contentHash?: string

#format?

readonly optional format?: string

#installedAt?

readonly optional installedAt?: string

#path

readonly path: string

#status

readonly status: UninstallReceiptStatus

#version?

readonly optional version?: string

---

#UninstallRegistrationReport

#Extends

• InstallRegistration

#Properties

#action

readonly action: UninstallRegistrationAction

#commit?

readonly optional commit?: string

Staged marketplace HEAD commit (cursor-marketplace-staging, grokbot-marketplace-staging), or the Grok Bot marketplace clone commit the plugin was sideloaded under (grokbot-sideload).

#Inherited from

InstallRegistration.commit

#detail?

readonly optional detail?: string

#id?

readonly optional id?: string

<plugin>@<marketplace> for plugin registrations.

#Inherited from

InstallRegistration.id

#kind

readonly kind: InstallRegistrationKind

#Inherited from

InstallRegistration.kind

#name?

readonly optional name?: string

Marketplace name for marketplace registrations.

#Inherited from

InstallRegistration.name

#scope?

readonly optional scope?: InstallReceiptScope

Claude only: the scope the registration was made at.

#Inherited from

InstallRegistration.scope

---

#UninstallResult

#Properties

#bundleRoot

readonly bundleRoot: string

#data

readonly data: UninstallDataReport

#destination?

readonly optional destination?: string

The installed plugin root the run acted on (cache copy, local directory, or staged repository).

#forced

readonly forced: boolean

#host

readonly host: InstallHost

#marketplace?

readonly optional marketplace?: string

#mode

readonly mode: InstallReceiptMode

#nextSteps?

readonly optional nextSteps?: readonly string[]

Host-owned steps the uninstaller cannot perform non-interactively.

#plugin

readonly plugin: string

#receipt

readonly receipt: UninstallReceiptReport

#registrations

readonly registrations: readonly UninstallRegistrationReport[]

#remnantReceipt?

readonly optional remnantReceipt?: string

Cursor local only: the plugin root survived (retained runtime state or unowned entries), so a remnant receipt owning no files was written there to keep the created host directories receipt-owned.

#removed

readonly removed: object

Exact absolute paths removed (or, under --plan, that would be removed; directories only when empty).

#directories

readonly directories: readonly string[]

#files

readonly files: readonly string[]

#retained

readonly retained: readonly string[]

Unowned entries left in place under the destination (relative to it); surviving unowned directories end in /.

#scope

readonly scope: InstallScope

#state

readonly state: UninstallResultState

#version

readonly version: string

#Type Aliases

#DevInstallHost

DevInstallHost = Exclude<InstallHost, "amp" | "grokbot">

---

#DoctorCommandResult

DoctorCommandResult = BoundedChildProcessResult<DoctorCommandTermination>

---

#DoctorCommandRunner

DoctorCommandRunner = (request) => Promise<DoctorCommandResult>

#Parameters

#request

BoundedChildProcessRequest

#Returns

Promise<DoctorCommandResult>

---

#DoctorCommandTermination

DoctorCommandTermination = "output-limit" | "timed-out"

---

#DoctorFindingState

DoctorFindingState = "conflicted" | "corrupt" | "disabled" | "drifted" | "failed" | "installed" | "interrupted-install" | "live" | "missing" | "registered" | "skipped" | "stale-lock" | "stale-socket" | "unknown" | "unregistered"

---

#DoctorHost

DoctorHost = Exclude<InstallHost, "amp" | "grokbot">

Hosts with a full Doctor report; grokbot has its own read-only report (install/grokbot.ts).

---

#DoctorHostProbeStatus

DoctorHostProbeStatus = "available" | "failed" | "unavailable"

---

#DoctorInstallComparisonStatus

DoctorInstallComparisonStatus = "current" | "foreign" | "load-failed" | "not-installed" | "stale" | "unknown" | "version-mismatch"

---

#DoctorInventoryStatus

DoctorInventoryStatus = "known" | "skipped" | "unknown"

---

#DoctorLifecycleObservation

DoctorLifecycleObservation = Readonly<{ evidence: string; status: "observed"; value: boolean; }> | Readonly<{ reason: string; status: "unavailable"; }>

One lifecycle observation. observed carries the host evidence that made it true or false; unavailable names why no pinned read-only surface exposes it — Doctor never guesses an activation state.

---

#DoctorLifecycleStage

DoctorLifecycleStage = "absent" | "active" | "enabled" | "placed" | "registered" | "unknown"

The furthest lifecycle stage observed true (unknown when placement itself is unobservable).

---

#DoctorRuntimeStatus

DoctorRuntimeStatus = Readonly<{ artifactEpoch: string; availability: "available" | "runtime-restarted" | "runtime-unavailable"; instanceId: string; pid: number; startedAt?: string; status: "available"; }> | Readonly<{ status: "failed" | "unavailable"; }>

---

#InstallHost

InstallHost = BundleIdentityHost | "grokbot"

grokbot installs the Cursor projection through a Grok Bot marketplace; see install/grokbot.ts.

---

#InstallMode

InstallMode = "local" | "marketplace"

Cursor delivery mode: local copies into ~/.cursor/plugins/local/<name> (loads on reload, shown as a local plugin); marketplace stages a committed local marketplace repository that Cursor's Customize import registers as a marketplace-installed plugin. See install/cursor-marketplace.ts.

---

#InstallResultState

InstallResultState = "already-installed" | "installed" | "replaced" | "staged"

---

#InstallScope

InstallScope = "local" | "project" | "user"

---

#PublicHostInventory

PublicHostInventory = { entries: readonly PublicHostInstalledEntry[]; status: "available"; } | { detail: string; status: "unavailable"; }

The host's own answer to "is this plugin installed, and where": usable, or not, never guessed. Claude can hold one copy per scope, so an unscoped read returns every matching copy; a scoped read returns at most one.

---

#PublicInstallHost

PublicInstallHost = Exclude<InstallHost, "amp" | "cursor" | "grokbot">

---

#UninstallDataOutcome

UninstallDataOutcome = "absent" | "kept" | "purged" | "removed-by-host" | "retained-by-host" | "unavailable"

What happened to the plugin's durable runtime state. kept/purged/absent are Agent Bundle's own doing; retained-by-host (Claude keeps the orphaned cache copy for its ~14-day grace period) and removed-by-host (Codex deletes the cached tree on plugin remove) name the host behaviour that decided instead; unavailable means the delivery has no Agent Bundle-owned runtime state (an Amp directory plugin or a staged marketplace repository).

---

#UninstallDataPolicy

UninstallDataPolicy = "keep" | "purge"

agent-bundle uninstall <host> (#101): the receipt-owned reverse of install. Every mutation is opt-in, fail-closed, and bounded by what the install receipt records — owned files and directories, the host registrations the installer performed, and the host directories it created. Nothing outside that set is ever removed; durable runtime state (the roots the receipt's state block records with ownership evidence) is kept unless --purge-data is confirmed explicitly. --plan computes the same result without opening a writer, and a second run after a successful uninstall is a not-installed no-op.

---

#UninstallReceiptStatus

UninstallReceiptStatus = "consumed" | "forced-mismatch" | "forced-missing" | "missing" | "remnant"

How the receipt drove this run: consumed (read, honoured, removed), forced-missing/forced-mismatch (--force overrode a host-registered copy with no store receipt, or an owned-content hash mismatch), missing (nothing installed; no receipt to consume), remnant (a remnant receipt from an earlier --keep-data uninstall was found and left in place because only retained entries remain and they are being kept).

---

#UninstallRegistrationAction

UninstallRegistrationAction = "already-absent" | "manual" | "planned" | "removed" | "retained"

removed: reversed by this run; already-absent: the host no longer held it (idempotent rerun, or the host pruned it); retained: deliberately left in place (another installed plugin still uses the marketplace); manual: the host exposes no non-interactive verb, nextSteps names the UI step; planned: --plan would remove it.

---

#UninstallResultState

UninstallResultState = "not-installed" | "planned" | "uninstalled"

#Variables

#ampInstallLocation

const ampInstallLocation: (options, identity, scope) => object

#Parameters

#options

InstallBundleOptions

#identity

PluginIdentity

#scope

InstallScope

#Returns

object

#destination

readonly destination: string

#hostDirectories

readonly hostDirectories: readonly string[]

#hostRoot

readonly hostRoot: string

#installRoot

readonly installRoot: string

#registration

readonly registration: "amp-project-plugin" | "amp-system-plugin"

#relativeDestination

readonly relativeDestination: string

---

#claudePluginRowErrors

const claudePluginRowErrors: (row) => readonly string[]

Reads a Claude plugin list --json row's errors array. Healthy rows omit the key (Claude Code 2.1.259); a refused row carries nonempty strings. Anything else is treated as "no readable errors" rather than a failure, so an unexpected shape cannot mask the row as uninstalled.

#Parameters

#row

Readonly<Record<string, unknown>>

#Returns

readonly string[]

---

#cursorMarketplaceReceiptPath

const cursorMarketplaceReceiptPath: (cursorRoot, plugin) => string

Where the store receipt for a Cursor marketplace-mode install lives.

#Parameters

#cursorRoot

string

#plugin

string

#Returns

string

---

#cursorPluginDataDirectory

const cursorPluginDataDirectory: (cursorRoot, plugin) => string

The PLUGIN_DATA directory the emitted installer creates for an Agent Plugins pack copied into Cursor (spec §9.1).

#Parameters

#cursorRoot

string

#plugin

string

#Returns

string

---

#defaultCommandRunner

const defaultCommandRunner: InstallCommandRunner

---

#doctorEndpointDirectory

const doctorEndpointDirectory: () => string

#Returns

string

---

#doctorEndpointProbeConcurrency

const doctorEndpointProbeConcurrency: 8 = 8

Endpoints are probed concurrently, this many at a time, so a directory of listeners that accept connections but never answer (the silent-runtime failure Doctor exists to diagnose) costs roughly one status-probe timeout per batch rather than one per endpoint (#324 review).

---

#formatDoctorReport

const formatDoctorReport: (result) => string

Human-readable doctor report shared by the agent-bundle CLI and package-bound installer bins.

#Parameters

#result

DoctorReport

#Returns

string

---

#formatInstallResult

const formatInstallResult: (result) => string

Human-readable install summary shared by the CLI and standalone artifact installer.

#Parameters

#result

InstallResult

#Returns

string

---

#formatUninstallResult

const formatUninstallResult: (result) => string

Human-readable uninstall summary shared by the CLI and standalone artifact installer. --plan output lists every exact path the run would remove, so an operator can audit the mutation before allowing it.

#Parameters

#result

UninstallResult

#Returns

string

---

#installBundle

const installBundle: (options) => Promise<InstallResult>

#Parameters

#options

InstallBundleOptions

#Returns

Promise<InstallResult>

---

#parsePublicHostInventory

const parsePublicHostInventory: (host, stdout, options) => PublicHostInventory

Parses <host> plugin list --json for one plugin. Claude rows carry the cache path (installPath) and scope; Codex rows confirm installation and version only, so the pinned cache layout supplies the path. Shared by install (before replacing) and doctor (when comparing), so both read the host's inventory identically.

#Parameters

#host

PublicInstallHost

#stdout

string

#options

#cacheRoot

string

#marketplace

string

#plugin

string

#scope?

InstallScope

Claude only: restrict to rows installed at this scope.

#Returns

PublicHostInventory

---

#parsePublicHostMarketplaces

const parsePublicHostMarketplaces: (host, stdout) => readonly PublicHostMarketplaceEntry[] | undefined

#Parameters

#host

PublicInstallHost

#stdout

string

#Returns

readonly PublicHostMarketplaceEntry[] | undefined

---

#publicHostCacheRoot

const publicHostCacheRoot: (host, environment, home) => string

Where a public host CLI caches an installed marketplace plugin; pinned by the real-host install proofs and shared with the development install sync.

#Parameters

#host

PublicInstallHost

#environment

Readonly<NodeJS.ProcessEnv>

#home

string

#Returns

string

---

#publicHostMarketplaceRemoveArguments

const publicHostMarketplaceRemoveArguments: (marketplace) => readonly string[]

The host verb that removes a configured marketplace (identical spelling on Claude 2.1.257 and Codex 0.147.0).

#Parameters

#marketplace

string

#Returns

readonly string[]

---

#publicHostProjectRoot

const publicHostProjectRoot: (host, scope, identity) => string | undefined

The project root a Claude project / local registration belongs to: the cwd the host verbs run in.

#Parameters

#host

PublicInstallHost

#scope

InstallScope

#identity

PluginIdentity

#Returns

string | undefined

---

#publicHostReceiptPath

const publicHostReceiptPath: (host, plugin, marketplace, scope, environment, home, projectRoot?) => string

Where the store receipt for a host-CLI install lives: <host root>/agent-bundle/receipts/<plugin>.<marketplace>.<scope>[.<project digest>].json. The host identifies a registration as <plugin>@<marketplace>, so the same plugin installed from two marketplaces is two installs with two receipts. Claude project / local registrations belong to the working directory the host verbs ran in (the bundle root), so each project keeps its own receipt.

#Parameters

#host

PublicInstallHost

#plugin

string

#marketplace

string

#scope

InstallScope

#environment

Readonly<NodeJS.ProcessEnv>

#home

string

#projectRoot?

string

#Returns

string

---

#publicHostRegistrations

const publicHostRegistrations: (host, id, marketplace, scope) => readonly InstallRegistration[]

The registrations install <host> performs for a public host CLI, in order.

#Parameters

#host

PublicInstallHost

#id

string

#marketplace

string

#scope

InstallScope

#Returns

readonly InstallRegistration[]

---

#publicHostRoot

const publicHostRoot: (host, environment, home) => string

A public host CLI's configuration root (CLAUDE_CONFIG_DIR or ~/.claude; CODEX_HOME or ~/.codex): where the host caches installed plugins and where Agent Bundle keeps its own agent-bundle/receipts store for them.

#Parameters

#host

PublicInstallHost

#environment

Readonly<NodeJS.ProcessEnv>

#home

string

#Returns

string

---

#publicHostUninstallArguments

const publicHostUninstallArguments: (host, id, scope) => readonly string[]

The host verb that removes an installed plugin. Claude's --keep-data always rides along: the installer and uninstall manage the plugin's durable data explicitly (--purge-data) instead of letting the host decide.

#Parameters

#host

PublicInstallHost

#id

string

#scope

InstallScope

#Returns

readonly string[]

---

#readCodexMarketplaceSource

const readCodexMarketplaceSource: (codexRoot, marketplace) => Promise<string | undefined>

#Parameters

#codexRoot

string

#marketplace

string

#Returns

Promise<string | undefined>

---

#readInstalledManifest

const readInstalledManifest: (destination) => Promise<InstalledManifestIdentity | undefined>

The loader manifest identity of an installed Cursor copy (.cursor-plugin/plugin.json, then root plugin.json).

#Parameters

#destination

string

#Returns

Promise<InstalledManifestIdentity | undefined>

---

#readPublicHostInventory

const readPublicHostInventory: (runner, identity, host, scope, environment, home) => Promise<PublicHostInventory>

Runs the host's inventory verb so replacement only uninstalls what the host reports as installed.

#Parameters

#runner

InstallCommandRunner

#identity

PluginIdentity

#host

PublicInstallHost

#scope

InstallScope

#environment

Readonly<NodeJS.ProcessEnv>

#home

string

#Returns

Promise<PublicHostInventory>

---

#readPublicHostMarketplaceState

const readPublicHostMarketplaceState: (runner, identity, host, marketplace) => Promise<"absent" | "present" | "unknown">

<host> plugin marketplace list --json: whether a marketplace of this name is configured; unknown when unusable.

#Parameters

#runner

InstallCommandRunner

#identity

PluginIdentity

#host

PublicInstallHost

#marketplace

string

#Returns

Promise<"absent" | "present" | "unknown">

---

#resolveCursorRoot

const resolveCursorRoot: (options) => Promise<string>

~/.cursor, which must already exist as a directory: installers never create a Cursor home.

#Parameters

#options

#home?

string

#Returns

Promise<string>

---

#runDoctor

const runDoctor: (options?) => Promise<DoctorReport>

#Parameters

#options?

DoctorOptions

#Returns

Promise<DoctorReport>

---

#runHostCommand

const runHostCommand: (runner, identity, host, args, operation?) => Promise<InstallCommandResult>

#Parameters

#runner

InstallCommandRunner

#identity

PluginIdentity

#host

PublicInstallHost

#args

readonly string[]

#operation?

"installation" | "removal"

#Returns

Promise<InstallCommandResult>

---

#runInstallCli

const runInstallCli: (argv, options) => Promise<number>

Runs install <host>, uninstall <host>, or doctor against the pinned bundle root and returns the process exit code, exactly like the agent-bundle CLI: 0 on success; 1 when the command threw (its diagnostics as one JSON line on stderr) or when doctor's report, written to stdout, carries an error diagnostic; 2 on a usage error.

#Parameters

#argv

readonly string[]

#options

InstallCliOptions

#Returns

Promise<number>

---

#treeHash

const treeHash: (root) => Promise<string>

sha256 over a plugin tree in installer order; the install receipt is never part of it.

#Parameters

#root

string

#Returns

Promise<string>

---

#uninstallBundle

const uninstallBundle: (options) => Promise<UninstallResult>

Uninstalls a plugin from a host, bounded by its install receipt. See the module comment for the policy; --plan (options.plan) returns the same report without changing anything.

#Parameters

#options

UninstallBundleOptions

#Returns

Promise<UninstallResult>