@abot-ai/runtime 1.3.0 → 1.4.0

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

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

@@ -0,0 +1,66 @@
+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/index.ts

@@ -0,0 +1,8 @@
+import { defineRuntimePlugin } from "../../../src/plugin-sdk/index.js";
+import { createSystemHandlers } from "./handlers.js";
+import { prepareSystemRequestModules } from "./request-system-modules.js";
+
+export default defineRuntimePlugin(({ rootDir }) => ({
+  handlers: createSystemHandlers(),
+  prepareRequest: (modules) => prepareSystemRequestModules(rootDir, modules),
+}));

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

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

@@ -0,0 +1,104 @@
+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/request-system-modules.ts

@@ -0,0 +1,117 @@
+import type {
+  ToolCallAdapter,
+  ToolImplementation,
+  ToolModuleDeclaration,
+} from "../../../src/plugin-sdk/index.js";
+import type { SystemTarget, SystemTargetId } from "./contracts.js";
+import { isHostOperation } from "./companion/protocol.js";
+import { createSystemHandlers } from "./handlers.js";
+import {
+  createBoundSystemHandlers,
+  defaultSystemHostConnection,
+  type SystemHostConnection,
+} from "./host-dispatch.js";
+import {
+  observeSystemTargets,
+  type SystemTargetObservation,
+} from "./target-observation.js";
+import {
+  captureSystemTargetSnapshot,
+  requireSystemRequestRoute,
+  resolveCapturedNativeTarget,
+  routeTargetId,
+  systemRouteBindingIdentity,
+  systemRouteMetadata,
+  type SystemTargetSnapshot,
+} from "./request-target-snapshot.js";
+
+export type SystemRequestDependencies = Readonly<{
+  observeTargets?: () => Promise<SystemTargetObservation>;
+  connection?: SystemHostConnection;
+  createNativeHandlers?: (
+    resolveTarget: (id: SystemTargetId) => Promise<SystemTarget>,
+  ) => Record<string, ToolImplementation>;
+}>;
+
+export async function prepareSystemRequestModules(
+  rootDir: string,
+  modules: readonly ToolModuleDeclaration[],
+  dependencies: SystemRequestDependencies = {},
+): Promise<readonly ToolModuleDeclaration[]> {
+  if (modules.length === 0) return Object.freeze([]);
+  if (modules.some((module) => !isHostOperation(module.definition.name)))
+    throw new Error("system_request_module_unknown");
+  const connection = dependencies.connection ?? defaultSystemHostConnection;
+  const snapshot = await captureSystemTargetSnapshot({
+    observeTargets: dependencies.observeTargets ?? observeSystemTargets,
+    readHostStatus: () => connection.readHostStatus(rootDir),
+  });
+  if (snapshot.length === 0) return Object.freeze([]);
+  const createNative =
+    dependencies.createNativeHandlers ??
+    ((resolve) => createSystemHandlers(undefined, resolve));
+  const nativeHandlers = createNative(async (target) =>
+    resolveCapturedNativeTarget(snapshot, target),
+  );
+  const handlers = createBoundSystemHandlers({
+    rootDir,
+    snapshot,
+    connection,
+    nativeHandlers,
+  });
+  return Object.freeze(
+    modules.map((module) =>
+      projectSystemRequestModule(module, snapshot, handlers),
+    ),
+  );
+}
+
+function projectSystemRequestModule(
+  module: ToolModuleDeclaration,
+  snapshot: SystemTargetSnapshot,
+  handlers: Readonly<Record<string, ToolImplementation>>,
+): ToolModuleDeclaration {
+  const targets = Object.freeze(snapshot.map(routeTargetId));
+  const availability = ` Available targets for this request: ${targets.join(", ")}.`;
+  return Object.freeze({
+    ...module,
+    normalInvocation: {
+      ...module.normalInvocation,
+      operations: module.normalInvocation.operations.map((operation) => ({
+        ...operation,
+        summary: operation.summary + availability,
+        input: {
+          ...operation.input,
+          properties: {
+            ...operation.input.properties,
+            ...(Object.hasOwn(operation.input.properties, "target")
+              ? { target: { type: "string" as const, enum: targets } }
+              : {}),
+          },
+        },
+      })),
+    },
+    implementation: handlers[module.definition.name]!,
+    adapter: {
+      ...module.adapter,
+      executionBinding: systemExecutionBinding(snapshot),
+    },
+  });
+}
+
+function systemExecutionBinding(
+  snapshot: SystemTargetSnapshot,
+): NonNullable<ToolCallAdapter["executionBinding"]> {
+  return (call) => {
+    if (call.tool === "system_targets")
+      return {
+        identity: JSON.stringify(snapshot.map(systemRouteBindingIdentity)),
+        metadata: { displayTarget: snapshot.map(routeTargetId).join(", ") },
+      };
+    const route = requireSystemRequestRoute(snapshot, call.params.target);
+    return {
+      identity: systemRouteBindingIdentity(route),
+      metadata: systemRouteMetadata(route),
+    };
+  };
+}

package/plugins/system/source/request-target-snapshot.ts

