@abot-ai/runtime 1.3.1 → 1.5.0

package/plugins/exec/source/handlers.ts

@@ -1,36 +1,23 @@
+import { runningResult, finalizeExecResult } from "./result-presentation.js";
+import { ExecRequestResources } from "./request-resources.js";
 import {
   boundText,
-  enforcePluginResultByteBudget,
-  failureResult,
   readBoundedInteger,
   readRequiredString,
   type RuntimePluginLoadContext,
+  type ToolRequestPreparationContext,
   type ToolExecutionContext,
   type ToolImplementation,
   type ToolImplementationOutput,
 } from "../../../src/plugin-sdk/index.js";
 
 import { execFailureFromError, ExecPluginError } from "./errors.js";
-import {
-  captureExecFilesystemSnapshot,
-  diffExecFilesystemSnapshots,
-} from "./filesystem-observer.js";
-import { resolveExecScopedPath, resolveExecWorkingDirectory } from "./paths.js";
+import { captureExecFilesystemSnapshot } from "./filesystem-observer.js";
+import { resolveExecWorkingDirectory } from "./paths.js";
 import { createExecProcessManager } from "./process-manager.js";
-import { EXEC_COMMAND_MAX_CHARS, type ExecSettings } from "./settings.js";
-import type {
-  ExecActionSummary,
-  ExecFilesystemDelta,
-  ExecProcessSnapshot,
-  ExecStreamSnapshot,
-  PendingExecExecution,
-} from "./types.js";
-import {
-  isInteractiveCommand,
-  sanitizeExecCommand,
-  scopedPathTokens,
-  stripHereDocBodies,
-} from "./validation.js";
+import type { ExecSettings } from "./settings.js";
+import type { ExecProcessSnapshot, PendingExecExecution } from "./types.js";
+import { readExecCommand } from "./validation.js";
 
 const COMMAND_PREVIEW_MAX_CHARS = 768;
 
@@ -39,270 +26,6 @@ function processScope(context: ToolExecutionContext | undefined): string {
   return sessionId || "anonymous";
 }
 
