@abot-ai/runtime 1.3.0 → 1.4.0

package/plugins/system/source/companion/process-owner-identity.ts

@@ -0,0 +1,190 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { promisify } from "node:util";
+
+const executeFile = promisify(execFile);
+type IdentityCommandOptions = Readonly<{
+  env: NodeJS.ProcessEnv;
+  windowsHide: true;
+  timeout: number;
+  maxBuffer: number;
+}>;
+export type ProcessOwnerIdentityDependencies = Readonly<{
+  platform: NodeJS.Platform;
+  currentPid: number;
+  readText(path: string): Promise<string>;
+  execute(
+    file: string,
+    args: readonly string[],
+    options: IdentityCommandOptions,
+  ): Promise<string>;
+  processIsAlive(pid: number): boolean;
+}>;
+
+const WINDOWS_OWNER_SCRIPT = `
+$ErrorActionPreference = 'Stop'
+$targetPid = [int]$env:ABOT_HOST_OWNER_PID
+$target = Get-Process -Id $targetPid -ErrorAction Stop
+$started = $target.StartTime.ToUniversalTime().Ticks
+$booted = (Get-CimInstance Win32_OperatingSystem -ErrorAction Stop).LastBootUpTime.ToUniversalTime().Ticks
+[Console]::Out.Write([string]$booted + '|' + [string]$started)
+`;
+
+function isProcessId(pid: number): boolean {
+  if (!Number.isSafeInteger(pid)) return false;
+  return pid > 0;
+}
+function isUuid(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(
+    value,
+  );
+}
+function observePidLiveness(pid: number): boolean {
+  if (!isProcessId(pid)) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (!error || typeof error !== "object" || !("code" in error)) return true;
+    return error.code !== "ESRCH";
+  }
+}
+
+async function linuxIdentity(
+  pid: number,
+  dependencies: ProcessOwnerIdentityDependencies,
+): Promise<string | undefined> {
+  const [bootText, processText] = await Promise.all([
+    dependencies.readText("/proc/sys/kernel/random/boot_id"),
+    dependencies.readText(`/proc/${pid}/stat`),
+  ]);
+  const boot = bootText.trim();
+  if (!isUuid(boot)) return undefined;
+  if (!processText.startsWith(`${pid} (`)) return undefined;
+  const commandEnd = processText.lastIndexOf(") ");
+  if (commandEnd < 0) return undefined;
+  // After the final command-name parenthesis, index zero is stat field 3.
+  const startTicks = processText
+    .slice(commandEnd + 2)
+    .trim()
+    .split(/\s+/u)[19];
+  if (!startTicks || !/^\d+$/u.test(startTicks)) return undefined;
+  return `linux:${boot.toLowerCase()}:${startTicks}`;
+}
+
+function commandOptions(pid: number): IdentityCommandOptions {
+  return {
+    env: {
+      ...process.env,
+      ABOT_HOST_OWNER_PID: String(pid),
+      LC_ALL: "C",
+      TZ: "UTC",
+    },
+    windowsHide: true,
+    timeout: 5_000,
+    maxBuffer: 4_096,
+  };
+}
+
+async function windowsIdentity(
+  pid: number,
+  dependencies: ProcessOwnerIdentityDependencies,
+): Promise<string | undefined> {
+  const text = await dependencies.execute(
+    "powershell.exe",
+    [
+      "-NoProfile",
+      "-NonInteractive",
+      "-EncodedCommand",
+      Buffer.from(WINDOWS_OWNER_SCRIPT, "utf16le").toString("base64"),
+    ],
+    commandOptions(pid),
+  );
+  const value = text.trim();
+  if (!/^\d{10,20}\|\d{10,20}$/u.test(value)) return undefined;
+  return `windows:${value}`;
+}
+
+async function macIdentity(
+  pid: number,
+  dependencies: ProcessOwnerIdentityDependencies,
+): Promise<string | undefined> {
+  const [bootText, startedText] = await Promise.all([
+    dependencies.execute(
+      "/usr/sbin/sysctl",
+      ["-n", "kern.bootsessionuuid"],
+      commandOptions(pid),
+    ),
+    dependencies.execute(
+      "/bin/ps",
+      ["-p", String(pid), "-o", "lstart="],
+      commandOptions(pid),
+    ),
+  ]);
+  const boot = bootText.trim();
+  const started = startedText.trim().replace(/\s+/gu, " ");
+  if (!isUuid(boot)) return undefined;
+  if (
+    !/^[A-Za-z]{3} [A-Za-z]{3} \d{1,2} \d{2}:\d{2}:\d{2} \d{4}$/u.test(started)
+  )
+    return undefined;
+  return `macos:${boot.toLowerCase()}:${started}`;
+}
+
+export function createProcessOwnerIdentityProbe(
+  dependencies: ProcessOwnerIdentityDependencies,
+) {
+  async function readProcessOwnerIdentity(
+    pid: number,
+  ): Promise<string | undefined> {
+    if (!isProcessId(pid)) return undefined;
+    try {
+      if (dependencies.platform === "linux")
+        return await linuxIdentity(pid, dependencies);
+      if (dependencies.platform === "win32")
+        return await windowsIdentity(pid, dependencies);
+      if (dependencies.platform === "darwin")
+        return await macIdentity(pid, dependencies);
+      return undefined;
+    } catch {
+      return undefined;
+    }
+  }
+  async function isProcessOwnerAlive(
+    pid: number,
+    ownerIdentity?: string,
+  ): Promise<boolean> {
+    if (!isProcessId(pid)) return false;
+    if (!dependencies.processIsAlive(pid)) return false;
+    if (!ownerIdentity) return true;
+    const observed = await readProcessOwnerIdentity(pid);
+    if (!observed) return true;
+    return ownerIdentity === observed;
+  }
+  async function requireCurrentProcessOwnerIdentity(): Promise<string> {
+    const identity = await readProcessOwnerIdentity(dependencies.currentPid);
+    if (!identity)
+      throw new Error(
+        "The host companion could not establish this process's OS identity; its ownership lock was not acquired.",
+      );
+    return identity;
+  }
+  return {
+    readProcessOwnerIdentity,
+    isProcessOwnerAlive,
+    requireCurrentProcessOwnerIdentity,
+  };
+}
+
+const nativeProbe = createProcessOwnerIdentityProbe({
+  platform: process.platform,
+  currentPid: process.pid,
+  readText: (path) => readFile(path, "utf8"),
+  execute: async (file, args, options) =>
+    (await executeFile(file, [...args], options)).stdout,
+  processIsAlive: observePidLiveness,
+});
+export const readProcessOwnerIdentity = nativeProbe.readProcessOwnerIdentity;
+export const isProcessOwnerAlive = nativeProbe.isProcessOwnerAlive;
+export const requireCurrentProcessOwnerIdentity =
+  nativeProbe.requireCurrentProcessOwnerIdentity;

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

