1910 lines · 46.6 KB · TypeScript
RawDownload
import {	type LiveSidecarRequestPayload,	type LiveSidecarResponsePayload,} from "./callbacks.js";import type { MountConfigJsonObject } from "./descriptors.js";import { type LiveSidecarEventSelector } from "./event-buffer.js";import {	decodeGuestFilesystemContent,	encodeGuestFilesystemContent,	type LiveRootFilesystemEntry,	type LiveRootFilesystemEntryEncoding,	type LiveRootFilesystemLowerDescriptor,} from "./filesystem.js";import type { CreateVmConfig } from "./generated/CreateVmConfig.js";import type { SidecarProcessTransport } from "./sidecar-client.js";import { type LiveOwnershipScope } from "./ownership.js";import {	type LiveFsPermissionRule,	type LivePatternPermissionRule,	type LivePermissionMode,	type LivePermissionScope,	type LivePermissionsPolicy,	type LiveRulePermissions,} from "./permissions.js";import { SIDECAR_PROTOCOL_SCHEMA } from "./protocol-schema.js";import type {	LiveFilesystemOperation,	LiveGuestRuntimeKind,	LiveWasmPermissionTier,} from "./protocol-maps.js";import {	type LiveEventFrame,	type LiveSidecarRequestHandler,	type LiveRequestFrame,	type LiveResponseFrame,	type LiveSidecarRequestFrame,	type LiveSidecarResponseFrame,	type ProtocolFramePayloadCodec,} from "./protocol-frames.js";import { type LiveRequestPayload } from "./request-payloads.js";import type { LiveGuestDirEntry } from "./response-payloads.js";import {	type LiveGuestFilesystemStat,	type LiveProcessSnapshotEntry,	type LiveSocketStateEntry,} from "./state.js";export {	SidecarProcessError,	SidecarProcessExited,	SidecarSilenceTimeout,} from "./sidecar-errors.js";export { SidecarEventBufferOverflow } from "./event-buffer.js";// `Sidecar` is the public name for the native sidecar process client. The class// is `SidecarProcess` internally; consumers import it as `Sidecar` via the// `@rivet-dev/agentos-runtime-core/sidecar-client` subpath and the package root.export { SidecarProcess as Sidecar }; const BRIDGE_CONTRACT_VERSION = 1; const DEFAULT_SIDECAR_EVENT_BUFFER_CAPACITY = 4_096;const DEFAULT_SIDECAR_GRACEFUL_EXIT_MS = 5_000;const DEFAULT_SIDECAR_FORCE_EXIT_MS = 2_000; type OwnershipScope = LiveOwnershipScope; type GuestRuntimeKind = Extract<	LiveGuestRuntimeKind,	"java_script" | "python" | "web_assembly">;type WasmPermissionTier = LiveWasmPermissionTier;type RootFilesystemEntryEncoding = LiveRootFilesystemEntryEncoding; type RootFilesystemDescriptor = {	mode?: "ephemeral" | "read_only";	disableDefaultBaseLayer?: boolean;	lowers?: RootFilesystemLowerDescriptor[];	bootstrapEntries?: RootFilesystemEntry[];}; export interface RootFilesystemEntry extends LiveRootFilesystemEntry {} export interface RootFilesystemLowerDescriptor {	kind: "snapshot" | "bundled_base_filesystem";	entries?: RootFilesystemEntry[];} type WireRootFilesystemLowerDescriptor = LiveRootFilesystemLowerDescriptor;type WireRootFilesystemEntry = LiveRootFilesystemEntry; export interface GuestFilesystemStat extends LiveGuestFilesystemStat {} export interface SidecarSocketStateEntry {	processId: string;	host?: string;	port?: number;	path?: string;} export interface SidecarSignalHandlerRegistration {	action: "default" | "ignore" | "user";	mask: number[];	flags: number;} export interface SidecarSignalState {	processId: string;	handlers: Map<number, SidecarSignalHandlerRegistration>;} export interface SidecarProcessSnapshotEntry {	processId: string;	pid: number;	ppid: number;	pgid: number;	sid: number;	driver: string;	command: string;	args: string[];	cwd: string;	status: "running" | "exited" | "stopped";	exitCode: number | null;} export interface SidecarQueueSnapshotEntry {	name: string;	category: string;	depth: number;	highWater: number;	capacity: number;	fillPercent: number;} export interface SidecarResourceSnapshot {	runningProcesses: number;	exitedProcesses: number;	fdTables: number;	openFds: number;	pipes: number;	pipeBufferedBytes: number;	ptys: number;	ptyBufferedInputBytes: number;	ptyBufferedOutputBytes: number;	sockets: number;	socketListeners: number;	socketConnections: number;	socketBufferedBytes: number;	socketDatagramQueueLen: number;	queueSnapshots: SidecarQueueSnapshotEntry[];} export interface SidecarZombieTimerCount {	count: number;} export interface SidecarRegisteredHostCallbackExample {	description: string;	input: unknown;} export interface SidecarRegisteredHostCallbackDefinition {	description: string;	inputSchema: unknown;	timeoutMs?: number;	examples?: SidecarRegisteredHostCallbackExample[];} export interface ExtEnvelope {	namespace: string;	payload: Uint8Array;} type RequestPayload = LiveRequestPayload; export type SidecarRequestPayload = LiveSidecarRequestPayload; export type SidecarResponsePayload = LiveSidecarResponsePayload; type RequestFrame = LiveRequestFrame; type EventFrame = LiveEventFrame; export type SidecarEventSelector = LiveSidecarEventSelector; export type SidecarRequestFrame = LiveSidecarRequestFrame; type ResponseFrame = LiveResponseFrame; export type SidecarResponseFrame = LiveSidecarResponseFrame; type NativeTransportPayloadCodec = ProtocolFramePayloadCodec; export type SidecarRequestHandler = LiveSidecarRequestHandler; export interface SidecarSpawnOptions {	cwd?: string;	command?: string;	args?: string[];	eventBufferCapacity?: number;	gracefulExitMs?: number;	forceExitMs?: number;	// Migration-only compatibility path for pre-BARE test fixtures.	payloadCodec?: NativeTransportPayloadCodec;	/**	 * Override the sidecar silence watchdog window (default 30s). Tests only —	 * it is a fixed protocol constant paired with the sidecar's 10s heartbeat	 * cadence, not an operator tunable.	 */	silenceTimeoutMs?: number;} export interface ResolvedSidecarSpawnOptions {	cwd?: string;	command?: string;	args: string[];	eventBufferCapacity: number;	gracefulExitMs: number;	forceExitMs: number;	disposedErrorMessage: string;	payloadCodec: NativeTransportPayloadCodec;	silenceTimeoutMs?: number;} type SidecarProcessSpawnFactory = (	options: ResolvedSidecarSpawnOptions,) => SidecarProcessTransport; let sidecarProcessSpawnFactory: SidecarProcessSpawnFactory | null = null; export function registerSidecarProcessSpawnFactory(	factory: SidecarProcessSpawnFactory,): void {	sidecarProcessSpawnFactory = factory;} export interface AuthenticatedSession {	connectionId: string;	sessionId: string;} export interface CreatedVm {	vmId: string;} export interface SidecarSessionState {	sessionId: string;	agentType: string;	processId: string;	pid?: number;	closed: boolean;	modes?: unknown;	configOptions: unknown[];	agentCapabilities?: unknown;	agentInfo?: unknown;} export interface SidecarMountPluginDescriptor {	id: string;	config?: MountConfigJsonObject;} export interface SidecarMountDescriptor {	guestPath: string;	guestSource?: string;	guestFstype?: string;	readOnly: boolean;	plugin: SidecarMountPluginDescriptor;} export interface SidecarSoftwareDescriptor {	packageName: string;	root: string;} export type SidecarPermissionMode = LivePermissionMode; export interface SidecarFsPermissionRule extends LiveFsPermissionRule {} export interface SidecarPatternPermissionRule	extends LivePatternPermissionRule {} export interface SidecarRulePermissions<TRule>	extends LiveRulePermissions<TRule> {} export type SidecarPermissionScope<TRule> = LivePermissionScope<TRule>; export interface SidecarPermissionsPolicy {	fs?: SidecarPermissionScope<SidecarFsPermissionRule>;	network?: SidecarPermissionScope<SidecarPatternPermissionRule>;	childProcess?: SidecarPermissionScope<SidecarPatternPermissionRule>;	process?: SidecarPermissionScope<SidecarPatternPermissionRule>;	env?: SidecarPermissionScope<SidecarPatternPermissionRule>;	binding?: SidecarPermissionScope<SidecarPatternPermissionRule>;} type WirePermissionsPolicy = LivePermissionsPolicy; export interface SidecarProjectedModuleDescriptor {	packageName: string;	entrypoint: string;} export interface SidecarPackageDescriptor {	path: string;} export interface SidecarProjectedAgent {	id: string;	acpEntrypoint: string;	adapterEntrypoint: string;} export interface SidecarLinkPackageResult {	projectedCommands: SidecarProjectedCommand[];	agents: SidecarProjectedAgent[];} export interface SidecarProjectedCommand {	name: string;	guestPath: string;} export interface SidecarPackageCommands {	packageName: string;	commands: string[];} export interface SidecarVmConfiguredResponse {	appliedMounts: number;	appliedSoftware: number;	projectedCommands: SidecarProjectedCommand[];	agents: SidecarProjectedAgent[];} export interface SidecarFilesystemResult {	operation: LiveFilesystemOperation;	status: string;	payloadSizeBytes: number;}export interface SidecarPersistenceState {	key: string;	found: boolean;	payloadSizeBytes: number;}export interface SidecarPersistenceFlushed {	key: string;	committedBytes: number;} export class SidecarProcess {	private readonly protocolClient: SidecarProcessTransport; 	private constructor(protocolClient: SidecarProcessTransport) {		this.protocolClient = protocolClient;	} 	static fromClient(protocolClient: SidecarProcessTransport): SidecarProcess {		return new SidecarProcess(protocolClient);	} 	static spawn(options: SidecarSpawnOptions = {}): SidecarProcess {		if (!sidecarProcessSpawnFactory) {			throw new Error(				"native sidecar spawn is not registered; import @rivet-dev/agentos-runtime-core/native-client before calling SidecarProcess.spawn, or use SidecarProcess.fromClient",			);		}		const protocolClient = sidecarProcessSpawnFactory({			command: options.command,			args: options.args ?? [],			cwd: options.cwd,			silenceTimeoutMs: options.silenceTimeoutMs,			eventBufferCapacity:				options.eventBufferCapacity ?? DEFAULT_SIDECAR_EVENT_BUFFER_CAPACITY,			gracefulExitMs: options.gracefulExitMs ?? DEFAULT_SIDECAR_GRACEFUL_EXIT_MS,			forceExitMs: options.forceExitMs ?? DEFAULT_SIDECAR_FORCE_EXIT_MS,			disposedErrorMessage: "native sidecar disposed",			payloadCodec: options.payloadCodec ?? "bare",		});		return SidecarProcess.fromClient(protocolClient);	} 	setSidecarRequestHandler(handler: SidecarRequestHandler | null): void {		this.protocolClient.setSidecarRequestHandler(handler);	} 	onEvent(handler: (event: EventFrame) => void): () => void {		return this.protocolClient.onEvent(handler);	} 	async authenticateAndOpenSession(		sessionMetadata: Record<string, string> = {},	): Promise<AuthenticatedSession> {		const authenticated = await this.sendRequest({			ownership: {				scope: "connection",				connection_id: "client-hint",			},			payload: {				type: "authenticate",				client_name: "secure-exec-core-client",				auth_token: "secure-exec-core-client-token",				protocol_version: SIDECAR_PROTOCOL_SCHEMA.version,				bridge_version: BRIDGE_CONTRACT_VERSION,			},		});		if (authenticated.payload.type !== "authenticated") {			throw new Error(				`unexpected authenticate response: ${authenticated.payload.type}`,			);		} 		const opened = await this.sendRequest({			ownership: {				scope: "connection",				connection_id: authenticated.payload.connection_id,			},			payload: {				type: "open_session",				placement: {					kind: "shared",					pool: null,				},				metadata: sessionMetadata,			},		});		if (opened.payload.type !== "session_opened") {			throw new Error(				`unexpected open_session response: ${opened.payload.type}`,			);		} 		return {			connectionId: authenticated.payload.connection_id,			sessionId: opened.payload.session_id,		};	} 	async createVm(		session: AuthenticatedSession,		options: {			runtime: GuestRuntimeKind;			config: CreateVmConfig;		},	): Promise<CreatedVm> {		const response = await this.sendRequest({			ownership: {				scope: "session",				connection_id: session.connectionId,				session_id: session.sessionId,			},			payload: {				type: "create_vm",				runtime: options.runtime,				config: options.config,			},		});		if (response.payload.type !== "vm_created") {			throw new Error(				`unexpected create_vm response: ${response.payload.type}`,			);		} 		return {			vmId: response.payload.vm_id,		};	} 	async extensionRequest(		session: AuthenticatedSession,		vm: CreatedVm,		envelope: ExtEnvelope,	): Promise<ExtEnvelope> {		const response = await this.sendRequest({			ownership: {				scope: "vm",				connection_id: session.connectionId,				session_id: session.sessionId,				vm_id: vm.vmId,			},			payload: {				type: "ext",				envelope,			},		});		if (response.payload.type !== "ext_result") {			throw new Error(`unexpected ext response: ${response.payload.type}`);		}		return response.payload.envelope;	} 	async configureVm(		session: AuthenticatedSession,		vm: CreatedVm,		options: {			mounts?: SidecarMountDescriptor[];			software?: SidecarSoftwareDescriptor[];			permissions?: SidecarPermissionsPolicy;			moduleAccessCwd?: string;			instructions?: string[];			projectedModules?: SidecarProjectedModuleDescriptor[];			commandPermissions?: Record<string, WasmPermissionTier>;

Lines 1–500 of 1910.

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t