@abot-ai/runtime 1.0.0

package/plugins/exec/plugin.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "exec",
+  "version": "1.0.0",
+  "description": "Execute, observe, and cancel bounded non-interactive Linux /bin/bash processes.",
+  "extensions": {
+    "ai.abot.runtime": {
+      "version": 1,
+      "entrypoint": "./src/index.cjs",
+      "catalogGroups": ["exec"],
+      "settings": {
+        "defaults": {
+          "timeoutMs": 600000,
+          "yieldAfterMs": 15000,
+          "idleTimeoutMs": 120000,
+          "outputMaxChars": 8000
+        }
+      },
+      "capabilities": {
+        "exec": {
+          "catalogGroups": ["read", "write", "exec"],
+          "description": "Execute one bounded non-interactive Linux /bin/bash command. The explicit cwd must resolve inside agent work or the configured workspace; `.` means the agent-work root and `workspace/...` selects the workspace. The shell itself runs with the runtime process permissions and is not an operating-system sandbox. A command still running after the foreground window yields a process ID and cursor that exec_wait can resume without restarting it. Prefer dedicated inspection and file-mutation capabilities when they can express the task.",
+          "routingCapability": "filesystem_inspection",
+          "developmentRoles": ["inspect", "establish", "verify", "auxiliary"],
+          "eventPresentation": {
+            "metadata": {
+              "command": { "param": "command", "kind": "string" },
+              "cwd": { "param": "cwd", "kind": "string" }
+            }
+          },
+          "skills": ["exec_skill"],
+          "operations": {
+            "execute_command": {
+              "summary": "Execute one bounded non-interactive Linux /bin/bash command in an explicit existing agent-work or workspace directory. The cwd boundary is not an OS sandbox. Full-access availability does not authorize servers, GUI automation, installs, service changes, background work, or other sensitive effects.",
+              "input": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "command": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 4096
+                  },
+                  "cwd": { "type": "string", "minLength": 1, "maxLength": 4096 }
+                },
+                "required": ["command", "cwd"]
+              },
+              "effect": "mixed",
+              "approval": "request_policy"
+            }
+          }
+        },
+        "exec_wait": {
+          "catalogGroups": ["read", "exec"],
+          "description": "Continue observing the exact running shell process returned by exec. Use only the process ID and next cursor from the latest exec or exec_wait result. This does not start the command again.",
+          "routingCapability": "filesystem_inspection",
+          "developmentRoles": ["inspect", "verify", "auxiliary"],
+          "skills": ["exec_process_skill"],
+          "operations": {
+            "wait_for_process": {
+              "summary": "Wait for the next bounded observation from one running exec process without restarting it.",
+              "input": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "process_id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 128
+                  },
+                  "cursor": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 1000000
+                  }
+                },
+                "required": ["process_id", "cursor"]
+              },
+              "effect": "read_only",
+              "approval": "request_policy"
+            }
+          }
+        },
+        "exec_cancel": {
+          "catalogGroups": ["write", "exec"],
+          "description": "Cancel one running shell process previously returned by exec. Use only when the current task no longer needs that process or the user asks to stop it.",
+          "routingCapability": "filesystem_inspection",
+          "developmentRoles": ["auxiliary"],
+          "skills": ["exec_process_skill"],
+          "operations": {
+            "cancel_process": {
+              "summary": "Stop one active exec process and report its final state.",
+              "input": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "process_id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 128
+                  }
+                },
+                "required": ["process_id"]
+              },
+              "effect": "mixed",
+              "approval": "request_policy"
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,7 @@
+# Exec Process Skill
+
+- Use `exec_wait` only after `exec` reports that the command is still running.
+- Copy the latest `process_id` and `cursor` exactly and continue the same process without restarting its command.
+- Use `exec_cancel` only when the current task no longer needs the active process or the user asks to stop it.
+- Process IDs belong to one loaded plugin instance and session; never reuse one across runtimes or sessions.
+- Do not cancel a process whose result is still required, and do not retry a stale cursor unchanged.

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

@@ -0,0 +1,12 @@
+# Exec Skill
+
+- Use `exec` for narrow shell-native discovery or verification when a dedicated tool is insufficient.
+- `exec` v1 is available only on Linux with executable `/bin/bash`; it does not select a Windows shell or another fallback shell.
+- Resolve `.` and ordinary relative `cwd` values from the configured agent work directory. They are never rewritten to the active Worker working directory. Use `workspace/...` only when the configured workspace is explicitly intended.
+- Always provide an explicit existing `cwd`. For an existing project, use its project path. To create a new project, use an existing parent `cwd` (normally `.`) and create the project path in the command.
+- The cwd is restricted to configured roots, but the shell runs with the runtime process permissions and is not an operating-system sandbox.
+- Keep commands deterministic, non-interactive, and scoped to the selected configured root.
+- Availability under full-access mode is not user authorization for sensitive effects. Starting a listener or server, launching a browser or GUI automation, installing software, changing services, or creating long-running background work requires explicit authorization in the current user request.
+- For multi-line input, use a single-quoted here-document instead of fragile quoted one-line payloads.
+- Prefer an active file creation or editing capability over shell redirection when it can express the requested change.
+- If a process remains active, continue the same process with `exec_wait`; do not launch it again.

