@abot-ai/runtime 1.6.0 → 1.8.0

package/plugins/exec/README.md

@@ -0,0 +1,19 @@
+# EXEC
+
+EXEC runs trusted, non-interactive commands on the Runtime host. Linux/macOS and WSL use `/bin/bash -lc`; native Windows uses the system Windows PowerShell with no profile or visible console window. Companion routing belongs to SYSTEM.
+
+The existing `exec`, `exec_wait`, and `exec_cancel` operations retain their exact-action approvals, request/session ownership, output cursors, retained output and time limits. Relative directories use the same agent-work root as filesystem; `workspace/...` uses the workspace, and absolute directories keep their explicit meaning. Commands run with the Runtime user's permissions; the directory is not a sandbox.
+
+## Windows process lifetime
+
+Before executing the supplied command, a PowerShell bootstrap compiles an internal C# adapter and attaches the shell to an unnamed Windows Job Object. The shell holds the sole, non-inheritable handle with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`; ordinary child processes inherit job membership. Cancellation, time limits and shell exit terminate the group. The adapter does not support escaping background services or elevate privileges.
+
+The command is sent over closed stdin, so multiline text and the full command limit do not depend on Windows command-line length. Output is UTF-8 and uses the existing retained-output path. Native program exit codes are preserved. PowerShell script execution policies are never changed or bypassed.
+
+If language policy, compilation or job setup blocks startup, the command never runs and the returned diagnostic tells the model not to retry or bypass the restriction. The user or administrator must restore helper availability. The adapter requires no separate installation.
+
+No live process is persisted or replayed during request restoration. The existing terminal-output snapshot remains the only saved execution state. A Job Object is process-local and ends with its owning shell.
+
+Output metadata is written to a synced temporary file and atomically renamed on every platform. Unix also syncs the parent directory; Node does not support that directory sync on Windows, so directory-entry durability across sudden power loss is not guaranteed there. Write, file-sync and rename errors remain failures.
+
+Filesystem change summaries on Windows use non-following file metadata (size and modification time). They do not read file contents for hashing, because Node has no Windows `O_NOFOLLOW`; a same-size edit that preserves the modification time can be unobserved. Command output and exit status are still reported. Linux/macOS retain bounded content hashing.

package/plugins/exec/plugin.json

@@ -2,8 +2,9 @@
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "exec",
   "version": "1.0.0",
