@abot-ai/runtime 1.3.1 → 1.5.0

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

@@ -3,59 +3,17 @@ import { randomUUID } from "node:crypto";
 import type { Readable } from "node:stream";
 import { StringDecoder } from "node:string_decoder";
 
-import { sanitizeJsonText } from "../../../src/plugin-sdk/index.js";
+import { CappedTextBuffer } from "./process-output-buffer.js";
 
 import { ExecPluginError } from "./errors.js";
 import { assertSupportedShell, EXEC_SHELL } from "./shell-platform.js";
-import type {
-  ExecProcessSnapshot,
-  ExecStreamSnapshot,
-  ExecTerminationReason,
-} from "./types.js";
+import type { ExecProcessSnapshot, ExecTerminationReason } from "./types.js";
 
 const COMPLETED_PROCESS_RETENTION_MS = 5 * 60_000;
 const MAX_ACTIVE_PROCESSES_PER_SCOPE = 4;
 
 type ExecChild = ChildProcessByStdio<null, Readable, Readable>;
 
-class CappedTextBuffer {
-  private text = "";
-  private originalChars = 0;
-  private omittedChars = 0;
-  private sawOutput = false;
-
-  constructor(private readonly maxChars: number) {}
-
-  append(chunk: string): void {
-    if (!chunk) return;
-    const safeChunk = sanitizeJsonText(chunk);
-    this.sawOutput = true;
-    this.originalChars += safeChunk.length;
-    const available = Math.max(this.maxChars - this.text.length, 0);
-    this.text += safeChunk.slice(0, available);
-    this.omittedChars += Math.max(safeChunk.length - available, 0);
-  }
-
-  consume(): ExecStreamSnapshot {
-    const text = this.text;
-    const originalChars = this.originalChars;
-    const omittedChars = this.omittedChars;
-    this.text = "";
-    this.originalChars = 0;
-    this.omittedChars = 0;
-    return Object.freeze({
-      text,
-      sawOutput: this.sawOutput,
-      metadata: Object.freeze({
-        truncated: omittedChars > 0,
-        originalChars,
-        returnedChars: text.length,
-        omittedChars,
-      }),
-    });
-  }
-}
-
 type ManagedExecProcess = {
   processId: string;
   scope: string;
@@ -94,6 +52,7 @@ export type ExecProcessManager = Readonly<{
       hardTimeoutMs: number;
       abortSignal?: AbortSignal;
       onDisposed?: (processId: string) => void;
+      onStarted?: (processId: string, settled: Promise<void>) => void;
     }>,
   ): Promise<ExecProcessSnapshot>;
   wait(
@@ -111,6 +70,10 @@ export type ExecProcessManager = Readonly<{
     }>,
   ): Promise<ExecProcessSnapshot>;
   release(processId: string, scope: string): Promise<void>;
+  snapshotSettled(
+    processId: string,
+    scope: string,
+  ): Readonly<{ cursor: number; snapshot: ExecProcessSnapshot }>;
 }>;
 
 export function createExecProcessManager(): ExecProcessManager {
@@ -312,6 +275,7 @@ export function createExecProcessManager(): ExecProcessManager {
         ...(params.onDisposed ? { onDisposed: params.onDisposed } : {}),
       };
       processes.set(managed.processId, managed);
+      params.onStarted?.(managed.processId, managed.settlePromise);
 
       const observe = (stream: "stdout" | "stderr", chunk: string): void => {
         if (managed.settled || !chunk) return;
@@ -397,6 +361,31 @@ export function createExecProcessManager(): ExecProcessManager {
       });
     },
 
