@slicervm/sdk 0.1.4 → 0.1.6

package/dist/index.d.cts

@@ -131,6 +131,91 @@ interface ExecResultBinary {
     exitCode: number;
     error?: string;
 }
+/**
+ * Launch parameters for a background exec. Mirrors the Go SDK's
+ * `ExecBackgroundRequest`. The child is detached at launch and survives
+ * client disconnect; manage it via `vm.bg.list/info/logs/kill/wait/remove`.
+ *
+ * `command` + `args` is the always-correct deterministic form (matches the
+ * `--cmd` / `--arg` CLI flags). For `$VAR` expansion or shell operators set
+ * `shell` to a shell path (e.g. `/bin/bash`) and pass the script as
+ * `command`; the agent runs `<shell> -lc "<command>"` in that case.
+ */
+interface BgExecRequest {
+    command: string;
+    args?: string[];
+    env?: string[];
+    uid?: number;
+    gid?: number;
+    cwd?: string;
+    /**
+     * Empty (default): direct exec. Set to a shell path (e.g. `/bin/bash`) for
+     * `$VAR` expansion, globs, and shell operators. With a shell, bash auto-
+     * `exec`s the last simple command in `-c` scripts so the daemon is the
+     * tracked PID for typical cases. Multi-statement scripts that need clean
+     * tree should write `exec` themselves.
+     */
+    shell?: string;
+    /** Per-process ring buffer cap in bytes. Zero means server default (1 MiB). */
+    ringBytes?: number;
+}
+/** Returned by `vm.bg.exec` on success. */
+interface BgExecResponse {
+    execId: string;
+    pid: number;
+    startedAt: string;
+    ringBytes: number;
+}
+/** Status of one background exec — returned by `vm.bg.list` and `vm.bg.info`. */
+interface BgExecInfo {
+    execId: string;
+    pid: number;
+    command: string;
+    args?: string[];
+    cwd?: string;
+    uid?: number;
+    startedAt: string;
+    running: boolean;
+    /** Present once the child has exited. */
+    exitCode?: number;
+    signal?: string;
+    endedAt?: string;
+    bytesWritten: number;
+    bytesDropped: number;
+    /** Next frame id the agent will emit on this exec's log ring. */
+    nextId: number;
+    ringBytes: number;
+}
+interface BgKillOptions {
+    /** Signal name (e.g. `TERM`, `KILL`, `HUP`). Default: `TERM`. */
+    signal?: string;
+    /** Grace period before the agent escalates to `SIGKILL`. Server default 5000ms. */
+    graceMs?: number;
+}
+interface BgKillResponse {
+    execId: string;
+    pid: number;
+    running: boolean;
+    signalSent: string;
+}
+interface BgWaitExitResponse {
+    execId: string;
+    running: boolean;
+    exitCode?: number;
+    signal?: string;
+    endedAt?: string;
+    timedOut: boolean;
+}
+interface BgDeleteResponse {
+    execId: string;
+    reaped: boolean;
+}
+interface BgLogOptions {
+    /** Stream live frames after replaying ring contents. */
+    follow?: boolean;
+    /** Start cursor at frame N. Lower than the live cursor replays history; higher waits (when `follow`). */
+    fromId?: number;
+}
 interface FSEntry {
     name: string;
     type: 'file' | 'directory' | 'symlink' | string;
@@ -456,6 +541,7 @@ declare class VM {
     readonly createdAt?: string;
     readonly arch?: string;
     readonly fs: VMFileSystem;
+    readonly bg: VMBg;
     private readonly transport;
     constructor(transport: TransportClient, init: VMInit);
     delete(): Promise<void>;
@@ -505,6 +591,57 @@ declare class VM {
     }): Promise<ExecResultBinary>;
     execBuffered(req: ExecRequest): Promise<ExecResult>;
 }