@@ -0,0 +1,108 @@
+import type { ToolImplementationOutput } from "../../../../src/plugin-sdk/index.js";
+
+export const HOST_PROTOCOL_VERSION = 1;
+export const HOST_SOCKET_PATH = "/system-host/connect";
+export const HOST_WIRE_MAX_BYTES = 256 * 1024;
+export const HOST_OPERATIONS = [
+  "system_targets",
+  "system_command",
+  "system_applications",
+  "system_launch",
+] as const;
+export type HostOperation = (typeof HOST_OPERATIONS)[number];
+export type HostIdentity = Readonly<{
+  name: string;
+  os: "windows" | "macos" | "linux";
+  user: string;
+  homeDir: string;
+}>;
+export type HostStatus = Readonly<
+  {
+    paired: boolean;
+    hostId?: string;
+    identity?: HostIdentity;
+  } & (
+    | { connected: true; connectionId: string }
+    | { connected: false; connectionId?: never }
+  )
+>;
+export type HostAgentHello = Readonly<{
+  type: "hello";
+  version: 1;
+  identity: HostIdentity;
+  hostId?: string;
+}>;
+export type HostAgentMessage =
+  | HostAgentHello
+  | Readonly<{
+      type: "result";
+      id: string;
+      result: ToolImplementationOutput;
+    }>;
+export type HostServerMessage =
+  | Readonly<{
+      type: "paired";
+      hostId: string;
+      credential: string;
+    }>
+  | Readonly<{ type: "ready"; hostId: string }>
+  | Readonly<{
+      type: "execute";
+      id: string;
+      hostId: string;
+      operation: HostOperation;
+      params: Record<string, unknown>;
+    }>
+  | Readonly<{ type: "cancel"; id: string }>;
+
+export function isHostOperation(value: unknown): value is HostOperation {
+  return HOST_OPERATIONS.some((operation) => operation === value);
+}
+export function isHostRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null) return false;
+  if (typeof value !== "object") return false;
+  return !Array.isArray(value);
+}
+export function isHostIdentifier(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(
+    value,
+  );
+}
+function isHostIdentityText(value: unknown, maximum: number): value is string {
+  if (typeof value !== "string") return false;
+  if (value.length === 0) return false;
+  if (value.length > maximum) return false;
+  return !/[\x00-\x1f\x7f]/u.test(value);
+}
+export function isHostIdentity(value: unknown): value is HostIdentity {
+  if (!isHostRecord(value)) return false;
+  if (
+    Object.keys(value).some(
+      (key) => !["name", "os", "user", "homeDir"].includes(key),
+    )
+  )
+    return false;
+  if (!["windows", "macos", "linux"].includes(String(value.os))) return false;
+  if (!isHostIdentityText(value.name, 128)) return false;
+  if (!isHostIdentityText(value.user, 128)) return false;
+  return isHostIdentityText(value.homeDir, 4096);
+}
+export function hasMatchingHostIdentity(
+  a: HostIdentity,
+  b: HostIdentity,
+): boolean {
+  if (a.name !== b.name) return false;
+  if (a.os !== b.os) return false;
+  if (a.user !== b.user) return false;
+  return a.homeDir === b.homeDir;
+}
+export function isHostToolResult(
+  value: unknown,
+): value is ToolImplementationOutput {
+  if (!isHostRecord(value)) return false;
+  if (typeof value.ok !== "boolean") return false;
+  if (typeof value.producedNewInformation !== "boolean") return false;
+  if (value.data !== undefined && !isHostRecord(value.data)) return false;
+  return typeof value.output === "string";
+}