+    snapshotSettled(processId, scope) {
+      const managed = getScopedProcess(processId, scope);
+      if (
+        !managed.settled ||
+        managed.waitInFlight ||
+        managed.terminalSnapshotClaimed
+      )
+        throw new Error("exec_snapshot_not_quiescent");
+      return Object.freeze({
+        cursor: managed.cursor,
+        snapshot: Object.freeze({
+          processId,
+          status: "settled" as const,
+          ...(managed.exitCode === undefined
+            ? {}
+            : { exitCode: managed.exitCode }),
+          stdout: managed.stdout.peek(),
+          stderr: managed.stderr.peek(),
+          ...(managed.terminationReason
+            ? { terminationReason: managed.terminationReason }
+            : {}),
+          elapsedMs: Date.now() - managed.startedAt,
+        }),
+      });
+    },
     async release(processId, scope) {
       const managed = processes.get(processId);
       if (!managed) return;

package/plugins/exec/source/process-output-buffer.ts

@@ -0,0 +1,44 @@
+import { sanitizeJsonText } from "../../../src/plugin-sdk/index.js";
+import type { ExecStreamSnapshot } from "./types.js";
+
+export class CappedTextBuffer {
+  private text = "";
+  private originalChars = 0;
+  private omittedChars = 0;
+  private sawOutput = false;
+
+  constructor(private readonly maxChars: number) {}
+
+  append(chunk: string): void {
+    if (!chunk) return;
+    const safeChunk = sanitizeJsonText(chunk);
+    this.sawOutput = true;
+    this.originalChars += safeChunk.length;
+    const available = Math.max(this.maxChars - this.text.length, 0);
+    this.text += safeChunk.slice(0, available);
+    this.omittedChars += Math.max(safeChunk.length - available, 0);
+  }
+
+  peek(): ExecStreamSnapshot {
+    const text = this.text;
+    const originalChars = this.originalChars;
+    const omittedChars = this.omittedChars;
+    return Object.freeze({
+      text,
+      sawOutput: this.sawOutput,
+      metadata: Object.freeze({
+        truncated: omittedChars > 0,
+        originalChars,
+        returnedChars: text.length,
+        omittedChars,
+      }),
+    });
+  }
+  consume(): ExecStreamSnapshot {
+    const result = this.peek();
+    this.text = "";
+    this.originalChars = 0;
+    this.omittedChars = 0;
+    return result;
+  }
+}

package/plugins/exec/source/request-resources.ts

@@ -0,0 +1,203 @@
+import type {
+  ToolRequestPreparationContext,
+  ToolExecutionContext,
+} from "../../../src/plugin-sdk/index.js";
+import type { ExecProcessManager } from "./process-manager.js";
+import type {
+  ExecProcessSnapshot,
+  PendingExecExecution,
+  ExecFilesystemSnapshot,
+} from "./types.js";
+import { ExecPluginError } from "./errors.js";
+
+type SavedExecution = Readonly<{
+  processId: string;
+  scope: string;
+  cursor: number;
+  snapshot: ExecProcessSnapshot;
+  execution: Omit<PendingExecExecution, "filesystemStateBefore"> & {
+    filesystemStateBefore:
+      | (Omit<ExecFilesystemSnapshot, "entries"> & {
+          entries: readonly (readonly [string, unknown])[];
+        })
+      | null;
+  };
+}>;
+
+/** Serializes only terminal output; a live child is never restored or replayed. */
+export class ExecRequestResources {
+  private readonly owned = new Map<string, string>();
+  private readonly restored = new Map<string, SavedExecution>();
+  constructor(
+    private readonly manager: ExecProcessManager,
+    private readonly pending: Map<string, PendingExecExecution>,
+    preparation?: ToolRequestPreparationContext,
+  ) {
+    const state = preparation?.requestState;
+    if (!state) return;
+    const saved = state.read("exec.terminal.v1");
+    if (saved !== undefined) this.restore(saved);
+    state.register("exec.terminal.v1", {
+      snapshot: () => this.snapshot(),
+      dispose: () => this.dispose(),
+    });
+  }
+  started(
+    processId: string,
+    scope: string,
+    settled: Promise<void>,
+    context?: ToolExecutionContext,
+  ) {
+    this.owned.set(processId, scope);
+    context?.requestWork?.trackUntil(settled);
+  }
+  forget(processId: string) {
+    this.owned.delete(processId);
+    this.restored.delete(processId);
+  }
+  terminal(
+    processId: string,
+    scope: string,
+    cursor?: number,
+  ): ExecProcessSnapshot | undefined {
+    const entry = this.restored.get(processId);
+    if (!entry) return undefined;
+    if (entry.scope !== scope)
+      throw new ExecPluginError(
+        "unknown_exec_process",
+        "The exec process belongs to a different session.",
+      );
+    if (cursor !== undefined && cursor !== entry.cursor)
+      throw new ExecPluginError(
+        "stale_exec_process_cursor",
+        "The saved exec cursor is stale.",
+      );
+    this.restored.delete(processId);
+    return structuredClone(entry.snapshot);
+  }
+  private snapshot() {
+    const executions: SavedExecution[] = [...this.restored.values()];
+    for (const [processId, scope] of this.owned) {
+      const execution = this.pending.get(processId);
+      if (!execution) continue;
+      const terminal = this.manager.snapshotSettled(processId, scope);
+      const before = execution.filesystemStateBefore;
+      executions.push({
+        processId,
+        scope,
+        ...terminal,
+        execution: {
+          ...execution,
+          filesystemStateBefore: before
+            ? { ...before, entries: [...before.entries] }
+            : null,
+        },
+      });
+    }
+    return { kind: "exec_terminal_state_v1", executions };
+  }
+  private restore(value: unknown) {
+    if (
+      !isRecord(value) ||
+      value.kind !== "exec_terminal_state_v1" ||
+      !Array.isArray(value.executions)
+    )
+      throw invalid();
+    for (const entry of value.executions) {
+      if (!isSavedExecution(entry) || this.restored.has(entry.processId))
+        throw invalid();
+      const before = entry.execution.filesystemStateBefore;
+      this.restored.set(entry.processId, structuredClone(entry));
+      this.pending.set(entry.processId, {
+        ...structuredClone(entry.execution),
+        filesystemStateBefore: before
+          ? { ...before, entries: new Map(before.entries as [string, any][]) }
+          : null,
+      });
+    }
+  }
+  private async dispose() {
+    for (const [processId, scope] of this.owned) {
+      try {
+        await this.manager.cancel({ processId, scope });
+      } catch {}
+      try {
+        await this.manager.release(processId, scope);
+      } catch {}
+      this.pending.delete(processId);
+    }
+    for (const id of this.restored.keys()) this.pending.delete(id);
+    this.owned.clear();
+    this.restored.clear();
+  }
+}
+function isSavedExecution(value: unknown): value is SavedExecution {
+  if (
+    !isRecord(value) ||
+    typeof value.processId !== "string" ||
+    typeof value.scope !== "string" ||
+    !Number.isSafeInteger(value.cursor) ||
+    value.cursor < 1 ||
+    !isRecord(value.snapshot) ||
+    value.snapshot.processId !== value.processId ||
+    value.snapshot.status !== "settled" ||
+    !isStream(value.snapshot.stdout) ||
+    !isStream(value.snapshot.stderr) ||
+    !Number.isFinite(value.snapshot.elapsedMs) ||
+    !isRecord(value.execution) ||
+    typeof value.execution.commandPreview !== "string" ||
+    !isRecord(value.execution.cwd) ||
+    typeof value.execution.cwd.absolutePath !== "string" ||
+    typeof value.execution.cwd.logicalPath !== "string"
+  )
+    return false;
+  if (
+    ![
+      value.execution.hardTimeoutMs,
+      value.execution.idleTimeoutMs,
+      value.execution.outputMaxChars,
+    ].every(Number.isFinite)
+  )
+    return false;
+  const before = value.execution.filesystemStateBefore;
+  return (
+    before === null ||
+    (isRecord(before) &&
+      typeof before.absoluteRoot === "string" &&
+      typeof before.logicalRoot === "string" &&
+      typeof before.rootExists === "boolean" &&
+      typeof before.complete === "boolean" &&
+      Array.isArray(before.entries) &&
+      before.entries.every(
+        (entry: unknown) =>
+          Array.isArray(entry) &&
+          entry.length === 2 &&
+          typeof entry[0] === "string" &&
+          isRecord(entry[1]) &&
+          typeof entry[1].kind === "string" &&
+          [entry[1].mode, entry[1].size, entry[1].mtimeMs].every(
+            Number.isFinite,
+          ),
+      ))
+  );
+}
+function isStream(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.text === "string" &&
+    typeof value.sawOutput === "boolean" &&
+    isRecord(value.metadata) &&
+    typeof value.metadata.truncated === "boolean" &&
+    [
+      value.metadata.originalChars,
+      value.metadata.returnedChars,
+      value.metadata.omittedChars,
+    ].every(Number.isFinite)
+  );
+}
+function isRecord(value: unknown): value is Record<string, any> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function invalid() {
+  return new Error("exec_terminal_snapshot_invalid");
+}

