Discover, materialize, prune, and read Console configuration

These operations return ordinary ConsoleConfig() objects. Discovery is an explicit read of optional files; materialization fills in defaults and tool presentation; pruning removes settings equal to the selected binary's defaults. None starts interpreters, installs packages, or creates a session.

Usage

materialize_console_config(
  config = ConsoleConfig(),
  ...,
  path = NULL,
  version = NULL,
  project = getwd()
)

prune_console_config(
  config = ConsoleConfig(),
  ...,
  path = NULL,
  version = NULL,
  project = getwd()
)

discover_console_config(
  ...,
  global_file = console_global_config_file(),
  project_file = ".agents/console/config.yaml",
  config = ConsoleConfig(),
  path = NULL,
  version = NULL,
  project = getwd()
)

read_console_config(
  file,
  ...,
  config = ConsoleConfig(),
  path = NULL,
  version = NULL,
  project = getwd()
)

Arguments

config

A ConsoleConfig(). In discovery and file reads, its settings override the selected files. Explicit permissions replace inherited permission nodes. Leave its discovery property NULL for these operations.

...

Must be empty. Reserved for future use.

path

NULL, or a path to an mcp-console executable.

version

NULL, or one published mcp-console version, such as "0.0.2".

project

Existing directory to use as the child process's working directory, defaulting to getwd(). Relative config and runtime paths use this directory; the caller's working directory is unchanged.

global_file

Optional global configuration path. Defaults to config.yaml in MCP_CONSOLE_HOME, or ~/.agents/console/config.yaml.

project_file

Optional project configuration path. Defaults to .agents/console/config.yaml in project.

file

A required JSON or YAML configuration path.

Value

A ConsoleConfig() with file discovery disabled. Nested settings use the same typed constructors as manually written configurations.

Details

discover_console_config() reads global_file, then project_file, then applies config. Missing discovery files are skipped; malformed or unreadable files fail. Set either file to NULL to skip it. Relative paths use project, including paths inside the files. A leading ~ in filenames and configured paths uses Console's launch-home convention, independently of R's path.expand() and R_USER. It returns a fully materialized config with file discovery disabled, so later edits to those files do not affect launch.

materialize_console_config() fills in the settings of a manually constructed or pruned config. With no argument it materializes built-in defaults without reading configuration files. prune_console_config() removes default-valued fields recursively, retaining changed arrays, explicit empty values, and overrides needed for conditional defaults. Both return the same S7 class. Pruned omissions follow the defaults of the binary used for the next launch.

read_console_config() reads one required JSON or YAML file and materializes it without global or project discovery. Use jsonlite::toJSON(as.list(config), auto_unbox = TRUE) to serialize application settings. The launch-only choice sandbox = FALSE is not stored in that document; supply it again in config when reading for host execution.

print() shows every supplied property; as.list() provides a JSON-ready view for serialization or comparison with all.equal(). Materialize to inspect generated descriptions and signature metadata, or prune to review overrides. Materialized descriptions are literal overrides: editing visibility or permissions does not regenerate saved text. Set the affected description to NULL first.

File discovery and environment inheritance are separate. For a scheduled job, supply a config explicitly and set inherit_environment = FALSE to exclude inherited worker/resolver variables. Interpreter selection, automatic package lists, and runtime-owned cache paths remain launch policies; these operations do not create a dependency lock or snapshot the process environment.

See vignette("autonomous-report", package = "mcp.console") for a scheduled-report workflow using these operations.

Examples

if (FALSE) { # \dontrun{
# Read once, inspect, then launch exactly this configuration.
config <- discover_console_config(global_file = NULL)
print(prune_console_config(config))
send <- console_tool(config = config)

# Built-in defaults, without configuration-file discovery.
config <- materialize_console_config(ConsoleConfig(languages = "r"))
config@sandbox@filesystem <- SandboxFilesystem(read_write = "./reports")
config@tool@parameters$timeout_ms@enabled <- FALSE
config@tool@description <- "Run one R report cell."
print(prune_console_config(config))

config <- read_console_config("job.json")
} # }