+/**
+ * Per-VM background-exec operations. A bg exec is detached at launch (its own
+ * session leader), survives client disconnect, and writes stdout/stderr into a
+ * per-process ring buffer on the agent. Manage one with the `execId` returned
+ * from `exec()` plus `info`, `logs`, `kill`, `wait`, `remove`. The ring stays
+ * allocated after the child exits — call `remove()` to free its budget.
+ */
+declare class VMBg {
+    private readonly transport;
+    private readonly hostname;
+    constructor(transport: TransportClient, hostname: string);
+    /**
+     * Launch a long-running process. `command` + `args` is the deterministic
+     * exec form (no shell). Set `shell: '/bin/bash'` (or similar) to opt in
+     * to shell semantics — `$VAR` expansion, globs, `&&`/`||`, etc.
+     */
+    exec(req: BgExecRequest): Promise<BgExecResponse>;
+    /** All background execs the agent currently tracks (running + exited-not-reaped). */
+    list(): Promise<BgExecInfo[]>;
+    /** Latest status snapshot for one bg exec. Throws 404 if reaped or never existed. */
+    info(execId: string): Promise<BgExecInfo>;
+    /**
+     * NDJSON log stream. Yields one frame per log line — `started`, `stdout`,
+     * `stderr`, `exit`, plus optional `gap` frames if the ring evicted history
+     * before the requested cursor. Frames carry `data` base64-encoded; the SDK
+     * also populates `dataBytes` / `stdoutBytes` / `stderrBytes` Buffers.
+     *
+     * `follow: false` (default) replays from the cursor and ends when the ring
+     * is drained. `follow: true` keeps the stream open until the child exits or
+     * the caller breaks out.
+     */
+    logs(execId: string, opts?: BgLogOptions): AsyncGenerator<ExecFrame, void, void>;
+    /**
+     * Signal a running bg exec. Default: SIGTERM with a 5 s grace period before
+     * the agent escalates to SIGKILL. No-op (running=false) if the child has
+     * already exited.
+     */
+    kill(execId: string, opts?: BgKillOptions): Promise<BgKillResponse>;
+    /**
+     * Long-poll until the child exits or `timeoutSec` elapses. Returns
+     * `timedOut: true` if the deadline hit. Server default for `timeoutSec=0`
+     * is 30 s.
+     */
+    wait(execId: string, timeoutSec?: number): Promise<BgWaitExitResponse>;
+    /**
+     * Reap a bg exec's ring buffer + registry entry. Does NOT kill a running
+     * process — pair with `kill()` for "stop and clean up". After remove,
+     * info/logs/kill/wait return 410 Gone.
+     */
+    remove(execId: string): Promise<BgDeleteResponse>;
+}
 
 /**
  * Top-level namespaces on SlicerClient: hostGroups, vms, secrets.
@@ -575,4 +712,70 @@ declare class SlicerClient {
     getInfo(): Promise<SlicerInfo>;
 }
 
-export { type AddressMapping, type AgentHealth, type CreateSecretRequest, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, type FSEntry, type FSMkdirRequest, type FSWatchEvent, type FSWatchEventType, type FSWatchRequest, Forwarder, type ForwarderListener, type ForwarderOptions, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, type Secret, SecretExistsError, SecretsAPI, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, type UpdateSecretRequest, VM, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, parseAddressMapping, resolveTransport };
+/**
+ * Browser-compatible shell adapter for Slicer VMs.
+ *
+ * Provides frame encode/decode helpers and a `SlicerShellSession` class that
+ * wires a standard browser WebSocket to an xterm.js Terminal instance using
+ * the Slicer binary shell protocol.
+ *
+ * This module intentionally avoids Node-only imports so it can be used in
+ * browser bundles.
+ */
+declare const FRAME_TYPE_DATA = 1;
+declare const FRAME_TYPE_WINDOW_SIZE = 2;
+declare const FRAME_TYPE_SHUTDOWN = 3;
+declare const FRAME_TYPE_HEARTBEAT = 4;
+declare const FRAME_TYPE_SESSION_CLOSE = 5;
+/** Encode a frame into the 5-byte-header binary protocol. */
+declare function encodeFrame(frameType: number, payload?: Uint8Array): Uint8Array;
+/** Parse a binary frame. Returns null if the data is malformed. */
+declare function parseFrame(data: ArrayBuffer): {
+    frameType: number;
+    payload: Uint8Array;
+} | null;
+interface ShellSessionOptions {
+    /** WebSocket URL for the shell endpoint (ws:// or wss://). */
+    url: string;
+    /** Heartbeat interval in ms. Default 30000. */
+    heartbeatIntervalMs?: number;
+    /** Called when connection state changes. */
+    onStateChange?: (state: 'connecting' | 'connected' | 'disconnected') => void;
+    /** Called on error. */
+    onError?: (error: string) => void;
+}
+/**
+ * Minimal xterm.js Terminal interface — only the methods SlicerShellSession
+ * actually calls. Avoids requiring @xterm/xterm as a dependency.
+ */
+interface XTermLike {
+    onData: (cb: (data: string) => void) => {
+        dispose: () => void;
+    };
+    write: (data: string) => void;
+    reset: () => void;
+    cols: number;
+    rows: number;
+}
+declare class SlicerShellSession {
+    private readonly terminal;
+    private readonly options;
+    private ws;
+    private heartbeatTimer;
+    private dataDisposable;
+    constructor(terminal: XTermLike, options: ShellSessionOptions);
+    /** True when the WebSocket is open and relaying. */
+    get connected(): boolean;
+    /** Open the WebSocket and begin relaying. */
+    connect(): void;
+    /** Send a graceful shutdown frame and close. */
+    disconnect(): void;
+    /** Send a window resize. Call this from FitAddon's onResize or a ResizeObserver. */
+    resize(cols: number, rows: number): void;
+    private sendResize;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private teardown;
+}
+
+export { type AddressMapping, type AgentHealth, type BgDeleteResponse, type BgExecInfo, type BgExecRequest, type BgExecResponse, type BgKillOptions, type BgKillResponse, type BgLogOptions, type BgWaitExitResponse, type CreateSecretRequest, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, FRAME_TYPE_DATA, FRAME_TYPE_HEARTBEAT, FRAME_TYPE_SESSION_CLOSE, FRAME_TYPE_SHUTDOWN, FRAME_TYPE_WINDOW_SIZE, type FSEntry, type FSMkdirRequest, type FSWatchEvent, type FSWatchEventType, type FSWatchRequest, Forwarder, type ForwarderListener, type ForwarderOptions, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, type Secret, SecretExistsError, SecretsAPI, type ShellSessionOptions, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, SlicerShellSession, type UpdateSecretRequest, VM, VMBg, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, type XTermLike, encodeFrame, parseAddressMapping, parseFrame, resolveTransport };

