@abot-ai/runtime 1.4.0 → 1.6.0

package/plugins/system/source/contracts.ts

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

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

@@ -1,120 +0,0 @@
-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-evidence.ts

@@ -1,72 +0,0 @@
-import {
-  enforcePluginResultByteBudget,
-  type ToolImplementationOutput,
-} from "../../../src/plugin-sdk/index.js";
-import { isHostRecord, type HostIdentity } from "./companion/protocol.js";
-
-/** Preserve execution provenance without publishing private connection identity. */
-export function attachHostEvidence(
-  result: ToolImplementationOutput,
-  _hostId: string,
-  identity: HostIdentity,
-): ToolImplementationOutput {
-  const data = modelSafeHostResultData(result.data ?? {});
-  const output = describeCompanionProcessNamespace(
-    result.output,
-    data.spawnedProcess,
-  );
-  return enforcePluginResultByteBudget({
-    ...result,
-    output: [
-      `Execution transport: host_companion; OS target: ${identity.os}.`,
-      "This is settled evidence from the selected host, not the runtime/container. A connection or dispatched process does not prove an application window or requested system effect.",
-      output,
-    ].join("\n"),
-    data: {
-      ...data,
-      ...(typeof data.transport === "string"
-        ? { nativeTransport: data.transport }
-        : {}),
-      transport: "host_companion",
-      ...(isHostRecord(data.spawnedProcess)
-        ? {
-            spawnedProcess: {
-              ...data.spawnedProcess,
-              pidNamespace: "companion_os",
-            },
-          }
-        : {}),
-    },
-  });
-}
-
-function modelSafeHostResultData(
-  data: Record<string, unknown>,
-): Record<string, unknown> {
-  const privateFields = new Set([
-    "hostId",
-    "host_id",
-    "connectionId",
-    "hostIdentity",
-    "companion",
-    "targetSelection",
-  ]);
-  return Object.fromEntries(
-    Object.entries(data).filter(([key]) => !privateFields.has(key)),
-  );
-}
-
-function describeCompanionProcessNamespace(
-  output: string,
-  spawnedProcess: unknown,
-): string {
-  if (!isHostRecord(spawnedProcess)) return output;
-  const excerptBoundary = output.indexOf("\nSTDOUT excerpt:");
-  if (excerptBoundary < 0) return output;
-  const header = output.slice(0, excerptBoundary);
-  const streams = output.slice(excerptBoundary);
-  return (
-    header.replace(" in runtime OS namespace.", " in companion OS namespace.") +
-    streams
-  );
-}

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

@@ -1,66 +0,0 @@
-import { existsSync } from "node:fs";
-import { release } from "node:os";
-import type { SystemTargetId } from "./contracts.js";
-
-export type SystemHostFacts = Readonly<{
-  platform: NodeJS.Platform;
-  kernelRelease: string;
-  containerMarker?: boolean;
-}>;
-
-export function readSystemHostFacts(): SystemHostFacts {
-  return {
-    platform: process.platform,
-    kernelRelease: release(),
-    containerMarker: hasSystemContainerMarker(),
-  };
-}
-
-function hasSystemContainerMarker(): boolean {
-  if (existsSync("/.dockerenv")) return true;
-  return existsSync("/run/.containerenv");
-}
-
-function isContainerHostRuntime(facts: SystemHostFacts): boolean {
-  if (facts.platform !== "linux") return false;
-  return facts.containerMarker === true;
-}
-
-export function isWslHostRuntime(facts: SystemHostFacts): boolean {
-  if (facts.platform !== "linux") return false;
-  if (isContainerHostRuntime(facts)) return false;
-  return /microsoft/iu.test(facts.kernelRelease);
-}
-
-function runtimeOs(platform: NodeJS.Platform): SystemTargetId | "unsupported" {
-  if (platform === "win32") return "windows";
-  if (platform === "darwin") return "macos";
-  if (platform === "linux") return "linux";
-  return "unsupported";
-}
-
-export function observeSystemHost(
-  facts: SystemHostFacts = readSystemHostFacts(),
-) {
-  const runtime = runtimeOs(facts.platform);
-  if (isContainerHostRuntime(facts)) return {
-    runtimeOs: runtime,
-    kernelRelease: facts.kernelRelease,
-    environment: "container",
-    inferredHostOs: "unknown",
-    hostInferenceSource: "container_marker",
-    windowsExecutionRequiresProbe: false,
-    guiSessionStatus: "not_checked",
-  } as const;
-  const wsl = isWslHostRuntime(facts);
-  const inferredHostOs = wsl ? "windows" : runtime;
-  return {
-    runtimeOs: runtime,
-    kernelRelease: facts.kernelRelease,
-    environment: wsl ? "wsl_guest" : "not_identified_as_wsl",
-    inferredHostOs,
-    hostInferenceSource: wsl ? "wsl_kernel_signature" : "runtime_platform_only",
-    windowsExecutionRequiresProbe: inferredHostOs === "windows",
-    guiSessionStatus: "not_checked",
-  } as const;
-}

