@abot-ai/runtime 1.6.0 → 1.7.0

package/dist/src/runtime/observability/request-control-diagnostics.js

@@ -0,0 +1,52 @@
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { traceDebug } from "./debug-logger.js";
+export { classifyRuntimeErrorType as diagnosticErrorType } from "./error-type.js";
+let fallbackId = 0;
+/** Diagnostic identity only; never used for request admission or ownership. */
+export function createRequestControlDiagnosticId(prefix) {
+    try {
+        return `${prefix}-${randomUUID()}`;
+    }
+    catch {
+        return `${prefix}-${process.pid}-${Date.now()}-${++fallbackId}`;
+    }
+}
+const processInstanceId = createRequestControlDiagnosticId("process");
+let packageIdentity;
+function readPackageIdentity() {
+    // Source and compiled layouts. Installed packages do not require a Git checkout.
+    for (const relative of [
+        "../../../package.json",
+        "../../../../package.json",
+    ]) {
+        try {
+            const value = JSON.parse(readFileSync(new URL(relative, import.meta.url), "utf8"));
+            if (value.name !== "@abot-ai/runtime")
+                continue;
+            return {
+                runtimeVersion: typeof value.version === "string" ? value.version : "unknown",
+                packageRevision: typeof value.gitHead === "string" ? value.gitHead : null,
+            };
+        }
+        catch {
+            // Metadata may be absent in an embedded host; it cannot block execution.
+        }
+    }
+    return { runtimeVersion: "unknown", packageRevision: null };
+}
+/** Best-effort, content-free diagnostics must never change a control result. */
+export function traceRequestControl(scope, event, fields = {}) {
+    try {
+        packageIdentity ??= readPackageIdentity();
+        traceDebug(scope, event, {
+            ...packageIdentity,
+            pid: process.pid,
+            processInstanceId,
+            ...fields,
+        });
+    }
+    catch {
+        // Includes synchronous serialization/console failures; disk writes are best effort.
+    }
+}

package/dist/src/runtime/plugins/configuration-context.d.ts

@@ -0,0 +1,9 @@
+import type { RuntimePluginLoadContext } from "../../plugin-contract/entrypoint.js";
+import type { AbotRuntimePluginExtension } from "../../plugin-contract/manifest.js";
+import type { PluginLocalConfiguration } from "./configuration-store.js";
+export type PluginConfigurationDeclaration = Pick<AbotRuntimePluginExtension, "settings" | "secrets">;
+export declare function effectivePluginSettings(declaration: PluginConfigurationDeclaration, local?: PluginLocalConfiguration): Record<string, unknown>;
+export declare function configuredPluginSecret(name: string, declaration: {
+    env: string;
+}, local?: PluginLocalConfiguration): string | undefined;
+export declare function pluginLoadConfiguration(pluginId: string, declaration: PluginConfigurationDeclaration, local?: PluginLocalConfiguration): Pick<RuntimePluginLoadContext, "config" | "secrets">;

package/dist/src/runtime/plugins/configuration-context.js

@@ -0,0 +1,42 @@
+import { requireRetainedPluginSettingTypes } from "./configuration-settings.js";
+export function effectivePluginSettings(declaration, local) {
+    return Object.fromEntries(Object.entries(declaration.settings?.defaults ?? {}).map(([name, fallback]) => [
+        name,
+        structuredClone(local && Object.hasOwn(local.settings, name)
+            ? local.settings[name]
+            : fallback),
+    ]));
+}
+export function configuredPluginSecret(name, declaration, local) {
+    const saved = local?.secrets[name];
+    if (saved?.env === declaration.env)
+        return saved.value?.trim() ? saved.value : undefined;
+    const inherited = process.env[declaration.env];
+    return inherited?.trim() ? inherited : undefined;
+}
+export function pluginLoadConfiguration(pluginId, declaration, local) {
+    requireRetainedPluginSettingTypes(pluginId, declaration.settings?.defaults ?? {}, local?.settings);
+    const declarations = declaration.secrets ?? {};
+    for (const [name, secret] of Object.entries(declarations)) {
+        if (!secret.required)
+            continue;
+        if (configuredPluginSecret(name, secret, local))
+            continue;
+        throw new Error(`Runtime plugin ${pluginId} requires secret ${name} from environment variable ${secret.env}`);
+    }
+    const secrets = Object.keys(declarations).length
+        ? Object.freeze({
+            get(name) {
+                if (!Object.hasOwn(declarations, name))
+                    throw new Error(`Runtime plugin ${pluginId} requested undeclared secret ${name}`);
+                return configuredPluginSecret(name, declarations[name], local);
+            },
+        })
+        : undefined;
+    return {
+        ...(declaration.settings
+            ? { config: effectivePluginSettings(declaration, local) }
+            : {}),
+        ...(secrets ? { secrets } : {}),
+    };
+}