@@ -0,0 +1,163 @@
+import {
+  SystemOperationError,
+  type SystemTarget,
+  type SystemTargetId,
+} from "./contracts.js";
+import {
+  isHostIdentifier,
+  isHostIdentity,
+  type HostIdentity,
+  type HostStatus,
+} from "./companion/protocol.js";
+import type { SystemTargetObservation } from "./target-observation.js";
+
+export type SystemRequestRoute = Readonly<
+  | { kind: "native"; target: SystemTarget }
+  | {
+      kind: "companion";
+      target: SystemTargetId;
+      hostId: string;
+      connectionId: string;
+      identity: HostIdentity;
+    }
+>;
+export type SystemTargetSnapshot = readonly SystemRequestRoute[];
+
+/** Capture availability once. A companion only supplies an OS missing natively. */
+export async function captureSystemTargetSnapshot(
+  input: Readonly<{
+    observeTargets(): Promise<SystemTargetObservation>;
+    readHostStatus(): Promise<HostStatus>;
+  }>,
+): Promise<SystemTargetSnapshot> {
+  const [native, companion] = await Promise.allSettled([
+    input.observeTargets(),
+    input.readHostStatus(),
+  ]);
+  const routes = capturedNativeRoutes(native);
+  if (companion.status !== "fulfilled") return Object.freeze(routes);
+  const remote = connectedCompanionRoute(companion.value);
+  if (!remote) return Object.freeze(routes);
+  if (routes.some((route) => routeTargetId(route) === remote.target))
+    return Object.freeze(routes);
+  return Object.freeze([...routes, remote]);
+}
+
+function capturedNativeRoutes(
+  observation: PromiseSettledResult<SystemTargetObservation>,
+): SystemRequestRoute[] {
+  if (observation.status !== "fulfilled") return [];
+  return observation.value.targets.flatMap((target) => {
+    if (!target.available) return [];
+    return [
+      Object.freeze({
+        kind: "native" as const,
+        target: Object.freeze({
+          id: target.id,
+          shell: target.shell,
+          transport: target.transport,
+        }),
+      }),
+    ];
+  });
+}
+
+function connectedCompanionRoute(
+  status: HostStatus,
+): SystemRequestRoute | undefined {
+  if (!status.paired) return undefined;
+  if (!status.connected) return undefined;
+  if (!isHostIdentifier(status.hostId)) return undefined;
+  if (!isHostIdentifier(status.connectionId)) return undefined;
+  if (!isHostIdentity(status.identity)) return undefined;
+  return Object.freeze({
+    kind: "companion",
+    target: status.identity.os,
+    hostId: status.hostId,
+    connectionId: status.connectionId,
+    identity: Object.freeze({ ...status.identity }),
+  });
+}
+
+export function routeTargetId(route: SystemRequestRoute): SystemTargetId {
+  if (route.kind === "native") return route.target.id;
+  return route.target;
+}
+
+export function requireSystemRequestRoute(
+  snapshot: SystemTargetSnapshot,
+  target: unknown,
+): SystemRequestRoute {
+  const route = snapshot.find(
+    (candidate) => routeTargetId(candidate) === target,
+  );
+  if (route) return route;
+  throw new SystemOperationError(
+    "system_target_unavailable",
+    "The requested OS target is unavailable in this request.",
+  );
+}
+
+export function resolveCapturedNativeTarget(
+  snapshot: SystemTargetSnapshot,
+  target: SystemTargetId,
+): SystemTarget {
+  const route = requireSystemRequestRoute(snapshot, target);
+  if (route.kind === "native") return route.target;
+  throw new SystemOperationError(
+    "system_target_unavailable",
+    "The request did not bind this target to native execution.",
+  );
+}
+
+export function systemRouteBindingIdentity(route: SystemRequestRoute): string {
+  if (route.kind === "native")
+    return JSON.stringify([route.kind, route.target]);
+  return JSON.stringify([
+    route.kind,
+    route.target,
+    route.hostId,
+    route.connectionId,
+  ]);
+}
+
+export function systemRouteMetadata(
+  route: SystemRequestRoute,
+): Readonly<Record<string, unknown>> {
+  if (route.kind === "native")
+    return {
+      displayTarget: route.target.id,
+      transport: route.target.transport,
+    };
+  return {
+    displayTarget: route.target,
+    transport: "host_companion",
+    computerName: route.identity.name,
+  };
+}
+
+export function observeCapturedSystemTargets(snapshot: SystemTargetSnapshot) {
+  return {
+    targets: snapshot.map((route) => ({
+      id: routeTargetId(route),
+      available: true,
+      ...modelSafeRouteObservation(route),
+      guiSessionStatus: "not_checked" as const,
+    })),
+    availabilityScope: "request_execution_routes",
+  } as const;
+}
+
+function modelSafeRouteObservation(route: SystemRequestRoute) {
+  if (route.kind === "native")
+    return {
+      transport: route.target.transport,
+      commandExecutionStatus: "probed",
+      availabilityScope: "command_execution_only",
+    } as const;
+  return {
+    transport: "host_companion",
+    commandExecutionStatus: "not_probed",
+    availabilityScope: "transport_connection_only",
+  } as const;
+}

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

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