package/plugins/system/source/contracts.ts

@@ -0,0 +1,44 @@
+export type SystemTargetId = "linux" | "macos" | "windows";
+export type SystemTarget = Readonly<{
+  id: SystemTargetId;
+  transport: "native" | "wsl_interop";
+  shell: string;
+}>;
+export type SystemProcessInput = Readonly<{
+  executable: string;
+  args: readonly string[];
+  cwd?: string;
+  timeoutMs?: number;
+  outputMaxChars?: number;
+  abortSignal?: AbortSignal;
+}>;
+export type SystemSpawnObservation = Readonly<{
+  pid: number;
+  pidNamespace: "runtime_os";
+  executable: string;
+  identitySource: "spawn_arguments";
+}>;
+export type SystemProcessResult = Readonly<{
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  status: "completed" | "timeout" | "aborted" | "spawn_failed";
+  outputTruncated: boolean;
+  spawnedProcess?: SystemSpawnObservation;
+}>;
+export type SystemProcessRunner = (
+  input: SystemProcessInput,
+) => Promise<SystemProcessResult>;
+export type SystemApplication = Readonly<{
+  id: string;
+  name: string;
+  target: SystemTargetId;
+}>;
+export class SystemOperationError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message);
+  }
+}

package/plugins/system/source/elevation.ts

@@ -0,0 +1,88 @@
+import {
+  SystemOperationError,
+  type SystemProcessInput,
+  type SystemProcessRunner,
+  type SystemTarget,
+} from "./contracts.js";
+import {
+  powershellArguments,
+  shellLiteral,
+  windowsSystemCommandScript,
+} from "./targets.js";
+
+const WINDOWS_ADMIN_PROBE =
+  "([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)";
+
+/** Resolve real native authority. Missing human authorization is an explicit result. */
+export async function elevatedSystemCommand(input: {
+  target: SystemTarget;
+  command: string;
+  cwd: string;
+  run: SystemProcessRunner;
+}): Promise<SystemProcessInput> {
+  const { target, command, cwd, run } = input;
+  if (target.id === "windows")
+    return windowsElevatedCommand(target, command, cwd, run);
+  if (process.getuid?.() === 0)
+    return { executable: target.shell, args: ["-lc", command], cwd };
+  if (target.id === "macos") {
+    const script = `cd ${shellLiteral(cwd)} && ${shellLiteral(target.shell)} -lc ${shellLiteral(command)}`;
+    const appleScriptString = JSON.stringify(script);
+    return {
+      executable: "/usr/bin/osascript",
+      args: [
+        "-e",
+        `do shell script ${appleScriptString} with administrator privileges`,
+      ],
+    };
+  }
+  const probe = await run({
+    executable: "/usr/bin/sudo",
+    args: ["-n", "--", "/usr/bin/true"],
+    timeoutMs: 5_000,
+  });
+  if (!hasSuccessfulPrivilegeProbe(probe))
+    throw new SystemOperationError(
+      "system_authorization_required",
+      "Linux sudo authorization requires a human or a configured native privilege policy. Authenticate in a native terminal or supply an authorized host; ABot does not request, invent or bypass passwords.",
+    );
+  return {
+    executable: "/usr/bin/sudo",
+    args: ["-n", "--", target.shell, "-lc", command],
+    cwd,
+  };
+}
+
+function hasSuccessfulPrivilegeProbe(
+  probe: Awaited<ReturnType<SystemProcessRunner>>,
+): boolean {
+  if (probe.status !== "completed") return false;
+  return probe.exitCode === 0;
+}
+function hasWindowsAdministratorAuthority(
+  probe: Awaited<ReturnType<SystemProcessRunner>>,
+): boolean {
+  if (!hasSuccessfulPrivilegeProbe(probe)) return false;
+  return probe.stdout.trim() === "True";
+}
+async function windowsElevatedCommand(
+  target: SystemTarget,
+  command: string,
+  cwd: string,
+  run: SystemProcessRunner,
+): Promise<SystemProcessInput> {
+  const probe = await run({
+    executable: target.shell,
+    args: powershellArguments(WINDOWS_ADMIN_PROBE),
+    timeoutMs: 5_000,
+  });
+  if (!hasWindowsAdministratorAuthority(probe))
+    throw new SystemOperationError(
+      "system_authorization_required",
+      "Windows Administrator authority is required. Approve UAC in a native Windows elevated host, then retry; this noninteractive transport cannot answer UAC or provide credentials.",
+    );
+  return {
+    executable: target.shell,
+    args: powershellArguments(windowsSystemCommandScript(command, cwd)),
+  };
+}

