omnyshell_node library

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.
AiConfigRequest: Client → Hub: ask for the Hub's default AI configuration (provider/model and agent defaults) so a browser embedder can offer "use the Hub default" without ever seeing an API key. Correlated by requestId.
AiConfigResponse: Hub → Client: the Hub's default AI configuration. Never carries an API key — the key stays on the Hub and is injected when proxying. available is false when the Hub has no AI provider configured. Correlated by requestId.
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.
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.
Clock: Time source used throughout OmnyShell so tests can fix now.
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.
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.
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.
DriveCredentialEntry: One masked git-credential entry returned by a list (secrets never leave the node — description is the credential's masked toString).
DriveCredentialRequest: Client → Hub: manage the caller's own git credentials on nodeId.
DriveCredentialResponse: Hub → Client: the result of a drive-credential operation. Correlated by requestId.
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.
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.
HttpProxyRequest: Client → Hub: make an outbound HTTPS request to an AI provider on the client's behalf (the browser cannot, due to CORS). The Hub validates the target against an allowlist, optionally injects credentials, and replies with an HttpProxyResponse. Correlated by requestId.
HttpProxyResponse: Hub → Client: the result of a proxied AI request. On a transport-level failure (rejected host, timeout, DNS) error is set and statusCode is 0. Correlated by requestId.
MachineId: Reads a stable, per-machine identifier provided by the operating system.
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.
NodeConfig: Configuration for a NodeRuntime.
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.
NodeDriveCredentialRequest: Hub → Node: manage principal's git credentials. The principal is stamped by the hub from the authenticated peer; the node only ever mutates that principal's scope. Correlated by requestId.
NodeDriveCredentialResponse: Node → Hub: the result of a drive-credential operation. entries carries the masked credential list for list. 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.
NodeProfile: A node's environment profile, persisted at ~/.omnyshell/profile.yaml and applied as the baseEnvironment of every shell/exec session the node serves.
NodeRegister: Node → Hub: registers the node's identity and platform.
NodeRegistered: Hub → Node: confirms registration.
NodeRuntime: An embeddable OmnyShell node: maintains a secure connection to the Hub, registers, advertises capabilities, and serves sessions, reconnecting with backoff if the connection drops.
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.
PathDiff: The difference between an old and new PATH, for the confirmation prompt.
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.
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.
ProcessShellBackend: A ShellBackend that runs commands and interactive shells as OS processes.
ProcessShellSession: A ShellSession backed by an OS process started with Process.start.
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.
ReconnectPolicy: Computes reconnect delays with exponential backoff and jitter.
RoleBasedAuthorizer: A role-based Authorizer with a small, predictable policy:
ScriptPtyShellBackend: A ShellBackend that runs interactive shells on a real pseudo-terminal allocated by the system script(1) utility — without dart:ffi or any native library.
ScriptPtyShellSession: A ShellSession backed by a real pseudo-terminal allocated by the system script(1) utility, which runs as an ordinary child Process.
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.
ShellBackend: Starts ShellSessions on a node in response to authorized session opens.
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.
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.
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.
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.
WinptyShellBackend: A ShellBackend that runs interactive shells on a real Windows pseudo-console allocated through libwinpty (winpty.dll, bundled with Git for Windows) via dart:ffi.
WinptyShellSession: A ShellSession backed by a real Windows pseudo-console allocated through libwinpty (winpty.dll) via dart:ffi.

Enums

DataOpcode: The stream a binary data frame belongs to, encoded as the msgType byte of the data-frame header.
HttpProxyCredentialMode: How the Hub should authenticate a proxied AI request.
NodeState: The lifecycle state of a NodeRuntime.
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

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

captureLoginPath({required String shell, Duration timeout = const Duration(seconds: 10)}) → Future<String?>: Runs shell as a login+interactive shell and returns the PATH it exports, or null on Windows, when script/the shell fails, on timeout, or when the markers are missing.
isProtocolCompatible(int remoteVersion, {int? remoteMin}) → bool: Whether a peer advertising remoteVersion (with optional remoteMin) is compatible with this build.
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.
pathDiff(String? oldPath, String newPath) → PathDiff: Computes the PathDiff between oldPath (may be null) and newPath.
rcFileFor(String shell) → String: Best-effort rc file path shown to the user for shell (display only).
shortId(String id, [int length = 8]) → String: Derives a short, human-friendly handle from a full id.
uniquePath(String path) → String: Returns path with empty and duplicate entries removed, keeping the first occurrence of each (order preserved). Used so the exported profile PATH never carries repeats a login shell may have accumulated.

Typedefs

ControlDecoder = ControlMessage Function(int? channelId, Map<String, dynamic> data): Decodes a control-message payload (the envelope d) for a registered type.
OmnyShellNode = NodeRuntime: Friendly alias for NodeRuntime, the embeddable OmnyShell node.

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.
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).
TransportException: The underlying transport failed or closed unexpectedly.
TunnelRejectedException: A tunnel could not be opened (rejected by the Hub).

omnyshell_node library

Classes

Enums

Constants

Functions

Typedefs

Exceptions / Errors

omnyshell package

omnyshell_node library