package/plugins/exec/source/errors.ts

@@ -0,0 +1,33 @@
+import {
+  failureFromError,
+  failureResult,
+  type ToolImplementationOutput,
+} from "../../../src/plugin-sdk/index.js";
+
+export class ExecPluginError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "ExecPluginError";
+    this.code = code;
+  }
+}
+
+export function execFailureFromError(
+  error: unknown,
+  operation: "exec" | "exec_wait" | "exec_cancel",
+): ToolImplementationOutput {
+  if (error instanceof ExecPluginError) {
+    return failureResult({
+      errorCode: error.code,
+      message: error.message,
+      output: `${operation} failed: ${error.message}`,
+    });
+  }
+  return failureFromError(error, {
+    fallbackCode: `${operation}_failed`,
+    fallbackMessage: `${operation} failed without a safe diagnostic.`,
+    operation,
+  });
+}

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

@@ -0,0 +1,362 @@
+import { createHash } from "node:crypto";
+import { constants, type Dirent, type Stats } from "node:fs";
+import { lstat, open, opendir, readlink } from "node:fs/promises";
+import { join, posix } from "node:path";
+
+import { sanitizeJsonText } from "../../../src/plugin-sdk/index.js";
+
+import type {
+  ExecActionSummary,
+  ExecFilesystemDelta,
+  ExecFilesystemEntry,
+  ExecFilesystemSnapshot,
+} from "./types.js";
+
+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,
+): Promise<Readonly<{ children: readonly Dirent[]; complete: boolean }>> {
+  let directory;
+  try {
+    directory = await opendir(absoluteDirectory);
+  } catch (error) {
+    if (isMissingPathError(error)) {
+      return Object.freeze({ children: Object.freeze([]), complete: true });
+    }
+    throw error;
+  }
+  const children: Dirent[] = [];
+  let complete = true;
+  try {
+    while (true) {
+      const child = await directory.read();
+      if (!child) break;
+      if (children.length >= maxItems) {
+        complete = false;
+        break;
+      }
+      children.push(child);
+    }
+  } finally {
+    await directory.close().catch((error: unknown) => {
+      if (
+        !(error instanceof Error) ||
+        !("code" in error) ||
+        error.code !== "ERR_DIR_CLOSED"
+      ) {
+        throw error;
+      }
+    });
+  }
+  children.sort((left, right) => left.name.localeCompare(right.name));
+  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,
+): Promise<ExecFilesystemSnapshot> {
+  const entries = new Map<string, ExecFilesystemEntry>();
+  let remainingHashBytes = SNAPSHOT_MAX_HASHED_BYTES;
+  let complete = true;
+  const rootInfo = await lstat(absoluteRoot).catch((error: unknown) => {
+    if (isMissingPathError(error)) return null;
+    throw error;
+  });
+  if (!rootInfo) {
+    return Object.freeze({
+      absoluteRoot,
+      logicalRoot,
+      rootExists: false,
+      complete: true,
+      entries,
+    });
+  }
+
+  const pendingDirectories = [""];
+  while (pendingDirectories.length > 0 && complete) {
+    const relativeDirectory = pendingDirectories.pop() ?? "";
+    const absoluteDirectory = relativeDirectory
+      ? join(absoluteRoot, relativeDirectory)
+      : absoluteRoot;
+    const directory = await readBoundedDirectory(
+      absoluteDirectory,
+      SNAPSHOT_MAX_ENTRIES - entries.size,
+    );
+    for (const child of directory.children) {
+      const relativePath = relativeDirectory
+        ? join(relativeDirectory, child.name)
+        : child.name;
+      const absolutePath = join(absoluteRoot, relativePath);
+      const info = await lstat(absolutePath).catch((error: unknown) => {
+        if (isMissingPathError(error)) return null;
+        throw error;
+      });
+      if (!info) continue;
+      if (info.isDirectory()) {
+        entries.set(
+          relativePath,
+          Object.freeze({
+            kind: "directory",
+            mode: info.mode,
+            size: info.size,
+            mtimeMs: info.mtimeMs,
+          }),
+        );
+        pendingDirectories.push(relativePath);
+        continue;
+      }
+      if (info.isSymbolicLink()) {
+        const linkTarget = await readlink(absolutePath).catch(() => undefined);
+        entries.set(
+          relativePath,
+          Object.freeze({
+            kind: "symlink",
+            mode: info.mode,
+            size: info.size,
+            mtimeMs: info.mtimeMs,
+            ...(linkTarget === undefined ? {} : { linkTarget }),
+          }),
+        );
+        continue;
+      }
+      if (info.isFile()) {
+        const inspected = await inspectRegularFile(
+          absolutePath,
+          remainingHashBytes,
+        );
+        if (!inspected) {
+          complete = false;
+          continue;
+        }
+        entries.set(relativePath, inspected.entry);
+        remainingHashBytes -= inspected.hashedBytes;
+        continue;
+      }
+      entries.set(
+        relativePath,
+        Object.freeze({
+          kind: "other",
+          mode: info.mode,
+          size: info.size,
+          mtimeMs: info.mtimeMs,
+        }),
+      );
+    }
+    if (!directory.complete) complete = false;
+  }
+  return Object.freeze({
+    absoluteRoot,
+    logicalRoot,
+    rootExists: true,
+    complete,
+    entries,
+  });
+}
+
+function entryChanged(
+  before: ExecFilesystemEntry,
+  after: ExecFilesystemEntry,
+): boolean {
+  if (before.kind !== after.kind || before.mode !== after.mode) return true;
+  if (before.kind === "directory") return false;
+  if (before.kind === "symlink") return before.linkTarget !== after.linkTarget;
+  if (
+    before.kind === "file" &&
+    before.contentHash !== undefined &&
+    after.contentHash !== undefined
+  ) {
+    return before.contentHash !== after.contentHash;
+  }
+  return before.size !== after.size || before.mtimeMs !== after.mtimeMs;
+}
+
+function logicalChild(root: string, relativePath: string): string {
+  const target = sanitizeJsonText(
+    root === "."
+      ? relativePath.replaceAll("\\", "/")
+      : posix.join(root, relativePath.replaceAll("\\", "/")),
+  );
+  const characters = [...target];
+  if (characters.length <= ACTION_TARGET_MAX_CHARS) return target;
+  const separator = "…";
+  const sideChars = Math.floor(
+    (ACTION_TARGET_MAX_CHARS - separator.length) / 2,
+  );
+  return `${characters.slice(0, sideChars).join("")}${separator}${characters.slice(-sideChars).join("")}`;
+}
+
+function actionForDelta(params: {
+  logicalRoot: string;
+  relativePath: string;
+  before?: ExecFilesystemEntry;
+  after?: ExecFilesystemEntry;
+}): ExecActionSummary {
+  const target = logicalChild(params.logicalRoot, params.relativePath);
+  if (!params.before && params.after?.kind === "directory") {
+    return { type: "mkdir", target, details: "exec_filesystem_created" };
+  }
+  if (!params.before && params.after?.kind === "file") {
+    return { type: "write_file", target, details: "exec_filesystem_created" };
+  }
+  return {
+    type: "refine_target",
+    target,
+    details: params.after
+      ? "exec_filesystem_modified"
+      : "exec_filesystem_removed",
+  };
+}
+
+export function diffExecFilesystemSnapshots(
+  before: ExecFilesystemSnapshot,
+  after: ExecFilesystemSnapshot,
+): ExecFilesystemDelta {
+  if (
+    before.absoluteRoot !== after.absoluteRoot ||
+    before.logicalRoot !== after.logicalRoot
+  ) {
+    throw new TypeError(
+      "Exec filesystem snapshots must share one observation root.",
+    );
+  }
+
+  let changes: Array<{
+    relativePath: string;
+    before?: ExecFilesystemEntry;
+    after?: ExecFilesystemEntry;
+  }>;
+  if (before.rootExists !== after.rootExists) {
+    changes = [{ relativePath: "" }];
+  } else if (!before.rootExists) {
+    changes = [];
+  } else {
+    const candidatePaths =
+      before.complete && after.complete
+        ? new Set([...before.entries.keys(), ...after.entries.keys()])
+        : new Set(
+            [...before.entries.keys()].filter((entry) =>
+              after.entries.has(entry),
+            ),
+          );
+    changes = [...candidatePaths]
+      .sort((left, right) => left.localeCompare(right))
+      .flatMap((relativePath) => {
+        const beforeEntry = before.entries.get(relativePath);
+        const afterEntry = after.entries.get(relativePath);
+        return beforeEntry === undefined ||
+          afterEntry === undefined ||
+          entryChanged(beforeEntry, afterEntry)
+          ? [
+              {
+                relativePath,
+                ...(beforeEntry === undefined ? {} : { before: beforeEntry }),
+                ...(afterEntry === undefined ? {} : { after: afterEntry }),
+              },
+            ]
+          : [];
+      });
+  }
+
+  const actions = changes.slice(0, DELTA_ACTION_LIMIT).map((entry) =>
+    entry.relativePath
+      ? actionForDelta({ logicalRoot: before.logicalRoot, ...entry })
+      : {
+          type: "refine_target",
+          target: logicalChild(".", before.logicalRoot),
+          details: after.rootExists
+            ? "exec_filesystem_created"
+            : "exec_filesystem_removed",
+        },
+  );
+  return Object.freeze({
+    observedStateChange: changes.length > 0,
+    changedEntryCount: changes.length,
+    actions: Object.freeze(actions),
+    observation: Object.freeze({
+      complete: before.complete && after.complete,
+      actionLimit: DELTA_ACTION_LIMIT,
+      actionsTruncated: changes.length > actions.length,
+    }),
+  });
+}