package/plugins/system/source/handlers.ts

@@ -0,0 +1,120 @@
+import {
+  failureFromError,
+  failureResult,
+  readBoundedInteger,
+  readOptionalString,
+  successResult,
+  type ToolImplementation,
+} from "../../../src/plugin-sdk/index.js";
+import { readSystemApplications } from "./application-catalog.js";
+import { systemApplicationObservation } from "./application-observation.js";
+import { observeSystemTargets } from "./target-observation.js";
+import { launchSystemApplication } from "./application-launch.js";
+import { executeSystemCommand } from "./commands.js";
+import {
+  SystemOperationError,
+  type SystemProcessRunner,
+  type SystemTarget,
+  type SystemTargetId,
+} from "./contracts.js";
+import { runSystemProcess } from "./process-runner.js";
+import { systemProcessResult } from "./process-result.js";
+import { readSystemTargetId, resolveSystemTarget } from "./targets.js";
+
+function withSystemOperationErrors(
+  operation: ToolImplementation,
+): ToolImplementation {
+  return async (params, context) => {
+    try {
+      return await operation(params, context);
+    } catch (error) {
+      if (error instanceof SystemOperationError)
+        return failureResult({
+          errorCode: error.code,
+          message: error.message,
+          data: {
+            humanActionRequired: error.code === "system_authorization_required",
+          },
+        });
+      return failureFromError(error, {
+        fallbackCode: "system_operation_failed",
+        fallbackMessage: "The native system operation failed.",
+        operation: "system",
+      });
+    }
+  };
+}
+
+export function createSystemHandlers(
+  run: SystemProcessRunner = runSystemProcess,
+  resolveTarget: (id: SystemTargetId) => Promise<SystemTarget> = (id) =>
+    resolveSystemTarget(id, run),
+): Record<string, ToolImplementation> {
+  const targets: ToolImplementation = async () => {
+    const observation = await observeSystemTargets(run);
+    return successResult({
+      output: JSON.stringify(observation),
+      data: {
+        ...observation,
+        observationMeta: { kind: "volatile_external", carryPolicy: "never" },
+      },
+    });
+  };
+  const command: ToolImplementation = async (params, context) => {
+    const target = await resolveTarget(readSystemTargetId(params.target));
+    const result = await executeSystemCommand({
+      target,
+      params,
+      run,
+      ...(context?.abortSignal ? { abortSignal: context.abortSignal } : {}),
+    });
+    return systemProcessResult(target, result, "command_process_completion");
+  };
+  const applications: ToolImplementation = async (params) => {
+    const target = await resolveTarget(readSystemTargetId(params.target));
+    const query = (readOptionalString(params.query) ?? "").toLowerCase();
+    const limit =
+      params.limit === undefined
+        ? 50
+        : readBoundedInteger(params.limit, {
+            name: "limit",
+            minimum: 1,
+            maximum: 100,
+          });
+    const catalog = await readSystemApplications(target, run);
+    const { output, data } = systemApplicationObservation(
+      target,
+      catalog,
+      query,
+      limit,
+    );
+    return successResult({
+      output,
+      data: {
+        ...data,
+        observationMeta: { kind: "volatile_external", carryPolicy: "never" },
+      },
+    });
+  };
+  const launch: ToolImplementation = async (params, context) => {
+    const target = await resolveTarget(readSystemTargetId(params.target));
+    const result = await launchSystemApplication({
+      target,
+      params,
+      run,
+      ...(context?.abortSignal ? { abortSignal: context.abortSignal } : {}),
+    });
+    return systemProcessResult(
+      target,
+      result.process,
+      "launch_request_dispatch",
+      result.application,
+    );
+  };
+  return {
+    system_targets: withSystemOperationErrors(targets),
+    system_command: withSystemOperationErrors(command),
+    system_applications: withSystemOperationErrors(applications),
+    system_launch: withSystemOperationErrors(launch),
+  };
+}