-function streamDisplay(snapshot: ExecStreamSnapshot): string {
-  if (snapshot.text) return snapshot.text;
-  return snapshot.sawOutput
-    ? "(no new output; earlier output was already returned)"
-    : "(empty)";
-}
-
-function renderedOutput(
-  lines: readonly string[],
-  outputMaxChars: number,
-): Readonly<{
-  output: string;
-  metadata: ReturnType<typeof boundText>["metadata"];
-}> {
-  const bounded = boundText(lines.join("\n"), {
-    maxChars: outputMaxChars,
-    marker: "\n[exec output truncated]",
-  });
-  return Object.freeze({ output: bounded.text, metadata: bounded.metadata });
-}
-
-function outputBoundsData(
-  snapshot: ExecProcessSnapshot,
-  rendered: ReturnType<typeof renderedOutput>["metadata"],
-  maxChars: number,
-) {
-  return Object.freeze({
-    maxChars,
-    stdout: snapshot.stdout.metadata,
-    stderr: snapshot.stderr.metadata,
-    rendered,
-  });
-}
-
-function runningResult(
-  snapshot: ExecProcessSnapshot,
-  execution: PendingExecExecution,
-): ToolImplementationOutput {
-  const nextCursor = snapshot.nextCursor ?? 1;
-  const rendered = renderedOutput(
-    [
-      `Command: ${execution.commandPreview}`,
-      ...(execution.commandWasNormalized
-        ? ["Command normalization: invalid control characters were removed."]
-        : []),
-      `CWD: ${execution.cwd.logicalPath}`,
-      "Process status: running",
-      `Process ID: ${snapshot.processId}`,
-      `Next cursor: ${nextCursor}`,
-      "STDOUT since the previous observation:",
-      streamDisplay(snapshot.stdout),
-      "STDERR since the previous observation:",
-      streamDisplay(snapshot.stderr),
-      "Continue this exact process with exec_wait; do not run the command again.",
-    ],
-    execution.outputMaxChars,
-  );
-  return failureResult({
-    errorCode: "exec_process_running",
-    message:
-      "The command is still running. Continue it with exec_wait using the returned process ID and cursor.",
-    output: rendered.output,
-    stdout: snapshot.stdout.text,
-    stderr: snapshot.stderr.text,
-    data: {
-      processId: snapshot.processId,
-      processStatus: "running",
-      nextCursor,
-      outputBounds: outputBoundsData(
-        snapshot,
-        rendered.metadata,
-        execution.outputMaxChars,
-      ),
-      observationMeta: {
-        kind: "volatile_external",
-        carryPolicy: "never",
-      },
-    },
-  });
-}
-
-async function captureFilesystemDelta(
-  execution: PendingExecExecution,
-): Promise<ExecFilesystemDelta | null> {
-  if (!execution.filesystemStateBefore) return null;
-  try {
-    const after = await captureExecFilesystemSnapshot(
-      execution.cwd.absolutePath,
-      execution.cwd.logicalPath,
-    );
-    return diffExecFilesystemSnapshots(execution.filesystemStateBefore, after);
-  } catch {
-    return null;
-  }
-}
-
-type ExecFilesystemEvidenceProjection = Readonly<{
-  outputLines: readonly string[];
-  mutationGrounding: string;
-}>;
-
-function projectExecFilesystemEvidence(
-  delta: ExecFilesystemDelta,
-  logicalRoot: string,
-): ExecFilesystemEvidenceProjection {
-  const effects = delta.actions.map(renderExecFilesystemEffect);
-  const omittedEffectCount = Math.max(
-    0,
-    delta.changedEntryCount - effects.length,
-  );
-  const omittedEffectLine =
-    omittedEffectCount > 0
-      ? `- ${omittedEffectCount} additional changed ${omittedEffectCount === 1 ? "entry" : "entries"} omitted by the ${delta.observation.actionLimit}-effect projection limit.`
-      : undefined;
-  const outputLines = Object.freeze([
-    `Filesystem changes observed: ${delta.changedEntryCount}${delta.observation.complete ? "" : " (bounded observation)"}`,
-    "Filesystem effects observed:",
-    ...effects,
-    ...(omittedEffectLine ? [omittedEffectLine] : []),
-  ]);
-  return Object.freeze({
-    outputLines,
-    mutationGrounding: [
-      "Observed post-command filesystem effects (settled tool evidence; not command intent, semantic verification, or complete artifact content):",
-      `- observation root: ${logicalRoot}`,
-      `- observation complete: ${delta.observation.complete}`,
-      `- changed entries: ${delta.changedEntryCount}`,
-      `- listed effects: ${effects.length}`,
-      `- effects truncated: ${delta.observation.actionsTruncated}`,
-      "Effects:",
-      ...effects,
-      ...(omittedEffectLine ? [omittedEffectLine] : []),
-    ].join("\n"),
-  });
-}
-
-function renderExecFilesystemEffect(action: ExecActionSummary): string {
-  const target = action.target ? `: ${action.target}` : "";
-  const state =
-    action.details === "exec_filesystem_created"
-      ? "created"
-      : action.details === "exec_filesystem_modified"
-        ? "modified"
-        : action.details === "exec_filesystem_removed"
-          ? "removed"
-          : undefined;
-  return `- ${action.type}${target}${state ? ` (${state})` : ""}`;
-}
-
-async function finalizeExecResult(params: {
-  snapshot: ExecProcessSnapshot;
-  execution: PendingExecExecution;
-  cancellationIsSuccess?: boolean;
-}): Promise<ToolImplementationOutput> {
-  const { snapshot, execution } = params;
-  const exitCode = snapshot.exitCode ?? -1;
-  const cancellationIsSuccess =
-    params.cancellationIsSuccess === true &&
-    snapshot.terminationReason === "cancelled";
-  const filesystemDelta = await captureFilesystemDelta(execution);
-  const observedStateChange = filesystemDelta?.observedStateChange === true;
-  const filesystemEvidence =
-    observedStateChange && filesystemDelta
-      ? projectExecFilesystemEvidence(
-          filesystemDelta,
-          execution.cwd.logicalPath,
-        )
-      : null;
-  const commandHasData = snapshot.stdout.sawOutput || snapshot.stderr.sawOutput;
-  const ok = exitCode === 0 || cancellationIsSuccess;
-  const inconclusiveSuccess =
-    exitCode === 0 && !commandHasData && !observedStateChange;
-  const producedNewInformation =
-    observedStateChange || cancellationIsSuccess || (ok && commandHasData);
-  const actions = filesystemDelta?.actions ?? [];
-  const resultSummary = cancellationIsSuccess
-    ? "Result summary: the running command was cancelled."
-    : inconclusiveSuccess
-      ? "Result summary: the command completed without observable output or filesystem change. Inspect a concrete target or use a dedicated creation capability."
-      : "";
-  const rendered = renderedOutput(
-    [
-      `Command: ${execution.commandPreview}`,
-      ...(execution.commandWasNormalized
-        ? ["Command normalization: invalid control characters were removed."]
-        : []),
-      `CWD: ${execution.cwd.logicalPath}`,
-      `Process ID: ${snapshot.processId}`,
-      `Process status: ${snapshot.terminationReason ?? "completed"}`,
-      `Exit code: ${exitCode}`,
-      ...(filesystemEvidence ? filesystemEvidence.outputLines : []),
-      "STDOUT:",
-      streamDisplay(snapshot.stdout),
-      "STDERR:",
-      streamDisplay(snapshot.stderr),
-      ...(resultSummary ? [resultSummary] : []),
-    ],
-    execution.outputMaxChars,
-  );
-  const processStatus = snapshot.terminationReason ?? "completed";
-  const data = {
-    ...(commandHasData ? { hasData: true } : {}),
-    ...(observedStateChange ? { mutationEvidence: true } : {}),
-    ...(filesystemEvidence
-      ? { mutationGrounding: filesystemEvidence.mutationGrounding }
-      : {}),
-    processId: snapshot.processId,
-    processStatus,
-    outputBounds: outputBoundsData(
-      snapshot,
-      rendered.metadata,
-      execution.outputMaxChars,
-    ),
-    ...(filesystemDelta
-      ? { filesystemObservation: filesystemDelta.observation }
-      : { filesystemObservation: { available: false } }),
-    observationMeta: {
-      kind: "volatile_external" as const,
-      carryPolicy: "never" as const,
-    },
-  };
-  const common = {
-    output: rendered.output,
-    progress: observedStateChange || cancellationIsSuccess,
-    producedNewInformation,
-    actions: [...actions],
-    exitCode,
-    stdout: snapshot.stdout.text,
-    stderr: snapshot.stderr.text,
-    data,
-  };
-  if (ok && (!inconclusiveSuccess || cancellationIsSuccess)) {
-    return enforcePluginResultByteBudget({ ok: true, ...common });
-  }
-  const errorCode = inconclusiveSuccess
-    ? "no_observable_result"
-    : snapshot.terminationReason === "aborted"
-      ? "exec_aborted"
-      : snapshot.terminationReason === "spawn_failed"
-        ? "exec_spawn_failed"
-        : snapshot.terminationReason === "idle_timeout"
-          ? "exec_idle_timeout"
-          : snapshot.terminationReason === "hard_timeout"
-            ? "exec_hard_timeout"
-            : "non_zero_exit";
-  const error = inconclusiveSuccess
-    ? resultSummary
-    : errorCode === "exec_aborted"
-      ? "The exec request was aborted."
-      : errorCode === "exec_spawn_failed"
-        ? "The runtime could not start the configured non-interactive shell."
-        : errorCode === "exec_idle_timeout"
-          ? `The command produced no output for ${execution.idleTimeoutMs}ms.`
-          : errorCode === "exec_hard_timeout"
-            ? `The command exceeded the ${execution.hardTimeoutMs}ms hard timeout.`
-            : `The command exited with code ${exitCode}.`;
-  return enforcePluginResultByteBudget({
-    ok: false,
-    ...common,
-    error,
-    errorCode,
-  });
-}
-
 type ExecHandlers = Readonly<{
   exec: ToolImplementation;
   exec_wait: ToolImplementation;
@@ -312,9 +35,15 @@ type ExecHandlers = Readonly<{
 export function createExecHandlers(
   pluginContext: RuntimePluginLoadContext,
   settings: ExecSettings,
+  preparation?: ToolRequestPreparationContext,
 ): ExecHandlers {
   const processManager = createExecProcessManager();
   const pendingExecutions = new Map<string, PendingExecExecution>();
+  const requestResources = new ExecRequestResources(
+    processManager,
+    pendingExecutions,
+    preparation,
+  );
 
   const finalizeAndRelease = async (params: {
     snapshot: ExecProcessSnapshot;
@@ -326,40 +55,19 @@ export function createExecHandlers(
       return await finalizeExecResult(params);
     } finally {
       pendingExecutions.delete(params.snapshot.processId);
+      requestResources.forget(params.snapshot.processId);
       await processManager.release(params.snapshot.processId, params.scope);
     }
   };
 
   const exec: ToolImplementation = async (params, context) => {
     try {
-      const rawCommand = readRequiredString(params.command, {
-        name: "command",
-        trim: false,
-        maxLength: EXEC_COMMAND_MAX_CHARS,
-      });
-      const { command, normalized } = sanitizeExecCommand(rawCommand);
-      if (!command) {
-        throw new ExecPluginError(
-          "exec_command_invalid",
-          "The command is empty after invalid control characters are removed.",
-        );
-      }
-      const interactive = isInteractiveCommand(command);
-      if (interactive) {
-        throw new ExecPluginError(
-          "exec_interactive_command_blocked",
-          `Interactive command ${interactive} is not supported by the non-interactive exec plugin.`,
-        );
-      }
+      const command = readExecCommand(params.command);
       const cwd = await resolveExecWorkingDirectory(
         pluginContext,
         context,
         params.cwd,
       );
-      const staticCommand = stripHereDocBodies(command);
-      for (const token of scopedPathTokens(staticCommand)) {
-        resolveExecScopedPath(pluginContext, context, token, cwd);
-      }
       const filesystemStateBefore = await captureExecFilesystemSnapshot(
         cwd.absolutePath,
         cwd.logicalPath,
@@ -370,7 +78,6 @@ export function createExecHandlers(
       }).text;
       const execution: PendingExecExecution = Object.freeze({
         commandPreview,
-        commandWasNormalized: normalized,
         cwd,
         filesystemStateBefore,
         hardTimeoutMs: settings.hardTimeoutMs,
@@ -387,7 +94,12 @@ export function createExecHandlers(
         idleTimeoutMs: execution.idleTimeoutMs,
         hardTimeoutMs: execution.hardTimeoutMs,
         ...(context?.abortSignal ? { abortSignal: context.abortSignal } : {}),
-        onDisposed: (processId) => pendingExecutions.delete(processId),
+        onDisposed: (processId) => {
+          pendingExecutions.delete(processId);
+          requestResources.forget(processId);
+        },
+        onStarted: (processId, settled) =>
+          requestResources.started(processId, scope, settled, context),
       });
       if (snapshot.status === "running") {
         pendingExecutions.set(snapshot.processId, execution);
@@ -418,12 +130,14 @@ export function createExecHandlers(
         );
       }
       const scope = processScope(context);
-      const snapshot = await processManager.wait({
-        processId,
-        scope,
-        cursor,
-        waitMs: settings.yieldAfterMs,
-      });
+      const snapshot =
+        requestResources.terminal(processId, scope, cursor) ??
+        (await processManager.wait({
+          processId,
+          scope,
+          cursor,
+          waitMs: settings.yieldAfterMs,
+        }));
       return snapshot.status === "running"
         ? runningResult(snapshot, execution)
         : finalizeAndRelease({ snapshot, execution, scope });
@@ -446,7 +160,9 @@ export function createExecHandlers(
         );
       }
       const scope = processScope(context);
-      const snapshot = await processManager.cancel({ processId, scope });
+      const snapshot =
+        requestResources.terminal(processId, scope) ??
+        (await processManager.cancel({ processId, scope }));
       return finalizeAndRelease({
         snapshot,
         execution,

package/plugins/exec/source/index.ts

@@ -6,6 +6,18 @@ import { createExecAdapter } from "./validation.js";
 
 export default defineRuntimePlugin((context) => ({
   handlers: createExecHandlers(context, readExecSettings(context.config)),
+  prepareRequest: async (modules, preparation) => {
+    if (!preparation?.requestState) return modules;
+    const handlers = createExecHandlers(
+      context,
+      readExecSettings(context.config),
+      preparation,
+    );
+    return modules.map((module) => ({
+      ...module,
+      implementation: handlers[module.definition.name as keyof typeof handlers],
+    }));
+  },
   adapters: {
     exec: createExecAdapter(),
   },

package/plugins/exec/source/paths.ts

@@ -1,69 +1,86 @@
-import { stat } from "node:fs/promises";
-import { isAbsolute, posix } from "node:path";
+import { realpath, stat } from "node:fs/promises";
+import { isAbsolute, posix, relative, sep } from "node:path";
 
 import {
   readRequiredString,
   resolvePluginPath,
-  type ResolvedRuntimeToolPath,
   type RuntimePluginLoadContext,
   type ToolExecutionContext,
 } from "../../../src/plugin-sdk/index.js";
-
 import { ExecPluginError } from "./errors.js";
+import type { ExecWorkingDirectory } from "./types.js";
 
-const EXEC_ALLOWED_LOCATIONS = Object.freeze([
-  "agent_work",
-  "workspace",
-] as const);
-
-function resolverContext(
-  pluginContext: RuntimePluginLoadContext,
-  executionContext: ToolExecutionContext | undefined,
-): Pick<RuntimePluginLoadContext, "runtimePathResolver"> {
-  return {
-    runtimePathResolver:
-      executionContext?.runtimePathResolver ??
-      pluginContext.runtimePathResolver,
-  };
-}
-
-export function resolveExecPath(
+function resolveContextualDirectory(
   pluginContext: RuntimePluginLoadContext,
   executionContext: ToolExecutionContext | undefined,
-  rawPath: unknown,
-): ResolvedRuntimeToolPath {
-  return resolvePluginPath(
-    resolverContext(pluginContext, executionContext),
-    rawPath,
+  requestedPath: string,
+): Readonly<{ absolutePath: string; base?: ExecWorkingDirectory }> {
+  if (isAbsolute(requestedPath)) return { absolutePath: requestedPath };
+  const isWorkspaceAlias =
+    requestedPath === "workspace" || requestedPath.startsWith("workspace/");
+  const base = resolvePluginPath(
     {
-      requirePath: true,
-      allowedLocations: EXEC_ALLOWED_LOCATIONS,
+      runtimePathResolver:
+        executionContext?.runtimePathResolver ??
+        pluginContext.runtimePathResolver,
     },
+    isWorkspaceAlias ? "workspace" : ".",
+    { allowedLocations: [isWorkspaceAlias ? "workspace" : "agent_work"] },
   );
+  const relativePath = isWorkspaceAlias
+    ? requestedPath.slice("workspace".length + 1) || "."
+    : requestedPath;
+  return { absolutePath: `${base.absolutePath}${sep}${relativePath}`, base };
+}
+
+function isOutsideExecContextBase(relativePath: string): boolean {
+  if (relativePath === "..") return true;
+  if (relativePath.startsWith(`..${sep}`)) return true;
+  return isAbsolute(relativePath);
+}
+
+function logicalDirectory(
+  absolutePath: string,
+  base: ExecWorkingDirectory | undefined,
+): string {
+  if (!base) return absolutePath;
+  const fromBase = relative(base.absolutePath, absolutePath);
+  if (isOutsideExecContextBase(fromBase)) return absolutePath;
+  return posix.join(base.logicalPath, fromBase.split(sep).join("/") || ".");
 }
 
 export async function resolveExecWorkingDirectory(
   pluginContext: RuntimePluginLoadContext,
   executionContext: ToolExecutionContext | undefined,
   rawPath: unknown,
-): Promise<ResolvedRuntimeToolPath> {
+): Promise<ExecWorkingDirectory> {
   const requestedPath = readRequiredString(rawPath, {
     name: "cwd",
+    trim: false,
     maxLength: 4_096,
   });
-  const target = resolveExecPath(
+  if (requestedPath.includes("\0")) {
+    throw new ExecPluginError(
+      "exec_cwd_invalid",
+      "The selected cwd contains NUL characters.",
+    );
+  }
+  const target = resolveContextualDirectory(
     pluginContext,
     executionContext,
     requestedPath,
   );
+  let absolutePath: string;
   let info;
   try {
-    info = await stat(target.absolutePath);
+    // The contextual base is not a permission boundary for raw shell execution.
+    absolutePath = await realpath(target.absolutePath);
+    info = await stat(absolutePath);
   } catch (error) {
     if (error instanceof Error && "code" in error && error.code === "ENOENT") {
       throw new ExecPluginError(
         "exec_cwd_not_found",
-        "The selected cwd does not exist. Select an existing agent-work or workspace directory.",
+        "The selected cwd does not exist. Select an existing directory.",
       );
     }
     throw new ExecPluginError(
@@ -77,21 +94,8 @@ export async function resolveExecWorkingDirectory(
       "The selected cwd is not a directory.",
     );
   }
-  return target;
-}
-
-export function resolveExecScopedPath(
-  pluginContext: RuntimePluginLoadContext,
-  executionContext: ToolExecutionContext | undefined,
-  rawPath: string,
-  cwd: ResolvedRuntimeToolPath,
-): ResolvedRuntimeToolPath {
-  const normalized = rawPath.replaceAll("\\", "/");
-  const requested =
-    isAbsolute(rawPath) ||
-    normalized === "workspace" ||
-    normalized.startsWith("workspace/")
-      ? rawPath
-      : posix.join(cwd.logicalPath, normalized || ".");
-  return resolveExecPath(pluginContext, executionContext, requested);
+  return Object.freeze({
+    absolutePath,
+    logicalPath: logicalDirectory(absolutePath, target.base),
+  });
 }