-  "description": "Execute, observe, and cancel trusted non-interactive /bin/bash processes on Linux and macOS with per-action approval in Ask/Full.",
+  "description": "Execute, observe, and cancel trusted non-interactive shell processes: Bash on Linux/macOS, Windows PowerShell on native Windows with per-action approval in Ask/Full.",
   "extensions": {
+    "ai.abot.compatibility": { "version": 1, "runtimePlatforms": ["linux", "darwin", "win32"] },
     "ai.abot.runtime": {
       "version": 1,
       "entrypoint": "./src/index.cjs",
@@ -19,7 +20,7 @@
       "capabilities": {
         "exec": {
           "catalogGroups": ["read", "write", "exec"],
-          "description": "Execute one trusted non-interactive /bin/bash command on Linux or macOS. Use an explicit existing directory: `.` and relative paths start at the agent-work root, `workspace/...` selects the workspace, and absolute host paths are accepted. Commands run with the runtime OS user permissions without parsing their contents for path or sensitivity restrictions. Ask/Full require approval of the exact action; FULL+ executes without that prompt. A command still running after the foreground window yields a process ID and cursor that exec_wait can resume without restarting it.",
+          "description": "Execute one trusted non-interactive shell command: /bin/bash on Linux/macOS, Windows PowerShell on native Windows. Use an explicit existing directory: `.` and relative paths start at the agent-work root, `workspace/...` selects the workspace, and absolute host paths are accepted. Commands run with the runtime OS user permissions without parsing their contents for path or sensitivity restrictions. Ask/Full require approval of the exact action; FULL+ executes without that prompt. A command still running after the foreground window yields a process ID and cursor that exec_wait can resume without restarting it.",
           "routingCapability": "filesystem_inspection",
           "developmentRoles": ["inspect", "establish", "mutate", "verify", "auxiliary"],
           "eventPresentation": {
@@ -41,7 +42,8 @@
           "skills": ["exec_skill"],
           "operations": {
             "execute_command": {
-              "summary": "Execute one trusted non-interactive /bin/bash command in an explicit existing directory. This sensitive operation requires exact-action approval in Ask/Full and runs automatically in FULL+. The OS user permissions still apply; the selected folder is not a sandbox.",
+              "summary": "Execute one trusted non-interactive command in an explicit existing directory: Bash on Linux/macOS, Windows PowerShell on native Windows. This sensitive operation requires exact-action approval in Ask/Full and runs automatically in FULL+. The OS user permissions still apply; the selected folder is not a sandbox.",
+              "outputChannels": {"text": "metadata", "data": "metadata"},
               "input": {
                 "type": "object",
                 "additionalProperties": false,
@@ -75,6 +77,7 @@
           "operations": {
             "wait_for_process": {
               "summary": "Wait for the next bounded observation from one running exec process without restarting it.",
+              "outputChannels": {"text": "metadata", "data": "metadata"},
               "input": {
                 "type": "object",
                 "additionalProperties": false,
@@ -111,6 +114,7 @@
           "operations": {
             "cancel_process": {
               "summary": "Stop one active exec process and report its final state.",
+              "outputChannels": {"text": "metadata", "data": "metadata"},
               "input": {
                 "type": "object",
                 "additionalProperties": false,

package/plugins/exec/skills/exec_skill/SKILL.md

@@ -1,11 +1,12 @@
 # Exec Skill
 
 - Use `exec` for shell work needed by the user's task. Prefer dedicated capabilities when they express that work directly.
-- `exec` uses non-interactive `/bin/bash` on Linux and macOS; it does not select a Windows shell. Use commands available on that target OS.
+- `exec` uses non-interactive `/bin/bash` on Linux/macOS (including WSL) and Windows PowerShell on native Windows. Use the syntax of that shell. It executes on the Runtime host; it does not target a paired computer.
 - Supply an explicit existing `cwd`. `.` and relative paths start from the configured agent-work directory, not an implicit Worker directory. `workspace/...` selects the configured workspace; absolute host directories are accepted.
 - To create a project, select an existing parent `cwd` and create its directory in the command. A selected project provides working context, not a filesystem sandbox.
 - The whole exec family is sensitive: Ask and Full request approval of each exact action through the normal tool flow; FULL+ executes without an additional ABot prompt. Submit the needed operation instead of declaring it unavailable solely because of the selected mode.
 - Commands run as the runtime OS user. The plugin does not parse command contents to infer sensitivity or restrict referenced paths. OS permissions still apply; FULL+ does not grant root or Administrator rights.
 - Execution has no interactive terminal and retains time, output and process limits. Use non-interactive forms; a terminal prompt cannot be answered through this tool.
-- For multi-line input, use a single-quoted here-document when it preserves the intended shell input.
+- For multi-line input, use the selected shell's syntax: a Bash here-document or a PowerShell here-string. Windows script execution policy remains in force; do not bypass it.
 - If a process remains active, continue that exact process with `exec_wait`; do not launch the command again.
+- Native Windows commands and their ordinary child processes share a Job Object. Cancelling, timing out, or exiting the shell ends that group; detached background services are not a persistent execution mode. If Windows blocks helper setup, no command runs: report the restriction to the user without retrying or bypassing it.

package/plugins/exec/source/filesystem-file-observer.ts

@@ -0,0 +1,98 @@
+import { createHash } from "node:crypto";
+import { constants, type Stats } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import type { ExecFilesystemEntry } from "./types.js";
+
+const SNAPSHOT_MAX_HASHED_FILE_BYTES = 2 * 1024 * 1024;
+
+export function isMissingPathError(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    "code" in error &&
+    (error.code === "ENOENT" || error.code === "ENOTDIR")
+  );
+}
+
+function hashBuffer(content: Buffer): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+export async function inspectExecRegularFile(
+  absolutePath: string,
+  remainingHashBytes: number,
+): Promise<
+  | Readonly<{
+      entry: ExecFilesystemEntry;
+      hashedBytes: number;
+    }>
+  | undefined
+> {
+  if (process.platform === "win32") {
+    // Windows has no O_NOFOLLOW. Observe metadata without opening content or
+    // following a reparse point; size/mtime deltas already support unhashed files.
+    const info = await lstat(absolutePath).catch((error: unknown) => {
+      if (isMissingPathError(error)) return null;
+      throw error;
+    });
+    if (!info?.isFile()) return undefined;
+    return Object.freeze({
+      entry: Object.freeze({
+        kind: "file" as const,
+        mode: info.mode,
+        size: info.size,
+        mtimeMs: info.mtimeMs,
+      }),
+      hashedBytes: 0,
+    });
+  }
+  const noFollow = constants.O_NOFOLLOW;
+  if (!Number.isInteger(noFollow)) return undefined;
+  let file;
+  try {
+    file = await open(absolutePath, constants.O_RDONLY | noFollow);
+  } catch (error) {
+    if (
+      isMissingPathError(error) ||
+      (error instanceof Error && "code" in error && error.code === "ELOOP")
+    ) {
+      return undefined;
+    }
+    throw error;
+  }
+  try {
+    const info: Stats = await file.stat();
+    if (!info.isFile()) return undefined;
+    let contentHash: string | undefined;
+    let hashedBytes = 0;
+    if (
+      info.size <= SNAPSHOT_MAX_HASHED_FILE_BYTES &&
+      info.size <= remainingHashBytes
+    ) {
+      const length = Math.max(0, Math.floor(info.size));
+      const content = Buffer.alloc(length);
+      while (hashedBytes < length) {
+        const { bytesRead } = await file.read(
+          content,
+          hashedBytes,
+          length - hashedBytes,
+          hashedBytes,
+        );
+        if (bytesRead === 0) break;
+        hashedBytes += bytesRead;
+      }
+      contentHash = hashBuffer(content.subarray(0, hashedBytes));
+    }
+    return Object.freeze({
+      entry: Object.freeze({
+        kind: "file",
+        mode: info.mode,
+        size: info.size,
+        mtimeMs: info.mtimeMs,
+        ...(contentHash === undefined ? {} : { contentHash }),
+      }),
+      hashedBytes,
+    });
+  } finally {
+    await file.close();
+  }
+}

package/plugins/exec/source/filesystem-observer.ts

@@ -1,10 +1,14 @@
-import { createHash } from "node:crypto";
-import { constants, type Dirent, type Stats } from "node:fs";
-import { lstat, open, opendir, readlink } from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import { lstat, opendir, readlink } from "node:fs/promises";
 import { join, posix } from "node:path";
 
 import { sanitizeJsonText } from "../../../src/plugin-sdk/index.js";
 
+import {
+  inspectExecRegularFile,
+  isMissingPathError,
+} from "./filesystem-file-observer.js";
+
 import type {
   ExecActionSummary,
   ExecFilesystemDelta,
@@ -14,22 +18,9 @@ import type {
 
 const SNAPSHOT_MAX_ENTRIES = 4_096;
 const SNAPSHOT_MAX_HASHED_BYTES = 16 * 1024 * 1024;
-const SNAPSHOT_MAX_HASHED_FILE_BYTES = 2 * 1024 * 1024;
 const DELTA_ACTION_LIMIT = 64;
 const ACTION_TARGET_MAX_CHARS = 96;
 
-function isMissingPathError(error: unknown): boolean {
-  return (
-    error instanceof Error &&
-    "code" in error &&
-    (error.code === "ENOENT" || error.code === "ENOTDIR")
-  );
-}
-
-function hashBuffer(content: Buffer): string {
-  return createHash("sha256").update(content).digest("hex");
-}
-
 async function readBoundedDirectory(
   absoluteDirectory: string,
   maxItems: number,
@@ -70,68 +61,6 @@ async function readBoundedDirectory(
   return Object.freeze({ children: Object.freeze(children), complete });
 }
 
-async function inspectRegularFile(
-  absolutePath: string,
-  remainingHashBytes: number,
-): Promise<
-  | Readonly<{
-      entry: ExecFilesystemEntry;
-      hashedBytes: number;
-    }>
-  | undefined
-> {
-  const noFollow = constants.O_NOFOLLOW;
-  if (!Number.isInteger(noFollow)) return undefined;
-  let file;
-  try {
-    file = await open(absolutePath, constants.O_RDONLY | noFollow);
-  } catch (error) {
-    if (
-      isMissingPathError(error) ||
-      (error instanceof Error && "code" in error && error.code === "ELOOP")
-    ) {
-      return undefined;
-    }
-    throw error;
-  }
-  try {
-    const info: Stats = await file.stat();
-    if (!info.isFile()) return undefined;
-    let contentHash: string | undefined;
-    let hashedBytes = 0;
-    if (
-      info.size <= SNAPSHOT_MAX_HASHED_FILE_BYTES &&
-      info.size <= remainingHashBytes
-    ) {
-      const length = Math.max(0, Math.floor(info.size));
-      const content = Buffer.alloc(length);
-      while (hashedBytes < length) {
-        const { bytesRead } = await file.read(
-          content,
-          hashedBytes,
-          length - hashedBytes,
-          hashedBytes,
-        );
-        if (bytesRead === 0) break;
-        hashedBytes += bytesRead;
-      }
-      contentHash = hashBuffer(content.subarray(0, hashedBytes));
-    }
-    return Object.freeze({
-      entry: Object.freeze({
-        kind: "file",
-        mode: info.mode,
-        size: info.size,
-        mtimeMs: info.mtimeMs,
-        ...(contentHash === undefined ? {} : { contentHash }),
-      }),
-      hashedBytes,
-    });
-  } finally {
-    await file.close();
-  }
-}
-
 export async function captureExecFilesystemSnapshot(
   absoluteRoot: string,
   logicalRoot: string,
@@ -201,7 +130,7 @@ export async function captureExecFilesystemSnapshot(
         continue;
       }
       if (info.isFile()) {
-        const inspected = await inspectRegularFile(
+        const inspected = await inspectExecRegularFile(
           absolutePath,
           remainingHashBytes,
         );

package/plugins/exec/source/output-files.ts

@@ -51,17 +51,23 @@ export async function writeOutputMetadata(
       await file.close();
     }
     await rename(temporary, path);
-    const directory = await open(dirname(path), "r");
-    try {
-      await directory.sync();
-    } finally {
-      await directory.close();
-    }
+    await syncOutputDirectoryEntry(path);
   } catch (error) {
     await rm(temporary, { force: true }).catch(() => undefined);
     throw outputFailure("metadata_write_failed", error);
   }
 }
+// Node cannot fsync a directory handle on Windows. The file is still synced
+// before atomic rename; Unix also flushes the parent directory entry.
+async function syncOutputDirectoryEntry(path: string): Promise<void> {
+  if (process.platform === "win32") return;
+  const directory = await open(dirname(path), "r");
+  try {
+    await directory.sync();
+  } finally {
+    await directory.close();
+  }
+}
 export async function prepareOutputOwnerDirectory(
   directory: string,
 ): Promise<void> {

package/plugins/exec/source/paths.ts

@@ -54,11 +54,13 @@ export async function resolveExecWorkingDirectory(
   executionContext: ToolExecutionContext | undefined,
   rawPath: unknown,
 ): Promise<ExecWorkingDirectory> {
-  const requestedPath = readRequiredString(rawPath, {
+  const inputPath = readRequiredString(rawPath, {
     name: "cwd",
     trim: false,
     maxLength: 4_096,
   });
+  const requestedPath =
+    process.platform === "win32" ? inputPath.replaceAll("\\", "/") : inputPath;
   if (requestedPath.includes("\0")) {
     throw new ExecPluginError(
       "exec_cwd_invalid",

package/plugins/exec/source/process-manager.ts

@@ -1,6 +1,4 @@
-import { spawn, type ChildProcessByStdio } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import type { Readable } from "node:stream";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { ExecTerminalDelivery } from "./terminal-delivery.js";
@@ -13,13 +11,16 @@ import {
 } from "./output-snapshot.js";
 
 import { ExecPluginError } from "./errors.js";
-import { assertSupportedShell, EXEC_SHELL } from "./shell-platform.js";
+import { assertSupportedShell } from "./shell-platform.js";
+import {
+  spawnExecShell,
+  killExecProcessTree,
+  type ExecChild,
+} from "./shell-process.js";
 import type { ExecProcessSnapshot, ExecTerminationReason } from "./types.js";
 
 const MAX_ACTIVE_PROCESSES_PER_SCOPE = 4;
 
-type ExecChild = ChildProcessByStdio<null, Readable, Readable>;
-
 type ManagedExecProcess = {
   processId: string;
   scope: string;
@@ -108,26 +109,13 @@ export function createExecProcessManager(
       (managed) => managed.scope === scope && !managed.settled,
     ).length + (opening.get(scope) ?? 0);
 
-  const killProcessTree = (managed: ManagedExecProcess): void => {
-    const pid = managed.child.pid;
-    if (typeof pid === "number") {
-      try {
-        process.kill(-pid, "SIGKILL");
-        return;
-      } catch {
-        // Fall through to the direct child as a best-effort fallback.
-      }
-    }
-    managed.child.kill("SIGKILL");
-  };
-
   const requestTermination = (
     managed: ManagedExecProcess,
     reason: ExecTerminationReason,
   ): void => {
     if (managed.settled || managed.terminationReason) return;
     managed.terminationReason = reason;
-    killProcessTree(managed);
+    killExecProcessTree(managed.child);
     if (reason === "output_storage_failed") {
       // A failed sink cannot drain the pipes; close them so child close settles.
       managed.child.stdout.destroy();
@@ -298,11 +286,7 @@ export function createExecProcessManager(
       });
       let child: ExecChild;
       try {
-        child = spawn(EXEC_SHELL, ["-lc", params.shellCommand], {
-          cwd: params.cwd,
-          detached: true,
-          stdio: ["ignore", "pipe", "pipe"],
-        });
+        child = spawnExecShell(params.shellCommand, params.cwd);
       } catch {
         await output.dispose();
         throw new ExecPluginError(

package/plugins/exec/source/shell-platform.ts

@@ -1,11 +1,27 @@
 import { constants } from "node:fs";
 import { access } from "node:fs/promises";
+import { win32 } from "node:path";
 
 import { ExecPluginError } from "./errors.js";
 
 export const EXEC_SHELL = "/bin/bash";
 
+export function execShell(
+  platform: NodeJS.Platform = process.platform,
+): string {
+  if (platform === "win32")
+    return win32.join(
+      process.env.SystemRoot ?? "C:\\Windows",
+      "System32",
+      "WindowsPowerShell",
+      "v1.0",
+      "powershell.exe",
+    );
+  return EXEC_SHELL;
+}
+
 function isSupportedExecPlatform(platform: NodeJS.Platform): boolean {
+  if (platform === "win32") return true;
   return platform === "linux" || platform === "darwin";
 }
 
@@ -15,15 +31,15 @@ export async function assertSupportedShell(
   if (!isSupportedExecPlatform(platform)) {
     throw new ExecPluginError(
       "exec_platform_unsupported",
-      "The exec plugin requires Linux or macOS and executable /bin/bash.",
+      "The exec plugin requires Linux/macOS with Bash or native Windows with Windows PowerShell.",
     );
   }
   try {
-    await access(EXEC_SHELL, constants.X_OK);
+    await access(execShell(platform), constants.X_OK);
   } catch {
     throw new ExecPluginError(
       "exec_shell_unavailable",
-      "The exec plugin cannot start because executable /bin/bash is unavailable.",
+      `The exec shell is unavailable: ${execShell(platform)}. No command ran. Do not retry until the user restores shell availability.`,
     );
   }
 }

package/plugins/exec/source/shell-process.ts

@@ -0,0 +1,55 @@
+import { spawn, type ChildProcessByStdio } from "node:child_process";
+import type { Readable, Writable } from "node:stream";
+import { execShell } from "./shell-platform.js";
+import { WINDOWS_EXEC_BOOTSTRAP } from "./windows-shell-bootstrap.js";
+import { WINDOWS_EXEC_JOB_SOURCE } from "./windows-job-source.js";
+
+export type ExecChild = ChildProcessByStdio<
+  Writable | null,
+  Readable,
+  Readable
+>;
+
+export function spawnExecShell(command: string, cwd: string): ExecChild {
+  if (process.platform !== "win32")
+    return spawn(execShell(), ["-lc", command], {
+      cwd,
+      detached: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+  const child = spawn(
+    execShell(),
+    [
+      "-NoLogo",
+      "-NoProfile",
+      "-NonInteractive",
+      "-EncodedCommand",
+      Buffer.from(WINDOWS_EXEC_BOOTSTRAP, "utf16le").toString("base64"),
+    ],
+    { cwd, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] },
+  );
+  // Startup denial may close stdin early. The existing error/close path reports it.
+  child.stdin.on("error", () => {});
+  child.stdin.end(
+    JSON.stringify({ source: WINDOWS_EXEC_JOB_SOURCE, command }),
+    "utf8",
+  );
+  return child;
+}
+
+export function killExecProcessTree(child: ExecChild): void {
+  if (process.platform === "win32") {
+    // The Job Object closes with its owning shell and terminates its descendants.
+    child.kill("SIGKILL");
+    return;
+  }
+  if (typeof child.pid === "number") {
+    try {
+      process.kill(-child.pid, "SIGKILL");
+      return;
+    } catch {
+      // Preserve the existing Unix best-effort direct-child fallback.
+    }
+  }
+  child.kill("SIGKILL");
+}

package/plugins/exec/source/windows-job-source.ts

@@ -0,0 +1 @@
+export { WINDOWS_EXEC_JOB_SOURCE } from "../../../src/shared/windows-job-object.js";

package/plugins/exec/source/windows-shell-bootstrap.ts

@@ -0,0 +1,20 @@
+/** No execution-policy override: setup must succeed before any supplied command runs. */
+export const WINDOWS_EXEC_BOOTSTRAP = [
+  "$ErrorActionPreference='Stop'",
+  "$ProgressPreference='SilentlyContinue'",
+  "if ($ExecutionContext.SessionState.LanguageMode -ne 'FullLanguage') { Write-Error 'Windows policy blocks the EXEC helper. No command ran. Do not retry or bypass this restriction; ask the user to contact their administrator.' -ErrorAction Continue; exit 126 }",
+  "$abotExecOriginalPSModulePath=$env:PSModulePath",
+  "try {",
+  "$env:PSModulePath=[IO.Path]::Combine($PSHOME,'Modules')",
+  "[Console]::InputEncoding=[Text.UTF8Encoding]::new($false)",
+  "[Console]::OutputEncoding=[Text.UTF8Encoding]::new($false)",
+  "$OutputEncoding=[Text.UTF8Encoding]::new($false)",
+  "$abotExecEnvelope=[Console]::In.ReadToEnd() | ConvertFrom-Json",
+  "Add-Type -TypeDefinition $abotExecEnvelope.source",
+  "[AbotExecJob]::Attach()",
+  "} catch { [Console]::Error.WriteLine('The Windows EXEC helper is unavailable or blocked. No command ran. Do not retry or bypass the restriction; the user must resolve helper availability first.'); exit 126 }",
+  "$env:PSModulePath=$abotExecOriginalPSModulePath",
+  "$global:LASTEXITCODE=0",
+  ". ([ScriptBlock]::Create($abotExecEnvelope.command))",
+  "if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }",
+].join(";\n");