package/plugins/system/source/host-dispatch.ts

@@ -0,0 +1,106 @@
+import {
+  failureResult,
+  successResult,
+  type ToolImplementation,
+  type ToolImplementationOutput,
+} from "../../../src/plugin-sdk/index.js";
+import {
+  executeHostOperation,
+  readHostStatus,
+} from "./companion/broker-client.js";
+import {
+  HOST_OPERATIONS,
+  type HostOperation,
+  type HostStatus,
+} from "./companion/protocol.js";
+import { SystemOperationError } from "./contracts.js";
+import {
+  observeCapturedSystemTargets,
+  requireSystemRequestRoute,
+  type SystemTargetSnapshot,
+} from "./request-target-snapshot.js";
+
+export type SystemHostConnection = Readonly<{
+  readHostStatus(rootDir: string): Promise<HostStatus>;
+  executeHostOperation(
+    rootDir: string,
+    input: Readonly<{
+      hostId: string;
+      connectionId: string;
+      operation: HostOperation;
+      params: Record<string, unknown>;
+      abortSignal?: AbortSignal;
+    }>,
+  ): Promise<ToolImplementationOutput>;
+}>;
+
+export const defaultSystemHostConnection: SystemHostConnection = {
+  readHostStatus,
+  executeHostOperation,
+};
+
+export function createBoundSystemHandlers(
+  input: Readonly<{
+    rootDir: string;
+    snapshot: SystemTargetSnapshot;
+    nativeHandlers: Readonly<Record<string, ToolImplementation>>;
+    connection: SystemHostConnection;
+  }>,
+): Record<string, ToolImplementation> {
+  return Object.fromEntries(
+    HOST_OPERATIONS.map((operation) => [
+      operation,
+      boundOperation(input, operation),
+    ]),
+  );
+}
+
+function boundOperation(
+  input: Parameters<typeof createBoundSystemHandlers>[0],
+  operation: HostOperation,
+): ToolImplementation {
+  return async (params, context) => {
+    if (hasConnectionControl(params))
+      return failureResult({
+        errorCode: "system_connection_control_forbidden",
+        message:
+          "Connection selection is managed internally and is not an operation input.",
+      });
+    if (operation === "system_targets") {
+      const observation = observeCapturedSystemTargets(input.snapshot);
+      return successResult({
+        output: JSON.stringify(observation),
+        data: {
+          ...observation,
+          observationMeta: { kind: "volatile_external", carryPolicy: "never" },
+        },
+      });
+    }
+    try {
+      const route = requireSystemRequestRoute(input.snapshot, params.target);
+      if (route.kind === "native")
+        return await input.nativeHandlers[operation]!(params, context);
+      return await input.connection.executeHostOperation(input.rootDir, {
+        hostId: route.hostId,
+        connectionId: route.connectionId,
+        operation,
+        params,
+        ...(context?.abortSignal ? { abortSignal: context.abortSignal } : {}),
+      });
+    } catch (error) {
+      if (error instanceof SystemOperationError)
+        return failureResult({ errorCode: error.code, message: error.message });
+      return failureResult({
+        errorCode: "system_execution_route_failed",
+        message:
+          "The bound execution route failed. No other destination was attempted; effects may be partial if dispatch began.",
+      });
+    }
+  };
+}
+
+function hasConnectionControl(params: Record<string, unknown>): boolean {
+  if (Object.hasOwn(params, "host_id")) return true;
+  if (Object.hasOwn(params, "hostId")) return true;
+  return Object.hasOwn(params, "connectionId");
+}