omnyshell_client library

OmnyShell Client: authenticate with a Hub, discover nodes, and open exec or interactive sessions.

final client = ClientRuntime(ClientConfig(
  hubUri: Uri.parse('wss://hub.example.com:8443'),
  credentials: credentials,
));
await client.connect();
final result = await client.execute(nodeId: 'web-01', command: 'uname -a');

Classes

ActiveSessionDetachRequest: Client → Hub: detach an active (attached) session on nodeId from another connection — e.g. when a full-screen program owns the original terminal. sessionRef is an id/short-id/prefix, or empty to target the caller's sole active session. Correlated by requestId.
ActiveSessionDetachResponse: Hub → Client: the result of an active-session detach. Correlated by requestId.
ActiveSessionDetachResult: The result of ClientRuntime.detachActiveSession.
Authenticator: Validates a Credential and resolves it to a Principal.
AuthFail: Failed authentication.
AuthOk: Successful authentication, carrying the resolved identity and a session token bound to this connection.
Authorizer: Decides whether an authenticated Principal may open a session on a node.
AuthRequest: A login attempt presenting a credential.
CertGenerator: Generates the TLS certificate material an OmnyShell Hub needs to run.
CertificateIdentity: Extracts a stable public-key identity from an X.509 certificate.
Channel: One logical, bidirectional stream multiplexed over a connection.
ChannelClose: Tear down a channel.
ChannelContentSource: An OmnyDrive ContentSource backed by a node-side path reached over a drive session.
ChannelEof: Half-close a stream (typically stdin) on the channel.
ChannelExit: Node → Client: the process exited.
ChannelId: A logical channel identifier, scoped to a single physical connection.
ChannelMultiplexer: Multiplexes logical Channels over a single OmnyShellConnection.
ChannelResize: Resize the terminal of an interactive session.
ChannelSignal: Deliver a POSIX signal to the session's process.
ChannelWindow: Backpressure credit grant for a stream on a channel.
ClientConfig: Configuration for a ClientRuntime.
ClientRuntime: An embeddable OmnyShell client: authenticates with the Hub, discovers nodes, and opens exec / interactive sessions.
ClientTransferLink: A TransferLink backed by a client-side RemoteSession.
Clock: Time source used throughout OmnyShell so tests can fix now.
CmdShellDialect: Windows cmd.exe — the degraded last resort. cmd /Q disables command echo; initLine shrinks the prompt to >. The marker reports only the working directory (%CD%): git branch/status and privilege are omitted, since cmd cannot compute them inline. The token is written in two set /p pieces so it never appears verbatim in the command text.
CommandHistory: Persistent, per-key command history backed by a plain-text file.
ControlFrame: A control message frame (carried as a WebSocket text frame).
ControlMessage: Base class for every structured control message.
Credential: A credential presented during the authentication handshake.
CredentialProvider: Produces the AuthRequest a node or client sends in response to the Hub's challenge hello.
CredentialStore: On-disk store of Hub logins, keyed by Hub URL, with a remembered default.
CwdMarker: Client-side shell integration that learns the remote working directory.
CwdScan: The outcome of feeding one chunk of remote stdout to a CwdMarker.
DataFrame: A binary stream-data frame (carried as a WebSocket binary frame) with a fixed 10-byte header followed by the raw payload bytes.
DetachedSessionInfo: A user-facing view of a detached session living in a node's in-memory registry, as returned by the list API and relayed through the Hub.
DetachedSessionKillRequest: Client → Hub: terminate the caller's detached session sessionRef (an unambiguous id or prefix) on nodeId. Correlated by requestId.
DetachedSessionKillResponse: Hub → Client: the result of a detached-session kill. Correlated by requestId.
DetachedSessionKillResult: The result of ClientRuntime.killDetachedSession.
DetachedSessionsRequest: Client → Hub: list the caller's detached sessions on nodeId. Correlated to the response by requestId (a connection-level request/response RPC).
DetachedSessionsResponse: Hub → Client: the caller's detached sessions. Correlated by requestId.
DetachOutcome: The result of RemoteSession.detach: the detached session's identifiers and optional expiry, used to print the resume hint.
DriveManager: Orchestrates OmnyDrive mounts over OmnyShell drive sessions.
DriveRpcClient: Issues OmnyDrive RPCs over a SessionMode.drive RemoteSession.
Ed25519PublicKey: An Ed25519 public key, used to identify users and nodes in an authorized_keys-style trust store. Equality is by key bytes.
ErrorCodes: Stable, machine-readable error codes carried in error control messages and surfaced on OmnyShellExceptions.
ExecResult: The result of a one-shot ClientRuntime.execute.
FrameCodec: Encodes and decodes OmnyShellFrames to and from WebSocket events.
GeneratedCertificates: The paths of the TLS files produced by CertGenerator.generate.
Hello: First frame after the WebSocket upgrade. The Hub sends hello with a single-use nonce; the peer replies with its role and capabilities.
LineEditor: A raw-mode line editor with command-history navigation.
LocalCommand: A local OmnyShell command, invoked with a leading : and never forwarded to the remote shell.
LocalCommandContext: Runtime context passed to a LocalCommand.
LocalCommandRegistry: An extensible registry of local : commands.
MachineId: Reads a stable, per-machine identifier provided by the operating system.
ManifestEntry: One file in a transfer manifest (path is POSIX-relative to the transfer root; size is the uncompressed byte length).
MountRecord: A persisted record of one OmnyDrive mount the client manages.
MountStore: On-disk registry of the client's OmnyDrive mounts.
NodeActiveSessionDetach: Hub → Node: detach the principal's active session sessionRef.
NodeActiveSessionDetachResponse: Node → Hub: the result of an active-session detach. Correlated by requestId.
NodeCapabilities: What a node can do, advertised to the Hub after registration and relayed to clients during discovery.
NodeCapabilitiesMessage: Node → Hub: advertises capabilities after registration.
NodeDescriptor: A node's public description as registered with the Hub and returned by discovery (nodes list). Combines identity, platform, operator labels and advertised capabilities.
NodeDetachedSessionKillRequest: Hub → Node: terminate the principal's detached session sessionRef.
NodeDetachedSessionKillResponse: Node → Hub: the result of a detached-session kill. Correlated by requestId.
NodeDetachedSessionsRequest: Hub → Node: list the principal's detached sessions. Correlated by requestId.
NodeDetachedSessionsResponse: Node → Hub: the principal's detached sessions. Correlated by requestId.
NodeHeartbeat: Node → Hub: periodic liveness signal with a monotonic sequence number.
NodeHeartbeatAck: Hub → Node: acknowledges a heartbeat.
NodeId: Stable identity of a node, used by clients to address it (instead of a host:port). Equality is by value.
NodeListRequest: Client → Hub: requests the list of nodes the client may see.
NodeListResponse: Hub → Client: the discovered nodes.
NodeRegister: Node → Hub: registers the node's identity and platform.
NodeRegistered: Hub → Node: confirms registration.
NodeSessionDetach: Hub → Node: detach the session on the node-side channel, on behalf of principal. Mirrors SessionDetachRequest across the relay.
NodeSessionDetached: Node → Hub: the session was detached and now lives in the node registry.
NodeSessionOpen: Hub → Node: instructs the node to start a session on a node-side channel.
NodeSessionOpened: Node → Hub: the node accepted and started the session.
NodeSessionRejected: Node → Hub: the node refused the session.
NodeSessionScreenRequest: Hub → Node: fetch the current screen snapshot of the principal's session sessionRef. Correlated by requestId.
NodeSessionScreenResponse: Node → Hub: the current screen snapshot of a session. The replayable bytes (the same a resume would paint) are base64-encoded in screenBase64. Correlated by requestId.
NodeTunnelConnect: Hub → exposer (node or client): a public connection arrived; adopt channel, dial targetHost:targetPort, and bridge bytes. Reply with NodeTunnelConnected or NodeTunnelConnectFailed.
NodeTunnelConnected: Exposer → Hub: the target was dialed; the Hub may relay bytes on channel.
NodeTunnelConnectFailed: Exposer → Hub: the target dial failed; the Hub closes the public socket.
OmnyShellConnection: A duplex, frame-oriented link between two OmnyShell peers.
OmnyShellFrame: A decoded unit travelling over a connection: either a structured control message (ControlFrame) or a binary stream payload (DataFrame).
OmnyUid: A deterministic, globally-stable identifier for a node or a hub.
Ping: Application-level keepalive request, used to measure round-trip latency and detect half-open connections.
PlatformInfo: Describes the operating system and architecture a node runs on, advertised to clients during discovery and shown by the :info local command.
Pong: Reply to a Ping.
PosixShellDialect: POSIX shells (sh, bash, zsh, Git Bash, WSL): the original protocol, unchanged. Uses trap, eval, stty and a printf/git/id marker.
PowerShellDialect: Windows PowerShell (pwsh/powershell). The shell reads commands from a redirected stdin (so input is never echoed); initLine silences the per-line prompt. The marker computes git status counts and the admin flag in PowerShell and writes one line directly to the console out.
Principal: An authenticated identity, as resolved by an Authenticator.
PrincipalId: Identity of an authenticated principal (a user or a node account) as known to the Hub. Equality is by value.
ProgressBar: A single-line, carriage-return progress bar for file transfers.
ProtocolError: A connection- or channel-level error.
PtySpec: Requested pseudo-terminal geometry for an interactive shell.
PublicKeyCredential: An Ed25519 public-key credential: the client proves possession of the private key by signing the connection challenge.
PublicKeyCredentialProvider: A CredentialProvider that signs the connection nonce with an Ed25519 private key.
RemoteSession: A client-side handle to one open session on a node.
RoleBasedAuthorizer: A role-based Authorizer with a small, predictable policy:
ScreenModeDetector: Detects when the remote terminal switches into or out of the alternate screen buffer, by watching the output byte stream for the DEC private-mode sequences full-screen programs emit:
Session: A domain view of a brokered session: who opened it, on which node, in what mode, and its current state and exit code.
SessionDetached: Hub → Client: the session was detached; resume it later by shortId.
SessionDetachRequest: Client → Hub: detach the live session on channel, keeping the node-side PTY/shell/processes running. Optional timeoutSeconds schedules automatic cleanup; null keeps the session indefinitely.
SessionId: Unique identity of a brokered session, minted by the Hub when a session is opened. Equality is by value.
SessionOpen: Client → Hub: opens a session on a node over a new client channel.
SessionOpened: Hub → Client: the session is open.
SessionRejected: Hub → Client (or Node → Hub via NodeSessionRejected): the session could not be opened.
SessionScreenRequest: Client → Hub: fetch the current screen snapshot of the caller's session sessionRef (active or detached) on nodeId, without attaching to it. Correlated by requestId.
SessionScreenResponse: Hub → Client: the current screen snapshot of a session. Correlated by requestId.
SessionScreenResult: The result of ClientRuntime.peekSession: the current screen snapshot of a session, captured without attaching to it.
ShellBackend: Starts ShellSessions on a node in response to authorized session opens.
ShellDialect: Generates the shell-specific text the interactive connect/resume loop sends to a remote shell: a one-time init line, the per-command wrapper, and the prompt-completion markers.
ShellRequest: A request to start a process or interactive shell on a node.
ShellSession: A running process or shell on the node, with byte streams wired to the session channel.
StoredSession: A persisted login to a single Hub.
SyncOutcome: The outcome of a synchronization, surfaced to the CLI.
SyncProgressBar: A single-line, carriage-return progress bar for OmnyDrive sync transfers.
SystemClock: The default Clock, backed by the system wall clock (UTC).
TokenCredential: A bearer-token credential, validated against a token store. Relies on TLS for secrecy in transit.
TokenCredentialProvider: A CredentialProvider that presents a bearer token.
TransferPreflight: Snapshot handed to a confirmation hook once both ends know the manifest and resume state, but before any file is written or any data flows.
TransferProgress: Progress notification emitted while a transfer runs.
TransferResult: The outcome of a completed transfer.
TunnelCloseRequest: Client → Hub: close the caller's tunnel tunnelRef (a full id or unambiguous prefix). Correlated by requestId.
TunnelCloseResponse: Hub → Client: the result of a tunnel close. Correlated by requestId.
TunnelCloseResult: The result of ClientRuntime.closeTunnel.
TunnelHandle: A handle to an open tunnel returned by ClientRuntime.openTunnel.
TunnelInfo: A user-facing view of an active TCP tunnel held by the Hub, as returned by the list API and relayed to the owning client.
TunnelListRequest: Client → Hub: list the caller's active tunnels. Correlated by requestId.
TunnelListResponse: Hub → Client: the caller's active tunnels. Correlated by requestId.
TunnelOpened: Hub → Client: the tunnel is open and listening. Correlated by requestId.
TunnelOpenRequest: Client → Hub: open a tunnel that exposes targetHost:targetPort (reachable by nodeId, or the requesting client's own machine when nodeId is the @local sentinel) on a public Hub port. When publicPort is set the Hub validates it against its configured range; otherwise the Hub allocates a free port in range. Correlated by requestId.
TunnelRejected: Hub → Client: the tunnel was refused. Correlated by requestId.
UidComputer: Computes deterministic OmnyUids from identity material.
UidResolution: The outcome of resolving an entity's UID against its persisted value.
UidStore: Persists an entity's UID under ~/.omnyshell/<fileName> and detects changes.

Enums

ArchiveFormat: A supported download archive format.
DataOpcode: The stream a binary data frame belongs to, encoded as the msgType byte of the data-frame header.
SessionMode: How a session runs on the node.
SessionState: Lifecycle state of a session as tracked by the Hub.
ShellFamily: The command-language family of a node's interactive shell.

Constants

kDefaultGzipLevel → const int: Default GZip compression level for transfers (1=fast … 9=best).
kMinProtocolVersion → const int: The lowest protocol version this build can interoperate with.
kProtocolVersion → const int: The wire protocol version implemented by this package.
omnyShellVersion → const String: The canonical OmnyShell package version (kept in sync with pubspec.yaml).

Functions

archiveError(ArchiveFormat format, {required bool isDir}) → String?: Validates format against whether the source isDir, returning an error message to show the user, or null when the combination is allowed.
archiveExtension(ArchiveFormat format) → String: The file extension (without a leading dot) for format.
downloadPath({required ClientRuntime client, required String nodeId, required String remotePath, required String localDest, bool destIsDir = false, int gzipLevel = kDefaultGzipLevel, void onProgress(TransferProgress)?, Future<bool> confirm(TransferPreflight)?}) → Future<TransferResult>: Downloads remotePath from nodeId to the local localDest (a directory to write into, or an explicit target path — see FileTransferEngine.runReceiver; destIsDir forces directory mode), resuming any partial files and verifying each file's SHA-256.
formatSyncProgress(ProgressEvent e) → String?: Formats a sync ProgressEvent as a compact one-line status for in-session display above the prompt, or null when there is nothing useful to show.
isProtocolCompatible(int remoteVersion, {int? remoteMin}) → bool: Whether a peer advertising remoteVersion (with optional remoteMin) is compatible with this build.
launchesForegroundProgram(String line) → bool: Whether line launches an interactive foreground program that should take over the terminal (so the client switches to raw passthrough).
mayChangeCwdOrGit(String line) → bool: Whether line could change the working directory or git state, and thus warrants a prompt refresh (the marker).
newId() → String: Generates a new globally-unique identifier (UUID v4).
newSecureToken([int byteLength = 32]) → String: Returns byteLength cryptographically secure random bytes encoded as a URL-safe, unpadded base64 string.
parseArchiveFlag(String arg) → ArchiveFormat?: Parses a --… compression flag into an ArchiveFormat, or null if arg is not a recognised compression flag.
parseStatLines(String stdout) → List<StatEntry>: Parses the TYPE|SIZE|PATH lines emitted by the node's find/stat run.
remoteArchiveCommand(String src, {required ArchiveFormat format, required bool isDir}) → String: Returns a POSIX sh command that builds an archive of src (a file or directory per isDir) in format and prints the resulting temporary archive path as its only stdout line.
remoteCompletionCommand(String word, {required bool isCommand}) → String: Returns a POSIX sh command that prints completion candidates for word, one per line. When isCommand is true the word is in command position.
renderTree(String root, List<StatEntry> entries, {required int maxDepth}) → List<String>: Renders entries (rooted at the start point root) as a tree-style listing: each line carries the aggregated size, directories are listed first, and subtrees deeper than maxDepth are collapsed (their line still reports the full aggregate). maxDepth == 0 means no depth limit.
shortId(String id, [int length = 8]) → String: Derives a short, human-friendly handle from a full id.
uploadPath({required ClientRuntime client, required String nodeId, required String localPath, required String remoteDir, int gzipLevel = kDefaultGzipLevel, void onProgress(TransferProgress)?, Future<bool> confirm(TransferPreflight)?}) → Future<TransferResult>: Uploads the local localPath to remoteDir on nodeId, resuming any partial files; the node verifies each file's SHA-256 and reports failure via the session exit code.

Typedefs

ControlDecoder = ControlMessage Function(int? channelId, Map<String, dynamic> data): Decodes a control-message payload (the envelope d) for a registered type.
DriveProgress = void Function(ProgressEvent event): Sink for live sync progress, fed omnydrive ProgressEvents as each file is uploaded/downloaded (directory mounts) or as a git push/clone advances.
OmnyShellClient = ClientRuntime: Friendly alias for ClientRuntime, the embeddable OmnyShell client.
StatEntry = ({bool isDir, bool isLink, String path, int size}): A single find … -exec stat … entry: its absolute path, byte size and whether it is a directory or a symlink (leaf; never followed).

Exceptions / Errors

AuthException: Authentication failed: credentials missing, malformed or rejected.
AuthorizationException: The authenticated principal is not permitted to perform the action.
CertGeneratorException: Thrown when certificate generation cannot complete.
ChannelException: A logical channel was closed or referenced after teardown.
DriveConflictException: Raised when an automatic sync cannot proceed because both sides changed.
DriveException: A general drive-management error surfaced to the CLI.
DriveRpcException: Raised when a drive RPC returns an error response.
NodeUnavailableException: The requested node is unknown or offline.
OmnyShellException: Base type for every expected, classified failure raised by OmnyShell.
OmnyShellTimeoutException: An operation exceeded its deadline.
ProtocolException: A frame could not be decoded, or a message violated the protocol.
SessionRejectedException: A session could not be opened (rejected by the Hub or node).
TransferException: Thrown when the transfer stream ends or is malformed mid-protocol.
TransportException: The underlying transport failed or closed unexpectedly.
TunnelRejectedException: A tunnel could not be opened (rejected by the Hub).

omnyshell_client library

Classes

Enums

Constants

Functions

Typedefs

Exceptions / Errors

omnyshell package

omnyshell_client library