@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/computer-access/computer/windows-topology-script.js

@@ -0,0 +1,80 @@
+/** Monitor source arrangement is part of opaque desktop identity, not a new tool field. */
+export const WINDOWS_TOPOLOGY_SCRIPT = String.raw `
+public static partial class AbotComputer {
+  [StructLayout(LayoutKind.Sequential,CharSet=CharSet.Unicode)] struct CaptureMonitorInfo {
+    public int Size; public Rect Monitor,Work; public uint Flags;
+    [MarshalAs(UnmanagedType.ByValTStr,SizeConst=32)] public string Device;
+  }
+  [StructLayout(LayoutKind.Sequential,CharSet=CharSet.Unicode)] struct CaptureDisplayMode {
+    [MarshalAs(UnmanagedType.ByValTStr,SizeConst=32)] public string DeviceName;
+    public ushort SpecVersion,DriverVersion,Size,DriverExtra; public uint Fields;
+    public int PositionX,PositionY; public uint Orientation,FixedOutput;
+    public short Color,Duplex,YResolution,TTOption,Collate;
+    [MarshalAs(UnmanagedType.ByValTStr,SizeConst=32)] public string FormName;
+    public ushort LogPixels; public uint BitsPerPixel,PixelWidth,PixelHeight,DisplayFlags,Frequency;
+    public uint IcmMethod,IcmIntent,MediaType,DitherType,Reserved1,Reserved2,PanningWidth,PanningHeight;
+  }
+  delegate bool CaptureMonitorCallback(IntPtr monitor,IntPtr dc,ref Rect bounds,IntPtr data);
+  [StructLayout(LayoutKind.Sequential,CharSet=CharSet.Unicode)] struct CaptureDisplayDevice {
+    public int Size;
+    [MarshalAs(UnmanagedType.ByValTStr,SizeConst=32)] public string Name;
+    [MarshalAs(UnmanagedType.ByValTStr,SizeConst=128)] public string Description;
+    public uint Flags;
+    [MarshalAs(UnmanagedType.ByValTStr,SizeConst=128)] public string InterfaceId;
+    [MarshalAs(UnmanagedType.ByValTStr,SizeConst=128)] public string RegistryKey;
+  }
+  [DllImport("user32.dll")] static extern bool EnumDisplayMonitors(IntPtr dc,IntPtr clip,CaptureMonitorCallback callback,IntPtr data);
+  [DllImport("user32.dll",CharSet=CharSet.Unicode)] static extern bool GetMonitorInfo(IntPtr monitor,ref CaptureMonitorInfo info);
+  [DllImport("user32.dll",CharSet=CharSet.Unicode)] static extern bool EnumDisplaySettingsEx(string device,int mode,ref CaptureDisplayMode settings,uint flags);
+  [DllImport("shcore.dll")] static extern int GetScaleFactorForMonitor(IntPtr monitor,out int scale);
+  [DllImport("user32.dll",CharSet=CharSet.Unicode)] static extern bool EnumDisplayDevices(string device,uint index,ref CaptureDisplayDevice info,uint flags);
+
+  static bool TryMonitorScale(IntPtr monitor,out int scale) {
+    scale=0;
+    try { return GetScaleFactorForMonitor(monitor,out scale)==0; }
+    catch(DllNotFoundException) { return false; }
+    catch(EntryPointNotFoundException) { return false; }
+  }
+
+  static string SourceFingerprint(List<string> records) {
+    records.Sort(StringComparer.Ordinal);
+    using(var hash=System.Security.Cryptography.SHA256.Create()) {
+      return BitConverter.ToString(hash.ComputeHash(Encoding.UTF8.GetBytes(Json.Serialize(records)))).Replace("-","").ToLowerInvariant();
+    }
+  }
+  static string MonitorSourceIds(string device) {
+    var sources=new List<string>();
+    for(uint index=0;index<128;index++) {
+      var info=new CaptureDisplayDevice { Size=Marshal.SizeOf(typeof(CaptureDisplayDevice)) };
+      if(!EnumDisplayDevices(device,index,ref info,1)) break;
+      if((info.Flags&1)==0) continue;
+      if(String.IsNullOrEmpty(info.InterfaceId)) return null;
+      sources.Add(info.InterfaceId);
+    }
+    if(sources.Count==0) return null;
+    return SourceFingerprint(sources);
+  }
+  static string ReadCaptureTopology() {
+    var records=new List<string>(); bool queryFailed=false;
+    CaptureMonitorCallback callback=delegate(IntPtr monitor,IntPtr dc,ref Rect bounds,IntPtr data) {
+      if(records.Count>=128) { queryFailed=true; return false; }
+      var info=new CaptureMonitorInfo { Size=Marshal.SizeOf(typeof(CaptureMonitorInfo)) };
+      if(!GetMonitorInfo(monitor,ref info)) { queryFailed=true; return false; }
+      var mode=new CaptureDisplayMode { Size=(ushort)Marshal.SizeOf(typeof(CaptureDisplayMode)) };
+      if(!EnumDisplaySettingsEx(info.Device,-1,ref mode,0)) { queryFailed=true; return false; }
+      int scale;
+      if(!TryMonitorScale(monitor,out scale)) { queryFailed=true; return false; }
+      string sources=MonitorSourceIds(info.Device);
+      if(sources==null) { queryFailed=true; return false; }
+      records.Add(Json.Serialize(new object[] {info.Device,monitor.ToInt64(),info.Monitor.Left,info.Monitor.Top,
+        info.Monitor.Right,info.Monitor.Bottom,info.Flags,mode.Orientation,mode.FixedOutput,
+        mode.PixelWidth,mode.PixelHeight,mode.PositionX,mode.PositionY,scale,sources}));
+      return true;
+    };
+    bool complete=EnumDisplayMonitors(IntPtr.Zero,IntPtr.Zero,callback,IntPtr.Zero);
+    if(!complete || queryFailed || records.Count==0)
+      throw new ComputerFault("computer_topology_unavailable","The monitor source arrangement could not be verified.");
+    return SourceFingerprint(records);
+  }
+}
+`;