package/dist/src/runtime/plugins/configuration-settings.d.ts

@@ -0,0 +1,2 @@
+export declare function pluginSettingMatchesDefault(value: unknown, fallback: unknown): boolean;
+export declare function requireRetainedPluginSettingTypes(pluginId: string, defaults: Record<string, unknown>, saved?: Record<string, unknown>): void;

package/dist/src/runtime/plugins/configuration-settings.js

@@ -0,0 +1,26 @@
+import { PluginConfigurationError } from "./configuration-store.js";
+function settingKind(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+export function pluginSettingMatchesDefault(value, fallback) {
+    if (fallback === null)
+        return true; // A null default supplies no type information.
+    if (typeof value === "number" && !Number.isFinite(value))
+        return false;
+    return settingKind(value) === settingKind(fallback);
+}
+export function requireRetainedPluginSettingTypes(pluginId, defaults, saved) {
+    if (!saved)
+        return;
+    for (const [name, fallback] of Object.entries(defaults)) {
+        if (!Object.hasOwn(saved, name))
+            continue;
+        if (pluginSettingMatchesDefault(saved[name], fallback))
+            continue;
+        throw new PluginConfigurationError("invalid_plugin_configuration", `Saved setting ${name} for plugin ${pluginId} does not match its current default type. Correct it in Plugins before applying.`, 409);
+    }
+}

package/dist/src/runtime/plugins/configuration-store.d.ts

@@ -0,0 +1,23 @@
+export type PluginLocalConfiguration = {
+    settings: Record<string, unknown>;
+    secrets: Record<string, {
+        env: string;
+        value: string | null;
+    }>;
+};
+export type PluginConfigurationStore = Record<string, PluginLocalConfiguration>;
+export type PluginConfigurationSnapshot = {
+    plugins: PluginConfigurationStore;
+    raw: string | undefined;
+    revision: string;
+};
+export declare const PLUGIN_CONFIGURATION_MAX_BYTES: number;
+export declare class PluginConfigurationError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    constructor(code: string, message: string, statusCode?: number);
+}
+export declare function isMissingPluginConfiguration(error: unknown): boolean;
+export declare function pluginConfigurationPath(rootDir: string): string;
+export declare function requirePrivateConfigurationDirectory(rootDir: string): void;
+export declare function readPluginConfigurationStore(rootDir: string): PluginConfigurationSnapshot;

