@falkenslab/agent-kit 0.19.0 → 0.21.0

package/dist/core/externalExtensions.js

@@ -10,6 +10,15 @@ import { truncate } from "./toolLabels.js";
 import { agentKitVersion } from "./version.js";
 import { outsideArchive } from "./packaged.js";
 export const LOCK_FILE = "extensions.lock.json";
+/**
+ * An installed extension's data folder: `${CLAUDE_PLUGIN_DATA}` in its servers' arguments and
+ * variables (a browser profile, a cache), in its scope, outside its plugin and its hash, so it's
+ * kept across sessions and updates. Created when a session starts it; removing the extension
+ * asks before deleting it.
+ */
+export function extensionDataDir(scopeDir, name) {
+    return path.join(scopeDir, ".data", name);
+}
 /** A scope's lock: its extensions by name. */
 export async function readLock(scopeDir) {
     try {
@@ -58,6 +67,7 @@ export async function readExternalManifest(dir) {
         provides: kit.provides ?? [],
         requires: kit.requires ?? [],
         ...(kit.kit ? { kit: kit.kit } : {}),
+        needs: Array.isArray(kit.needs) ? kit.needs.filter((program) => typeof program === "string") : [],
         servers: await pluginServers(dir, raw),
         readOnlyTools: kit.readOnlyTools ?? [],
         labels: kit.labels ?? {},
@@ -98,29 +108,32 @@ async function pluginServers(dir, raw) {
     }
     return servers;
 }
-/** `${CLAUDE_PLUGIN_ROOT}` (the extension's folder) and `${VAR}` (the agent's variable) in a server's values. */
-function expand(value, root) {
-    return value.replace(/\$\{(\w+)\}/g, (_, name) => (name === "CLAUDE_PLUGIN_ROOT" ? root : (process.env[name] ?? "")));
+/** `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}` and `${VAR}` (the agent's variable) in a server's values. */
+function expand(value, folders) {
+    return value.replace(/\$\{(\w+)\}/g, (_, name) => name === "CLAUDE_PLUGIN_ROOT" ? folders.root : name === "CLAUDE_PLUGIN_DATA" ? folders.data : (process.env[name] ?? ""));
 }
 /**
  * Why one of an extension's servers can't run through the launcher (only Node, its script
  * first, inside the extension), or how the kit starts it.
  */
-function serverLaunch(name, server, root) {
+function serverLaunch(name, server, folders) {
+    const { root } = folders;
     if (!/^node(\.exe)?$/i.test(path.basename(server.command)))
         return `runs its server "${name}" with "${server.command}": only Node servers can be installed`;
-    const [script, ...args] = (server.args ?? []).map((arg) => expand(arg, root));
+    const [script, ...args] = (server.args ?? []).map((arg) => expand(arg, folders));
     if (!script)
         return `gives its server "${name}" no script to run`;
     const entry = path.resolve(root, script);
     if (path.relative(root, entry).startsWith(".."))
         return `runs its server "${name}" from outside its folder (${script})`;
-    return { entry, args, env: Object.fromEntries(Object.entries(server.env ?? {}).map(([key, value]) => [key, expand(String(value), root)])) };
+    // Its folders as variables too, as Claude Code gives them to a plugin's servers.
+    const declared = Object.fromEntries(Object.entries(server.env ?? {}).map(([key, value]) => [key, expand(String(value), folders)]));
+    return { entry, args, env: { CLAUDE_PLUGIN_ROOT: root, CLAUDE_PLUGIN_DATA: folders.data, ...declared } };
 }
 /** Why an extension's servers can't run, or nothing: each must be Node, with its script there. */
 async function serversProblem(manifest, root) {
     for (const [name, server] of Object.entries(manifest.servers)) {
-        const launch = serverLaunch(name, server, root);
+        const launch = serverLaunch(name, server, { root, data: "" });
         if (typeof launch === "string")
             return launch;
         if (!(await stat(launch.entry).catch(() => null))?.isFile())
@@ -187,9 +200,9 @@ export async function listInstalled(dirs) {
         if (!scopeDir)
             continue;
         for (const [name, lock] of Object.entries(await readLock(scopeDir))) {
-            const dir = path.join(scopeDir, name);
+            const dir = lock.linked ? lock.source : path.join(scopeDir, name);
             const manifest = await readExternalManifest(dir).catch(() => undefined);
-            installed.push({ name, scope, dir, lock, shadowed: installed.some((other) => other.name === name), ...(manifest ? { manifest } : {}) });
+            installed.push({ name, scope, scopeDir, dir, dataDir: extensionDataDir(scopeDir, name), lock, shadowed: installed.some((other) => other.name === name), ...(manifest ? { manifest } : {}) });
         }
     }
     return installed;
@@ -217,10 +230,13 @@ function externalExtension(installed, manifest) {
         name: manifest.name,
         plugin: installed.dir,
         external: true,
+        installedIn: installed.scopeDir,
         async contribute() {
             const servers = {};
+            if (Object.keys(manifest.servers).length)
+                await mkdir(installed.dataDir, { recursive: true });
             for (const [name, server] of Object.entries(manifest.servers)) {
-                const launch = serverLaunch(name, server, installed.dir);
+                const launch = serverLaunch(name, server, { root: installed.dir, data: installed.dataDir });
                 if (typeof launch === "string")
                     continue; // checked when it loaded
                 // Its `env` reaches it (the SDK merges it with the agent's); the launcher removes the rest.
@@ -254,10 +270,23 @@ export async function loadExternalExtensions(dirs) {
     return { extensions, off };
 }
 /** Why an installed extension can't load, or its manifest when it can. */
+/** Whether a program is on the `PATH`, as a shell would find it (with `PATHEXT`'s extensions on Windows). */
+export async function onPath(program, env = process.env) {
+    const dirs = (env.PATH ?? env.Path ?? "").split(path.delimiter).filter(Boolean);
+    const extensions = process.platform === "win32" ? ["", ...(env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").map((extension) => extension.toLowerCase())] : [""];
+    for (const dir of dirs) {
+        for (const extension of extensions) {
+            const found = await stat(path.join(dir, `${program}${extension}`)).then((entry) => entry.isFile(), () => false);
+            if (found)
+                return true;
+        }
+    }
+    return false;
+}
 async function problem(installed) {
     let manifest;
     try {
-        if ((await hashExtension(installed.dir)) !== installed.lock.sha256)
+        if (!installed.lock.linked && (await hashExtension(installed.dir)) !== installed.lock.sha256)
             return "has files that changed since it was installed: install it again to trust them";
         manifest = await readExternalManifest(installed.dir);
     }
@@ -268,6 +297,12 @@ async function problem(installed) {
         return `is installed as "${installed.name}" but its manifest says "${manifest.name}"`;
     if (manifest.kit && !inKitRange(agentKitVersion(), manifest.kit))
         return `works with agent-kit ${manifest.kit}, and this agent runs ${agentKitVersion()}`;
+    const missing = [];
+    for (const program of manifest.needs)
+        if (!(await onPath(program)))
+            missing.push(program);
+    if (missing.length)
+        return `needs ${missing.join(", ")}, which ${missing.length === 1 ? "isn't" : "aren't"} on this computer (on the PATH)`;
     return (await serversProblem(manifest, installed.dir)) ?? manifest;
 }
 const exec = promisify(execFile);
@@ -276,19 +311,29 @@ export function isGitSource(source) {
     return /^(https?:\/\/|git@|ssh:\/\/|git:\/\/|file:\/\/|github:)/.test(source) || /\.git(#.*)?$/.test(source);
 }
 /**
- * Installs an extension into a scope from a folder or a git repository (`url#ref`, and `subdir`
- * for one inside it): copies its files (never runs a script), checks its manifest, and locks it,
- * enabled. An extension with the same name in that scope is replaced.
+ * Installs an extension into a scope from a folder or a git repository (`url#ref`, `sha` to pin
+ * a commit, and `subdir` for one inside it): copies its files (never runs a script), checks its
+ * manifest, and locks it, enabled, with the marketplace it came from when it did (`origin`, for a
+ * temporary folder, is what the lock says it came from). An extension with the same name in that
+ * scope is replaced; its data folder stays. With `link`, a folder is registered where it is
+ * instead, to develop it: not copied, and its files not checked.
  */
 export async function addExtension(source, scopeDir, options = {}) {
+    if (options.link && isGitSource(source))
+        throw new Error("Only a folder can be linked: a git repository is installed as a copy.");
     let from = path.resolve(source);
     let commit;
     let clone;
     if (isGitSource(source)) {
         const [url, ref] = source.replace(/^github:/, "https://github.com/").split("#");
         clone = await mkdtemp(path.join(os.tmpdir(), "agent-kit-extension-"));
-        await exec("git", ["clone", "--depth", "1", ...(ref ? ["--branch", ref] : []), url, clone]);
+        // A pinned commit needs the history to check it out; otherwise the tip is enough.
+        await exec("git", ["clone", ...(options.sha ? [] : ["--depth", "1"]), ...(ref ? ["--branch", ref] : []), url, clone]);
+        if (options.sha)
+            await exec("git", ["-C", clone, "checkout", "--quiet", options.sha]);
         commit = (await exec("git", ["-C", clone, "rev-parse", "HEAD"])).stdout.trim();
+        if (options.sha && commit !== options.sha.toLowerCase())
+            throw new Error(`${url} has no commit ${options.sha}.`);
         from = clone;
     }
     try {
@@ -299,14 +344,23 @@ export async function addExtension(source, scopeDir, options = {}) {
         if (servers)
             throw new Error(`${manifest.name} can't be installed: it ${servers}.`);
         const target = path.join(scopeDir, manifest.name);
+        // Replacing what's installed there would delete the source itself.
+        if (path.resolve(from) === path.resolve(target))
+            throw new Error(`${from} is where ${manifest.name} is installed: install it from another folder.`);
         const lock = await readLock(scopeDir);
         const replaced = Boolean(lock[manifest.name]);
         await rm(target, { recursive: true, force: true });
         await mkdir(scopeDir, { recursive: true });
+        if (options.link) {
+            lock[manifest.name] = { source: from, linked: true, sha256: "", enabled: true, installed: new Date().toISOString() };
+            await writeLock(scopeDir, lock);
+            return { name: manifest.name, replaced };
+        }
         await cp(from, target, { recursive: true, filter: (file) => path.basename(file) !== ".git" });
         lock[manifest.name] = {
-            source: isGitSource(source) ? `${source}${options.subdir ? ` (${options.subdir})` : ""}` : from,
+            source: options.origin ?? (isGitSource(source) ? `${source}${options.subdir ? ` (${options.subdir})` : ""}` : from),
             ...(commit ? { commit } : {}),
+            ...(options.marketplace ? { marketplace: options.marketplace } : {}),
             sha256: await hashExtension(target),
             enabled: true,
             installed: new Date().toISOString(),
@@ -319,16 +373,33 @@ export async function addExtension(source, scopeDir, options = {}) {
             await rm(clone, { recursive: true, force: true });
     }
 }
-/** Removes an extension from a scope (its files and its lock entry); false when it wasn't there. */
-export async function removeExtension(scopeDir, name) {
+/**
+ * Removes an extension from a scope (its files and its lock entry; a linked one's folder is left
+ * where it is), and its data folder with `deleteData`; false when it wasn't there.
+ */
+export async function removeExtension(scopeDir, name, options = {}) {
     const lock = await readLock(scopeDir);
     if (!lock[name])
         return false;
     delete lock[name];
     await rm(path.join(scopeDir, name), { recursive: true, force: true });
+    if (options.deleteData)
+        await rm(extensionDataDir(scopeDir, name), { recursive: true, force: true });
     await writeLock(scopeDir, lock);
     return true;
 }
+/** The size in bytes of the files under `dir` (0 when it doesn't exist). */
+export async function folderSize(dir) {
+    let size = 0;
+    for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory())
+            size += await folderSize(full);
+        else if (entry.isFile())
+            size += (await stat(full)).size;
+    }
+    return size;
+}
 /** Enables or disables an installed extension in a scope; false when it isn't there. */
 export async function setExtensionEnabled(scopeDir, name, enabled) {
     const lock = await readLock(scopeDir);

package/dist/core/liveExtensions.d.ts

@@ -0,0 +1,65 @@
+import type { ExtensionsStatus } from "./session.js";
+import type { SessionLive, StaticSessionFacts } from "./sessionFacts.js";
+import type { ToolLabels } from "./toolLabels.js";
+/**
+ * Turning an installed extension off and on in a running session (#49), without reopening it.
+ * Only one that was running when the session opened: its MCP servers are toggled
+ * (`toggleMcpServer()`, which removes their tools from the model's context and brings them back,
+ * confirmed empirically) and its plugin, mounted in the run's folder, is unmounted or mounted again
+ * before `reloadPlugins()` (its skills, commands and subagents go and come back, confirmed
+ * empirically, through a link too). The kit's own lists follow: the plan gate's read-only tools, the subagent gates'
+ * allowed types, the chat's labels, `/extensions` and what `about_me` says. One that wasn't
+ * running has no plugin path the session knows: it takes reopening the session.
+ *
+ * Not through `setMcpServers()`: it leaves the servers given at start alone (confirmed
+ * empirically: removing one from its set removes nothing).
+ */
+/**
+ * Mounts an installed extension's plugin at `at`, in a run's folder, for the session to load from
+ * there: a link to it (a junction on Windows, which needs no privilege), so nothing is copied and
+ * its `node_modules` costs nothing; a copy where a link can't be made. The CLI loads a plugin
+ * through a link, and `reloadPlugins()` unloads it when the link goes and loads it when it's back
+ * (confirmed empirically).
+ */
+export declare function mountPlugin(from: string, at: string): Promise<"link" | "copy">;
+/**
+ * Takes a mounted plugin away: a link is removed, never what it points at (its contents are the
+ * installed extension); a copy is emptied, so the path stays for mounting it again.
+ */
+export declare function unmountPlugin(at: string): Promise<void>;
+/** What an installed extension brought to this session, to take it away and bring it back. */
+export interface LiveExtension {
+    name: string;
+    /** Its plugin as installed (in its scope's folder, or where it's linked): what's mounted in the run's folder. */
+    installedDir: string;
+    /** Its scope's folder, where its lock is. */
+    scopeDir: string;
+    /** Where its plugin is mounted in the run's folder for this session (`mountPlugin()`). */
+    pluginMount: string;
+    servers: string[];
+    readOnlyTools: string[];
+    toolLabels: ToolLabels;
+    /** Its subagents, as the type gate names them (`<plugin>:<name>`). */
+    agents: string[];
+    description: string;
+    provides: string[];
+    help: string[];
+}
+/** The session's own lists the switch keeps in step: the same objects the gates, the chat and the view read. */
+export interface LiveTargets {
+    readOnlyTools: string[];
+    allowedSubagentTypes: string[];
+    toolLabels: ToolLabels;
+    status: ExtensionsStatus;
+    facts: StaticSessionFacts;
+    /** The running session's controls, once it has started. */
+    controls: () => SessionLive;
+}
+/**
+ * Turns `name` on or off in the running session; false when it can't be done here (it wasn't
+ * running when the session opened, the session hasn't started, or its files changed since it
+ * was installed), and the session must be opened again.
+ */
+export type ExtensionSwitch = (name: string, enabled: boolean) => Promise<boolean>;
+/** The switch for a session's installed extensions. */
+export declare function createExtensionSwitch(extensions: readonly LiveExtension[], targets: LiveTargets): ExtensionSwitch;

package/dist/core/liveExtensions.js

@@ -0,0 +1,121 @@
+import { cp, lstat, mkdir, readdir, rm, symlink, unlink } from "node:fs/promises";
+import path from "node:path";
+import { hashExtension, listInstalled, readLock } from "./externalExtensions.js";
+/**
+ * Turning an installed extension off and on in a running session (#49), without reopening it.
+ * Only one that was running when the session opened: its MCP servers are toggled
+ * (`toggleMcpServer()`, which removes their tools from the model's context and brings them back,
+ * confirmed empirically) and its plugin, mounted in the run's folder, is unmounted or mounted again
+ * before `reloadPlugins()` (its skills, commands and subagents go and come back, confirmed
+ * empirically, through a link too). The kit's own lists follow: the plan gate's read-only tools, the subagent gates'
+ * allowed types, the chat's labels, `/extensions` and what `about_me` says. One that wasn't
+ * running has no plugin path the session knows: it takes reopening the session.
+ *
+ * Not through `setMcpServers()`: it leaves the servers given at start alone (confirmed
+ * empirically: removing one from its set removes nothing).
+ */
+/**
+ * Mounts an installed extension's plugin at `at`, in a run's folder, for the session to load from
+ * there: a link to it (a junction on Windows, which needs no privilege), so nothing is copied and
+ * its `node_modules` costs nothing; a copy where a link can't be made. The CLI loads a plugin
+ * through a link, and `reloadPlugins()` unloads it when the link goes and loads it when it's back
+ * (confirmed empirically).
+ */
+export async function mountPlugin(from, at) {
+    // Whatever was there goes: a link (never what it points at), or a copy, whole.
+    const found = await lstat(at).catch(() => undefined);
+    if (found?.isSymbolicLink())
+        await unlink(at);
+    else if (found)
+        await rm(at, { recursive: true, force: true });
+    await mkdir(path.dirname(at), { recursive: true });
+    try {
+        await symlink(from, at, process.platform === "win32" ? "junction" : "dir");
+        return "link";
+    }
+    catch {
+        await cp(from, at, { recursive: true });
+        return "copy";
+    }
+}
+/**
+ * Takes a mounted plugin away: a link is removed, never what it points at (its contents are the
+ * installed extension); a copy is emptied, so the path stays for mounting it again.
+ */
+export async function unmountPlugin(at) {
+    const found = await lstat(at).catch(() => undefined);
+    if (!found)
+        return;
+    if (found.isSymbolicLink())
+        await unlink(at);
+    else
+        for (const entry of await readdir(at))
+            await rm(path.join(at, entry), { recursive: true, force: true });
+}
+/** The switch for a session's installed extensions. */
+export function createExtensionSwitch(extensions, targets) {
+    const off = new Set();
+    return async (name, enabled) => {
+        const extension = extensions.find((candidate) => candidate.name === name);
+        const controls = targets.controls();
+        if (!extension || !controls.toggleMcpServer || !controls.reloadPlugins)
+            return false;
+        if (enabled === !off.has(name))
+            return true; // already as asked
+        if (enabled) {
+            // Its files as they were installed, or nothing: a changed one is for a new session to judge.
+            // A linked one's aren't checked: it's being developed, and a rebuild is why it's turned on again.
+            const lock = (await readLock(extension.scopeDir))[name];
+            if (!lock || (!lock.linked && lock.sha256 !== (await hashExtension(extension.installedDir))))
+                return false;
+            await mountPlugin(extension.installedDir, extension.pluginMount);
+        }
+        else {
+            await unmountPlugin(extension.pluginMount);
+        }
+        await controls.reloadPlugins();
+        for (const server of extension.servers)
+            await controls.toggleMcpServer(server, enabled);
+        if (enabled)
+            off.delete(name);
+        else
+            off.add(name);
+        follow(extension, enabled, targets);
+        targets.status.installed = await listInstalled(targets.status.dirs);
+        return true;
+    };
+}
+/** The kit's lists, as the extension is now. */
+function follow(extension, enabled, targets) {
+    const without = (list, items) => {
+        for (const item of items) {
+            const index = list.indexOf(item);
+            if (index >= 0)
+                list.splice(index, 1);
+        }
+    };
+    const { status, facts } = targets;
+    if (enabled) {
+        targets.readOnlyTools.push(...extension.readOnlyTools);
+        targets.allowedSubagentTypes.push(...extension.agents);
+        Object.assign(targets.toolLabels, extension.toolLabels);
+        status.active.push(extension.name);
+        status.about[extension.name] = { description: extension.description, provides: extension.provides };
+        status.inactive = status.inactive.filter((entry) => entry.name !== extension.name);
+        facts.extensions.active.push({ name: extension.name, description: extension.description, provides: extension.provides, servers: extension.servers, help: extension.help });
+        facts.extensions.inactive = facts.extensions.inactive.filter((entry) => entry.name !== extension.name);
+    }
+    else {
+        without(targets.readOnlyTools, extension.readOnlyTools);
+        without(targets.allowedSubagentTypes, extension.agents);
+        // The same object the chat reads its labels from: changed in place, readonly to everyone else.
+        for (const tool of Object.keys(extension.toolLabels))
+            delete targets.toolLabels[tool];
+        without(status.active, [extension.name]);
+        delete status.about[extension.name];
+        const reason = { name: extension.name, reason: "was turned off in this session" };
+        status.inactive.push(reason);
+        facts.extensions.active = facts.extensions.active.filter((entry) => entry.name !== extension.name);
+        facts.extensions.inactive.push(reason);
+    }
+}

package/dist/core/marketplaces.d.ts

@@ -0,0 +1,118 @@
+/** Where a marketplace's plugin comes from, as `marketplace.json` says (Claude Code's forms). */
+export type PluginSource = string | {
+    source: "github";
+    repo: string;
+    ref?: string;
+    sha?: string;
+} | {
+    source: "url";
+    url: string;
+    ref?: string;
+    sha?: string;
+} | {
+    source: "git-subdir";
+    url: string;
+    path: string;
+    ref?: string;
+    sha?: string;
+} | {
+    source: string;
+    [field: string]: unknown;
+};
+/** A plugin a marketplace offers. */
+export interface MarketplacePlugin {
+    name: string;
+    source: PluginSource;
+    description?: string;
+    version?: string;
+    category?: string;
+    tags?: string[];
+    keywords?: string[];
+}
+/** A marketplace's `marketplace.json`, as the kit reads it. */
+export interface MarketplaceManifest {
+    name: string;
+    owner: {
+        name: string;
+        email?: string;
+        url?: string;
+    };
+    description?: string;
+    /** Where bare plugin sources resolve, relative to the marketplace's root. */
+    pluginRoot?: string;
+    plugins: MarketplacePlugin[];
+}
+/** A marketplace an agent knows. */
+export interface KnownMarketplace {
+    name: string;
+    /** Where it came from: a folder, a git URL (`#ref`), or `owner/repo`. */
+    source: string;
+    /** The commit its copy was taken at, for a git one. */
+    commit?: string;
+    /** The agent's own: known without asking, and its plugins installed without a confirmation. */
+    official: boolean;
+    /** When its copy was taken, ISO 8601 in UTC. */
+    updated: string;
+    /** Its copy, inside the agent's extensions folder. */
+    dir: string;
+    manifest?: MarketplaceManifest;
+}
+/** Reads and checks a marketplace's `.claude-plugin/marketplace.json`. */
+export declare function readMarketplaceManifest(root: string): Promise<MarketplaceManifest>;
+/** Reads a marketplace from a folder, a git URL (`#ref`) or `owner/repo` without adding it: what to show before asking. */
+export declare function inspectMarketplace(source: string): Promise<MarketplaceManifest>;
+/**
+ * Adds a marketplace to the agent (its extensions folder, `dir`) from a folder, a git URL
+ * (`#ref`) or `owner/repo`, taking a copy; one with the same name is replaced. Asking the person
+ * first is the caller's: the kit's command asks them to type its name, unless it's `official`.
+ */
+export declare function addMarketplace(source: string, dir: string, options?: {
+    official?: boolean;
+}): Promise<{
+    name: string;
+    replaced: boolean;
+    manifest: MarketplaceManifest;
+    commit?: string;
+}>;
+/** The marketplaces the agent knows, with their manifests when they can be read. */
+export declare function listMarketplaces(dir: string): Promise<KnownMarketplace[]>;
+/** Takes a fresh copy of a known marketplace from where it came from. */
+export declare function updateMarketplace(dir: string, name: string): Promise<{
+    commit?: string;
+}>;
+/** Forgets a marketplace (its copy and its entry); the extensions installed from it stay. False when it wasn't known. */
+export declare function removeMarketplace(dir: string, name: string): Promise<boolean>;
+/** A plugin found in the known marketplaces: `<name>@<marketplace>`, or a name only one of them offers. */
+export declare function findPlugin(dir: string, spec: string): Promise<{
+    marketplace: KnownMarketplace;
+    plugin: MarketplacePlugin;
+}>;
+/** Where a plugin comes from: a folder or git repository for `addExtension()`, or a download (npm, archive). */
+export type ResolvedSource = {
+    source: string;
+    subdir?: string;
+    sha?: string;
+} | {
+    npm: {
+        name: string;
+        version?: string;
+        registry?: string;
+    };
+} | {
+    archive: {
+        url: string;
+        sha256?: string;
+    };
+};
+/** Where a plugin's source points: a folder of the marketplace's copy, a git repository, an npm package or a zip. */
+export declare function resolvePluginSource(marketplace: KnownMarketplace, plugin: MarketplacePlugin): ResolvedSource;
+/**
+ * Installs `<plugin>@<marketplace>` (or a plugin only one known marketplace offers) into a scope,
+ * locked with where it came from. Its name in the agent is its `plugin.json`'s, as for any extension.
+ */
+export declare function installFromMarketplace(dir: string, spec: string, scopeDir: string): Promise<{
+    name: string;
+    replaced: boolean;
+    commit?: string;
+    marketplace: string;
+}>;