@abot-ai/runtime 1.5.0 → 1.7.0

package/dist/src/computer-access/command-output-retention.js

@@ -0,0 +1,90 @@
+import { readFile, readdir, rm, stat } from "node:fs/promises";
+import { join } from "node:path";
+export const DEFAULT_SYSTEM_OUTPUT_RETENTION_MS = 7 * 24 * 60 * 60_000;
+export const activeSystemCaptures = new Set();
+const jobs = new Map();
+const CAPTURE_ID = /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/;
+export async function cleanupSystemOutput(root, retentionMs) {
+    const entries = await readdir(root, { withFileTypes: true }).catch((error) => {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    });
+    let removed = 0;
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !CAPTURE_ID.test(entry.name))
+            continue;
+        const directory = join(root, entry.name);
+        if (activeSystemCaptures.has(directory))
+            continue;
+        const files = await readdir(directory);
+        const times = await Promise.all(files.map(async (file) => (await stat(join(directory, file))).mtimeMs));
+        const completedAt = Math.max((await stat(directory)).mtimeMs, ...times);
+        const captureRetentionMs = await readCaptureRetention(directory, entry.name, retentionMs);
+        if (Date.now() - completedAt < captureRetentionMs)
+            continue;
+        if (activeSystemCaptures.has(directory))
+            continue;
+        await rm(directory, { recursive: true });
+        removed += 1;
+    }
+    return removed;
+}
+/** Completed captures keep the policy recorded by their producer across reconnects. */
+async function readCaptureRetention(directory, id, fallbackMs) {
+    let receipt;
+    try {
+        receipt = JSON.parse(await readFile(join(directory, "receipt.json"), "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return fallbackMs;
+        if (error instanceof SyntaxError)
+            return fallbackMs;
+        throw error;
+    }
+    if (receipt === null || typeof receipt !== "object")
+        return fallbackMs;
+    if (!("kind" in receipt) || receipt.kind !== "system_command_output_v1")
+        return fallbackMs;
+    if (!("id" in receipt) || receipt.id !== id)
+        return fallbackMs;
+    if (!("retentionMs" in receipt) || typeof receipt.retentionMs !== "number")
+        return fallbackMs;
+    if (!Number.isSafeInteger(receipt.retentionMs) || receipt.retentionMs < 1)
+        return fallbackMs;
+    return receipt.retentionMs;
+}
+/** One cleanup job per storage root; the supplied policy also covers incomplete captures. */
+export function scheduleSystemOutputCleanup(root, retentionMs) {
+    const previous = jobs.get(root);
+    if (previous) {
+        previous.retentionMs = retentionMs;
+        previous.requested = true;
+        return;
+    }
+    const job = { retentionMs, requested: false };
+    jobs.set(root, job);
+    const sweep = async () => {
+        job.requested = false;
+        let empty = false;
+        try {
+            await cleanupSystemOutput(root, job.retentionMs);
+            empty = (await readdir(root).catch((error) => {
+                if (error.code === "ENOENT")
+                    return [];
+                throw error;
+            })).length === 0;
+        }
+        catch {
+            process.emitWarning("SYSTEM output cleanup failed; retained output was not confirmed removed.", { code: "SYSTEM_OUTPUT_CLEANUP_FAILED" });
+        }
+        if (empty && !job.requested) {
+            jobs.delete(root);
+            return;
+        }
+        const timer = setTimeout(() => { void sweep(); }, Math.max(1, Math.min(job.retentionMs, 60 * 60_000)));
+        timer.unref();
+    };
+    void sweep();
+}

package/dist/src/computer-access/command-output.d.ts

@@ -0,0 +1,7 @@
+import type { ToolExecutionContext, ToolImplementationOutput } from "../plugin-sdk/index.js";
+import type { SystemProcessResult, SystemProcessRunner, SystemTarget } from "./contracts.js";
+/** Allocated per command; probes and companion calls retain their existing runner. */
+export type SystemCommandOutputFactory = (context?: ToolExecutionContext) => Readonly<{
+    run: SystemProcessRunner;
+    present(target: SystemTarget, result: SystemProcessResult): Promise<ToolImplementationOutput>;
+}>;

package/dist/src/computer-access/command-output.js

@@ -0,0 +1 @@
+export {};

package/dist/src/computer-access/commands.d.ts

@@ -3,5 +3,6 @@ export declare function executeSystemCommand(input: {
     target: SystemTarget;
     params: Record<string, unknown>;
     run: SystemProcessRunner;
+    runCommand?: SystemProcessRunner;
     abortSignal?: AbortSignal;
 }): Promise<SystemProcessResult>;

package/dist/src/computer-access/commands.js

@@ -32,7 +32,7 @@ export async function executeSystemCommand(input) {
     const plan = params.elevated === true
         ? await elevatedSystemCommand({ target, command, cwd, run })
         : unprivilegedSystemCommand(target, command, cwd);
-    return run({
+    return (input.runCommand ?? run)({
         ...plan,
         timeoutMs,
         ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),

package/dist/src/computer-access/companion/command-output-protocol.d.ts

@@ -0,0 +1,12 @@
+export declare const SYSTEM_OUTPUT_CAPABILITY = "system_command_output_v1";
+/** Base64 plus receipts stay below both Companion and broker message limits. */
+export declare const SYSTEM_OUTPUT_CHUNK_BYTES: number;
+export type SystemOutputTransfer = Readonly<{
+    kind: typeof SYSTEM_OUTPUT_CAPABILITY;
+    id: string;
+    stdoutBytes: number;
+    stderrBytes: number;
+    stdoutSha256: string;
+    stderrSha256: string;
+}>;
+export declare function readSystemOutputTransfer(value: unknown): SystemOutputTransfer;

package/dist/src/computer-access/companion/command-output-protocol.js

@@ -0,0 +1,28 @@
+import { isHostIdentifier, isHostRecord } from "./protocol.js";
+export const SYSTEM_OUTPUT_CAPABILITY = "system_command_output_v1";
+/** Base64 plus receipts stay below both Companion and broker message limits. */
+export const SYSTEM_OUTPUT_CHUNK_BYTES = 64 * 1024;
+function isStreamByteCount(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isStreamDigest(value) {
+    return typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+}
+export function readSystemOutputTransfer(value) {
+    if (!isHostRecord(value))
+        throw new Error("system_output_receipt_invalid");
+    if (value.kind !== SYSTEM_OUTPUT_CAPABILITY)
+        throw new Error("system_output_receipt_invalid");
+    if (!isHostIdentifier(value.id))
+        throw new Error("system_output_receipt_invalid");
+    if (!isStreamByteCount(value.stdoutBytes))
+        throw new Error("system_output_receipt_invalid");
+    if (!isStreamByteCount(value.stderrBytes))
+        throw new Error("system_output_receipt_invalid");
+    if (!isStreamDigest(value.stdoutSha256))
+        throw new Error("system_output_receipt_invalid");
+    if (!isStreamDigest(value.stderrSha256))
+        throw new Error("system_output_receipt_invalid");
+    return { kind: SYSTEM_OUTPUT_CAPABILITY, id: value.id, stdoutBytes: value.stdoutBytes,
+        stderrBytes: value.stderrBytes, stdoutSha256: value.stdoutSha256, stderrSha256: value.stderrSha256 };
+}

package/dist/src/computer-access/companion/command-output.d.ts

@@ -0,0 +1,13 @@
+import { type ToolImplementation } from "../../plugin-sdk/index.js";
+/** References belong to this authenticated connection; no arbitrary file access. */
+export declare class CompanionCommandOutput {
+    private readonly stateDir;
+    private readonly captures;
+    private closed;
+    constructor(stateDir: string);
+    hasTransfers(): boolean;
+    close(): void;
+    handlers(): Record<string, ToolImplementation>;
+    private command;
+    private read;
+}

package/dist/src/computer-access/companion/command-output.js

@@ -0,0 +1,110 @@
+import { join } from "node:path";
+import { failureResult, readBoundedInteger, successResult } from "../../plugin-sdk/index.js";
+import { createSystemHandlers } from "../handlers.js";
+import { createSystemOutputCapture } from "../command-output-capture.js";
+import { DEFAULT_SYSTEM_OUTPUT_RETENTION_MS, scheduleSystemOutputCleanup } from "../command-output-retention.js";
+import { runSystemProcess } from "../process-runner.js";
+import { buildSystemProcessResult } from "../process-result.js";
+import { isHostIdentifier } from "./protocol.js";
+import { SYSTEM_OUTPUT_CAPABILITY, SYSTEM_OUTPUT_CHUNK_BYTES, readSystemOutputTransfer } from "./command-output-protocol.js";
+/** References belong to this authenticated connection; no arbitrary file access. */
+export class CompanionCommandOutput {
+    stateDir;
+    captures = new Map();
+    closed = false;
+    constructor(stateDir) {
+        this.stateDir = stateDir;
+        scheduleSystemOutputCleanup(join(stateDir, "command-output"), DEFAULT_SYSTEM_OUTPUT_RETENTION_MS);
+    }
+    hasTransfers() { return this.captures.size > 0; }
+    close() {
+        this.closed = true;
+        for (const capture of this.captures.values())
+            capture.release();
+        this.captures.clear();
+    }
+    handlers() {
+        return {
+            system_command_capture: (params, context) => this.command(params, context),
+            system_command_output: async (params) => {
+                try {
+                    return await this.read(params);
+                }
+                catch {
+                    return failureResult({ errorCode: "system_output_unavailable", message: "Retained command output is unavailable in this connection. The command was not replayed." });
+                }
+            },
+            system_command_output_close: async (params) => {
+                if (!isHostIdentifier(params.captureId))
+                    return failureResult({ errorCode: "system_output_reference_invalid", message: "Invalid output reference." });
+                this.captures.get(params.captureId)?.release();
+                this.captures.delete(params.captureId);
+                return successResult({ output: "Output transfer closed; disk retention remains in effect." });
+            },
+        };
+    }
+    async command(params, context) {
+        if (this.closed)
+            return failureResult({ errorCode: "system_output_closed", message: "The connection closed before dispatch." });
+        const retentionMs = readBoundedInteger(params.outputRetentionMs, {
+            name: "outputRetentionMs", defaultValue: DEFAULT_SYSTEM_OUTPUT_RETENTION_MS,
+            minimum: 1, maximum: Number.MAX_SAFE_INTEGER,
+        });
+        let captured;
+        const handlers = createSystemHandlers(undefined, undefined, () => ({
+            run: async (input) => {
+                if (input.abortSignal?.aborted)
+                    return runSystemProcess(input);
+                captured = await createSystemOutputCapture(join(this.stateDir, "command-output"), retentionMs);
+                captured.retain();
+                try {
+                    const result = await runSystemProcess(input, captured.capture);
+                    await captured.finish(result, false);
+                    return { ...result, outputTruncated: Boolean(captured.failure) };
+                }
+                catch (error) {
+                    await captured.finish(undefined, false);
+                    captured.release();
+                    throw error;
+                }
+            },
+            present: async (target, result) => {
+                const receipt = buildSystemProcessResult(target, result, "command_process_completion");
+                if (!captured?.receipt)
+                    return receipt;
+                const data = { ...receipt.data, outputCapture: captured.receipt };
+                if (captured.failure) {
+                    captured.release();
+                    return failureResult({ errorCode: "system_output_storage_failed", message: "Command output storage failed after dispatch; inspect the process receipt before another action.",
+                        data: { ...data, storageFailure: captured.failure }, ...(result.exitCode !== null ? { exitCode: result.exitCode } : {}) });
+                }
+                if (this.closed || context?.abortSignal?.aborted) {
+                    captured.release();
+                    return { ...receipt, data };
+                }
+                const transfer = readSystemOutputTransfer({ kind: SYSTEM_OUTPUT_CAPABILITY, ...captured.receipt });
+                this.captures.set(transfer.id, captured);
+                return { ...receipt, output: receipt.output.split("\nSTDOUT excerpt:")[0] + "\nSTDOUT excerpt:\nStreams retained for exact transfer.",
+                    data: { ...data, outputTransfer: transfer } };
+            },
+        }));
+        const { outputRetentionMs: _retention, ...command } = params;
+        return handlers.system_command(command, context);
+    }
+    async read(params) {
+        if (!isHostIdentifier(params.captureId))
+            throw new Error("system_output_reference_invalid");
+        const capture = this.captures.get(params.captureId);
+        if (!capture?.receipt)
+            throw new Error("system_output_reference_unknown");
+        if (params.stream !== "stdout" && params.stream !== "stderr")
+            throw new Error("system_output_stream_invalid");
+        const stream = params.stream;
+        const size = stream === "stdout" ? capture.receipt.stdoutBytes : capture.receipt.stderrBytes;
+        const offset = readBoundedInteger(params.offset, { name: "offset", minimum: 0, maximum: size });
+        const bytes = await capture.read(stream, offset, Math.min(SYSTEM_OUTPUT_CHUNK_BYTES, size - offset));
+        return successResult({ output: "Private command-output chunk.", data: {
+                captureId: params.captureId, stream, offset, bytes: bytes.toString("base64"),
+            } });
+    }
+}

package/dist/src/computer-access/companion/install-link-macos.d.ts

@@ -0,0 +1,7 @@
+import type { NativeAutostartOptions } from "./autostart.js";
+export declare function renderMacInstallLinkHandler(options: NativeAutostartOptions): string;
+export declare const MAC_INSTALL_LINK_BUNDLE_ID = "com.abot.install-links";
+export declare const MAC_INSTALL_LINK_HANDLER_QUERY_SCRIPT = "ObjC.import('CoreServices');\nfunction run(argv) {\n  var handler = ObjC.castRefToObject($.LSCopyDefaultHandlerForURLScheme($(argv[0])));\n  if (handler.isNil()) return '';\n  return ObjC.unwrap(handler);\n}\n";
+export declare function requireAvailableMacInstallScheme(): Promise<void>;
+/** Preserve the executable and scripting metadata emitted by osacompile. */
+export declare const MAC_INSTALL_LINK_PLIST_SCRIPT = "ObjC.import('Foundation');\nfunction run(argv) {\n  var plist = $.NSMutableDictionary.alloc.initWithContentsOfFile($(argv[0]));\n  if (!plist) throw new Error('Installation-link bundle has no property list.');\n  var updates = {\n    CFBundleIdentifier: 'com.abot.install-links',\n    CFBundleName: 'ABot Install',\n    LSUIElement: true,\n    CFBundleURLTypes: [{CFBundleURLName: 'ABot installation links', CFBundleURLSchemes: ['abot']}]\n  };\n  Object.keys(updates).forEach(function(key) { plist.setObjectForKey($(updates[key]), $(key)); });\n  if (!plist.writeToFileAtomically($(argv[0]), true)) throw new Error('Could not register installation links.');\n}\n";

package/dist/src/computer-access/companion/install-link-macos.js

@@ -0,0 +1,48 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+export function renderMacInstallLinkHandler(options) {
+    const literal = (value) => JSON.stringify(value);
+    return `ObjC.import('Foundation');
+function openDocuments() {}
+function openLocation(url) {
+  var task = $.NSTask.alloc.init;
+  task.launchPath = ${literal(options.nodePath)};
+  task.arguments = [${literal(options.cliPath)}, 'host', 'open-link', String(url)];
+  task.launch;
+}
+`;
+}
+export const MAC_INSTALL_LINK_BUNDLE_ID = "com.abot.install-links";
+export const MAC_INSTALL_LINK_HANDLER_QUERY_SCRIPT = `ObjC.import('CoreServices');
+function run(argv) {
+  var handler = ObjC.castRefToObject($.LSCopyDefaultHandlerForURLScheme($(argv[0])));
+  if (handler.isNil()) return '';
+  return ObjC.unwrap(handler);
+}
+`;
+const executeFile = promisify(execFile);
+function isAvailableMacInstallScheme(handler) {
+    if (!handler)
+        return true;
+    return handler === MAC_INSTALL_LINK_BUNDLE_ID;
+}
+export async function requireAvailableMacInstallScheme() {
+    const { stdout } = await executeFile("/usr/bin/osascript", ["-l", "JavaScript", "-e", MAC_INSTALL_LINK_HANDLER_QUERY_SCRIPT, "abot"], { timeout: 30_000, maxBuffer: 16_384 });
+    if (!isAvailableMacInstallScheme(stdout.trim()))
+        throw new Error("The abot URL scheme belongs to another application.");
+}
+/** Preserve the executable and scripting metadata emitted by osacompile. */
+export const MAC_INSTALL_LINK_PLIST_SCRIPT = `ObjC.import('Foundation');
+function run(argv) {
+  var plist = $.NSMutableDictionary.alloc.initWithContentsOfFile($(argv[0]));
+  if (!plist) throw new Error('Installation-link bundle has no property list.');
+  var updates = {
+    CFBundleIdentifier: '${MAC_INSTALL_LINK_BUNDLE_ID}',
+    CFBundleName: 'ABot Install',
+    LSUIElement: true,
+    CFBundleURLTypes: [{CFBundleURLName: 'ABot installation links', CFBundleURLSchemes: ['abot']}]
+  };
+  Object.keys(updates).forEach(function(key) { plist.setObjectForKey($(updates[key]), $(key)); });
+  if (!plist.writeToFileAtomically($(argv[0]), true)) throw new Error('Could not register installation links.');
+}
+`;

package/dist/src/computer-access/companion/install-link-registration.d.ts

@@ -0,0 +1,4 @@
+import type { NativeAutostartOptions } from "./autostart.js";
+export declare function renderLinuxInstallLinkDesktop(options: NativeAutostartOptions): string;
+export declare function installCompanionInstallLinks(options: NativeAutostartOptions): Promise<void>;
+export declare function uninstallCompanionInstallLinks(options: NativeAutostartOptions): Promise<void>;

package/dist/src/computer-access/companion/install-link-registration.js

@@ -0,0 +1,184 @@
+import { execFile } from "node:child_process";
+import { lstat, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, posix } from "node:path";
+import { promisify } from "node:util";
+import { ensurePrivateRuntimeDirectory } from "../../runtime/local-host/private-directory.js";
+import { renderWindowsInstallLinkLauncher, windowsInstallLinkLauncherPath, windowsInstallLinkRegistryScript, } from "./install-link-windows.js";
+import { renderMacInstallLinkHandler, requireAvailableMacInstallScheme, MAC_INSTALL_LINK_PLIST_SCRIPT, MAC_INSTALL_LINK_BUNDLE_ID, } from "./install-link-macos.js";
+const OWNER = "ABot managed installation links";
+const executeFile = promisify(execFile);
+function desktopArgument(value) {
+    if (/[\r\n\0]/u.test(value))
+        throw new Error("Unsupported Companion path.");
+    return ('"' +
+        value
+            .replaceAll("\\", "\\\\")
+            .replaceAll('"', '\\"')
+            .replaceAll("$", "\\$")
+            .replaceAll("`", "\\`")
+            .replaceAll("%", "%%") +
+        '"');
+}
+export function renderLinuxInstallLinkDesktop(options) {
+    return `[Desktop Entry]
+# ${OWNER}
+Type=Application
+Name=ABot Install
+Exec=${desktopArgument(options.nodePath)} ${desktopArgument(options.cliPath)} host open-link %u
+Terminal=false
+NoDisplay=true
+MimeType=x-scheme-handler/abot;
+`;
+}
+function registrationDirectory(options) {
+    return join(options.stateDir, "install-links");
+}
+async function run(options, file, args) {
+    if (options.execute)
+        return options.execute(file, args);
+    await executeFile(file, [...args], {
+        windowsHide: true,
+        timeout: 30_000,
+        maxBuffer: 16_384,
+    });
+}
+async function existingOwnedDirectory(path) {
+    const stat = await lstat(path).catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (!stat)
+        return false;
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error("Installation-link directory is not owned.");
+    if ((await readFile(join(path, ".owner"), "utf8")) !== OWNER)
+        throw new Error("Installation-link directory is not owned.");
+    return true;
+}
+function hasAbsoluteLinuxDataHome(value) {
+    if (!value)
+        return false;
+    return posix.isAbsolute(value);
+}
+function linuxDesktopPath(options) {
+    const dataHome = process.env.XDG_DATA_HOME;
+    if (hasAbsoluteLinuxDataHome(dataHome))
+        return join(dataHome, "applications", "com.abot.install-links.desktop");
+    return join(options.homeDir, ".local", "share", "applications", "com.abot.install-links.desktop");
+}
+async function requireOwnedLinuxRegistration(path) {
+    const stat = await lstat(path).catch((error) => {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    });
+    if (!stat)
+        return;
+    if (!stat.isFile() ||
+        stat.isSymbolicLink() ||
+        !(await readFile(path, "utf8")).includes("# " + OWNER))
+        throw new Error("Installation-link desktop registration is not owned.");
+}
+function isAvailableLinuxInstallScheme(handler) {
+    if (!handler)
+        return true;
+    return handler === "com.abot.install-links.desktop";
+}
+async function requireAvailableLinuxInstallScheme() {
+    const { stdout } = await executeFile("xdg-mime", ["query", "default", "x-scheme-handler/abot"], { timeout: 30_000, maxBuffer: 16_384 });
+    if (!isAvailableLinuxInstallScheme(stdout.trim()))
+        throw new Error("The abot URL scheme belongs to another application.");
+}
+export async function installCompanionInstallLinks(options) {
+    const directory = registrationDirectory(options);
+    if (!(await existingOwnedDirectory(directory))) {
+        await ensurePrivateRuntimeDirectory(directory);
+        await writeFile(join(directory, ".owner"), OWNER, {
+            flag: "wx",
+            mode: 0o600,
+        });
+    }
+    if (options.platform === "win32") {
+        const launcher = windowsInstallLinkLauncherPath(options);
+        await writeFile(launcher, renderWindowsInstallLinkLauncher(options), {
+            mode: 0o600,
+        });
+        await run(options, "powershell.exe", [
+            "-NoProfile",
+            "-NonInteractive",
+            "-EncodedCommand",
+            Buffer.from(windowsInstallLinkRegistryScript("install", launcher), "utf16le").toString("base64"),
+        ]);
+        return;
+    }
+    if (options.platform === "linux") {
+        const desktop = linuxDesktopPath(options);
+        await requireOwnedLinuxRegistration(desktop);
+        await requireAvailableLinuxInstallScheme();
+        await mkdir(dirname(desktop), { recursive: true, mode: 0o700 });
+        await writeFile(desktop, renderLinuxInstallLinkDesktop(options), {
+            mode: 0o600,
+        });
+        await run(options, "xdg-mime", [
+            "default",
+            "com.abot.install-links.desktop",
+            "x-scheme-handler/abot",
+        ]);
+        return;
+    }
+    if (options.platform === "darwin") {
+        await requireAvailableMacInstallScheme();
+        const source = join(directory, "handler.js");
+        const app = join(directory, "ABot Install.app");
+        await writeFile(source, renderMacInstallLinkHandler(options), {
+            mode: 0o600,
+        });
+        await rm(app, { recursive: true, force: true });
+        await run(options, "/usr/bin/osacompile", [
+            "-l",
+            "JavaScript",
+            "-o",
+            app,
+            source,
+        ]);
+        await run(options, "/usr/bin/osascript", [
+            "-l",
+            "JavaScript",
+            "-e",
+            MAC_INSTALL_LINK_PLIST_SCRIPT,
+            join(app, "Contents", "Info.plist"),
+        ]);
+        await run(options, "/usr/bin/codesign", [
+            "--force",
+            "--sign",
+            "-",
+            "--identifier",
+            MAC_INSTALL_LINK_BUNDLE_ID,
+            app,
+        ]);
+        await run(options, "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister", ["-f", app]);
+        return;
+    }
+    throw new Error("Installation links are not supported on this platform.");
+}
+export async function uninstallCompanionInstallLinks(options) {
+    const directory = registrationDirectory(options);
+    if (!(await existingOwnedDirectory(directory)))
+        return;
+    if (options.platform === "win32")
+        await run(options, "powershell.exe", [
+            "-NoProfile",
+            "-NonInteractive",
+            "-EncodedCommand",
+            Buffer.from(windowsInstallLinkRegistryScript("remove", windowsInstallLinkLauncherPath(options)), "utf16le").toString("base64"),
+        ]);
+    if (options.platform === "linux") {
+        const desktop = linuxDesktopPath(options);
+        await requireOwnedLinuxRegistration(desktop);
+        await rm(desktop, { force: true });
+    }
+    if (options.platform === "darwin")
+        await run(options, "/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister", ["-u", join(directory, "ABot Install.app")]);
+    await rm(directory, { recursive: true });
+}

package/dist/src/computer-access/companion/install-link-windows.d.ts

@@ -0,0 +1,4 @@
+import type { NativeAutostartOptions } from "./autostart.js";
+export declare function renderWindowsInstallLinkLauncher(options: NativeAutostartOptions): string;
+export declare function windowsInstallLinkRegistryScript(action: "install" | "remove", launcher: string): string;
+export declare function windowsInstallLinkLauncherPath(options: NativeAutostartOptions): string;

package/dist/src/computer-access/companion/install-link-windows.js

@@ -0,0 +1,65 @@
+import { join } from "node:path";
+function vbsText(value) {
+    if (/[\r\n\0]/u.test(value))
+        throw new Error("Unsupported Companion path.");
+    return '"' + value.replaceAll('"', '""') + '"';
+}
+export function renderWindowsInstallLinkLauncher(options) {
+    if (/["\r\n\0]/u.test(options.nodePath + options.cliPath))
+        throw new Error("Unsupported Companion path.");
+    const prefix = `"${options.nodePath}" "${options.cliPath}" host open-link --encoded `;
+    return [
+        "' ABot managed installation links",
+        "If WScript.Arguments.Count <> 1 Then WScript.Quit 1",
+        "value = WScript.Arguments(0)",
+        "If InStr(value, Chr(34)) > 0 Or InStr(value, vbCr) > 0 Or InStr(value, vbLf) > 0 Then WScript.Quit 1",
+        "If Len(value) > 2048 Then WScript.Quit 1",
+        'Set stream = CreateObject("ADODB.Stream")',
+        "stream.Type = 2",
+        'stream.Charset = "utf-8"',
+        "stream.Open",
+        "stream.WriteText value",
+        "stream.Position = 0",
+        "stream.Type = 1",
+        "stream.Position = 3",
+        'Set document = CreateObject("Msxml2.DOMDocument.6.0")',
+        'Set encoded = document.createElement("encoded")',
+        'encoded.dataType = "bin.base64"',
+        "encoded.nodeTypedValue = stream.Read",
+        "stream.Close",
+        'value = Replace(Replace(encoded.text, vbCr, ""), vbLf, "")',
+        'Set shell = CreateObject("WScript.Shell")',
+        `shell.Run ${vbsText(prefix)} & value, 0, False`,
+        "",
+    ].join("\r\n");
+}
+export function windowsInstallLinkRegistryScript(action, launcher) {
+    const quoted = (value) => "'" + value.replaceAll("'", "''") + "'";
+    const command = `wscript.exe "${launcher}" "%1"`;
+    return `
+$ErrorActionPreference = 'Stop'
+$key = 'HKCU:\\Software\\Classes\\abot'
+$expected = ${quoted(launcher)}
+$exists = Test-Path -LiteralPath $key
+function Assert-OwnedInstallLinkRegistration([string]$path) {
+  if (!(Test-Path -LiteralPath $path)) { return }
+  $owner = (Get-ItemProperty -LiteralPath $path -Name ABotInstallLinkOwner -ErrorAction SilentlyContinue).ABotInstallLinkOwner
+  if ($owner -ne $expected) { throw 'The abot protocol belongs to another application.' }
+}
+Assert-OwnedInstallLinkRegistration $key
+${action === "remove"
+        ? "if ($exists) { Remove-Item -LiteralPath $key -Recurse -Force }"
+        : `
+Assert-OwnedInstallLinkRegistration 'Registry::HKEY_CLASSES_ROOT\\abot'
+New-Item -Path $key -Force | Out-Null
+Set-Item -LiteralPath $key -Value 'URL:ABot installation'
+New-ItemProperty -LiteralPath $key -Name 'URL Protocol' -Value '' -PropertyType String -Force | Out-Null
+New-ItemProperty -LiteralPath $key -Name ABotInstallLinkOwner -Value $expected -PropertyType String -Force | Out-Null
+New-Item -Path ($key + '\\shell\\open\\command') -Force | Out-Null
+Set-Item -LiteralPath ($key + '\\shell\\open\\command') -Value ${quoted(command)}
+`}
+`;
+}
+export function windowsInstallLinkLauncherPath(options) {
+    return join(options.stateDir, "install-links", "open-link.vbs");
+}

package/dist/src/computer-access/companion/install-link.d.ts

@@ -0,0 +1,9 @@
+import type { NativeHostState } from "./native-state.js";
+export declare function pluginInstallReviewUrl(link: string, runtimeUrl: string): string;
+/** The saved pairing owns the destination. Incoming links cannot select a host. */
+export declare function openPluginInstallLink(state: Pick<NativeHostState, "read">, link: string, open?: typeof openReviewBrowser): Promise<void>;
+declare function openReviewBrowser(url: string): Promise<void>;
+/** Windows Script Host expands percent-delimited environment variables in Run().
+ * The launcher sends base64 so a website URL can never interpolate local values. */
+export declare function parsePluginInstallArguments(args: readonly string[]): string;
+export {};