package/dist/src/runtime/plugins/configuration-store.js

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isRecord } from "../config/utils.js";
+export const PLUGIN_CONFIGURATION_MAX_BYTES = 1024 * 1024;
+export class PluginConfigurationError extends Error {
+    code;
+    statusCode;
+    constructor(code, message, statusCode = 400) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+    }
+}
+export function isMissingPluginConfiguration(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+export function pluginConfigurationPath(rootDir) {
+    return join(rootDir, ".runtime", "plugin-configuration.json");
+}
+export function requirePrivateConfigurationDirectory(rootDir) {
+    try {
+        const info = lstatSync(join(rootDir, ".runtime"));
+        if (info.isDirectory() && !info.isSymbolicLink())
+            return;
+    }
+    catch (error) {
+        if (isMissingPluginConfiguration(error))
+            return;
+        throw error;
+    }
+    throw new PluginConfigurationError("unsafe_plugin_configuration", "Plugin configuration requires a local directory.", 409);
+}
+function isStoredPluginSecret(value) {
+    if (!isRecord(value))
+        return false;
+    if (typeof value.env !== "string")
+        return false;
+    return value.value === null || typeof value.value === "string";
+}
+function isStoredPluginConfiguration(value) {
+    if (!isRecord(value))
+        return false;
+    if (!isRecord(value.settings))
+        return false;
+    if (!isRecord(value.secrets))
+        return false;
+    return Object.values(value.secrets).every(isStoredPluginSecret);
+}
+function parsePluginConfigurationStore(raw) {
+    if (raw === undefined)
+        return {};
+    try {
+        const value = JSON.parse(raw);
+        if (!isRecord(value))
+            throw new Error();
+        if (value.version !== 1)
+            throw new Error();
+        if (!isRecord(value.plugins))
+            throw new Error();
+        if (!Object.values(value.plugins).every(isStoredPluginConfiguration))
+            throw new Error();
+        return value.plugins;
+    }
+    catch {
+        throw new PluginConfigurationError("invalid_plugin_configuration_file", "The local plugin configuration file could not be read.", 409);
+    }
+}
+function requirePrivatePluginConfigurationPermissions(mode) {
+    if (process.platform === "win32")
+        return;
+    if ((mode & 0o077) === 0)
+        return;
+    throw new PluginConfigurationError("unsafe_plugin_configuration", "Plugin configuration permissions are too open. Run chmod 600 on .runtime/plugin-configuration.json before retrying.", 409);
+}
+export function readPluginConfigurationStore(rootDir) {
+    requirePrivateConfigurationDirectory(rootDir);
+    let raw;
+    try {
+        const path = pluginConfigurationPath(rootDir);
+        const info = lstatSync(path);
+        if (!info.isFile() || info.isSymbolicLink())
+            throw new PluginConfigurationError("unsafe_plugin_configuration", "Plugin configuration must be a regular local file.", 409);
+        requirePrivatePluginConfigurationPermissions(info.mode);
+        if (info.size > PLUGIN_CONFIGURATION_MAX_BYTES)
+            throw new PluginConfigurationError("plugin_configuration_too_large", "The local plugin configuration file is too large.", 409);
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (!isMissingPluginConfiguration(error))
+            throw error;
+    }
+    return {
+        plugins: parsePluginConfigurationStore(raw),
+        raw,
+        revision: createHash("sha256")
+            .update(raw === undefined ? "missing" : `present:${raw}`)
+            .digest("hex"),
+    };
+}

package/dist/src/runtime/plugins/configuration-write.d.ts

@@ -0,0 +1,5 @@
+import { type PluginConfigurationSnapshot, type PluginConfigurationStore } from "./configuration-store.js";
+/** Writers and Apply take the Runtime config lock before this installation-wide lock. */
+export declare function withPluginConfigurationLock<T>(rootDir: string, operation: () => Promise<T>): Promise<T>;
+/** Caller holds the installation-wide lock through commit and any restoration. */
+export declare function commitPluginConfigurationStore<T>(rootDir: string, previous: PluginConfigurationSnapshot, plugins: PluginConfigurationStore, commit: () => Promise<T>): Promise<T>;

package/dist/src/runtime/plugins/configuration-write.js

@@ -0,0 +1,58 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, realpath, rename, rm, writeFile, } from "node:fs/promises";
+import { dirname } from "node:path";
+import { withFileLock } from "../adapters/long-term-memory/file-lock.js";
+import { PLUGIN_CONFIGURATION_MAX_BYTES, PluginConfigurationError, pluginConfigurationPath, readPluginConfigurationStore, requirePrivateConfigurationDirectory, } from "./configuration-store.js";
+/** Writers and Apply take the Runtime config lock before this installation-wide lock. */
+export async function withPluginConfigurationLock(rootDir, operation) {
+    const root = await realpath(rootDir);
+    requirePrivateConfigurationDirectory(root);
+    const path = pluginConfigurationPath(root);
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    requirePrivateConfigurationDirectory(root);
+    return withFileLock(`${path}.lock`, operation, {
+        waitMs: Number.POSITIVE_INFINITY,
+    });
+}
+function requireUnchangedPluginConfiguration(rootDir, expected) {
+    if (readPluginConfigurationStore(rootDir).raw === expected)
+        return;
+    throw new PluginConfigurationError("plugin_configuration_changed", "Plugin configuration changed. Reload the form before saving.", 409);
+}
+async function replacePluginConfiguration(rootDir, expected, next) {
+    const path = pluginConfigurationPath(rootDir);
+    requireUnchangedPluginConfiguration(rootDir, expected);
+    if (next === undefined) {
+        await rm(path);
+        return;
+    }
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, next, { flag: "wx", mode: 0o600 });
+        await chmod(temporary, 0o600);
+        requireUnchangedPluginConfiguration(rootDir, expected);
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Caller holds the installation-wide lock through commit and any restoration. */
+export async function commitPluginConfigurationStore(rootDir, previous, plugins, commit) {
+    const next = JSON.stringify({ version: 1, plugins }, null, 2) + "\n";
+    if (Buffer.byteLength(next) > PLUGIN_CONFIGURATION_MAX_BYTES)
+        throw new PluginConfigurationError("plugin_configuration_too_large", "Plugin configuration is too large.");
+    await replacePluginConfiguration(rootDir, previous.raw, next);
+    try {
+        return await commit();
+    }
+    catch (error) {
+        try {
+            await replacePluginConfiguration(rootDir, next, previous.raw);
+        }
+        catch (restoreError) {
+            throw new AggregateError([error, restoreError], "Plugin configuration could not be restored after a failed save.");
+        }
+        throw error;
+    }
+}