package/plugins/system/source/process-result.ts

@@ -1,111 +0,0 @@
-import {
-  failureResult,
-  successResult,
-  type ToolImplementationOutput,
-} from "../../../src/plugin-sdk/index.js";
-import type {
-  SystemApplication,
-  SystemProcessResult,
-  SystemTarget,
-} from "./contracts.js";
-
-export type SystemEvidenceScope =
-  | "command_process_completion"
-  | "launch_request_dispatch";
-const STREAM_EXCERPT_CHARS = 2_000;
-const IDENTITY_EXCERPT_CHARS = 512;
-const LEGACY_EVIDENCE_LABELS: Record<SystemEvidenceScope, string> = {
-  command_process_completion: "system command process completion",
-  launch_request_dispatch: "application launch request dispatch",
-};
-
-export function systemProcessResult(
-  target: SystemTarget,
-  result: SystemProcessResult,
-  evidenceScope: SystemEvidenceScope,
-  application?: SystemApplication,
-): ToolImplementationOutput {
-  const stdoutOmittedChars = Math.max(
-    0,
-    result.stdout.length - STREAM_EXCERPT_CHARS,
-  );
-  const stderrOmittedChars = Math.max(
-    0,
-    result.stderr.length - STREAM_EXCERPT_CHARS,
-  );
-  const data = {
-    evidenceScope,
-    evidence: LEGACY_EVIDENCE_LABELS[evidenceScope],
-    independentOutcomeCheck: "not_performed" as const,
-    target: target.id,
-    transport: target.transport,
-    processStatus: result.status,
-    spawnedProcess: result.spawnedProcess ?? null,
-    ...(application ? { catalogApplication: application } : {}),
-    outputTruncated: result.outputTruncated,
-    summaryOmittedChars: {
-      stdout: stdoutOmittedChars,
-      stderr: stderrOmittedChars,
-    },
-    observationMeta: {
-      kind: "volatile_external" as const,
-      carryPolicy: "never" as const,
-    },
-  };
-  const output = [
-    `Adapter evidence: ${evidenceScope}. Independent outcome check: not performed. Completion/dispatch alone does not verify the requested application, window or system effect; evaluate command evidence separately.`,
-    `Target: ${target.id} (${target.transport})`,
-    `Process status: ${result.status}; exit code: ${result.exitCode ?? "unavailable"}`,
-    result.spawnedProcess
-      ? `Spawned helper: ${identityExcerpt(result.spawnedProcess.executable)}; PID ${result.spawnedProcess.pid} in runtime OS namespace. Identity comes from spawn arguments, not application image inspection.`
-      : "Spawned helper identity: not recorded.",
-    ...(application
-      ? [
-          `Revalidated catalog identity: ${identityExcerpt(application.id)} (identity only; no application process/window check).`,
-        ]
-      : []),
-    "STDOUT excerpt:",
-    result.stdout.slice(0, STREAM_EXCERPT_CHARS) || "(empty)",
-    "STDERR excerpt:",
-    result.stderr.slice(0, STREAM_EXCERPT_CHARS) || "(empty)",
-    `Summary omitted characters: stdout=${stdoutOmittedChars}, stderr=${stderrOmittedChars}. Raw stream capture truncated: ${result.outputTruncated}.`,
-  ].join("\n");
-  if (hasSuccessfulSystemObservation(result)) {
-    return successResult({
-      output,
-      stdout: result.stdout,
-      stderr: result.stderr,
-      exitCode: 0,
-      data,
-    });
-  }
-  const errorCode =
-    result.status === "completed"
-      ? "system_command_failed"
-      : `system_${result.status}`;
-  return failureResult({
-    errorCode,
-    message: hasUncertainDescendantState(result)
-      ? "System command observation stopped. External or detached descendants may remain; inspect the target before retrying."
-      : "The target did not report successful command completion.",
-    output,
-    stdout: result.stdout,
-    stderr: result.stderr,
-    ...(result.exitCode !== null ? { exitCode: result.exitCode } : {}),
-    data,
-  });
-}
-
-function hasSuccessfulSystemObservation(result: SystemProcessResult): boolean {
-  if (result.status !== "completed") return false;
-  return result.exitCode === 0;
-}
-function hasUncertainDescendantState(result: SystemProcessResult): boolean {
-  if (result.status === "timeout") return true;
-  return result.status === "aborted";
-}
-
-function identityExcerpt(identity: string): string {
-  if (identity.length <= IDENTITY_EXCERPT_CHARS) return identity;
-  return `${identity.slice(0, IDENTITY_EXCERPT_CHARS)} [${identity.length - IDENTITY_EXCERPT_CHARS} characters omitted; full identity in result data]`;
-}

package/plugins/system/source/process-runner.ts

