start method

@override Future<ShellSession> start(ShellRequest request)

Starts a session for request, returning a live ShellSession.

May throw if the command is invalid or the node is at capacity; the node runtime translates failures into a node.session.rejected message.

Implementation

@override
Future<ShellSession> start(ShellRequest request) async {
  final spec = request.pty;
  if (spec == null || !_scriptUsable) {
    return fallback.start(request);
  }

  if (allowCommand != null && !allowCommand!(request)) {
    throw ProcessException(
      request.command ?? defaultShell,
      request.args,
      'Command not permitted by node policy',
    );
  }

  try {
    final script = _scriptPath();
    if (script == null) throw StateError('script(1) not found');
    final (executable, args) = _scriptInvocation(request, spec);
    final process = await Process.start(
      script,
      args,
      workingDirectory: request.cwd ?? workingDirectory,
      environment: {
        ...baseEnvironment,
        ..._environment(spec),
        ...request.env,
      },
      includeParentEnvironment: true,
    );
    return ScriptPtyShellSession(process);
  } on Object catch (e) {
    // Disable the `script` path for the rest of the process and fall back so
    // the session still works (with env-var geometry) instead of being
    // rejected.
    _scriptUsable = false;
    onWarning?.call(
      'script PTY backend unavailable, using pipe fallback: $e',
    );
    return fallback.start(request);
  }
}