@abot-ai/runtime 1.5.0 → 1.7.0

package/dist/src/runtime/passive-learning/staged-review-call.js

@@ -14,14 +14,18 @@ export async function runStagedCoWorkerReview(options) {
     const binding = fingerprintReviewProgress({ method: "super-v2", activity: options.activity,
         reviewId: options.reviewId, input: options.binding,
         preference: request.modelPreference, models: request.modelPolicy, runner: request.runnerConfig });
-    const previous = readCoWorkerReviewProgress(options.progress?.read());
+    const maxAgeMs = options.maxProgressAgeMs ?? MAX_CO_WORKER_REVIEW_PROGRESS_AGE_MS;
+    const trace = options.replayOnly ? () => { } : traceDebug;
+    const previous = readCoWorkerReviewProgress(options.progress?.read(), maxAgeMs);
     const canResume = canResumeReview(previous, binding, now(), options.expiresAt);
-    let progress = canResume ? previous : createProgress(options, binding);
+    if (options.replayOnly && !canResume)
+        throw new Error("co_worker_review_requires_model_call");
+    let progress = canResume ? previous : createProgress(options, binding, maxAgeMs);
     const correlation = { requestId: request.requestId, reviewId: options.reviewId,
         activity: options.activity, method: "staged", modelProfileId: request.modelPreference?.profileId };
     if (previous && !canResume) {
         await options.progress?.save(progress);
-        traceDebug("runtime.passive_learning", "review.progress_discarded", { ...correlation, reason: "binding_or_retention_changed" });
+        trace("runtime.passive_learning", "review.progress_discarded", { ...correlation, reason: "binding_or_retention_changed" });
     }
     const invoker = new RequestModelStepInvoker(request);
     const visited = new Set();
@@ -39,19 +43,21 @@ export async function runStagedCoWorkerReview(options) {
                 result = params.accept(saved.response, { outputLength: saved.response.length, acceptedAt: saved.acceptedAt });
             }
             catch (error) {
-                traceDebug("runtime.passive_learning", "review.stage_failed", { ...correlation, stage,
+                trace("runtime.passive_learning", "review.stage_failed", { ...correlation, stage,
                     reason: safeStagedReviewFailure(error), ...reviewValidationDetails(error) });
                 throw error;
             }
             request.abortSignal.throwIfAborted();
             assertReviewProgressUnexpired(progress, now());
             if (!reuse || reuse(result)) {
-                traceDebug("runtime.passive_learning", "review.stage_resumed", { ...correlation, stage });
+                trace("runtime.passive_learning", "review.stage_resumed", { ...correlation, stage });
                 return result;
             }
-            traceDebug("runtime.passive_learning", "review.stage_invalidated", { ...correlation, stage, reason: "result_expired" });
+            trace("runtime.passive_learning", "review.stage_invalidated", { ...correlation, stage, reason: "result_expired" });
         }
-        traceDebug("runtime.passive_learning", "review.stage_started", { ...correlation, stage,
+        if (options.replayOnly)
+            throw new Error("co_worker_review_requires_model_call");
+        trace("runtime.passive_learning", "review.stage_started", { ...correlation, stage,
             inputCharacters: params.messages.reduce((sum, message) => sum + (message.content?.length ?? 0), 0),
             schemaCharacters: JSON.stringify(params.format ?? {}).length });
         try {
@@ -70,15 +76,15 @@ export async function runStagedCoWorkerReview(options) {
             assertReviewProgressUnexpired(progress, now());
             // Keep only the executed prefix when a stage's inputs change.
             const stages = progress.stages.filter(item => visited.has(item.key) && item.key !== stage);
-            const next = readCoWorkerReviewProgress({ ...progress, stages: [...stages, { key: stage, fingerprint, response, acceptedAt }] });
+            const next = readCoWorkerReviewProgress({ ...progress, stages: [...stages, { key: stage, fingerprint, response, acceptedAt }] }, maxAgeMs);
             await options.progress?.save(next);
             progress = next;
             request.abortSignal.throwIfAborted();
-            traceDebug("runtime.passive_learning", "review.stage_completed", { ...correlation, stage, savedStages: progress.stages.length });
+            trace("runtime.passive_learning", "review.stage_completed", { ...correlation, stage, savedStages: progress.stages.length });
             return result;
         }
         catch (error) {
-            traceDebug("runtime.passive_learning", "review.stage_failed", { ...correlation, stage,
+            trace("runtime.passive_learning", "review.stage_failed", { ...correlation, stage,
                 reason: safeStagedReviewFailure(error), ...reviewValidationDetails(error) });
             throw error;
         }
@@ -95,10 +101,10 @@ function canResumeReview(progress, binding, now, expiresAt) {
         return false;
     return Date.parse(progress.expiresAt) <= Date.parse(expiresAt);
 }
-function createProgress(options, binding) {
-    const expiresAt = new Date(Math.min(Date.parse(options.expiresAt), Date.parse(options.referenceTime) + MAX_CO_WORKER_REVIEW_PROGRESS_AGE_MS)).toISOString();
+function createProgress(options, binding, maxAgeMs) {
+    const expiresAt = new Date(Math.min(Date.parse(options.expiresAt), Date.parse(options.referenceTime) + maxAgeMs)).toISOString();
     return readCoWorkerReviewProgress({ schemaVersion: 1, method: "super-v2", binding,
-        referenceTime: options.referenceTime, expiresAt, stages: [] });
+        referenceTime: options.referenceTime, expiresAt, stages: [] }, maxAgeMs);
 }
 function assertReviewStageAdmission(stage, visited, maximum) {
     if (!isReviewStageKey(stage))

package/dist/src/runtime/passive-learning/store.js

@@ -11,6 +11,7 @@ import { DEFAULT_ANALYSIS_TRIGGER, DEFAULT_ANALYSIS_OBSERVATION_COUNT } from "./
 import { readObservationReviewPass } from "./processing-pass.js";
 import { readCoWorkerReviewProgress } from "./review-progress.js";
 import { normalizeLearningActivityControls } from "./activity-permissions.js";
+import { readSparkToolPermissionMode } from "./spark-chat-preferences.js";
 export const DEFAULT_LEARNING_PREFERENCES = Object.freeze({
     enabled: false,
     processingPaused: true,
@@ -22,6 +23,7 @@ export const DEFAULT_LEARNING_PREFERENCES = Object.freeze({
     analysisWindow: null,
     collectionWindow: null,
     proactiveEnabled: false,
+    sparkToolPermissionMode: "ask",
     proactiveIntervalMinutes: 60,
     proactiveWindow: null,
     proactiveMessagesPerDay: 2,
@@ -101,6 +103,8 @@ export function normalizeLearningPreferences(input, previous) {
         processingExcludedApplications: processingExcluded,
         ...schedule,
         ...normalizeIndependentLearningPreferences(input, previous),
+        sparkToolPermissionMode: readSparkToolPermissionMode(input.sparkToolPermissionMode === undefined
+            ? previous.sparkToolPermissionMode : input.sparkToolPermissionMode),
         ...normalizeLearningActivityControls(input, previous),
         maturation: Object.freeze({ ...maturation }),
         resourceLimits: Object.freeze({ ...resourceLimits }),

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;
+    }
+}