Secure, Fast, and Extensible Sandbox runtime for AI agents.
// 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 {
InvalidArgumentException,
SandboxApiException,
SandboxReadyTimeoutException,
} from "../core/exceptions.js";
import { subscribeAbort, type AbortSubscription } from "./abort.js";
export function validatePollingInterval(interval: number): void {
// setTimeout() runs a negative delay immediately, which would hammer the
// endpoint until the deadline. The Python SDK rejects the same values.
if (interval < 0) {
throw new InvalidArgumentException({
message: `Ready polling interval must not be negative, got: ${interval}`,
});
}
}
export class ReadinessBudget {
private readonly deadline: number;
private lastError: unknown;
private context?: string;
private attempts = 0;
private timedOut = false;
constructor(private readonly seconds: number, private readonly caller?: AbortSignal) {
this.deadline = performance.now() + seconds * 1000;
}
remaining(): number {
this.caller?.throwIfAborted();
const remaining = this.deadline - performance.now();
if (this.timedOut || remaining <= 0) throw this.timeout();
return remaining;
}
healthContext(context: string): void {
this.context = context;
this.lastError = undefined;
}
attempt(): void { this.attempts++; }
record(error: unknown): void { this.lastError = error; }
private timeout(): SandboxReadyTimeoutException {
return new SandboxReadyTimeoutException({
message: this.context === undefined
? `Sandbox readiness timed out. Last error: ${String(this.lastError ?? "Endpoint not yet available.")}`
: `Sandbox health check timed out after ${this.seconds}s (${this.attempts} attempts). ${this.lastError instanceof Error ? `Last health check error: ${this.lastError.message}` : String(this.lastError ?? "Health check returned false continuously.")} Connection context: ${this.context}.`,
cause: this.lastError,
});
}
async run<T>(action: (signal: AbortSignal) => Promise<T>): Promise<T> {
const remaining = this.remaining();
const controller = new AbortController();
const onAbort = () => controller.abort(this.caller?.reason);
const unsubscribeCaller = subscribeAbort(this.caller, onAbort);
const timer = setTimeout(() => {
this.timedOut = true;
controller.abort(this.timeout());
}, remaining);
let rejectAbort: (() => void) | undefined;
try {
const aborted = new Promise<never>((_, reject) => {
rejectAbort = () => reject(controller.signal.reason);
controller.signal.addEventListener("abort", rejectAbort, { once: true });
});
const result = await Promise.race([action(controller.signal), aborted]);
this.remaining();
return result;
} catch (error) {
this.remaining();
throw error;
} finally {
clearTimeout(timer);
unsubscribeCaller();
if (rejectAbort) controller.signal.removeEventListener("abort", rejectAbort);
}
}
async pause(interval: number): Promise<void> {
const duration = Math.min(interval, this.remaining());
await new Promise<void>((resolve, reject) => {
let unsubscribeCaller: AbortSubscription = () => undefined;
const timer = setTimeout(() => { unsubscribeCaller(); resolve(); }, duration);
const abort = () => { clearTimeout(timer); reject(this.caller?.reason); };
unsubscribeCaller = subscribeAbort(this.caller, abort);
});
this.remaining();
}
async endpoint<T>(action: (signal: AbortSignal) => Promise<T>, interval: number): Promise<T> {
while (true) {
try { return await this.run(action); }
catch (error) {
if (!(error instanceof SandboxApiException) || error.statusCode !== 404 ||
error.error.code !== "KUBERNETES::POD_IP_NOT_AVAILABLE") throw error;
this.record(error);
}
await this.pause(interval);
}
}
}