Skip to content

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

2.6 KB
Raw Blame
// Copyright 2025 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.

package model

const (
	PTYWebSocketProtocol    = "opensandbox-pty"
	PTYWebSocketTokenPrefix = "base64url.bearer.execd.opensandbox."
)

type ClientFrame struct {
	Type   string `json:"type"`
	Data   string `json:"data,omitempty"`
	Cols   int    `json:"cols,omitempty"`
	Rows   int    `json:"rows,omitempty"`
	Signal string `json:"signal,omitempty"`
}

type ServerFrame struct {
	Type      string `json:"type"`
	SessionID string `json:"session_id,omitempty"`
	Mode      string `json:"mode,omitempty"`
	Role      string `json:"role,omitempty"`
	Data      string `json:"data,omitempty"`
	Offset    int64  `json:"offset,omitempty"`
	ExitCode  *int   `json:"exit_code,omitempty"`
	Error     string `json:"error,omitempty"`
	Code      string `json:"code,omitempty"`
	Timestamp int64  `json:"timestamp,omitempty"`
}

// Binary WebSocket frame type bytes — prefix byte for all binary frames.
const (
	BinStdin  byte = 0x00 // Client → Server: raw stdin bytes
	BinStdout byte = 0x01 // Server → Client: raw stdout bytes
	BinStderr byte = 0x02 // Server → Client: raw stderr bytes (pipe mode)
	BinReplay byte = 0x03 // Server → Client: [8 bytes int64 BE offset][raw bytes]
)

// WebSocket error codes sent in ServerFrame.Code.
const (
	WSErrCodeSessionGone      = "SESSION_GONE"
	WSErrCodeStartFailed      = "START_FAILED"
	WSErrCodeStdinWriteFailed = "STDIN_WRITE_FAILED"
	WSErrCodeInvalidFrame     = "INVALID_FRAME"
	WSErrCodeAlreadyConnected = "ALREADY_CONNECTED"
	WSErrCodeTakenOver        = "TAKEN_OVER"
	WSErrCodeReadOnly         = "READ_ONLY"
	WSErrCodeViewerNotRunning = "VIEWER_REQUIRES_RUNNING_SESSION"
	WSErrCodeRuntimeError     = "RUNTIME_ERROR"
)

// WSCloseTakenOver is the WebSocket close code sent to a client whose session was
// taken over by another client (via ?takeover=1). It lives in the application-private
// range (4000–4999, RFC 6455 §7.4.2) so clients can distinguish an intentional
// handoff from a network drop and avoid auto-reconnecting into the new holder.
const WSCloseTakenOver = 4001