Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

3.8 KB
Raw Blame
// Copyright 2026 The OpenSandbox Authors
// 
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// 
//     http://www.apache.org/licenses/LICENSE-2.0
// 
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

import type { Execution, ExecutionComplete, ExecutionError, ExecutionHandlers, ExecutionInit, ExecutionResult, OutputMessage } from "./execution.js";
import { normalizeExitCode } from "./execution.js";
import type { ServerStreamEvent } from "./execd.js";

function extractText(results: ServerStreamEvent["results"] | undefined): string | undefined {
  if (!results || typeof results !== "object") return undefined;
  const r = results as any;
  const v = r["text/plain"] ?? r.text ?? r.textPlain;
  return v == null ? undefined : String(v);
}

/**
 * Dispatches streamed execution events to handlers.
 *
 * This mutates the provided `execution` object (appending logs/results and setting fields like
 * `id`, `executionCount`, and `complete`) and invokes optional callbacks in {@link ExecutionHandlers}.
 */
export class ExecutionEventDispatcher {
  constructor(
    private readonly execution: Execution,
    private readonly handlers?: ExecutionHandlers,
  ) {}

  async dispatch(ev: ServerStreamEvent): Promise<void> {
    await this.handlers?.onEvent?.(ev);

    const ts = ev.timestamp ?? Date.now();
    switch (ev.type) {
      case "init": {
        const id = ev.text ?? "";
        if (id) this.execution.id = id;
        const init: ExecutionInit = { id, timestamp: ts };
        await this.handlers?.onInit?.(init);
        return;
      }
      case "stdout": {
        const msg: OutputMessage = { text: ev.text ?? "", timestamp: ts, isError: false };
        if (!this.handlers?.skipAccumulation) {
          this.execution.logs.stdout.push(msg);
        }
        await this.handlers?.onStdout?.(msg);
        return;
      }
      case "stderr": {
        const msg: OutputMessage = { text: ev.text ?? "", timestamp: ts, isError: true };
        if (!this.handlers?.skipAccumulation) {
          this.execution.logs.stderr.push(msg);
        }
        await this.handlers?.onStderr?.(msg);
        return;
      }
      case "result": {
        const r: ExecutionResult = { text: extractText(ev.results), timestamp: ts, raw: ev.results as any };
        this.execution.result.push(r);
        await this.handlers?.onResult?.(r);
        return;
      }
      case "execution_count": {
        const c = (ev as any).execution_count;
        if (typeof c === "number") this.execution.executionCount = c;
        return;
      }
      case "execution_complete": {
        const ms = (ev as any).execution_time;
        const complete: ExecutionComplete = { timestamp: ts, executionTimeMs: typeof ms === "number" ? ms : 0 };
        this.execution.complete = complete;
        await this.handlers?.onExecutionComplete?.(complete);
        return;
      }
      case "error": {
        const e = ev.error as any;
        if (e) {
          const err: ExecutionError = {
            name: String(e.ename ?? e.name ?? ""),
            value: String(e.evalue ?? e.value ?? ""),
            timestamp: ts,
            traceback: Array.isArray(e.traceback) ? e.traceback.map(String) : [],
          };
          const exitCode = normalizeExitCode(e.exit_code);
          if (exitCode !== undefined) {
            err.exitCode = exitCode;
          }
          this.execution.error = err;
          await this.handlers?.onError?.(err);
        }
        return;
      }
      default:
        return;
    }
  }
}