package/dist/index.d.ts

@@ -131,6 +131,91 @@ interface ExecResultBinary {
     exitCode: number;
     error?: string;
 }
+/**
+ * Launch parameters for a background exec. Mirrors the Go SDK's
+ * `ExecBackgroundRequest`. The child is detached at launch and survives
+ * client disconnect; manage it via `vm.bg.list/info/logs/kill/wait/remove`.
+ *
+ * `command` + `args` is the always-correct deterministic form (matches the
+ * `--cmd` / `--arg` CLI flags). For `$VAR` expansion or shell operators set
+ * `shell` to a shell path (e.g. `/bin/bash`) and pass the script as
+ * `command`; the agent runs `<shell> -lc "<command>"` in that case.
+ */
+interface BgExecRequest {
+    command: string;
+    args?: string[];
+    env?: string[];
+    uid?: number;
+    gid?: number;
+    cwd?: string;
+    /**
+     * Empty (default): direct exec. Set to a shell path (e.g. `/bin/bash`) for
+     * `$VAR` expansion, globs, and shell operators. With a shell, bash auto-
+     * `exec`s the last simple command in `-c` scripts so the daemon is the
+     * tracked PID for typical cases. Multi-statement scripts that need clean
+     * tree should write `exec` themselves.
+     */
+    shell?: string;
+    /** Per-process ring buffer cap in bytes. Zero means server default (1 MiB). */
+    ringBytes?: number;
+}
+/** Returned by `vm.bg.exec` on success. */
+interface BgExecResponse {
+    execId: string;
+    pid: number;
+    startedAt: string;
+    ringBytes: number;
+}
+/** Status of one background exec — returned by `vm.bg.list` and `vm.bg.info`. */
+interface BgExecInfo {
+    execId: string;
+    pid: number;
+    command: string;
+    args?: string[];
+    cwd?: string;
+    uid?: number;
+    startedAt: string;
+    running: boolean;
+    /** Present once the child has exited. */
+    exitCode?: number;
+    signal?: string;
+    endedAt?: string;
+    bytesWritten: number;
+    bytesDropped: number;
+    /** Next frame id the agent will emit on this exec's log ring. */
+    nextId: number;
+    ringBytes: number;
+}
+interface BgKillOptions {
+    /** Signal name (e.g. `TERM`, `KILL`, `HUP`). Default: `TERM`. */
+    signal?: string;
+    /** Grace period before the agent escalates to `SIGKILL`. Server default 5000ms. */
+    graceMs?: number;
+}
+interface BgKillResponse {
+    execId: string;
+    pid: number;
+    running: boolean;
+    signalSent: string;
+}
+interface BgWaitExitResponse {
+    execId: string;
+    running: boolean;
+    exitCode?: number;
+    signal?: string;
+    endedAt?: string;
+    timedOut: boolean;
+}
+interface BgDeleteResponse {
+    execId: string;
+    reaped: boolean;
+}
+interface BgLogOptions {
+    /** Stream live frames after replaying ring contents. */
+    follow?: boolean;
+    /** Start cursor at frame N. Lower than the live cursor replays history; higher waits (when `follow`). */
+    fromId?: number;
+}
 interface FSEntry {
     name: string;
     type: 'file' | 'directory' | 'symlink' | string;
@@ -456,6 +541,7 @@ declare class VM {
     readonly createdAt?: string;
     readonly arch?: string;
     readonly fs: VMFileSystem;
+    readonly bg: VMBg;
     private readonly transport;
     constructor(transport: TransportClient, init: VMInit);
     delete(): Promise<void>;
@@ -505,6 +591,57 @@ declare class VM {
     }): Promise<ExecResultBinary>;
     execBuffered(req: ExecRequest): Promise<ExecResult>;
 }