package/dist/src/runtime/plugins/installation/archive.d.ts

@@ -0,0 +1,2 @@
+/** Expand only regular files. Nothing from the repository is executed. */
+export declare function extractPluginArchive(archive: Buffer, destination: string, subdirectory?: string): Promise<string>;

package/dist/src/runtime/plugins/installation/archive.js

@@ -0,0 +1,107 @@
+import { createHash } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import JSZip from "jszip";
+import { isPortablePluginPathComponent } from "./portable-path.js";
+import { Readable } from "node:stream";
+import { PluginInstallError } from "../../../plugin-contract/install-source.js";
+function rejectArchive(message) {
+    throw new PluginInstallError("plugin_archive_invalid", message);
+}
+function requireArchivePath(name) {
+    if (name.length > 1024 || /[\\\u0000-\u001f\u007f:]/u.test(name))
+        return rejectArchive("The archive contains an unsupported path.");
+    const parts = name.replace(/\/$/u, "").split("/");
+    if (parts.some((part) => !part || part === "." || part === ".."))
+        return rejectArchive("The archive contains an unsafe path.");
+    if (!parts.every(isPortablePluginPathComponent))
+        return rejectArchive("The archive contains a non-portable file name.");
+    return parts;
+}
+async function boundedEntry(entry, remaining) {
+    const stream = new Readable().wrap(entry.nodeStream());
+    const chunks = [];
+    let size = 0;
+    try {
+        for await (const chunk of stream) {
+            const bytes = Buffer.from(chunk);
+            size += bytes.length;
+            if (size > Math.min(16 * 1024 * 1024, remaining))
+                return rejectArchive("The expanded plugin exceeds its size limit.");
+            chunks.push(bytes);
+        }
+        return Buffer.concat(chunks);
+    }
+    finally {
+        stream.destroy();
+    }
+}
+/** Expand only regular files. Nothing from the repository is executed. */
+export async function extractPluginArchive(archive, destination, subdirectory = "") {
+    if (archive.length > 25 * 1024 * 1024)
+        return rejectArchive("The repository archive is too large.");
+    let zip;
+    try {
+        zip = await JSZip.loadAsync(archive, { createFolders: false });
+    }
+    catch {
+        return rejectArchive("The repository did not contain a valid ZIP archive.");
+    }
+    const entries = Object.values(zip.files);
+    if (entries.length > 2000)
+        return rejectArchive("The repository contains too many files.");
+    const roots = new Set();
+    const seen = new Set();
+    const hash = createHash("sha256");
+    let total = 0;
+    let written = 0;
+    const prefix = subdirectory ? subdirectory + "/" : "";
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name, "en"))) {
+        const original = entry
+            .unsafeOriginalName ?? entry.name;
+        const parts = requireArchivePath(original);
+        if (original !== entry.name)
+            return rejectArchive("The archive contains a rewritten path.");
+        roots.add(parts[0]);
+        if (roots.size !== 1)
+            return rejectArchive("The archive must have one repository root.");
+        const mode = typeof entry.unixPermissions === "number" ? entry.unixPermissions : 0;
+        const kind = mode & 0o170000;
+        if (kind && kind !== 0o100000 && kind !== 0o040000)
+            return rejectArchive("Plugin archives cannot contain links or special files.");
+        if (entry.dir)
+            continue;
+        if (kind === 0o040000)
+            return rejectArchive("The archive has inconsistent file types.");
+        const relative = parts.slice(1).join("/");
+        if (!relative.startsWith(prefix))
+            continue;
+        const target = relative.slice(prefix.length);
+        if (!target)
+            return rejectArchive("The plugin path must select a directory.");
+        if (target.split("/").includes(".git"))
+            return rejectArchive("Plugin packages cannot contain Git metadata.");
+        const identity = target.toLowerCase();
+        if (seen.has(identity))
+            return rejectArchive("The archive contains conflicting file names.");
+        seen.add(identity);
+        const bytes = await boundedEntry(entry, 64 * 1024 * 1024 - total);
+        total += bytes.length;
+        const path = join(destination, target);
+        await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        await writeFile(path, bytes, {
+            flag: "wx",
+            mode: mode & 0o111 ? 0o700 : 0o600,
+        });
+        hash
+            .update(target)
+            .update("\0")
+            .update(String(bytes.length))
+            .update("\0")
+            .update(bytes);
+        written += 1;
+    }
+    if (!written)
+        return rejectArchive("No plugin files were found in the selected folder.");
+    return hash.digest("hex");
+}

