@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/cli/host-companion-entry.d.ts

@@ -0,0 +1,8 @@
+import type { Readable } from "node:stream";
+import { runHostCompanionCli } from "./host-companion.js";
+/** Installer-only setup receives secrets over stdin; login startup uses host run. */
+export declare function runHostCompanionEntry(args: string[], options?: Readonly<{
+    input?: Readable;
+    cliPath?: string;
+    runCli?: typeof runHostCompanionCli;
+}>): Promise<void>;

package/dist/src/cli/host-companion-entry.js

@@ -0,0 +1,80 @@
+import { stdin } from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { isNativeCredential } from "../computer-access/companion/native-state.js";
+import { isHostIdentifier, isHostRecord, } from "../computer-access/companion/protocol.js";
+import { runHostCompanionCli } from "./host-companion.js";
+const SETUP_INPUT_LIMIT_BYTES = 16_384;
+const SETUP_INPUT_TIMEOUT_MS = 10_000;
+async function readSetupInput(input) {
+    const chunks = [];
+    let length = 0;
+    const deadline = setTimeout(() => {
+        input.destroy(new Error("Host setup input timed out."));
+    }, SETUP_INPUT_TIMEOUT_MS);
+    try {
+        for await (const chunk of input) {
+            const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            length += bytes.length;
+            if (length > SETUP_INPUT_LIMIT_BYTES)
+                throw new Error("Host setup input exceeds the size limit.");
+            chunks.push(bytes);
+        }
+        try {
+            return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        }
+        catch {
+            throw new Error("Host setup requires a JSON object on standard input.");
+        }
+    }
+    finally {
+        clearTimeout(deadline);
+    }
+}
+function readSetupRequest(value) {
+    if (!isHostRecord(value))
+        throw new Error("Invalid host setup request.");
+    if (Object.keys(value).some((key) => !["url", "code", "upgradeHostId"].includes(key)))
+        throw new Error("Unexpected host setup fields.");
+    if (typeof value.url !== "string")
+        throw new Error("Missing Runtime URL.");
+    if (value.url.length === 0 || value.url.length > 4_096)
+        throw new Error("Invalid Runtime URL length.");
+    if (!isNativeCredential(value.code))
+        throw new Error("Invalid pairing code.");
+    if (value.upgradeHostId !== undefined &&
+        !isHostIdentifier(value.upgradeHostId))
+        throw new Error("Invalid paired computer identity.");
+    return {
+        url: value.url,
+        code: value.code,
+        ...(value.upgradeHostId !== undefined
+            ? { upgradeHostId: value.upgradeHostId }
+            : {}),
+    };
+}
+/** Installer-only setup receives secrets over stdin; login startup uses host run. */
+export async function runHostCompanionEntry(args, options = {}) {
+    const cliPath = options.cliPath ?? fileURLToPath(import.meta.url);
+    const runCli = options.runCli ?? runHostCompanionCli;
+    if (args[0] === "setup") {
+        if (args.length !== 1)
+            throw new Error("Host setup accepts JSON on standard input, not arguments.");
+        const setup = readSetupRequest(await readSetupInput(options.input ?? stdin));
+        await runCli(["connect", "--url", setup.url], {
+            cliPath,
+            pairingCode: setup.code,
+            ...(setup.upgradeHostId ? { upgradeHostId: setup.upgradeHostId } : {}),
+        });
+        return;
+    }
+    if (args[0] !== "host")
+        throw new Error("Use setup or host <run|status|disconnect|uninstall>.");
+    await runCli(args.slice(1), { cliPath });
+}
+if (process.argv[1] &&
+    import.meta.url === pathToFileURL(process.argv[1]).href) {
+    void runHostCompanionEntry(process.argv.slice(2)).catch((error) => {
+        console.error(error instanceof Error ? error.message : "Host companion failed.");
+        process.exitCode = 1;
+    });
+}

package/dist/src/cli/host-companion-setup-target.d.ts

