@abot-ai/runtime 1.3.0 → 1.4.0

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

@@ -0,0 +1,113 @@
+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

@@ -0,0 +1,78 @@
+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

@@ -0,0 +1,106 @@
+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

@@ -0,0 +1,185 @@
+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

@@ -0,0 +1,183 @@
+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,
+      },
+    });
+  }
+}