package/dist/src/runtime/plugins/installation/github-download.d.ts

@@ -0,0 +1,9 @@
+import { type PluginInstallSource } from "../../../plugin-contract/install-source.js";
+export type PluginDownload = Readonly<{
+    source: PluginInstallSource & {
+        ref: string;
+    };
+    archive: Buffer;
+}>;
+export type PluginSourceFetcher = (input: PluginInstallSource) => Promise<PluginDownload>;
+export declare const downloadGitHubPlugin: PluginSourceFetcher;

package/dist/src/runtime/plugins/installation/github-download.js

@@ -0,0 +1,72 @@
+import { PluginInstallError, parsePluginInstallSource, } from "../../../plugin-contract/install-source.js";
+const ARCHIVE_LIMIT = 25 * 1024 * 1024;
+async function readBoundedResponse(response, maximum) {
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new PluginInstallError("plugin_download_failed", "GitHub could not provide this public repository or revision.", 502);
+    }
+    if (Number(response.headers.get("content-length") ?? 0) > maximum) {
+        await response.body?.cancel();
+        throw new PluginInstallError("plugin_download_limit", "The repository archive is too large.");
+    }
+    if (!response.body)
+        throw new PluginInstallError("plugin_download_failed", "GitHub returned no content.", 502);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let length = 0;
+    try {
+        while (true) {
+            const part = await reader.read();
+            if (part.done)
+                break;
+            length += part.value.byteLength;
+            if (length > maximum)
+                throw new PluginInstallError("plugin_download_limit", "The repository archive is too large.");
+            chunks.push(Buffer.from(part.value));
+        }
+        return Buffer.concat(chunks);
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+export const downloadGitHubPlugin = async (input) => {
+    const source = parsePluginInstallSource(input);
+    const repository = new URL(source.repository).pathname.slice(1);
+    const signal = AbortSignal.timeout(60_000);
+    try {
+        let ref = source.ref;
+        if (!ref) {
+            const response = await fetch(`https://api.github.com/repos/${repository}`, {
+                headers: { accept: "application/vnd.github+json" },
+                redirect: "error",
+                signal,
+            });
+            const metadata = JSON.parse((await readBoundedResponse(response, 256 * 1024)).toString("utf8"));
+            if (typeof metadata.default_branch !== "string")
+                throw new Error("missing_branch");
+            ref = metadata.default_branch;
+        }
+        const response = await fetch(`https://api.github.com/repos/${repository}/commits/${encodeURIComponent(ref)}`, {
+            headers: { accept: "application/vnd.github+json" },
+            redirect: "error",
+            signal,
+        });
+        const commit = JSON.parse((await readBoundedResponse(response, 2 * 1024 * 1024)).toString("utf8"));
+        if (typeof commit.sha !== "string" || !/^[a-f0-9]{40}$/u.test(commit.sha))
+            throw new Error("invalid_commit");
+        if (/^[a-f0-9]{40}$/u.test(ref) && commit.sha !== ref)
+            throw new Error("commit_mismatch");
+        const archiveResponse = await fetch(`https://codeload.github.com/${repository}/zip/${commit.sha}`, { redirect: "error", signal });
+        return {
+            source: { ...source, ref: commit.sha },
+            archive: await readBoundedResponse(archiveResponse, ARCHIVE_LIMIT),
+        };
+    }
+    catch (error) {
+        if (error instanceof PluginInstallError)
+            throw error;
+        throw new PluginInstallError("plugin_download_failed", "The GitHub download failed or timed out. Check the repository and revision.", 502);
+    }
+};

package/dist/src/runtime/plugins/installation/installed-package.d.ts

@@ -0,0 +1,9 @@
+import type { DiscoveredAgentPluginManifest } from "../discovered-manifest.js";
+/** Stable package identity also works after moving it outside the discovery directory. */
+export declare function installedPluginPackageIdentity(path: string): string | undefined;
+/** Only installer-owned, direct consumer folders are removable. Never follow links. */
+export declare function installedPluginPackage(rootDir: string, plugin: DiscoveredAgentPluginManifest): {
+    path: string;
+    identity: string;
+    packageIdentity: string;
+} | undefined;

package/dist/src/runtime/plugins/installation/installed-package.js

@@ -0,0 +1,66 @@
+import { lstatSync, readFileSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parsePluginInstallSource } from "../../../plugin-contract/install-source.js";
+import { isPortablePluginPathComponent } from "./portable-path.js";
+/** Stable package identity also works after moving it outside the discovery directory. */
+export function installedPluginPackageIdentity(path) {
+    try {
+        const folder = lstatSync(path);
+        const receiptPath = join(path, ".abot-install.json");
+        const receiptStat = lstatSync(receiptPath);
+        if (!folder.isDirectory() ||
+            !receiptStat.isFile() ||
+            receiptStat.size > 4096)
+            return undefined;
+        const receipt = JSON.parse(readFileSync(receiptPath, "utf8"));
+        if (receipt.schemaVersion !== 1 ||
+            typeof receipt.digest !== "string" ||
+            !/^[a-f0-9]{64}$/u.test(receipt.digest) ||
+            typeof receipt.installedAt !== "string" ||
+            !Number.isFinite(Date.parse(receipt.installedAt)))
+            return undefined;
+        const source = parsePluginInstallSource(receipt.source);
+        if (!source.ref || !/^[a-f0-9]{40}$/u.test(source.ref))
+            return undefined;
+        const manifestPath = join(path, "plugin.json");
+        const manifestStat = lstatSync(manifestPath);
+        if (!manifestStat.isFile())
+            return undefined;
+        return JSON.stringify([
+            folder.dev,
+            folder.ino,
+            folder.birthtimeMs,
+            receipt,
+            readFileSync(manifestPath, "utf8"),
+        ]);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Only installer-owned, direct consumer folders are removable. Never follow links. */
+export function installedPluginPackage(rootDir, plugin) {
+    const id = plugin.manifest.name;
+    if (!isPortablePluginPathComponent(id))
+        return undefined;
+    try {
+        const directory = join(realpathSync(rootDir), "plugins");
+        const path = join(directory, id);
+        if (resolve(plugin.pluginRoot) !== path)
+            return undefined;
+        const parent = lstatSync(directory);
+        if (!parent.isDirectory())
+            return undefined;
+        const packageIdentity = installedPluginPackageIdentity(path);
+        if (!packageIdentity)
+            return undefined;
+        return {
+            path,
+            packageIdentity,
+            identity: JSON.stringify([parent.dev, parent.ino, packageIdentity]),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/src/runtime/plugins/installation/package.d.ts

@@ -0,0 +1,45 @@
+import { type PluginInstallSource } from "../../../plugin-contract/install-source.js";
+import { ABOT_RUNTIME_EXTENSION } from "../../../plugin-contract/manifest.js";
+import { type PluginSourceFetcher } from "./github-download.js";
+export declare function preparePluginPackage(rootDir: string, source: PluginInstallSource, download?: PluginSourceFetcher): Promise<{
+    staging: string;
+    manifest: Readonly<{
+        $schema: typeof import("../../../plugin-contract/manifest.js").AGENT_PLUGIN_MANIFEST_SCHEMA;
+        name: string;
+        version?: string;
+        description?: string;
+        extensions: Readonly<{
+            [ABOT_RUNTIME_EXTENSION]: import("../../../plugin-contract/manifest.js").AbotRuntimePluginExtension;
+            [namespace: string]: unknown;
+        }>;
+    }>;
+    review: {
+        source: Readonly<{
+            repository: string;
+            ref?: string;
+            path?: string;
+        }> & {
+            ref: string;
+        };
+        digest: string;
+        id: string;
+        version: string;
+        description: string;
+        capabilities: {
+            id: string;
+            description: string;
+            operations: {
+                name: string;
+                effect: import("../../../capabilities/tool-types.js").ToolNormalInvocationEffect;
+                approval: import("../../../capabilities/tool-types.js").ToolNormalInvocationApproval;
+            }[];
+        }[];
+        settings: Readonly<Record<string, unknown>>;
+        secrets: {
+            name: string;
+            env: string;
+            required: boolean;
+        }[];
+    };
+}>;
+export declare function requireNewPluginIdentity(rootDir: string, id: string, capabilityIds: readonly string[]): void;