@abot-ai/runtime 1.5.0 → 1.7.0

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

@@ -9,6 +9,8 @@ import type {
   ExecFilesystemSnapshot,
 } from "./types.js";
 import { ExecPluginError } from "./errors.js";
+import { ExecTerminalDelivery } from "./terminal-delivery.js";
+import { isExecOutputBody } from "./output-files.js";
 
 type SavedExecution = Readonly<{
   processId: string;
@@ -28,6 +30,7 @@ type SavedExecution = Readonly<{
 export class ExecRequestResources {
   private readonly owned = new Map<string, string>();
   private readonly restored = new Map<string, SavedExecution>();
+  private readonly deliveries = new Map<string, ExecTerminalDelivery>();
   constructor(
     private readonly manager: ExecProcessManager,
     private readonly pending: Map<string, PendingExecExecution>,
@@ -54,6 +57,10 @@ export class ExecRequestResources {
   forget(processId: string) {
     this.owned.delete(processId);
     this.restored.delete(processId);
+    this.deliveries.delete(processId);
+  }
+  isRestored(processId: string): boolean {
+    return this.restored.has(processId);
   }
   terminal(
     processId: string,
@@ -72,10 +79,16 @@ export class ExecRequestResources {
         "stale_exec_process_cursor",
         "The saved exec cursor is stale.",
       );
-    this.restored.delete(processId);
-    return structuredClone(entry.snapshot);
+    return this.deliveries.get(processId)!.reserve({
+      ...structuredClone(entry.snapshot),
+      nextCursor: entry.cursor,
+    });
+  }
+  rejectTerminal(snapshot: ExecProcessSnapshot): void {
+    this.deliveries.get(snapshot.processId)?.reject(snapshot);
   }
   private snapshot() {
+    for (const delivery of this.deliveries.values()) delivery.assertAvailable();
     const executions: SavedExecution[] = [...this.restored.values()];
     for (const [processId, scope] of this.owned) {
       const execution = this.pending.get(processId);
@@ -94,12 +107,13 @@ export class ExecRequestResources {
         },
       });
     }
-    return { kind: "exec_terminal_state_v1", executions };
+    return { kind: "exec_terminal_state_v2", executions };
   }
   private restore(value: unknown) {
     if (
       !isRecord(value) ||
-      value.kind !== "exec_terminal_state_v1" ||
+      (value.kind !== "exec_terminal_state_v1" &&
+        value.kind !== "exec_terminal_state_v2") ||
       !Array.isArray(value.executions)
     )
       throw invalid();
@@ -108,6 +122,7 @@ export class ExecRequestResources {
         throw invalid();
       const before = entry.execution.filesystemStateBefore;
       this.restored.set(entry.processId, structuredClone(entry));
+      this.deliveries.set(entry.processId, new ExecTerminalDelivery());
       this.pending.set(entry.processId, {
         ...structuredClone(entry.execution),
         filesystemStateBefore: before
@@ -129,6 +144,7 @@ export class ExecRequestResources {
     for (const id of this.restored.keys()) this.pending.delete(id);
     this.owned.clear();
     this.restored.clear();
+    this.deliveries.clear();
   }
 }
 function isSavedExecution(value: unknown): value is SavedExecution {
@@ -141,8 +157,8 @@ function isSavedExecution(value: unknown): value is SavedExecution {
     !isRecord(value.snapshot) ||
     value.snapshot.processId !== value.processId ||
     value.snapshot.status !== "settled" ||
-    !isStream(value.snapshot.stdout) ||
-    !isStream(value.snapshot.stderr) ||
+    !isStream(value.snapshot.stdout, "stdout") ||
+    !isStream(value.snapshot.stderr, "stderr") ||
     !Number.isFinite(value.snapshot.elapsedMs) ||
     !isRecord(value.execution) ||
     typeof value.execution.commandPreview !== "string" ||
@@ -152,11 +168,9 @@ function isSavedExecution(value: unknown): value is SavedExecution {
   )
     return false;
   if (
-    ![
-      value.execution.hardTimeoutMs,
-      value.execution.idleTimeoutMs,
-      value.execution.outputMaxChars,
-    ].every(Number.isFinite)
+    ![value.execution.hardTimeoutMs, value.execution.idleTimeoutMs].every(
+      Number.isFinite,
+    )
   )
     return false;
   const before = value.execution.filesystemStateBefore;
@@ -181,11 +195,13 @@ function isSavedExecution(value: unknown): value is SavedExecution {
       ))
   );
 }
-function isStream(value: unknown): boolean {
+function isStream(value: unknown, stream: "stdout" | "stderr"): boolean {
   return (
     isRecord(value) &&
     typeof value.text === "string" &&
     typeof value.sawOutput === "boolean" &&
+    (value.body === undefined ||
+      (isExecOutputBody(value.body) && value.body.stream === stream)) &&
     isRecord(value.metadata) &&
     typeof value.metadata.truncated === "boolean" &&
     [

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

@@ -1,8 +1,7 @@
 import {
-  boundText,
-  enforcePluginResultByteBudget,
-  failureResult,
+  deliverPluginTextResult,
   type ToolImplementationOutput,
+  type ToolResultBudget,
 } from "../../../src/plugin-sdk/index.js";
 import {
   captureExecFilesystemSnapshot,
@@ -13,37 +12,44 @@ import type {
   ExecFilesystemDelta,
   ExecProcessSnapshot,
   ExecStreamSnapshot,
+  ExecStreamMetadata,
   PendingExecExecution,
 } from "./types.js";
 
-function streamDisplay(snapshot: ExecStreamSnapshot): string {
-  if (snapshot.text) return snapshot.text;
+const EXEC_CONTEXT_TEXT_FIELDS = Object.freeze(["stdout", "stderr"] as const);
+
+function streamReceipt(
+  snapshot: ExecStreamSnapshot,
+  field: "stdout" | "stderr",
+): string {
+  if (snapshot.text) return `See the ${field} field (${snapshot.text.length} characters).`;
   return snapshot.sawOutput
     ? "(no new output; earlier output was already returned)"
     : "(empty)";
 }
 
-function renderedOutput(
-  lines: readonly string[],
-  outputMaxChars: number,
-): Readonly<{
+function renderedOutput(lines: readonly string[]): Readonly<{
   output: string;
-  metadata: ReturnType<typeof boundText>["metadata"];
+  metadata: ExecStreamMetadata;
 }> {
-  const bounded = boundText(lines.join("\n"), {
-    maxChars: outputMaxChars,
-    marker: "\n[exec output truncated]",
+  const output = lines.join("\n");
+  return Object.freeze({
+    output,
+    metadata: Object.freeze({
+      truncated: false,
+      originalChars: output.length,
+      returnedChars: output.length,
+      omittedChars: 0,
+    }),
   });
-  return Object.freeze({ output: bounded.text, metadata: bounded.metadata });
 }
 
 function outputBoundsData(
   snapshot: ExecProcessSnapshot,
-  rendered: ReturnType<typeof renderedOutput>["metadata"],
-  maxChars: number,
+  rendered: ExecStreamMetadata,
 ) {
   return Object.freeze({
-    maxChars,
+    maxChars: null,
     stdout: snapshot.stdout.metadata,
     stderr: snapshot.stderr.metadata,
     rendered,
@@ -53,6 +59,7 @@ function outputBoundsData(
 export function runningResult(
   snapshot: ExecProcessSnapshot,
   execution: PendingExecExecution,
+  resultBudget?: ToolResultBudget,
 ): ToolImplementationOutput {
   const nextCursor = snapshot.nextCursor ?? 1;
   const rendered = renderedOutput(
@@ -63,16 +70,17 @@ export function runningResult(
       `Process ID: ${snapshot.processId}`,
       `Next cursor: ${nextCursor}`,
       "STDOUT since the previous observation:",
-      streamDisplay(snapshot.stdout),
+      streamReceipt(snapshot.stdout, "stdout"),
       "STDERR since the previous observation:",
-      streamDisplay(snapshot.stderr),
+      streamReceipt(snapshot.stderr, "stderr"),
       "Continue this exact process with exec_wait; do not run the command again.",
     ],
-    execution.outputMaxChars,
   );
-  return failureResult({
+  return deliverPluginTextResult({
+    ok: false,
+    producedNewInformation: false,
     errorCode: "exec_process_running",
-    message:
+    error:
       "The command is still running. Continue it with exec_wait using the returned process ID and cursor.",
     output: rendered.output,
     stdout: snapshot.stdout.text,
@@ -81,17 +89,13 @@ export function runningResult(
       processId: snapshot.processId,
       processStatus: "running",
       nextCursor,
-      outputBounds: outputBoundsData(
-        snapshot,
-        rendered.metadata,
-        execution.outputMaxChars,
-      ),
+      outputBounds: outputBoundsData(snapshot, rendered.metadata),
       observationMeta: {
         kind: "volatile_external",
         carryPolicy: "never",
       },
     },
-  });
+  }, EXEC_CONTEXT_TEXT_FIELDS, resultBudget);
 }
 
 async function captureFilesystemDelta(
@@ -166,6 +170,7 @@ export async function finalizeExecResult(params: {
   snapshot: ExecProcessSnapshot;
   execution: PendingExecExecution;
   cancellationIsSuccess?: boolean;
+  resultBudget?: ToolResultBudget;
 }): Promise<ToolImplementationOutput> {
   const { snapshot, execution } = params;
   const exitCode = snapshot.exitCode ?? -1;
@@ -202,12 +207,11 @@ export async function finalizeExecResult(params: {
       `Exit code: ${exitCode}`,
       ...(filesystemEvidence ? filesystemEvidence.outputLines : []),
       "STDOUT:",
-      streamDisplay(snapshot.stdout),
+      streamReceipt(snapshot.stdout, "stdout"),
       "STDERR:",
-      streamDisplay(snapshot.stderr),
+      streamReceipt(snapshot.stderr, "stderr"),
       ...(resultSummary ? [resultSummary] : []),
     ],
-    execution.outputMaxChars,
   );
   const processStatus = snapshot.terminationReason ?? "completed";
   const data = {
@@ -218,11 +222,7 @@ export async function finalizeExecResult(params: {
       : {}),
     processId: snapshot.processId,
     processStatus,
-    outputBounds: outputBoundsData(
-      snapshot,
-      rendered.metadata,
-      execution.outputMaxChars,
-    ),
+    outputBounds: outputBoundsData(snapshot, rendered.metadata),
     ...(filesystemDelta
       ? { filesystemObservation: filesystemDelta.observation }
       : { filesystemObservation: { available: false } }),
@@ -242,7 +242,7 @@ export async function finalizeExecResult(params: {
     data,
   };
   if (ok && (!inconclusiveSuccess || cancellationIsSuccess)) {
-    return enforcePluginResultByteBudget({ ok: true, ...common });
+    return deliverPluginTextResult({ ok: true, ...common }, EXEC_CONTEXT_TEXT_FIELDS, params.resultBudget);
   }
   const errorCode = inconclusiveSuccess
     ? "no_observable_result"
@@ -266,10 +266,10 @@ export async function finalizeExecResult(params: {
           : errorCode === "exec_hard_timeout"
             ? `The command exceeded the ${execution.hardTimeoutMs}ms hard timeout.`
             : `The command exited with code ${exitCode}.`;
-  return enforcePluginResultByteBudget({
+  return deliverPluginTextResult({
     ok: false,
     ...common,
     error,
     errorCode,
-  });
+  }, EXEC_CONTEXT_TEXT_FIELDS, params.resultBudget);
 }

package/plugins/exec/source/retained-output-failure.ts

@@ -0,0 +1,51 @@
+import {
+  failureResult,
+  type ToolExecutionContext,
+  type ToolImplementationOutput,
+} from "../../../src/plugin-sdk/index.js";
+import type { ExecProcessSnapshot } from "./types.js";
+
+/** Output remains pending; neither an exit nor a size rejection is an acknowledgement. */
+export function retainedOutputFailure(
+  snapshot: ExecProcessSnapshot,
+  context?: ToolExecutionContext,
+): ToolImplementationOutput {
+  const expired = hasUnavailableOutput(snapshot);
+  return failureResult(
+    {
+      errorCode: expired
+        ? "exec_output_expired"
+        : snapshot.outputFailure
+          ? "exec_output_storage_failed"
+          : "exec_output_delivery_pending",
+      message: expired
+        ? "The retained output expired or is no longer available. The command was already started; it has not been run again."
+        : snapshot.outputFailure
+          ? "Output storage or delivery failed. The command was already started; do not run it again. Any committed bytes are retained for the configured retention period; complete output delivery is not confirmed."
+          : "The output exceeds the delivery envelope and remains retained. The command was already executed; do not run it again.",
+      data: {
+        processId: snapshot.processId,
+        processStatus: snapshot.status,
+        nextCursor: snapshot.nextCursor,
+        ...(snapshot.exitCode !== undefined
+          ? { exitCode: snapshot.exitCode }
+          : {}),
+        ...(snapshot.terminationReason
+          ? { terminationReason: snapshot.terminationReason }
+          : {}),
+        outputDelivery: expired ? "expired" : "pending",
+        ...(snapshot.outputFailure
+          ? { outputStorageFailure: snapshot.outputFailure }
+          : {}),
+        retainedCharacters:
+          snapshot.stdout.text.length + snapshot.stderr.text.length,
+      },
+    },
+    context?.resultBudget,
+  );
+}
+
+function hasUnavailableOutput(snapshot: ExecProcessSnapshot): boolean {
+  if (snapshot.outputFailure?.code === "exec_output_expired") return true;
+  return snapshot.outputFailure?.code === "exec_output_expired_or_unavailable";
+}

package/plugins/exec/source/settings.ts

@@ -1,23 +1,28 @@
 import { readBoundedInteger } from "../../../src/plugin-sdk/index.js";
+import { DEFAULT_EXEC_OUTPUT_RETENTION_MS } from "./output-contracts.js";
 
 export type ExecSettings = Readonly<{
   hardTimeoutMs: number;
   yieldAfterMs: number;
   idleTimeoutMs: number;
-  outputMaxChars: number;
+  outputRetentionMs?: number;
 }>;
 
 export const DEFAULT_EXEC_HARD_TIMEOUT_MS = 600_000;
 export const DEFAULT_EXEC_YIELD_AFTER_MS = 15_000;
 export const DEFAULT_EXEC_IDLE_TIMEOUT_MS = 120_000;
-export const DEFAULT_EXEC_OUTPUT_MAX_CHARS = 8_000;
-export const EXEC_OUTPUT_MAX_CHARS = 8_000;
-export const EXEC_COMMAND_MAX_CHARS = 4_096;
+export const EXEC_COMMAND_MAX_CHARS = 8_192;
 
 export function readExecSettings(
   config: Readonly<Record<string, unknown>> | undefined,
 ): ExecSettings {
   return Object.freeze({
+    outputRetentionMs: readBoundedInteger(config?.outputRetentionMs, {
+      defaultValue: DEFAULT_EXEC_OUTPUT_RETENTION_MS,
+      minimum: 1,
+      maximum: Number.MAX_SAFE_INTEGER,
+      name: "outputRetentionMs",
+    }),
     hardTimeoutMs: readBoundedInteger(config?.timeoutMs, {
       defaultValue: DEFAULT_EXEC_HARD_TIMEOUT_MS,
       minimum: 1,
@@ -36,11 +41,5 @@ export function readExecSettings(
       maximum: 3_600_000,
       name: "idleTimeoutMs",
     }),
-    outputMaxChars: readBoundedInteger(config?.outputMaxChars, {
-      defaultValue: DEFAULT_EXEC_OUTPUT_MAX_CHARS,
-      minimum: 64,
-      maximum: EXEC_OUTPUT_MAX_CHARS,
-      name: "outputMaxChars",
-    }),
   });
 }

package/plugins/exec/source/terminal-delivery.ts

@@ -0,0 +1,49 @@
+import { randomUUID } from "node:crypto";
+import { ExecPluginError } from "./errors.js";
+import type { ExecProcessSnapshot } from "./types.js";
+
+/** One terminal observation may be presented until it is accepted or rejected. */
+export class ExecTerminalDelivery {
+  private claim?: string;
+  private accepted = false;
+
+  get isClaimed(): boolean {
+    return this.claim !== undefined;
+  }
+
+  assertAvailable(): void {
+    if (this.isClaimed) throw this.unavailable();
+  }
+
+  reserve(snapshot: ExecProcessSnapshot): ExecProcessSnapshot {
+    if (snapshot.status !== "settled") return snapshot;
+    this.assertAvailable();
+    this.claim = randomUUID();
+    return Object.freeze({ ...snapshot, deliveryId: this.claim });
+  }
+
+  assertOwner(snapshot: ExecProcessSnapshot): void {
+    if (snapshot.status !== "settled") return;
+    if (!this.claim || snapshot.deliveryId !== this.claim || this.accepted)
+      throw this.unavailable();
+  }
+
+  accept(snapshot: ExecProcessSnapshot): void {
+    if (snapshot.status !== "settled") return;
+    this.assertOwner(snapshot);
+    this.accepted = true;
+  }
+
+  reject(snapshot: ExecProcessSnapshot): void {
+    if (this.accepted) return;
+    if (snapshot.deliveryId !== this.claim) return;
+    this.claim = undefined;
+  }
+
+  private unavailable(): ExecPluginError {
+    return new ExecPluginError(
+      "unknown_exec_process",
+      "The terminal exec result is already claimed by another observation.",
+    );
+  }
+}

package/plugins/exec/source/types.ts

@@ -1,3 +1,5 @@
+import type { ExecOutputBody } from "./output-contracts.js";
+
 export type ExecActionSummary = Readonly<{
   type: string;
   target?: string;
@@ -10,6 +12,7 @@ export type ExecTerminationReason =
   | "completed"
   | "hard_timeout"
   | "idle_timeout"
+  | "output_storage_failed"
   | "spawn_failed";
 
 export type ExecStreamMetadata = Readonly<{
@@ -23,17 +26,26 @@ export type ExecStreamSnapshot = Readonly<{
   text: string;
   metadata: ExecStreamMetadata;
   sawOutput: boolean;
+  /** Plugin-private disk receipt; never projected as model instructions. */
+  body?: ExecOutputBody;
 }>;
 
 export type ExecProcessSnapshot = Readonly<{
   processId: string;
   status: "running" | "settled";
   nextCursor?: number;
+  /** Plugin-private terminal presentation reservation; never persisted. */
+  deliveryId?: string;
   exitCode?: number;
   stdout: ExecStreamSnapshot;
   stderr: ExecStreamSnapshot;
   terminationReason?: ExecTerminationReason;
   elapsedMs: number;
+  outputFailure?: Readonly<{
+    code: string;
+    stdoutBytes: number;
+    stderrBytes: number;
+  }>;
 }>;
 
 export type ExecFilesystemEntry = Readonly<{
@@ -75,5 +87,4 @@ export type PendingExecExecution = Readonly<{
   filesystemStateBefore: ExecFilesystemSnapshot | null;
   hardTimeoutMs: number;
   idleTimeoutMs: number;
-  outputMaxChars: number;
 }>;