package/dist/src/computer-access/contracts.d.ts

@@ -0,0 +1,38 @@
+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 declare class SystemOperationError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}

package/dist/src/computer-access/contracts.js

@@ -0,0 +1,7 @@
+export class SystemOperationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}

package/dist/src/computer-access/elevation.d.ts

@@ -0,0 +1,8 @@
+import { type SystemProcessInput, type SystemProcessRunner, type SystemTarget } from "./contracts.js";
+/** Resolve real native authority. Missing human authorization is an explicit result. */
+export declare function elevatedSystemCommand(input: {
+    target: SystemTarget;
+    command: string;
+    cwd: string;
+    run: SystemProcessRunner;
+}): Promise<SystemProcessInput>;

package/dist/src/computer-access/elevation.js

@@ -0,0 +1,57 @@
+import { SystemOperationError, } 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) {
+    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) {
+    if (probe.status !== "completed")
+        return false;
+    return probe.exitCode === 0;
+}
+function hasWindowsAdministratorAuthority(probe) {
+    if (!hasSuccessfulPrivilegeProbe(probe))
+        return false;
+    return probe.stdout.trim() === "True";
+}
+async function windowsElevatedCommand(target, command, cwd, run) {
+    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/dist/src/computer-access/handlers.d.ts

@@ -0,0 +1,3 @@
+import { type ToolImplementation } from "../plugin-sdk/index.js";
+import { type SystemProcessRunner, type SystemTarget, type SystemTargetId } from "./contracts.js";
+export declare function createSystemHandlers(run?: SystemProcessRunner, resolveTarget?: (id: SystemTargetId) => Promise<SystemTarget>): Record<string, ToolImplementation>;

package/dist/src/computer-access/handlers.js

@@ -0,0 +1,90 @@
+import { failureFromError, failureResult, readBoundedInteger, readOptionalString, successResult, } from "../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, } from "./contracts.js";
+import { runSystemProcess } from "./process-runner.js";
+import { systemProcessResult } from "./process-result.js";
+import { readSystemTargetId, resolveSystemTarget } from "./targets.js";
+function withSystemOperationErrors(operation) {
+    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 = runSystemProcess, resolveTarget = (id) => resolveSystemTarget(id, run)) {
+    const targets = async () => {
+        const observation = await observeSystemTargets(run);
+        return successResult({
+            output: JSON.stringify(observation),
+            data: {
+                ...observation,
+                observationMeta: { kind: "volatile_external", carryPolicy: "never" },
+            },
+        });
+    };
+    const command = 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 = 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 = 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/dist/src/computer-access/host-evidence.d.ts

@@ -0,0 +1,4 @@
+import { type ToolImplementationOutput } from "../plugin-sdk/index.js";
+import { type HostIdentity } from "./companion/protocol.js";
+/** Preserve execution provenance without publishing private connection identity. */
+export declare function attachHostEvidence(result: ToolImplementationOutput, _hostId: string, identity: HostIdentity): ToolImplementationOutput;

package/dist/src/computer-access/host-evidence.js

@@ -0,0 +1,52 @@
+import { enforcePluginResultByteBudget, } from "../plugin-sdk/index.js";
+import { isHostRecord } from "./companion/protocol.js";
+/** Preserve execution provenance without publishing private connection identity. */
+export function attachHostEvidence(result, _hostId, identity) {
+    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) {
+    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, spawnedProcess) {
+    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/dist/src/computer-access/host-observation.d.ts

@@ -0,0 +1,25 @@
+import type { SystemTargetId } from "./contracts.js";
+export type SystemHostFacts = Readonly<{
+    platform: NodeJS.Platform;
+    kernelRelease: string;
+    containerMarker?: boolean;
+}>;
+export declare function readSystemHostFacts(): SystemHostFacts;
+export declare function isWslHostRuntime(facts: SystemHostFacts): boolean;
+export declare function observeSystemHost(facts?: SystemHostFacts): {
+    readonly runtimeOs: "unsupported" | SystemTargetId;
+    readonly kernelRelease: string;
+    readonly environment: "container";
+    readonly inferredHostOs: "unknown";
+    readonly hostInferenceSource: "container_marker";
+    readonly windowsExecutionRequiresProbe: false;
+    readonly guiSessionStatus: "not_checked";
+} | {
+    readonly runtimeOs: "unsupported" | SystemTargetId;
+    readonly kernelRelease: string;
+    readonly environment: "wsl_guest" | "not_identified_as_wsl";
+    readonly inferredHostOs: "unsupported" | SystemTargetId;
+    readonly hostInferenceSource: "wsl_kernel_signature" | "runtime_platform_only";
+    readonly windowsExecutionRequiresProbe: boolean;
+    readonly guiSessionStatus: "not_checked";
+};

package/dist/src/computer-access/host-observation.js

@@ -0,0 +1,59 @@
+import { existsSync } from "node:fs";
+import { release } from "node:os";
+export function readSystemHostFacts() {
+    return {
+        platform: process.platform,
+        kernelRelease: release(),
+        containerMarker: hasSystemContainerMarker(),
+    };
+}
+function hasSystemContainerMarker() {
+    if (existsSync("/.dockerenv"))
+        return true;
+    return existsSync("/run/.containerenv");
+}
+function isContainerHostRuntime(facts) {
+    if (facts.platform !== "linux")
+        return false;
+    return facts.containerMarker === true;
+}
+export function isWslHostRuntime(facts) {
+    if (facts.platform !== "linux")
+        return false;
+    if (isContainerHostRuntime(facts))
+        return false;
+    return /microsoft/iu.test(facts.kernelRelease);
+}
+function runtimeOs(platform) {
+    if (platform === "win32")
+        return "windows";
+    if (platform === "darwin")
+        return "macos";
+    if (platform === "linux")
+        return "linux";
+    return "unsupported";
+}
+export function observeSystemHost(facts = 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",
+        };
+    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",
+    };
+}

package/dist/src/computer-access/process-result.d.ts

@@ -0,0 +1,4 @@
+import { type ToolImplementationOutput } from "../plugin-sdk/index.js";
+import type { SystemApplication, SystemProcessResult, SystemTarget } from "./contracts.js";
+export type SystemEvidenceScope = "command_process_completion" | "launch_request_dispatch";
+export declare function systemProcessResult(target: SystemTarget, result: SystemProcessResult, evidenceScope: SystemEvidenceScope, application?: SystemApplication): ToolImplementationOutput;

package/dist/src/computer-access/process-result.js

@@ -0,0 +1,86 @@
+import { failureResult, successResult, } from "../plugin-sdk/index.js";
+const STREAM_EXCERPT_CHARS = 2_000;
+const IDENTITY_EXCERPT_CHARS = 512;
+const LEGACY_EVIDENCE_LABELS = {
+    command_process_completion: "system command process completion",
+    launch_request_dispatch: "application launch request dispatch",
+};
+export function systemProcessResult(target, result, evidenceScope, application) {
+    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",
+        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",
+            carryPolicy: "never",
+        },
+    };
+    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) {
+    if (result.status !== "completed")
+        return false;
+    return result.exitCode === 0;
+}
+function hasUncertainDescendantState(result) {
+    if (result.status === "timeout")
+        return true;
+    return result.status === "aborted";
+}
+function identityExcerpt(identity) {
+    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/dist/src/computer-access/process-runner.d.ts

@@ -0,0 +1,3 @@
+import type { SystemProcessInput, SystemProcessResult } from "./contracts.js";
+/** Bounded process observation; exit zero proves command completion, not effects. */
+export declare function runSystemProcess(input: SystemProcessInput): Promise<SystemProcessResult>;

package/dist/src/computer-access/process-runner.js

@@ -0,0 +1,103 @@
+import { spawn } from "node:child_process";
+const STREAM_MAX_CHARS = 16_000;
+/** Bounded process observation; exit zero proves command completion, not effects. */
+export function runSystemProcess(input) {
+    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 = "completed";
+        let spawnedProcess;
+        let timeout;
+        let stopGrace;
+        const finish = (exitCode) => {
+            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) => {
+            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) => {
+            const remaining = streamMaxChars - stdout.length;
+            truncated ||= chunk.length > remaining;
+            stdout += chunk.slice(0, remaining);
+        });
+        child.stderr.on("data", (chunk) => {
+            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/dist/src/computer-access/target-observation.d.ts

@@ -0,0 +1,18 @@
+import type { SystemProcessRunner, SystemTarget, SystemTargetId } from "./contracts.js";
+import { observeSystemHost } from "./host-observation.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 declare function observeSystemTargets(run?: SystemProcessRunner): Promise<SystemTargetObservation>;
+export {};