@@ -0,0 +1,3 @@
+import type { NativeHostConnection } from "../computer-access/companion/native-state.js";
+/** Upgrade identity selects existing private state, never a new credential destination. */
+export declare function resolveHostCompanionSetupUrl(saved: NativeHostConnection | undefined, requestedUrl: string, upgradeHostId?: string): string;

package/dist/src/cli/host-companion-setup-target.js

@@ -0,0 +1,23 @@
+import { isHostIdentifier } from "../computer-access/companion/protocol.js";
+function hasConflictingSavedRuntime(saved, requestedUrl) {
+    if (!saved)
+        return false;
+    return saved.url !== requestedUrl;
+}
+function resolveOrdinaryConnectUrl(saved, requestedUrl) {
+    if (hasConflictingSavedRuntime(saved, requestedUrl))
+        throw new Error("A Runtime is already paired. Use 'abot host disconnect' before pairing another.");
+    return requestedUrl;
+}
+/** Upgrade identity selects existing private state, never a new credential destination. */
+export function resolveHostCompanionSetupUrl(saved, requestedUrl, upgradeHostId) {
+    if (upgradeHostId === undefined)
+        return resolveOrdinaryConnectUrl(saved, requestedUrl);
+    if (!isHostIdentifier(upgradeHostId))
+        throw new Error("Invalid paired computer identity.");
+    if (!saved)
+        throw new Error("The paired computer connection is missing. Reconnect from ABot Settings.");
+    if (saved.hostId !== upgradeHostId)
+        throw new Error("This upgrade belongs to a different paired computer connection.");
+    return saved.url;
+}

package/dist/src/cli/host-companion-startup.d.ts

@@ -0,0 +1,4 @@
+import { type NativeAutostartOptions } from "../computer-access/companion/autostart.js";
+import type { NativeHostState } from "../computer-access/companion/native-state.js";
+/** Startup can be resumed without consuming another grant or changing the saved pairing. */
+export declare function completeHostCompanionStartup(state: NativeHostState, startup: NativeAutostartOptions, hostId: string): Promise<void>;

package/dist/src/cli/host-companion-startup.js

@@ -0,0 +1,49 @@
+import { spawn } from "node:child_process";
+import { installDesktopNotificationIdentity } from "../computer-access/companion/notification-installation.js";
+import { setTimeout as delay } from "node:timers/promises";
+import { installNativeAutostart, existingOwnedRegistration, nativeAutostartFile, } from "../computer-access/companion/autostart.js";
+import { readNativeCompanionBuildId } from "../computer-access/companion/native-build-identity.js";
+import { stopOwnedNativeCompanion } from "../computer-access/companion/native-replacement.js";
+import { prepareNativeCompanionRuntime } from "../computer-access/companion/native-runtime-installation.js";
+async function startDetachedCompanion(options) {
+    const child = spawn(options.nodePath, [options.cliPath, "host", "run"], {
+        cwd: options.homeDir,
+        detached: true,
+        stdio: "ignore",
+        windowsHide: true,
+    });
+    await new Promise((resolve, reject) => {
+        child.once("spawn", resolve);
+        child.once("error", reject);
+    });
+    child.unref();
+}
+async function waitForNativeConnection(state, hostId, buildId, connectedAfter) {
+    const deadline = Date.now() + 10_000;
+    do {
+        if (await state.isConnected(hostId, buildId, connectedAfter))
+            return true;
+        await delay(200);
+    } while (Date.now() < deadline);
+    return false;
+}
+/** Startup can be resumed without consuming another grant or changing the saved pairing. */
+export async function completeHostCompanionStartup(state, startup, hostId) {
+    const buildId = await readNativeCompanionBuildId(startup.cliPath);
+    await existingOwnedRegistration(nativeAutostartFile(startup));
+    await stopOwnedNativeCompanion(state.directory);
+    const managedStartup = await prepareNativeCompanionRuntime(startup);
+    const connection = await state.read();
+    if (connection)
+        await installDesktopNotificationIdentity(managedStartup, connection.url).catch((error) => {
+            console.warn("Desktop notifications setup needs attention: " +
+                (error instanceof Error ? error.message : String(error)));
+        });
+    const connectedAfter = Date.now();
+    const installed = await installNativeAutostart(managedStartup);
+    if (!installed.started)
+        await startDetachedCompanion(managedStartup);
+    if (!(await waitForNativeConnection(state, hostId, buildId, connectedAfter)))
+        throw new Error("The updated host companion did not connect. The saved pairing is preserved; run setup again to retry.");
+    console.log("Host companion connected. It will start automatically when you log in.");
+}

package/dist/src/cli/host-companion.d.ts

@@ -0,0 +1,6 @@
+export type HostCompanionCliOptions = Readonly<{
+    cliPath?: string;
+    pairingCode?: string;
+    upgradeHostId?: string;
+}>;
+export declare function runHostCompanionCli(args: string[], options?: HostCompanionCliOptions): Promise<void>;

package/dist/src/cli/host-companion.js

@@ -0,0 +1,203 @@
+import { homedir } from "node:os";
+import { uninstallDesktopNotificationIdentity } from "../computer-access/companion/notification-installation.js";
+import { join } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { fileURLToPath } from "node:url";
+import { nativeAutostartFile, uninstallNativeAutostart, } from "../computer-access/companion/autostart.js";
+import { normalizeNativeRuntimeUrl, resolveNativeRuntimeAddress, } from "../computer-access/companion/native-address.js";
+import { readNativeHostIdentity } from "../computer-access/companion/native-identity.js";
+import { connectNativeHost } from "../computer-access/companion/native-session.js";
+import { createNativeHostState, } from "../computer-access/companion/native-state.js";
+import { runNativeHostSupervisor } from "../computer-access/companion/native-supervisor.js";
+import { isProcessOwnerAlive, requireCurrentProcessOwnerIdentity, } from "../computer-access/companion/process-owner-identity.js";
+import { acquireFileLock } from "../runtime/adapters/long-term-memory/file-lock/acquisition.js";
+import { ensurePrivateRuntimeDirectory } from "../runtime/local-host/private-directory.js";
+import { assertPrivateRuntimeAccess } from "../runtime/local-host/private-access.js";
+import { completeHostCompanionStartup } from "./host-companion-startup.js";
+import { resolveHostCompanionSetupUrl } from "./host-companion-setup-target.js";
+import { readNativeCompanionBuildId } from "../computer-access/companion/native-build-identity.js";
+function printHostHelp() {
+    console.log([
+        "Usage:",
+        "  abot host connect --url http://localhost:5177",
+        "  abot host status",
+        "  abot host disconnect",
+        "  abot host uninstall",
+        "  abot host run",
+        "",
+        "Connect asks for a one-time code from ABot Settings, saves a private credential,",
+        "and starts the companion now and at future Windows/macOS/Linux desktop logins.",
+        "Run is the foreground companion used by the login registration.",
+        "Disconnect/uninstall stop the registration and remove this computer's credential.",
+        "Revoke the host in ABot Settings to remove Runtime-side pairing too.",
+    ].join("\n"));
+}
+function nativeState() {
+    return createNativeHostState(join(homedir(), ".abot", "host-companion"), {
+        ensureDirectory: ensurePrivateRuntimeDirectory,
+        assertFile: (path, stat) => assertPrivateRuntimeAccess(path, stat, "host_companion_state_not_private"),
+    });
+}
+function autostartOptions(state, options = {}) {
+    return {
+        platform: process.platform,
+        homeDir: homedir(),
+        appData: process.env.APPDATA,
+        xdgConfigHome: process.env.XDG_CONFIG_HOME,
+        uid: process.getuid?.(),
+        nodePath: process.execPath,
+        cliPath: options.cliPath ?? fileURLToPath(new URL("./bin.js", import.meta.url)),
+        stateDir: state.directory,
+    };
+}
+async function readPairingCode() {
+    const prompt = createInterface({ input: stdin, output: stdout });
+    try {
+        return (await prompt.question("One-time pairing code: ")).trim();
+    }
+    finally {
+        prompt.close();
+    }
+}
+async function withStopSignals(operation) {
+    const controller = new AbortController();
+    const stop = () => controller.abort();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    try {
+        await operation(controller.signal);
+    }
+    finally {
+        process.removeListener("SIGINT", stop);
+        process.removeListener("SIGTERM", stop);
+    }
+}
+async function connectHost(args, state, options) {
+    if (args.length !== 2 || args[0] !== "--url")
+        throw new Error("Usage: abot host connect --url http://localhost:5177");
+    const startup = autostartOptions(state, options);
+    nativeAutostartFile(startup);
+    const saved = await state.read();
+    const url = resolveHostCompanionSetupUrl(saved, normalizeNativeRuntimeUrl(args[1]), options.upgradeHostId);
+    await resolveNativeRuntimeAddress(url);
+    if (saved) {
+        await completeHostCompanionStartup(state, startup, saved.hostId);
+        return;
+    }
+    const code = options.pairingCode ?? (await readPairingCode());
+    let pairedHostId;
+    let interrupted = false;
+    await withStopSignals(async (signal) => {
+        const connection = new AbortController();
+        const stop = () => connection.abort();
+        signal.addEventListener("abort", stop, { once: true });
+        try {
+            if (signal.aborted)
+                stop();
+            await connectNativeHost({
+                url,
+                authorization: code,
+                identity: readNativeHostIdentity(),
+                signal: connection.signal,
+                onPaired: async (hostId, credential) => {
+                    await state.write({ version: 1, url, hostId, credential });
+                    pairedHostId = hostId;
+                },
+                onReady: () => {
+                    throw new Error("Pairing must finish before an authenticated native connection becomes ready.");
+                },
+            });
+        }
+        finally {
+            interrupted = signal.aborted;
+            signal.removeEventListener("abort", stop);
+        }
+    });
+    if (interrupted)
+        throw new Error("Host setup was interrupted before startup installation.");
+    if (!pairedHostId)
+        throw new Error("Pairing did not complete. Check ABot Settings and use a fresh pairing code.");
+    await completeHostCompanionStartup(state, startup, pairedHostId);
+}
+async function runHost(state, options) {
+    if (!(await state.read()))
+        return;
+    const buildId = await readNativeCompanionBuildId(autostartOptions(state, options).cliPath);
+    const ownerIdentity = await requireCurrentProcessOwnerIdentity();
+    let release;
+    try {
+        release = await acquireFileLock(join(state.directory, "agent"), {
+            waitMs: 0,
+            releaseMode: "synchronous",
+            ownerIdentity,
+            processIsAlive: isProcessOwnerAlive,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            error.message === "long_term_memory_store_lock_timeout")
+            return;
+        throw error;
+    }
+    try {
+        await withStopSignals((signal) => runNativeHostSupervisor({
+            state,
+            identity: readNativeHostIdentity(),
+            signal,
+            buildId,
+        }));
+    }
+    finally {
+        await release();
+    }
+}
+async function disconnectHost(state) {
+    await state.remove();
+    await uninstallNativeAutostart(autostartOptions(state));
+    await uninstallDesktopNotificationIdentity(autostartOptions(state));
+    const ownerIdentity = await requireCurrentProcessOwnerIdentity();
+    const release = await acquireFileLock(join(state.directory, "agent"), {
+        waitMs: 5_000,
+        releaseMode: "synchronous",
+        ownerIdentity,
+        processIsAlive: isProcessOwnerAlive,
+    });
+    await release();
+    console.log("Host companion stopped. Login startup and the saved credential were removed.");
+}
+export async function runHostCompanionCli(args, options = {}) {
+    const [command, ...rest] = args;
+    if (!command || ["help", "--help", "-h"].includes(command)) {
+        printHostHelp();
+        return;
+    }
+    const state = nativeState();
+    if (command === "connect") {
+        await connectHost(rest, state, options);
+        return;
+    }
+    if (rest.length > 0)
+        throw new Error(`Unknown host argument: ${rest[0]}`);
+    if (command === "run") {
+        await runHost(state, options);
+        return;
+    }
+    if (command === "disconnect" || command === "uninstall") {
+        await disconnectHost(state);
+        return;
+    }
+    if (command === "status") {
+        const saved = await state.read();
+        console.log(JSON.stringify(saved
+            ? {
+                paired: true,
+                url: saved.url,
+                hostId: saved.hostId,
+                connected: await state.isConnected(saved.hostId),
+            }
+            : { paired: false, connected: false }, null, 2));
+        return;
+    }
+    throw new Error(`Unknown host command: ${command}`);
+}

package/dist/src/computer-access/application-catalog.d.ts

@@ -0,0 +1,14 @@
+import { type SystemApplication, type SystemProcessRunner, type SystemTarget } from "./contracts.js";
+export type SystemApplicationCatalogScope = Readonly<{
+    source: "windows_start_apps" | "macos_application_bundles" | "linux_desktop_entries";
+    roots: readonly string[];
+    includesExecutableSearch: false;
+    includesOtherTargets: false;
+}>;
+export type SystemApplicationCatalog = Readonly<{
+    applications: readonly SystemApplication[];
+    complete: boolean;
+    scope: SystemApplicationCatalogScope;
+}>;
+export declare function parseDesktopApplication(content: string, path: string): SystemApplication | undefined;
+export declare function readSystemApplications(target: SystemTarget, run: SystemProcessRunner): Promise<SystemApplicationCatalog>;

package/dist/src/computer-access/application-catalog.js

@@ -0,0 +1,185 @@
+import { readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { SystemOperationError, } from "./contracts.js";
+import { powershellArguments } from "./targets.js";
+const CATALOG_ENTRY_LIMIT = 2_000;
+function isAbsentOptionalCatalogRoot(error, depth) {
+    if (depth !== 0 || !(error instanceof Error))
+        return false;
+    return "code" in error && error.code === "ENOENT";
+}
+async function readApplicationDirectory(path, depth) {
+    try {
+        return {
+            entries: await readdir(path, { withFileTypes: true }),
+            complete: true,
+        };
+    }
+    catch (error) {
+        return { entries: [], complete: isAbsentOptionalCatalogRoot(error, depth) };
+    }
+}
+async function collectApplicationPaths(roots, extension) {
+    const pending = roots.map((path) => ({ path, depth: 0 }));
+    const paths = [];
+    let scannedEntries = 0;
+    let complete = true;
+    while (pending.length > 0 &&
+        scannedEntries < 20_000 &&
+        paths.length < CATALOG_ENTRY_LIMIT) {
+        const current = pending.shift();
+        const directory = await readApplicationDirectory(current.path, current.depth);
+        complete = complete && directory.complete;
+        for (const entry of directory.entries) {
+            scannedEntries += 1;
+            if (scannedEntries >= 20_000 || paths.length >= CATALOG_ENTRY_LIMIT) {
+                complete = false;
+                break;
+            }
+            const absolute = join(current.path, entry.name);
+            if (entry.name.endsWith(extension)) {
+                paths.push(absolute);
+                continue;
+            }
+            if (!entry.isDirectory())
+                continue;
+            if (current.depth >= 4) {
+                complete = false;
+                continue;
+            }
+            pending.push({ path: absolute, depth: current.depth + 1 });
+        }
+    }
+    return {
+        paths: [...new Set(paths)].sort(),
+        complete: complete && pending.length === 0,
+    };
+}
+export function parseDesktopApplication(content, path) {
+    const section = content
+        .split(/^\[Desktop Entry\]\s*$/mu)[1]
+        ?.split(/^\[/mu)[0];
+    if (!section)
+        return undefined;
+    const fields = new Map(section.split(/\r?\n/u).map((line) => {
+        const split = line.indexOf("=");
+        return [
+            line.slice(0, split).trim(),
+            line.slice(split + 1).trim(),
+        ];
+    }));
+    if (fields.get("Type") !== "Application")
+        return undefined;
+    if (fields.get("Hidden") === "true")
+        return undefined;
+    const name = fields.get("Name");
+    if (!name)
+        return undefined;
+    return { id: path, name, target: "linux" };
+}
+async function windowsApplications(target, run) {
+    const result = await run({
+        executable: target.shell,
+        args: powershellArguments("@(Get-StartApps | Sort-Object AppID | Select-Object -First 2001 Name,AppID) | ConvertTo-Json -Compress"),
+        timeoutMs: 15_000,
+        outputMaxChars: 512_000,
+    });
+    if (result.status !== "completed" ||
+        result.exitCode !== 0 ||
+        result.outputTruncated)
+        throw new SystemOperationError("system_application_catalog_unavailable", "Windows Start application catalog could not be read completely within the observation budget.");
+    let entries;
+    try {
+        entries = JSON.parse(result.stdout || "[]");
+    }
+    catch {
+        throw new SystemOperationError("system_application_catalog_invalid", "Windows returned an unreadable application catalog.");
+    }
+    const rows = Array.isArray(entries) ? entries : [entries];
+    const applications = rows
+        .slice(0, CATALOG_ENTRY_LIMIT)
+        .flatMap((entry) => {
+        if (!entry || typeof entry !== "object")
+            return [];
+        if (!("Name" in entry) || !("AppID" in entry))
+            return [];
+        if (typeof entry.Name !== "string" || typeof entry.AppID !== "string")
+            return [];
+        return [
+            { id: entry.AppID, name: entry.Name, target: "windows" },
+        ];
+    });
+    return {
+        applications,
+        complete: rows.length <= CATALOG_ENTRY_LIMIT,
+        scope: {
+            source: "windows_start_apps",
+            roots: [],
+            includesExecutableSearch: false,
+            includesOtherTargets: false,
+        },
+    };
+}
+export async function readSystemApplications(target, run) {
+    if (target.id === "windows")
+        return windowsApplications(target, run);
+    if (target.id === "macos") {
+        const roots = [
+            "/Applications",
+            "/System/Applications",
+            join(homedir(), "Applications"),
+        ];
+        const catalog = await collectApplicationPaths(roots, ".app");
+        return {
+            applications: catalog.paths.map((id) => ({
+                id,
+                name: basename(id, ".app"),
+                target: "macos",
+            })),
+            complete: catalog.complete,
+            scope: {
+                source: "macos_application_bundles",
+                roots,
+                includesExecutableSearch: false,
+                includesOtherTargets: false,
+            },
+        };
+    }
+    const dataHome = process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share");
+    const dataDirs = (process.env.XDG_DATA_DIRS ?? "/usr/local/share:/usr/share").split(":");
+    const roots = [dataHome, ...dataDirs].map((directory) => join(directory, "applications"));
+    const catalog = await collectApplicationPaths(roots, ".desktop");
+    const applications = [];
+    let complete = catalog.complete;
+    for (const path of catalog.paths) {
+        let content;
+        try {
+            content = await readFile(path, "utf8");
+        }
+        catch {
+            complete = false;
+            continue;
+        }
+        if (isDesktopEntryOverBudget(content)) {
+            complete = false;
+            continue;
+        }
+        const application = parseDesktopApplication(content, path);
+        if (application)
+            applications.push(application);
+    }
+    return {
+        applications,
+        complete,
+        scope: {
+            source: "linux_desktop_entries",
+            roots,
+            includesExecutableSearch: false,
+            includesOtherTargets: false,
+        },
+    };
+}
+function isDesktopEntryOverBudget(content) {
+    return content.length > 128_000;
+}

package/dist/src/computer-access/application-launch.d.ts

@@ -0,0 +1,10 @@
+import { type SystemApplication, type SystemProcessResult, type SystemProcessRunner, type SystemTarget } from "./contracts.js";
+export declare function launchSystemApplication(input: {
+    target: SystemTarget;
+    params: Record<string, unknown>;
+    run: SystemProcessRunner;
+    abortSignal?: AbortSignal;
+}): Promise<{
+    application: SystemApplication;
+    process: SystemProcessResult;
+}>;

package/dist/src/computer-access/application-launch.js

@@ -0,0 +1,80 @@
+import { readRequiredString } from "../plugin-sdk/index.js";
+import { readSystemApplications } from "./application-catalog.js";
+import { SystemOperationError, } from "./contracts.js";
+import { findExecutable, powershellArguments, powershellLiteral, } from "./targets.js";
+function readApplicationArguments(value) {
+    if (value === undefined)
+        return [];
+    if (!hasBoundedArgumentArray(value))
+        throw new SystemOperationError("system_application_arguments_invalid", "arguments must be an array of at most 32 strings.");
+    for (const argument of value) {
+        if (!isSupportedApplicationArgument(argument))
+            throw new SystemOperationError("system_application_arguments_invalid", "Each application argument must be a string without null bytes, at most 4096 characters.");
+    }
+    return [...value];
+}
+export async function launchSystemApplication(input) {
+    const { target, params, run } = input;
+    const id = readRequiredString(params.application_id, {
+        name: "application_id",
+        maxLength: 4_096,
+    });
+    const args = readApplicationArguments(params.arguments);
+    const catalog = await readSystemApplications(target, run);
+    const application = catalog.applications.find((entry) => entry.id === id);
+    if (!application)
+        throw new SystemOperationError("system_application_not_found", "The identity is absent from the current target catalog; this does not establish that the application is uninstalled. Inspect the correct OS target and use system_command for bounded executable discovery when this catalog is insufficient.");
+    const common = {
+        timeoutMs: 30_000,
+        ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
+    };
+    if (target.id === "macos")
+        return {
+            application,
+            process: await run({
+                ...common,
+                executable: "/usr/bin/open",
+                args: ["-a", id, ...(args.length ? ["--args", ...args] : [])],
+            }),
+        };
+    if (hasUnsupportedTargetArguments(target, args))
+        throw new SystemOperationError("system_application_arguments_unsupported", "This target application catalog does not define generic raw arguments. Use system_command with the application's documented native invocation.");
+    if (target.id === "windows") {
+        return {
+            application,
+            process: await run({
+                ...common,
+                executable: target.shell,
+                args: powershellArguments(`$applicationPath=${powershellLiteral("shell:AppsFolder\\" + id)}; Start-Process -FilePath (Join-Path $env:SystemRoot 'explorer.exe') -ArgumentList ('"' + $applicationPath + '"'); Write-Output 'Launch request dispatched to Windows shell.'`),
+            }),
+        };
+    }
+    const launcher = await findExecutable("gio");
+    if (!launcher)
+        throw new SystemOperationError("system_application_launcher_unavailable", "The installed desktop application catalog was read, but a native gio launcher is unavailable.");
+    return {
+        application,
+        process: await run({
+            ...common,
+            executable: launcher,
+            args: ["launch", id],
+        }),
+    };
+}
+function hasBoundedArgumentArray(value) {
+    if (!Array.isArray(value))
+        return false;
+    return value.length <= 32;
+}
+function isSupportedApplicationArgument(value) {
+    if (typeof value !== "string")
+        return false;
+    if (value.length > 4_096)
+        return false;
+    return !value.includes("\0");
+}
+function hasUnsupportedTargetArguments(target, args) {
+    if (target.id === "macos")
+        return false;
+    return args.length > 0;
+}