@rivet-dev/agentos-runtime-core 0.0.0-chdir-fix.3d9feab

package/dist/sidecar-process.d.ts

@@ -0,0 +1,360 @@
+import { type LiveSidecarRequestPayload, type LiveSidecarResponsePayload } from "./callbacks.js";
+import type { MountConfigJsonObject } from "./descriptors.js";
+import { type LiveSidecarEventSelector } from "./event-buffer.js";
+import { type LiveRootFilesystemEntry } from "./filesystem.js";
+import type { CreateVmConfig } from "./generated/CreateVmConfig.js";
+import type { SidecarProcessTransport } from "./sidecar-client.js";
+import { type LiveFsPermissionRule, type LivePatternPermissionRule, type LivePermissionMode, type LivePermissionScope, type LiveRulePermissions } from "./permissions.js";
+import type { LiveFilesystemOperation, LiveGuestRuntimeKind, LiveWasmPermissionTier } from "./protocol-maps.js";
+import { type LiveEventFrame, type LiveSidecarRequestHandler, type LiveSidecarRequestFrame, type LiveSidecarResponseFrame, type ProtocolFramePayloadCodec } from "./protocol-frames.js";
+import type { LiveGuestDirEntry } from "./response-payloads.js";
+import { type LiveGuestFilesystemStat } from "./state.js";
+export { SidecarProcessError, SidecarProcessExited, SidecarSilenceTimeout, } from "./sidecar-errors.js";
+export { SidecarEventBufferOverflow } from "./event-buffer.js";
+export { SidecarProcess as Sidecar };
+type GuestRuntimeKind = Extract<LiveGuestRuntimeKind, "java_script" | "python" | "web_assembly">;
+type WasmPermissionTier = LiveWasmPermissionTier;
+export interface RootFilesystemEntry extends LiveRootFilesystemEntry {
+}
+export interface RootFilesystemLowerDescriptor {
+    kind: "snapshot" | "bundled_base_filesystem";
+    entries?: RootFilesystemEntry[];
+}
+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;
+}
+export type SidecarRequestPayload = LiveSidecarRequestPayload;
+export type SidecarResponsePayload = LiveSidecarResponsePayload;
+type EventFrame = LiveEventFrame;
+export type SidecarEventSelector = LiveSidecarEventSelector;
+export type SidecarRequestFrame = LiveSidecarRequestFrame;
+export type SidecarResponseFrame = LiveSidecarResponseFrame;
+type NativeTransportPayloadCodec = ProtocolFramePayloadCodec;
+export type SidecarRequestHandler = LiveSidecarRequestHandler;
+export interface SidecarSpawnOptions {
+    cwd?: string;
+    command?: string;
+    args?: string[];
+    eventBufferCapacity?: number;
+    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;
+export declare function registerSidecarProcessSpawnFactory(factory: SidecarProcessSpawnFactory): void;
+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;
+    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>;
+}
+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 declare class SidecarProcess {
+    private readonly protocolClient;
+    private constructor();
+    static fromClient(protocolClient: SidecarProcessTransport): SidecarProcess;
+    static spawn(options?: SidecarSpawnOptions): SidecarProcess;
+    setSidecarRequestHandler(handler: SidecarRequestHandler | null): void;
+    onEvent(handler: (event: EventFrame) => void): () => void;
+    authenticateAndOpenSession(sessionMetadata?: Record<string, string>): Promise<AuthenticatedSession>;
+    createVm(session: AuthenticatedSession, options: {
+        runtime: GuestRuntimeKind;
+        config: CreateVmConfig;
+    }): Promise<CreatedVm>;
+    extensionRequest(session: AuthenticatedSession, vm: CreatedVm, envelope: ExtEnvelope): Promise<ExtEnvelope>;
+    configureVm(session: AuthenticatedSession, vm: CreatedVm, options: {
+        mounts?: SidecarMountDescriptor[];
+        software?: SidecarSoftwareDescriptor[];
+        permissions?: SidecarPermissionsPolicy;
+        moduleAccessCwd?: string;
+        instructions?: string[];
+        projectedModules?: SidecarProjectedModuleDescriptor[];
+        commandPermissions?: Record<string, WasmPermissionTier>;
+        loopbackExemptPorts?: number[];
+        packages?: SidecarPackageDescriptor[];
+        packagesMountAt?: string;
+        bootstrapCommands?: string[];
+        toolShimCommands?: string[];
+    }): Promise<SidecarVmConfiguredResponse>;
+    /**
+     * Runtime dynamic `linkSoftware`: project one package into the live
+     * `/opt/agentos` tree. Returns projected command entrypoints and agents.
+     */
+    linkPackage(session: AuthenticatedSession, vm: CreatedVm, descriptor: SidecarPackageDescriptor): Promise<SidecarLinkPackageResult>;
+    providedCommands(session: AuthenticatedSession, vm: CreatedVm): Promise<SidecarPackageCommands[]>;
+    registerHostCallbacks(session: AuthenticatedSession, vm: CreatedVm, registration: {
+        name: string;
+        description: string;
+        commandAliases?: string[];
+        registryCommandAliases?: string[];
+        callbacks: Record<string, SidecarRegisteredHostCallbackDefinition>;
+    }): Promise<{
+        registration: string;
+        commandCount: number;
+    }>;
+    createLayer(session: AuthenticatedSession, vm: CreatedVm): Promise<string>;
+    sealLayer(session: AuthenticatedSession, vm: CreatedVm, layerId: string): Promise<string>;
+    importSnapshot(session: AuthenticatedSession, vm: CreatedVm, entries: RootFilesystemEntry[]): Promise<string>;
+    exportSnapshot(session: AuthenticatedSession, vm: CreatedVm, layerId: string): Promise<RootFilesystemEntry[]>;
+    createOverlay(session: AuthenticatedSession, vm: CreatedVm, options: {
+        mode?: "ephemeral" | "read_only";
+        upperLayerId?: string;
+        lowerLayerIds: string[];
+    }): Promise<string>;
+    bootstrapRootFilesystem(session: AuthenticatedSession, vm: CreatedVm, entries: RootFilesystemEntry[]): Promise<void>;
+    snapshotRootFilesystem(session: AuthenticatedSession, vm: CreatedVm): Promise<RootFilesystemEntry[]>;
+    readFile(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<Uint8Array>;
+    pread(session: AuthenticatedSession, vm: CreatedVm, path: string, offset: number, length: number): Promise<Uint8Array>;
+    writeFile(session: AuthenticatedSession, vm: CreatedVm, path: string, content: string | Uint8Array): Promise<void>;
+    mkdir(session: AuthenticatedSession, vm: CreatedVm, path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    readdir(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<string[]>;
+    readdirRecursive(session: AuthenticatedSession, vm: CreatedVm, path: string, options?: {
+        maxDepth?: number;
+    }): Promise<LiveGuestDirEntry[]>;
+    exists(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<boolean>;
+    stat(session: AuthenticatedSession, vm: CreatedVm, path: string, options?: {
+        dereference?: boolean;
+    }): Promise<GuestFilesystemStat>;
+    lstat(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<GuestFilesystemStat>;
+    rename(session: AuthenticatedSession, vm: CreatedVm, fromPath: string, toPath: string): Promise<void>;
+    realpath(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<string>;
+    removeFile(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<void>;
+    removeDir(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<void>;
+    removePath(session: AuthenticatedSession, vm: CreatedVm, path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    copyPath(session: AuthenticatedSession, vm: CreatedVm, fromPath: string, toPath: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    movePath(session: AuthenticatedSession, vm: CreatedVm, fromPath: string, toPath: string): Promise<void>;
+    symlink(session: AuthenticatedSession, vm: CreatedVm, target: string, linkPath: string): Promise<void>;
+    readLink(session: AuthenticatedSession, vm: CreatedVm, path: string): Promise<string>;
+    link(session: AuthenticatedSession, vm: CreatedVm, fromPath: string, toPath: string): Promise<void>;
+    chmod(session: AuthenticatedSession, vm: CreatedVm, path: string, mode: number): Promise<void>;
+    chown(session: AuthenticatedSession, vm: CreatedVm, path: string, uid: number, gid: number): Promise<void>;
+    utimes(session: AuthenticatedSession, vm: CreatedVm, path: string, atimeMs: number, mtimeMs: number): Promise<void>;
+    truncate(session: AuthenticatedSession, vm: CreatedVm, path: string, length: number): Promise<void>;
+    disposeVm(session: AuthenticatedSession, vm: CreatedVm): Promise<void>;
+    execute(session: AuthenticatedSession, vm: CreatedVm, options: {
+        processId: string;
+        command?: string;
+        runtime?: GuestRuntimeKind;
+        entrypoint?: string;
+        args?: string[];
+        env?: Record<string, string>;
+        cwd?: string;
+        wasmPermissionTier?: WasmPermissionTier;
+    }): Promise<{
+        pid: number | null;
+    }>;
+    writeStdin(session: AuthenticatedSession, vm: CreatedVm, processId: string, chunk: string | Uint8Array): Promise<void>;
+    resizePty(session: AuthenticatedSession, vm: CreatedVm, processId: string, cols: number, rows: number): Promise<void>;
+    closeStdin(session: AuthenticatedSession, vm: CreatedVm, processId: string): Promise<void>;
+    killProcess(session: AuthenticatedSession, vm: CreatedVm, processId: string, signal?: string): Promise<void>;
+    findListener(session: AuthenticatedSession, vm: CreatedVm, request: {
+        host?: string;
+        port?: number;
+        path?: string;
+    }): Promise<SidecarSocketStateEntry | null>;
+    getProcessSnapshot(session: AuthenticatedSession, vm: CreatedVm): Promise<SidecarProcessSnapshotEntry[]>;
+    getResourceSnapshot(session: AuthenticatedSession, vm: CreatedVm): Promise<SidecarResourceSnapshot>;
+    findBoundUdp(session: AuthenticatedSession, vm: CreatedVm, request: {
+        host?: string;
+        port?: number;
+    }): Promise<SidecarSocketStateEntry | null>;
+    vmFetch(session: AuthenticatedSession, vm: CreatedVm, request: {
+        port: number;
+        method: string;
+        path: string;
+        headersJson: string;
+        body?: string;
+    }): Promise<string>;
+    getSignalState(session: AuthenticatedSession, vm: CreatedVm, processId: string): Promise<SidecarSignalState>;
+    getZombieTimerCount(session: AuthenticatedSession, vm: CreatedVm): Promise<SidecarZombieTimerCount>;
+    hostFilesystemCall(session: AuthenticatedSession, vm: CreatedVm, request: {
+        operation: LiveFilesystemOperation;
+        path: string;
+        payloadSizeBytes: number;
+    }): Promise<SidecarFilesystemResult>;
+    persistenceLoad(session: AuthenticatedSession, key: string): Promise<SidecarPersistenceState>;
+    persistenceFlush(session: AuthenticatedSession, request: {
+        key: string;
+        payloadSizeBytes: number;
+    }): Promise<SidecarPersistenceFlushed>;
+    waitForEvent(matcher: SidecarEventSelector | ((event: EventFrame) => boolean), timeoutMs?: number, options?: {
+        signal?: AbortSignal;
+    }): Promise<EventFrame>;
+    dispose(): Promise<void>;
+    private sendRequest;
+    private guestFilesystemCall;
+}