@@ -1,104 +0,0 @@
-import { spawn } from "node:child_process";
-import type { SystemProcessInput, SystemProcessResult } from "./contracts.js";
-
-const STREAM_MAX_CHARS = 16_000;
-/** Bounded process observation; exit zero proves command completion, not effects. */
-export function runSystemProcess(
-  input: SystemProcessInput,
-): Promise<SystemProcessResult> {
-  if (input.abortSignal?.aborted)
-    return Promise.resolve({
-      exitCode: null,
-      stdout: "",
-      stderr: "",
-      status: "aborted",
-      outputTruncated: false,
-    });
-  return new Promise((resolve) => {
-    const streamMaxChars = Math.min(
-      input.outputMaxChars ?? STREAM_MAX_CHARS,
-      512_000,
-    );
-    let stdout = "";
-    let stderr = "";
-    let truncated = false;
-    let settled = false;
-    let status: SystemProcessResult["status"] = "completed";
-    let spawnedProcess: SystemProcessResult["spawnedProcess"];
-    let timeout: ReturnType<typeof setTimeout> | undefined;
-    let stopGrace: ReturnType<typeof setTimeout> | undefined;
-    const finish = (exitCode: number | null) => {
-      if (settled) return;
-      settled = true;
-      if (timeout) clearTimeout(timeout);
-      if (stopGrace) clearTimeout(stopGrace);
-      input.abortSignal?.removeEventListener("abort", abort);
-      resolve(
-        Object.freeze({
-          exitCode,
-          stdout,
-          stderr,
-          status,
-          outputTruncated: truncated,
-          ...(spawnedProcess ? { spawnedProcess } : {}),
-        }),
-      );
-    };
-    const child = spawn(input.executable, [...input.args], {
-      ...(input.cwd ? { cwd: input.cwd } : {}),
-      stdio: ["ignore", "pipe", "pipe"],
-      windowsHide: true,
-      detached: process.platform !== "win32",
-    });
-    child.once("spawn", () => {
-      if (child.pid === undefined) return;
-      spawnedProcess = {
-        pid: child.pid,
-        pidNamespace: "runtime_os",
-        executable: input.executable,
-        identitySource: "spawn_arguments",
-      };
-    });
-    const stop = (reason: "timeout" | "aborted") => {
-      if (settled) return;
-      status = reason;
-      const pid = child.pid;
-      if (pid && process.platform !== "win32") {
-        try {
-          process.kill(-pid, "SIGKILL");
-        } catch {
-          child.kill("SIGKILL");
-        }
-      } else {
-        child.kill("SIGKILL");
-      }
-      // Native/external descendants can outlive a stopped transport; never claim
-      // their termination from the shell observation alone.
-      stopGrace = setTimeout(() => finish(null), 1_000);
-      stopGrace.unref();
-    };
-    const abort = () => stop("aborted");
-    child.stdout.setEncoding("utf8");
-    child.stderr.setEncoding("utf8");
-    child.stdout.on("data", (chunk: string) => {
-      const remaining = streamMaxChars - stdout.length;
-      truncated ||= chunk.length > remaining;
-      stdout += chunk.slice(0, remaining);
-    });
-    child.stderr.on("data", (chunk: string) => {
-      const remaining = streamMaxChars - stderr.length;
-      truncated ||= chunk.length > remaining;
-      stderr += chunk.slice(0, remaining);
-    });
-    child.once("error", (error) => {
-      status = "spawn_failed";
-      stderr = error.message.slice(0, STREAM_MAX_CHARS);
-      finish(null);
-    });
-    child.once("close", (code) => finish(code));
-    timeout = setTimeout(() => stop("timeout"), input.timeoutMs ?? 30_000);
-    timeout.unref();
-    input.abortSignal?.addEventListener("abort", abort, { once: true });
-    if (input.abortSignal?.aborted) abort();
-  });
-}

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

@@ -1,43 +0,0 @@
-import type { SystemProcessRunner, SystemTarget, SystemTargetId } from "./contracts.js";
-import { observeSystemHost } from "./host-observation.js";
-import { runSystemProcess } from "./process-runner.js";
-import { resolveSystemTarget } from "./targets.js";
-
-type TargetObservation = Readonly<
-  | (SystemTarget & { available: true; commandExecutionAvailable: true; guiSessionStatus: "not_checked" })
-  | { id: SystemTargetId; available: false; reason: string }
->;
-
-export type SystemTargetObservation = Readonly<{
-  host: ReturnType<typeof observeSystemHost>;
-  availabilityScope: "command_execution_only";
-  targets: readonly TargetObservation[];
-}>;
-
-export async function observeSystemTargets(
-  run: SystemProcessRunner = runSystemProcess,
-): Promise<SystemTargetObservation> {
-  const observations: TargetObservation[] = [];
-  for (const id of ["linux", "macos", "windows"] as const) {
-    try {
-      const target = await resolveSystemTarget(id, run);
-      observations.push({
-        ...target,
-        available: true,
-        commandExecutionAvailable: true,
-        guiSessionStatus: "not_checked",
-      });
-    } catch (error) {
-      observations.push({
-        id,
-        available: false,
-        reason: error instanceof Error ? error.message : String(error),
-      });
-    }
-  }
-  return {
-    host: observeSystemHost(),
-    availabilityScope: "command_execution_only",
-    targets: observations,
-  };
-}