LocalCommandContext class

Runtime context passed to a LocalCommand.

Exposes the connected client, the target node's metadata, the live session and a line-oriented output sink. Commands call requestExit to end the interactive session.

Constructors

LocalCommandContext({required NodeDescriptor node, required DateTime startedAt, required void writeLine(String line), ClientRuntime? client, Principal? principal, RemoteSession? session, ShellFamily? shellFamily, Clock clock = const SystemClock(), Future<String> readLine(String prompt)?, String? currentRemoteCwd()?, void printAbove(String line)?, LocalCommandRegistry? registry, Future<SessionCommandResult> runInSession(String command)?, void onInterruptRequest(void handler()?)?, String horizontalRule()?, Future<void> runFullScreen(Future<void> body(Stream<List<int>> input))?})
Creates a command context.

Properties

client → ClientRuntime?
The connected client runtime, or null in local mode (omnyshell local), which runs the shell on this machine with no Hub. Commands that genuinely need a Hub connection read requireClient; commands installed in local mode must not touch the client.
final
clock → Clock
The clock used for duration/latency reporting.
final
currentRemoteCwd → String? Function()?
Returns the current remote working directory, if known, so commands can resolve relative remote paths. null when unavailable.
final
detachRequested → bool
Whether a command detached the session (the remote shell keeps running). When set, the host must drop the connection without closing the session.
no setter
exitRequested → bool
Whether a command requested the session to end.
no setter
hashCode → int
The hash code for this object.
no setterinherited
horizontalRule → String Function()?
Returns a horizontal-rule string sized to the terminal, for commands that frame their output (e.g. the AI agent brackets its run with a rule). null when the host does not provide one.
final
node → NodeDescriptor
The node the session is attached to.
final
onInterruptRequest → void Function(void handler()?)?
Registers handler to run when the user presses Ctrl-C while this command is executing (e.g. so the AI agent can offer to abort), or clears it with null. The host only invokes the handler when no remote command is in flight (otherwise Ctrl-C interrupts that command). null when the host has no interrupt channel.
final
principal → Principal?
The authenticated principal, if known.
final
printAbove → void Function(String line)?
Emits a line of asynchronous/background output without disturbing the active input line (e.g. a background :drive watch reporting a sync). null when the host cannot repaint around output; callers then fall back to writeLine.
final
readLine → Future<String> Function(String prompt)?
Reads a line of user input after writing prompt; null when the host cannot prompt (commands then assume a non-interactive default).
final
registry → LocalCommandRegistry?
The registry the command was dispatched from, so :help can list the exact command set the embedder installed (which may include commands beyond the browser-safe defaults, e.g. the CLI's file-transfer commands). null falls back to the default set.
final
requireClient → ClientRuntime
The connected client, or throws when the context has none (local mode). Used by commands that require a Hub connection; those commands are never installed in local mode, so this never throws in practice.
no setter
runFullScreen → Future<void> Function(Future<void> body(Stream<List<int>> input))?
Runs body with exclusive ownership of the terminal for a full-screen takeover (e.g. the :ide TUI's alternate-screen UI): the host pauses its line editor and forwards raw input bytes to body via the stream it receives, so body reads keystrokes and paints the whole screen, then the prompt is restored when body returns. body must read from the provided stream rather than stdin directly (stdin is single-subscription and is already owned by the host). null when the host cannot grant exclusive terminal access (the web client, non-interactive runs); commands that need it should report that they require an interactive terminal.
final
runInSession → Future<SessionCommandResult> Function(String command)?
Runs command in the host's current interactive shell session (with its PTY, cwd/env and cached credentials), returning its captured output and exit code. Used by the AI agent so its commands behave like the user typed them. null when the host has no live interactive session to run in (the web client, non-interactive runs, or non-POSIX shells) — callers then fall back to a one-off exec.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
session → RemoteSession?
The active interactive session, if one is open.
final
shellFamily → ShellFamily?
The command-language family of the host's shell, used by the AI agent to pick its command syntax when there is no live session to read it from (notably local mode). null falls back to the session's family, then POSIX.
final
startedAt → DateTime
When the interactive session started.
final
writeLine → void Function(String line)
Writes a line of output back to the user.
final

Methods

noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
requestDetach() → void
Requests that the host leave the interactive session because it was detached: the connection should be dropped but the session left running.
requestExit() → void
Requests that the interactive session terminate (closing the remote shell).
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited