@abot-ai/runtime 1.4.0 → 1.5.0

package/plugins/system/source/application-launch.ts

@@ -1,113 +0,0 @@
-import { readRequiredString } from "../../../src/plugin-sdk/index.js";
-import { readSystemApplications } from "./application-catalog.js";
-import {
-  SystemOperationError,
-  type SystemApplication,
-  type SystemProcessResult,
-  type SystemProcessRunner,
-  type SystemTarget,
-} from "./contracts.js";
-import {
-  findExecutable,
-  powershellArguments,
-  powershellLiteral,
-} from "./targets.js";
-
-function readApplicationArguments(value: unknown): string[] {
-  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] as string[];
-}
-
-export async function launchSystemApplication(input: {
-  target: SystemTarget;
-  params: Record<string, unknown>;
-  run: SystemProcessRunner;
-  abortSignal?: AbortSignal;
-}): Promise<{ application: SystemApplication; process: SystemProcessResult }> {
-  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: unknown): value is unknown[] {
-  if (!Array.isArray(value)) return false;
-  return value.length <= 32;
-}
-function isSupportedApplicationArgument(value: unknown): value is string {
-  if (typeof value !== "string") return false;
-  if (value.length > 4_096) return false;
-  return !value.includes("\0");
-}
-function hasUnsupportedTargetArguments(
-  target: SystemTarget,
-  args: readonly string[],
-): boolean {
-  if (target.id === "macos") return false;
-  return args.length > 0;
-}

package/plugins/system/source/application-observation.ts

@@ -1,78 +0,0 @@
-import type { SystemApplicationCatalog } from "./application-catalog.js";
-import type { SystemTarget } from "./contracts.js";
-
-const SUMMARY_MAX_CHARS = 7_000;
-const SUMMARY_ROOT_LIMIT = 16;
-const SUMMARY_ROOT_CHARS = 256;
-
-export function systemApplicationObservation(
-  target: SystemTarget,
-  catalog: SystemApplicationCatalog,
-  query: string,
-  limit: number,
-) {
-  const matches = catalog.applications.filter((application) =>
-    matchesApplicationQuery(application.name, application.id, query),
-  );
-  const data = {
-    target: target.id,
-    transport: target.transport,
-    absenceConclusionSupported: false,
-    completenessMeaning: "declared_catalog_sources_only",
-    catalogScope: catalog.scope,
-    catalogComplete: catalog.complete,
-    observedMatches: matches.length,
-    omittedMatches: Math.max(0, matches.length - limit),
-    applications: matches.slice(0, limit),
-  };
-  const summaryRoots = catalog.scope.roots
-    .slice(0, SUMMARY_ROOT_LIMIT)
-    .map((root) => root.slice(0, SUMMARY_ROOT_CHARS));
-  const summary = {
-    ...data,
-    catalogScope: { ...catalog.scope, roots: summaryRoots },
-    summaryRootsOmitted: Math.max(
-      0,
-      catalog.scope.roots.length - summaryRoots.length,
-    ),
-    summaryRootCharactersOmitted: catalog.scope.roots.reduce(
-      (total, root, index) =>
-        total + root.length - (summaryRoots[index]?.length ?? 0),
-      0,
-    ),
-    applications: [...data.applications],
-    summaryApplicationsOmitted: 0,
-  };
-  while (isApplicationSummaryOverBudget(summary)) {
-    summary.applications.pop();
-    summary.summaryApplicationsOmitted += 1;
-  }
-  while (isCatalogRootSummaryOverBudget(summary)) {
-    const removedRoot = summary.catalogScope.roots.pop()!;
-    summary.summaryRootsOmitted += 1;
-    summary.summaryRootCharactersOmitted += removedRoot.length;
-  }
-  return { output: JSON.stringify(summary), data };
-}
-
-function matchesApplicationQuery(
-  name: string,
-  id: string,
-  query: string,
-): boolean {
-  if (name.toLowerCase().includes(query)) return true;
-  return id.toLowerCase().includes(query);
-}
-function isApplicationSummaryOverBudget(summary: {
-  applications: readonly unknown[];
-}): boolean {
-  if (summary.applications.length === 0) return false;
-  return JSON.stringify(summary).length > SUMMARY_MAX_CHARS;
-}
-
-function isCatalogRootSummaryOverBudget(summary: {
-  catalogScope: { roots: readonly string[] };
-}): boolean {
-  if (summary.catalogScope.roots.length === 0) return false;
-  return JSON.stringify(summary).length > SUMMARY_MAX_CHARS;
-}

package/plugins/system/source/commands.ts

@@ -1,106 +0,0 @@
-import { stat } from "node:fs/promises";
-import { isAbsolute } from "node:path";
-import {
-  readBoundedInteger,
-  readRequiredString,
-} from "../../../src/plugin-sdk/index.js";
-import {
-  SystemOperationError,
-  type SystemProcessInput,
-  type SystemProcessResult,
-  type SystemProcessRunner,
-  type SystemTarget,
-} from "./contracts.js";
-import { elevatedSystemCommand } from "./elevation.js";
-import { powershellArguments, windowsSystemCommandScript } from "./targets.js";
-
-export async function executeSystemCommand(input: {
-  target: SystemTarget;
-  params: Record<string, unknown>;
-  run: SystemProcessRunner;
-  abortSignal?: AbortSignal;
-}): Promise<SystemProcessResult> {
-  const { target, params, run } = input;
-  const command = readRequiredString(params.command, {
-    name: "command",
-    trim: false,
-    maxLength: 4_096,
-  });
-  const cwd = readRequiredString(params.cwd, { name: "cwd", maxLength: 4_096 });
-  const timeoutMs =
-    params.timeout_ms === undefined
-      ? 60_000
-      : readBoundedInteger(params.timeout_ms, {
-          name: "timeout_ms",
-          minimum: 1_000,
-          maximum: 600_000,
-        });
-  if (hasSystemCommandNullBytes(command, cwd))
-    throw new SystemOperationError(
-      "system_command_invalid",
-      "Commands and directories cannot contain null bytes.",
-    );
-  if (hasInvalidElevationFlag(params.elevated))
-    throw new SystemOperationError(
-      "system_command_invalid",
-      "elevated must be a boolean.",
-    );
-  const absoluteCwd =
-    target.id === "windows"
-      ? hasExplicitWindowsDirectory(cwd)
-      : isAbsolute(cwd);
-  if (!absoluteCwd)
-    throw new SystemOperationError(
-      "system_cwd_invalid",
-      "System commands require an explicit absolute directory in the selected OS namespace.",
-    );
-  await requireNativeWorkingDirectory(target, cwd);
-  const plan =
-    params.elevated === true
-      ? await elevatedSystemCommand({ target, command, cwd, run })
-      : unprivilegedSystemCommand(target, command, cwd);
-  return run({
-    ...plan,
-    timeoutMs,
-    ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
-  });
-}
-
-function unprivilegedSystemCommand(
-  target: SystemTarget,
-  command: string,
-  cwd: string,
-): SystemProcessInput {
-  if (target.id === "windows")
-    return {
-      executable: target.shell,
-      args: powershellArguments(windowsSystemCommandScript(command, cwd)),
-    };
-  return { executable: target.shell, args: ["-lc", command], cwd };
-}
-
-function hasExplicitWindowsDirectory(path: string): boolean {
-  if (/^[a-z]:[\\/]/iu.test(path)) return true;
-  return /^\\\\[^\\/]+[\\/][^\\/]+(?:[\\/]|$)/u.test(path);
-}
-
-function hasSystemCommandNullBytes(command: string, cwd: string): boolean {
-  if (command.includes("\0")) return true;
-  return cwd.includes("\0");
-}
-function hasInvalidElevationFlag(value: unknown): boolean {
-  if (value === undefined) return false;
-  return typeof value !== "boolean";
-}
-async function requireNativeWorkingDirectory(
-  target: SystemTarget,
-  cwd: string,
-): Promise<void> {
-  if (target.id === "windows") return;
-  const directory = await stat(cwd).catch(() => undefined);
-  if (directory?.isDirectory()) return;
-  throw new SystemOperationError(
-    "system_cwd_unavailable",
-    "The selected target directory is unavailable or not a directory.",
-  );
-}

package/plugins/system/source/companion/autostart.ts

@@ -1,185 +0,0 @@
-import { execFile } from "node:child_process";
-import {
-  lstat,
-  mkdir,
-  readFile,
-  rename,
-  unlink,
-  writeFile,
-} from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { promisify } from "node:util";
-import { randomUUID } from "node:crypto";
-
-const executeFile = promisify(execFile);
-const LABEL = "com.abot.host-companion";
-const OWNER_MARKER = "ABot managed native host companion";
-export type NativeAutostartOptions = Readonly<{
-  platform: NodeJS.Platform;
-  homeDir: string;
-  appData?: string;
-  uid?: number;
-  nodePath: string;
-  cliPath: string;
-  stateDir: string;
-  execute?: (file: string, args: readonly string[]) => Promise<void>;
-}>;
-
-function xmlText(value: string): string {
-  return value.replace(
-    /[&<>"']/gu,
-    (character) =>
-      ({
-        "&": "&amp;",
-        "<": "&lt;",
-        ">": "&gt;",
-        '"': "&quot;",
-        "'": "&apos;",
-      })[character]!,
-  );
-}
-function windowsArgument(value: string): string {
-  if (/["\r\n\0]/u.test(value))
-    throw new Error("Unsupported native startup path.");
-  return `"${value}"`;
-}
-function vbsString(value: string): string {
-  return `"${value.replaceAll('"', '""')}"`;
-}
-
-export function nativeAutostartFile(options: NativeAutostartOptions): string {
-  if (options.platform === "darwin")
-    return join(options.homeDir, "Library", "LaunchAgents", `${LABEL}.plist`);
-  if (options.platform !== "win32")
-    throw new Error("Automatic host startup supports Windows and macOS only.");
-  if (!options.appData)
-    throw new Error("Windows APPDATA is unavailable for current-user startup.");
-  return join(
-    options.appData,
-    "Microsoft",
-    "Windows",
-    "Start Menu",
-    "Programs",
-    "Startup",
-    "ABot Host Companion.vbs",
-  );
-}
-
-export function renderNativeAutostart(options: NativeAutostartOptions): string {
-  if (options.platform === "win32") {
-    const command = `${windowsArgument(options.nodePath)} ${windowsArgument(options.cliPath)} host run`;
-    return [
-      `' ${OWNER_MARKER}`,
-      'Set shell = CreateObject("WScript.Shell")',
-      `shell.Run ${vbsString(command)}, 0, False`,
-      "",
-    ].join("\r\n");
-  }
-  if (options.platform !== "darwin")
-    throw new Error("Automatic host startup supports Windows and macOS only.");
-  const argumentsXml = [options.nodePath, options.cliPath, "host", "run"]
-    .map((argument) => `<string>${xmlText(argument)}</string>`)
-    .join("");
-  return `<?xml version="1.0" encoding="UTF-8"?>\n<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\n<!-- ${OWNER_MARKER} -->\n<plist version="1.0"><dict>
-<key>Label</key><string>${LABEL}</string>
-<key>ProgramArguments</key><array>${argumentsXml}</array>
-<key>RunAtLoad</key><true/>
-<key>KeepAlive</key><dict><key>SuccessfulExit</key><false/></dict>
-<key>LimitLoadToSessionType</key><string>Aqua</string>
-<key>ProcessType</key><string>Interactive</string>
-<key>WorkingDirectory</key><string>${xmlText(options.homeDir)}</string>
-<key>StandardOutPath</key><string>${xmlText(join(options.stateDir, "agent.log"))}</string>
-<key>StandardErrorPath</key><string>${xmlText(join(options.stateDir, "agent.log"))}</string>
-</dict></plist>\n`;
-}
-
-function errorCode(error: unknown): unknown {
-  return error && typeof error === "object" && "code" in error
-    ? error.code
-    : undefined;
-}
-async function existingOwnedRegistration(path: string): Promise<boolean> {
-  const stat = await lstat(path).catch((error) => {
-    if (errorCode(error) === "ENOENT") return undefined;
-    throw error;
-  });
-  if (!stat) return false;
-  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 16_384)
-    throw new Error(
-      "Refusing to change an unexpected host startup registration.",
-    );
-  if (!(await readFile(path, "utf8")).includes(OWNER_MARKER))
-    throw new Error("The host startup path belongs to an unmanaged file.");
-  return true;
-}
-async function execute(
-  options: NativeAutostartOptions,
-  file: string,
-  args: readonly string[],
-): Promise<void> {
-  if (options.execute) return options.execute(file, args);
-  await executeFile(file, [...args], {
-    windowsHide: true,
-    timeout: 10_000,
-    maxBuffer: 16_384,
-  });
-}
-function macUserDomain(options: NativeAutostartOptions): string {
-  if (!Number.isInteger(options.uid))
-    throw new Error("The macOS GUI user identity is unavailable.");
-  return `gui/${options.uid}`;
-}
-async function unloadMacRegistration(
-  options: NativeAutostartOptions,
-): Promise<void> {
-  try {
-    await execute(options, "/bin/launchctl", [
-      "bootout",
-      `${macUserDomain(options)}/${LABEL}`,
-    ]);
-  } catch (error) {
-    if ([3, 113].includes(Number(errorCode(error)))) return;
-    throw error;
-  }
-}
-
-export async function installNativeAutostart(
-  options: NativeAutostartOptions,
-): Promise<{ started: boolean }> {
-  const path = nativeAutostartFile(options);
-  const existing = await existingOwnedRegistration(path);
-  if (existing && options.platform === "darwin")
-    await unloadMacRegistration(options);
-  await mkdir(dirname(path), { recursive: true });
-  const temporary = `${path}.${randomUUID()}.tmp`;
-  try {
-    await writeFile(temporary, renderNativeAutostart(options), {
-      encoding: "utf8",
-      mode: 0o600,
-      flag: "wx",
-    });
-    await rename(temporary, path);
-  } finally {
-    await unlink(temporary).catch((error) => {
-      if (errorCode(error) !== "ENOENT") throw error;
-    });
-  }
-  if (options.platform === "darwin") {
-    await execute(options, "/bin/launchctl", [
-      "bootstrap",
-      macUserDomain(options),
-      path,
-    ]);
-    return { started: true };
-  }
-  return { started: false };
-}
-
-export async function uninstallNativeAutostart(
-  options: NativeAutostartOptions,
-): Promise<void> {
-  const path = nativeAutostartFile(options);
-  if (!(await existingOwnedRegistration(path))) return;
-  await unlink(path);
-  if (options.platform === "darwin") await unloadMacRegistration(options);
-}

package/plugins/system/source/companion/broker-client.ts

@@ -1,183 +0,0 @@
-import { connect } from "node:net";
-import {
-  failureResult,
-  type ToolImplementationOutput,
-} from "../../../../src/plugin-sdk/index.js";
-import { readBrokerLocation } from "./broker-location.js";
-import { HostPairingStore } from "./pairing-store.js";
-import {
-  HOST_WIRE_MAX_BYTES,
-  isHostIdentity,
-  isHostIdentifier,
-  isHostRecord,
-  isHostToolResult,
-  type HostOperation,
-  type HostStatus,
-} from "./protocol.js";
-
-async function callBroker(
-  rootDir: string,
-  request: Record<string, unknown>,
-  signal?: AbortSignal,
-): Promise<unknown> {
-  const location = readBrokerLocation(rootDir);
-  if (!location) throw new Error("host_broker_unavailable");
-  if (signal?.aborted) throw new Error("host_request_cancelled");
-  return new Promise((resolve, reject) => {
-    const socket = connect(location.socketPath);
-    let received = Buffer.alloc(0);
-    let settled = false;
-    let sent = false;
-    const finish = (error?: Error, result?: unknown) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(deadline);
-      signal?.removeEventListener("abort", abort);
-      socket.destroy();
-      if (error) {
-        reject(
-          sent && request.kind === "execute"
-            ? new Error("host_outcome_unknown")
-            : error,
-        );
-        return;
-      }
-      resolve(result);
-    };
-    const abort = () =>
-      finish(
-        new Error(sent ? "host_outcome_unknown" : "host_request_cancelled"),
-      );
-    const deadline = setTimeout(
-      abort,
-      request.kind === "status" ? 3_000 : 615_000,
-    );
-    signal?.addEventListener("abort", abort, { once: true });
-    socket.once("connect", () => {
-      const bytes =
-        JSON.stringify({ ...request, version: 1, token: location.token }) +
-        "\n";
-      if (Buffer.byteLength(bytes) > HOST_WIRE_MAX_BYTES) {
-        finish(new Error("host_request_too_large"));
-        return;
-      }
-      sent = true;
-      socket.write(bytes);
-    });
-    socket.on("error", () =>
-      finish(
-        new Error(sent ? "host_outcome_unknown" : "host_broker_unavailable"),
-      ),
-    );
-    socket.on("close", () =>
-      finish(
-        new Error(sent ? "host_outcome_unknown" : "host_broker_unavailable"),
-      ),
-    );
-    socket.on("data", (chunk: Buffer) => {
-      received = Buffer.concat([received, chunk]);
-      if (received.length > HOST_WIRE_MAX_BYTES) {
-        finish(new Error("host_response_too_large"));
-        return;
-      }
-      const boundary = received.indexOf(10);
-      if (boundary < 0) return;
-      if (boundary !== received.length - 1) {
-        finish(new Error("host_response_invalid"));
-        return;
-      }
-      try {
-        finish(
-          undefined,
-          JSON.parse(received.subarray(0, boundary).toString()),
-        );
-      } catch {
-        finish(new Error("host_response_invalid"));
-      }
-    });
-  });
-}
-function isHostStatus(value: unknown): value is HostStatus {
-  if (!isHostRecord(value)) return false;
-  if (typeof value.paired !== "boolean") return false;
-  if (typeof value.connected !== "boolean") return false;
-  if (!hasValidHostConnectionBinding(value)) return false;
-  if (!value.paired) return value.connected === false;
-  if (!isHostIdentifier(value.hostId)) return false;
-  return isHostIdentity(value.identity);
-}
-function hasValidHostConnectionBinding(
-  value: Record<string, unknown>,
-): boolean {
-  if (value.connected === true) return isHostIdentifier(value.connectionId);
-  return !Object.hasOwn(value, "connectionId");
-}
-export async function readHostStatus(rootDir: string): Promise<HostStatus> {
-  try {
-    const response = await callBroker(rootDir, { kind: "status" });
-    if (!isHostRecord(response)) throw new Error("host_response_invalid");
-    if (!isHostStatus(response.status)) throw new Error("host_status_invalid");
-    return response.status;
-  } catch {
-    const host = new HostPairingStore(rootDir).host();
-    if (!host) return { paired: false, connected: false };
-    return {
-      paired: true,
-      connected: false,
-      hostId: host.hostId,
-      identity: host.identity,
-    };
-  }
-}
-export async function executeHostOperation(
-  rootDir: string,
-  input: {
-    hostId: string;
-    connectionId: string;
-    operation: HostOperation;
-    params: Record<string, unknown>;
-    abortSignal?: AbortSignal;
-  },
-): Promise<ToolImplementationOutput> {
-  if (!isHostIdentifier(input.connectionId))
-    return failureResult({
-      errorCode: "system_host_binding_invalid",
-      message:
-        "An observed host connection identity is required before dispatch.",
-      data: { outcome: "not_dispatched", retrySafe: true },
-    });
-  try {
-    const response = await callBroker(
-      rootDir,
-      {
-        kind: "execute",
-        hostId: input.hostId,
-        connectionId: input.connectionId,
-        operation: input.operation,
-        params: input.params,
-      },
-      input.abortSignal,
-    );
-    if (!isHostRecord(response)) throw new Error("host_outcome_unknown");
-    if (response.ok !== true) throw new Error("host_outcome_unknown");
-    if (!isHostToolResult(response.result))
-      throw new Error("host_outcome_unknown");
-    return response.result;
-  } catch (error) {
-    const message =
-      error instanceof Error ? error.message : "host_request_failed";
-    const uncertain = message === "host_outcome_unknown";
-    return failureResult({
-      errorCode: uncertain
-        ? "system_host_outcome_unknown"
-        : "system_host_unavailable",
-      message: uncertain
-        ? "Host communication ended after dispatch. Effects may remain; inspect before retrying. The action was not replayed."
-        : "The selected host connection is unavailable. No fallback target was used.",
-      data: {
-        outcome: uncertain ? "unknown" : "not_dispatched",
-        retrySafe: !uncertain,
-      },
-    });
-  }
-}