+/**
+ * Per-VM background-exec operations. A bg exec is detached at launch (its own
+ * session leader), survives client disconnect, and writes stdout/stderr into a
+ * per-process ring buffer on the agent. Manage one with the `execId` returned
+ * from `exec()` plus `info`, `logs`, `kill`, `wait`, `remove`. The ring stays
+ * allocated after the child exits — call `remove()` to free its budget.
+ */
+declare class VMBg {
+    private readonly transport;
+    private readonly hostname;
+    constructor(transport: TransportClient, hostname: string);
+    /**
+     * Launch a long-running process. `command` + `args` is the deterministic
+     * exec form (no shell). Set `shell: '/bin/bash'` (or similar) to opt in
+     * to shell semantics — `$VAR` expansion, globs, `&&`/`||`, etc.
+     */
+    exec(req: BgExecRequest): Promise<BgExecResponse>;
+    /** All background execs the agent currently tracks (running + exited-not-reaped). */
+    list(): Promise<BgExecInfo[]>;
+    /** Latest status snapshot for one bg exec. Throws 404 if reaped or never existed. */
+    info(execId: string): Promise<BgExecInfo>;
+    /**
+     * NDJSON log stream. Yields one frame per log line — `started`, `stdout`,
+     * `stderr`, `exit`, plus optional `gap` frames if the ring evicted history
+     * before the requested cursor. Frames carry `data` base64-encoded; the SDK
+     * also populates `dataBytes` / `stdoutBytes` / `stderrBytes` Buffers.
+     *
+     * `follow: false` (default) replays from the cursor and ends when the ring
+     * is drained. `follow: true` keeps the stream open until the child exits or
+     * the caller breaks out.
+     */
+    logs(execId: string, opts?: BgLogOptions): AsyncGenerator<ExecFrame, void, void>;
+    /**
+     * Signal a running bg exec. Default: SIGTERM with a 5 s grace period before
+     * the agent escalates to SIGKILL. No-op (running=false) if the child has
+     * already exited.
+     */
+    kill(execId: string, opts?: BgKillOptions): Promise<BgKillResponse>;
+    /**
+     * Long-poll until the child exits or `timeoutSec` elapses. Returns
+     * `timedOut: true` if the deadline hit. Server default for `timeoutSec=0`
+     * is 30 s.
+     */
+    wait(execId: string, timeoutSec?: number): Promise<BgWaitExitResponse>;
+    /**
+     * Reap a bg exec's ring buffer + registry entry. Does NOT kill a running
+     * process — pair with `kill()` for "stop and clean up". After remove,
+     * info/logs/kill/wait return 410 Gone.
+     */
+    remove(execId: string): Promise<BgDeleteResponse>;
+}
 
 /**
  * Top-level namespaces on SlicerClient: hostGroups, vms, secrets.
@@ -575,4 +712,70 @@ declare class SlicerClient {
     getInfo(): Promise<SlicerInfo>;
 }
 
-export { type AddressMapping, type AgentHealth, type CreateSecretRequest, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, type FSEntry, type FSMkdirRequest, type FSWatchEvent, type FSWatchEventType, type FSWatchRequest, Forwarder, type ForwarderListener, type ForwarderOptions, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, type Secret, SecretExistsError, SecretsAPI, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, type UpdateSecretRequest, VM, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, parseAddressMapping, resolveTransport };
+/**
+ * Browser-compatible shell adapter for Slicer VMs.
+ *
+ * Provides frame encode/decode helpers and a `SlicerShellSession` class that
+ * wires a standard browser WebSocket to an xterm.js Terminal instance using
+ * the Slicer binary shell protocol.
+ *
+ * This module intentionally avoids Node-only imports so it can be used in
+ * browser bundles.
+ */
+declare const FRAME_TYPE_DATA = 1;
+declare const FRAME_TYPE_WINDOW_SIZE = 2;
+declare const FRAME_TYPE_SHUTDOWN = 3;
+declare const FRAME_TYPE_HEARTBEAT = 4;
+declare const FRAME_TYPE_SESSION_CLOSE = 5;
+/** Encode a frame into the 5-byte-header binary protocol. */
+declare function encodeFrame(frameType: number, payload?: Uint8Array): Uint8Array;
+/** Parse a binary frame. Returns null if the data is malformed. */
+declare function parseFrame(data: ArrayBuffer): {
+    frameType: number;
+    payload: Uint8Array;
+} | null;
+interface ShellSessionOptions {
+    /** WebSocket URL for the shell endpoint (ws:// or wss://). */
+    url: string;
+    /** Heartbeat interval in ms. Default 30000. */
+    heartbeatIntervalMs?: number;
+    /** Called when connection state changes. */
+    onStateChange?: (state: 'connecting' | 'connected' | 'disconnected') => void;
+    /** Called on error. */
+    onError?: (error: string) => void;
+}
+/**
+ * Minimal xterm.js Terminal interface — only the methods SlicerShellSession
+ * actually calls. Avoids requiring @xterm/xterm as a dependency.
+ */
+interface XTermLike {
+    onData: (cb: (data: string) => void) => {
+        dispose: () => void;
+    };
+    write: (data: string) => void;
+    reset: () => void;
+    cols: number;
+    rows: number;
+}
+declare class SlicerShellSession {
+    private readonly terminal;
+    private readonly options;
+    private ws;
+    private heartbeatTimer;
+    private dataDisposable;
+    constructor(terminal: XTermLike, options: ShellSessionOptions);
+    /** True when the WebSocket is open and relaying. */
+    get connected(): boolean;
+    /** Open the WebSocket and begin relaying. */
+    connect(): void;
+    /** Send a graceful shutdown frame and close. */
+    disconnect(): void;
+    /** Send a window resize. Call this from FitAddon's onResize or a ResizeObserver. */
+    resize(cols: number, rows: number): void;
+    private sendResize;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private teardown;
+}
+
+export { type AddressMapping, type AgentHealth, type BgDeleteResponse, type BgExecInfo, type BgExecRequest, type BgExecResponse, type BgKillOptions, type BgKillResponse, type BgLogOptions, type BgWaitExitResponse, type CreateSecretRequest, type CreateVMOptions, type CreateVMRequest, type CreateVMResponse, type DeleteResponse, type ExecFrame, type ExecRequest, type ExecResult, type ExecResultBinary, type ExecStdio, ExecStdioBase64, ExecStdioText, FRAME_TYPE_DATA, FRAME_TYPE_HEARTBEAT, FRAME_TYPE_SESSION_CLOSE, FRAME_TYPE_SHUTDOWN, FRAME_TYPE_WINDOW_SIZE, type FSEntry, type FSMkdirRequest, type FSWatchEvent, type FSWatchEventType, type FSWatchRequest, Forwarder, type ForwarderListener, type ForwarderOptions, GiB, type HostGroup, HostGroupsAPI, type ListOptions, MiB, NonRootUser, type Secret, SecretExistsError, SecretsAPI, type ShellSessionOptions, type ShutdownRequest, SlicerAPIError, SlicerClient, type SlicerClientOptions, type SlicerInfo, SlicerShellSession, type UpdateSecretRequest, VM, VMBg, VMFileSystem, type VMInfo, type VMInit, type VMLogs, type VMSnapshot, type VMStat, VMsAPI, type WaitOptions, type XTermLike, encodeFrame, parseAddressMapping, parseFrame, resolveTransport };