@slicervm/sdk 0.1.5 → 0.1.7

package/dist/index.d.cts

@@ -27,6 +27,15 @@ interface VMInfo {
     status?: string;
     persistent?: boolean;
 }
+/**
+ * Per-launch network policy override for isolated host groups.
+ * Omitted lists inherit the host group's policy. Empty lists intentionally
+ * clear that list for this VM launch.
+ */
+interface CreateVMNetworkPolicy {
+    allow?: string[];
+    drop?: string[];
+}
 interface CreateVMRequest {
     ramBytes?: number;
     cpus?: number;
@@ -39,6 +48,7 @@ interface CreateVMRequest {
     ip?: string;
     tags?: string[];
     secrets?: string[];
+    network?: CreateVMNetworkPolicy;
 }
 interface CreateVMResponse {
     hostname: string;
@@ -685,6 +695,185 @@ declare class SecretsAPI {
     delete(name: string): Promise<void>;
 }
 
+/**
+ * Slicer egress-proxy admin API.
+ *
+ * Three resources:
+ *   - clients: opaque token holders. Each VM (or other consumer) presents
+ *     the token via HTTPS_PROXY; the proxy resolves it to the client and
+ *     walks the client's allow rules.
+ *   - secrets: upstream credentials (bearer or basic). When an allow rule
+ *     references a secret, the proxy strips the client's Authorization on
+ *     the inner request and substitutes the secret's value.
+ *   - allow rules: per-client. host (exact, *.suffix wildcard, or "*"),
+ *     optional method/path filters, optional secret reference, optional
+ *     TTL, optional `passthrough` (TCP-splice CONNECT, no MITM).
+ *
+ * Calls go through slicerd's `/proxy/v1/*` broker (the same transport
+ * SlicerClient already uses for every other API), so no extra
+ * configuration is needed beyond a working SlicerClient.
+ *
+ * Wire shapes mirror the Go SDK at github.com/slicervm/sdk/proxy.go.
+ * Field-name conversion (snake_case ↔ camelCase) is handled in the
+ * `*FromWire` / `*ToWire` helpers; user-facing types are camelCase.
+ */
+
+/** Credential type for upstream injection. */
+type ProxySecretType = 'bearer' | 'basic';
+declare const ProxySecretBearer: ProxySecretType;
+/** For basic auth, the secret value must be in `user:pass` form. */
+declare const ProxySecretBasic: ProxySecretType;
+/** A registered proxy client. Tokens are never returned by list/get. */
+interface ProxyClient {
+    name: string;
+    /** RFC 3339 timestamp. */
+    createdAt: string;
+}
+/**
+ * Returned only by `clients.create`. The token is shown once and never
+ * surfaced by any other endpoint — store it now or rotate the client.
+ */
+interface ProxyClientCreated {
+    name: string;
+    token: string;
+    createdAt: string;
+}
+/**
+ * Optional input to `clients.create`. Pass `token` to bring your own
+ * literal (handy for demos and reproducible tests); omit for a
+ * server-minted high-entropy `spt_…` token (recommended).
+ */
+interface CreateProxyClientOptions {
+    token?: string;
+}
+/** A registered upstream credential. `value` is never returned. */
+interface ProxySecret {
+    name: string;
+    host: string;
+    /** Defaults to `bearer` when empty in older state files. */
+    type?: ProxySecretType;
+    createdAt: string;
+}
+interface CreateProxySecretRequest {
+    name: string;
+    host: string;
+    /** Defaults to `bearer` when omitted. */
+    type?: ProxySecretType;
+    /**
+     * Plaintext credential. For `bearer`, the raw token. For `basic`,
+     * must be in `user:pass` form (the proxy base64-encodes it on the
+     * inner request).
+     */
+    value: string;
+}
+/**
+ * Per-client allow entry. First-match-wins by declaration order.
+ *
+ * - When `secret` is set, the proxy strips the client's Authorization
+ *   on the inner request and substitutes the secret's value.
+ * - `methods`/`paths` are optional filters (any-of within each list,
+ *   all-of across lists). Empty list = any.
+ * - When `passthrough` is true, the proxy splices TCP both ways at
+ *   CONNECT without terminating TLS. Cert-pinned clients work
+ *   unchanged. Mutually exclusive with `secret`, `methods`, `paths`;
+ *   the admin API rejects rules that combine them.
+ */
+interface ProxyAllowRule {
+    host: string;
+    secret?: string;
+    methods?: string[];
+    paths?: string[];
+    /** RFC 3339 timestamp; absent / zero-value when no expiry. */
+    expires?: string;
+    passthrough?: boolean;
+}
+/** Input to `allows.add`. */
+interface AddProxyAllowRequest {
+    client: string;
+    host: string;
+    secret?: string;
+    methods?: string[];
+    paths?: string[];
+    /**
+     * Time-to-live in seconds. 0 / omitted = never expires. Resolved to
+     * an absolute `expires` timestamp on the returned rule.
+     */
+    ttlSeconds?: number;
+    /** See ProxyAllowRule.passthrough. Mutually exclusive with secret/methods/paths. */
+    passthrough?: boolean;
+}
+/**
+ * Input to `allows.removeByTuple`. Mirrors the create payload minus
+ * `ttlSeconds` (TTL is mutable lifetime, not part of identity). The
+ * proxy matches the rule by (host, methods, paths, passthrough) and
+ * removes the single matching rule. Use when several rules share a
+ * host and you want surgical removal of one — pass exactly the same
+ * fields you used at create time.
+ */
+interface RemoveProxyAllowByTupleRequest {
+    client: string;
+    host: string;
+    secret?: string;
+    methods?: string[];
+    paths?: string[];
+    passthrough?: boolean;
+}
+declare class ProxyAPI {
+    private readonly transport;
+    readonly clients: ProxyClientsAPI;
+    readonly secrets: ProxySecretsAPI;
+    readonly allows: ProxyAllowsAPI;
+    constructor(transport: TransportClient);
+}
+declare class ProxyClientsAPI {
+    private readonly transport;
+    constructor(transport: TransportClient);
+    /** Mint a new proxy client. The returned token is shown once. */
+    create(name: string, opts?: CreateProxyClientOptions): Promise<ProxyClientCreated>;
+    list(): Promise<ProxyClient[]>;
+    /**
+     * Revoke the token, drop every allow rule the client owned, and
+     * remove the client.
+     */
+    delete(name: string): Promise<void>;
+    /** List a client's allow rules in declaration order (first-match-wins). */
+    rules(name: string): Promise<ProxyAllowRule[]>;
+}
+declare class ProxySecretsAPI {
+    private readonly transport;
+    constructor(transport: TransportClient);
+    create(req: CreateProxySecretRequest): Promise<void>;
+    list(): Promise<ProxySecret[]>;
+    /**
+     * Remove a secret. Allow rules that reference it stop matching until
+     * the secret is recreated or the rule is rewritten.
+     */
+    delete(name: string): Promise<void>;
+}
+declare class ProxyAllowsAPI {
+    private readonly transport;
+    constructor(transport: TransportClient);
+    /** Add an allow rule. Returns the resolved rule with absolute `expires`. */
+    add(req: AddProxyAllowRequest): Promise<ProxyAllowRule>;
+    /**
+     * Host-bulk revoke: removes **every** rule on the client whose host
+     * matches. For surgical removal of one rule among siblings on the
+     * same host (e.g. several path-scoped rules on `github.com`), use
+     * `removeByTuple` instead.
+     */
+    remove(client: string, host: string): Promise<void>;
+    /**
+     * Surgical revoke: removes the single rule whose
+     * (host, methods, paths, passthrough) tuple matches the request.
+     * Pass exactly the same fields you used at create time. Method and
+     * host casing are normalised server-side, so `"GET"` / `"get"` and
+     * `"github.com"` / `"GITHUB.COM"` all match the same stored rule.
+     *
+     * Returns 404 (surfaced as a SlicerAPIError) when no rule matches.
+     */
+    removeByTuple(req: RemoveProxyAllowByTupleRequest): Promise<void>;
+}
+
 /**
  * SlicerClient — grouped TypeScript client for the Slicer VM API.
  *
@@ -707,9 +896,76 @@ declare class SlicerClient {
     readonly hostGroups: HostGroupsAPI;
     readonly vms: VMsAPI;
     readonly secrets: SecretsAPI;
+    readonly proxy: ProxyAPI;
     constructor(opts: SlicerClientOptions);
     static fromEnv(overrides?: Partial<SlicerClientOptions>): SlicerClient;
     getInfo(): Promise<SlicerInfo>;
 }
 
-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, 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, VMBg, 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 AddProxyAllowRequest, type AddressMapping, type AgentHealth, type BgDeleteResponse, type BgExecInfo, type BgExecRequest, type BgExecResponse, type BgKillOptions, type BgKillResponse, type BgLogOptions, type BgWaitExitResponse, type CreateProxyClientOptions, type CreateProxySecretRequest, type CreateSecretRequest, type CreateVMNetworkPolicy, 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, ProxyAPI, type ProxyAllowRule, ProxyAllowsAPI, type ProxyClient, type ProxyClientCreated, ProxyClientsAPI, type ProxySecret, ProxySecretBasic, ProxySecretBearer, type ProxySecretType, ProxySecretsAPI, type RemoveProxyAllowByTupleRequest, 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

@@ -27,6 +27,15 @@ interface VMInfo {
     status?: string;
     persistent?: boolean;
 }
+/**
+ * Per-launch network policy override for isolated host groups.
+ * Omitted lists inherit the host group's policy. Empty lists intentionally
+ * clear that list for this VM launch.
+ */
+interface CreateVMNetworkPolicy {
+    allow?: string[];
+    drop?: string[];
+}
 interface CreateVMRequest {
     ramBytes?: number;
     cpus?: number;
@@ -39,6 +48,7 @@ interface CreateVMRequest {
     ip?: string;
     tags?: string[];
     secrets?: string[];
+    network?: CreateVMNetworkPolicy;
 }
 interface CreateVMResponse {
     hostname: string;
@@ -685,6 +695,185 @@ declare class SecretsAPI {
     delete(name: string): Promise<void>;
 }
 
+/**
+ * Slicer egress-proxy admin API.
+ *
+ * Three resources:
+ *   - clients: opaque token holders. Each VM (or other consumer) presents
+ *     the token via HTTPS_PROXY; the proxy resolves it to the client and
+ *     walks the client's allow rules.
+ *   - secrets: upstream credentials (bearer or basic). When an allow rule
+ *     references a secret, the proxy strips the client's Authorization on
+ *     the inner request and substitutes the secret's value.
+ *   - allow rules: per-client. host (exact, *.suffix wildcard, or "*"),
+ *     optional method/path filters, optional secret reference, optional
+ *     TTL, optional `passthrough` (TCP-splice CONNECT, no MITM).
+ *
+ * Calls go through slicerd's `/proxy/v1/*` broker (the same transport
+ * SlicerClient already uses for every other API), so no extra
+ * configuration is needed beyond a working SlicerClient.
+ *
+ * Wire shapes mirror the Go SDK at github.com/slicervm/sdk/proxy.go.
+ * Field-name conversion (snake_case ↔ camelCase) is handled in the
+ * `*FromWire` / `*ToWire` helpers; user-facing types are camelCase.
+ */
+
+/** Credential type for upstream injection. */
+type ProxySecretType = 'bearer' | 'basic';
+declare const ProxySecretBearer: ProxySecretType;
+/** For basic auth, the secret value must be in `user:pass` form. */
+declare const ProxySecretBasic: ProxySecretType;
+/** A registered proxy client. Tokens are never returned by list/get. */
+interface ProxyClient {
+    name: string;
+    /** RFC 3339 timestamp. */
+    createdAt: string;
+}
+/**
+ * Returned only by `clients.create`. The token is shown once and never
+ * surfaced by any other endpoint — store it now or rotate the client.
+ */
+interface ProxyClientCreated {
+    name: string;
+    token: string;
+    createdAt: string;
+}
+/**
+ * Optional input to `clients.create`. Pass `token` to bring your own
+ * literal (handy for demos and reproducible tests); omit for a
+ * server-minted high-entropy `spt_…` token (recommended).
+ */
+interface CreateProxyClientOptions {
+    token?: string;
+}
+/** A registered upstream credential. `value` is never returned. */
+interface ProxySecret {
+    name: string;
+    host: string;
+    /** Defaults to `bearer` when empty in older state files. */
+    type?: ProxySecretType;
+    createdAt: string;
+}
+interface CreateProxySecretRequest {
+    name: string;
+    host: string;
+    /** Defaults to `bearer` when omitted. */
+    type?: ProxySecretType;
+    /**
+     * Plaintext credential. For `bearer`, the raw token. For `basic`,
+     * must be in `user:pass` form (the proxy base64-encodes it on the
+     * inner request).
+     */
+    value: string;
+}
+/**
+ * Per-client allow entry. First-match-wins by declaration order.
+ *
+ * - When `secret` is set, the proxy strips the client's Authorization
+ *   on the inner request and substitutes the secret's value.
+ * - `methods`/`paths` are optional filters (any-of within each list,
+ *   all-of across lists). Empty list = any.
+ * - When `passthrough` is true, the proxy splices TCP both ways at
+ *   CONNECT without terminating TLS. Cert-pinned clients work
+ *   unchanged. Mutually exclusive with `secret`, `methods`, `paths`;
+ *   the admin API rejects rules that combine them.
+ */
+interface ProxyAllowRule {
+    host: string;
+    secret?: string;
+    methods?: string[];
+    paths?: string[];
+    /** RFC 3339 timestamp; absent / zero-value when no expiry. */
+    expires?: string;
+    passthrough?: boolean;
+}
+/** Input to `allows.add`. */
+interface AddProxyAllowRequest {
+    client: string;
+    host: string;
+    secret?: string;
+    methods?: string[];
+    paths?: string[];
+    /**
+     * Time-to-live in seconds. 0 / omitted = never expires. Resolved to
+     * an absolute `expires` timestamp on the returned rule.
+     */
+    ttlSeconds?: number;
+    /** See ProxyAllowRule.passthrough. Mutually exclusive with secret/methods/paths. */
+    passthrough?: boolean;
+}
+/**
+ * Input to `allows.removeByTuple`. Mirrors the create payload minus
+ * `ttlSeconds` (TTL is mutable lifetime, not part of identity). The
+ * proxy matches the rule by (host, methods, paths, passthrough) and
+ * removes the single matching rule. Use when several rules share a
+ * host and you want surgical removal of one — pass exactly the same
+ * fields you used at create time.
+ */
+interface RemoveProxyAllowByTupleRequest {
+    client: string;
+    host: string;
+    secret?: string;
+    methods?: string[];
+    paths?: string[];
+    passthrough?: boolean;
+}
+declare class ProxyAPI {
+    private readonly transport;
+    readonly clients: ProxyClientsAPI;
+    readonly secrets: ProxySecretsAPI;
+    readonly allows: ProxyAllowsAPI;
+    constructor(transport: TransportClient);
+}
+declare class ProxyClientsAPI {
+    private readonly transport;
+    constructor(transport: TransportClient);
+    /** Mint a new proxy client. The returned token is shown once. */
+    create(name: string, opts?: CreateProxyClientOptions): Promise<ProxyClientCreated>;
+    list(): Promise<ProxyClient[]>;
+    /**
+     * Revoke the token, drop every allow rule the client owned, and
+     * remove the client.
+     */
+    delete(name: string): Promise<void>;
+    /** List a client's allow rules in declaration order (first-match-wins). */
+    rules(name: string): Promise<ProxyAllowRule[]>;
+}
+declare class ProxySecretsAPI {
+    private readonly transport;
+    constructor(transport: TransportClient);
+    create(req: CreateProxySecretRequest): Promise<void>;
+    list(): Promise<ProxySecret[]>;
+    /**
+     * Remove a secret. Allow rules that reference it stop matching until
+     * the secret is recreated or the rule is rewritten.
+     */
+    delete(name: string): Promise<void>;
+}
+declare class ProxyAllowsAPI {
+    private readonly transport;
+    constructor(transport: TransportClient);
+    /** Add an allow rule. Returns the resolved rule with absolute `expires`. */
+    add(req: AddProxyAllowRequest): Promise<ProxyAllowRule>;
+    /**
+     * Host-bulk revoke: removes **every** rule on the client whose host
+     * matches. For surgical removal of one rule among siblings on the
+     * same host (e.g. several path-scoped rules on `github.com`), use
+     * `removeByTuple` instead.
+     */
+    remove(client: string, host: string): Promise<void>;
+    /**
+     * Surgical revoke: removes the single rule whose
+     * (host, methods, paths, passthrough) tuple matches the request.
+     * Pass exactly the same fields you used at create time. Method and
+     * host casing are normalised server-side, so `"GET"` / `"get"` and
+     * `"github.com"` / `"GITHUB.COM"` all match the same stored rule.
+     *
+     * Returns 404 (surfaced as a SlicerAPIError) when no rule matches.
+     */
+    removeByTuple(req: RemoveProxyAllowByTupleRequest): Promise<void>;
+}
+
 /**
  * SlicerClient — grouped TypeScript client for the Slicer VM API.
  *
@@ -707,9 +896,76 @@ declare class SlicerClient {
     readonly hostGroups: HostGroupsAPI;
     readonly vms: VMsAPI;
     readonly secrets: SecretsAPI;
+    readonly proxy: ProxyAPI;
     constructor(opts: SlicerClientOptions);
     static fromEnv(overrides?: Partial<SlicerClientOptions>): SlicerClient;
     getInfo(): Promise<SlicerInfo>;
 }
 
-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, 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, VMBg, 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 AddProxyAllowRequest, type AddressMapping, type AgentHealth, type BgDeleteResponse, type BgExecInfo, type BgExecRequest, type BgExecResponse, type BgKillOptions, type BgKillResponse, type BgLogOptions, type BgWaitExitResponse, type CreateProxyClientOptions, type CreateProxySecretRequest, type CreateSecretRequest, type CreateVMNetworkPolicy, 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, ProxyAPI, type ProxyAllowRule, ProxyAllowsAPI, type ProxyClient, type ProxyClientCreated, ProxyClientsAPI, type ProxySecret, ProxySecretBasic, ProxySecretBearer, type ProxySecretType, ProxySecretsAPI, type RemoveProxyAllowByTupleRequest, 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 };