package/plugins/exec/source/result-presentation.ts

@@ -0,0 +1,275 @@
+import {
+  boundText,
+  enforcePluginResultByteBudget,
+  failureResult,
+  type ToolImplementationOutput,
+} from "../../../src/plugin-sdk/index.js";
+import {
+  captureExecFilesystemSnapshot,
+  diffExecFilesystemSnapshots,
+} from "./filesystem-observer.js";
+import type {
+  ExecActionSummary,
+  ExecFilesystemDelta,
+  ExecProcessSnapshot,
+  ExecStreamSnapshot,
+  PendingExecExecution,
+} from "./types.js";
+
+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,
+  });
+}
+
+export function runningResult(
+  snapshot: ExecProcessSnapshot,
+  execution: PendingExecExecution,
+): ToolImplementationOutput {
+  const nextCursor = snapshot.nextCursor ?? 1;
+  const rendered = renderedOutput(
+    [
+      `Command: ${execution.commandPreview}`,
+      `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})` : ""}`;
+}
+
+export 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}`,
+      `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,
+  });
+}

package/plugins/exec/source/types.ts

@@ -1,5 +1,3 @@
-import type { ResolvedRuntimeToolPath } from "../../../src/plugin-sdk/index.js";
-
 export type ExecActionSummary = Readonly<{
   type: string;
   target?: string;
@@ -66,10 +64,14 @@ export type ExecFilesystemDelta = Readonly<{
   }>;
 }>;
 
+export type ExecWorkingDirectory = Readonly<{
+  absolutePath: string;
+  logicalPath: string;
+}>;
+
 export type PendingExecExecution = Readonly<{
   commandPreview: string;
-  commandWasNormalized: boolean;
-  cwd: ResolvedRuntimeToolPath;
+  cwd: ExecWorkingDirectory;
   filesystemStateBefore: ExecFilesystemSnapshot | null;
   hardTimeoutMs: number;
   idleTimeoutMs: number;