Strict loader for host-installed provider authority.
The host document is operator-owned and separate from an application manifest. It fixes provider sources, credentials, data classes, and outer ceilings. MCP installations additionally fix transports, tool mappings, and effects; live LLM installations fix the model, cache policy, and optional sampling parameters. A manifest may later select an installed alias and narrow its authority; it cannot introduce or replace any field decoded here.
An optional limits block replaces cataloged installed ceilings, so an
operator can permit work measured in hours rather than in one bounded run.
Omitted names keep their installed default. A manifest requests only
manifest-narrowable values at or below whatever is installed here;
installed-only operational limits remain host-owned. install is required
and may be empty: a limits-only host document raises ceilings for a
provider-free application without fabricating a provider.
Loading is bounded, path-confined, duplicate-key rejecting, and side-effect free. In particular, credential declarations are validated but environment variables and files are not read. Executables are not resolved, processes are not started, and remote endpoints are not contacted. Those operations belong to the later preflight and acquisition phases.
The closed V1 source identifiers are mcp, llm, llm_replay,
ptc_trace_snapshot, ptc_private_trace_snapshot, and ptc_inspection_snapshot. LLM credentials are explicit bindings passed to
the adapter per request rather than ambient provider-specific environment
lookup. The native snapshot sources fix host-relative directories and
expose only PtcRunner's canonical or private inspection query vocabularies.
Every installation requires a public, non-secret installation_revision
matching \A[a-z][a-z0-9._-]{0,127}\z; command decoding reports its
absence before generic schema failure, including for unselected aliases.
Stdio MCP transports always run with the runtime-owned LC_ALL=C.UTF-8;
credential environment bindings cannot replace that protocol locale.
A streamable_http endpoint is settled here rather than at acquisition, so a
malformed or inadmissible URL is a host fault naming its installation instead
of the connectivity failure of an unreachable server. It requires https.
Plain http is admitted only against the literal loopback addresses
127.0.0.1 and ::1, only with allow_insecure_loopback, and only when the
transport declares neither auth nor oauth, so no configured credential
crosses a plaintext socket. The allowance is refused against an https
endpoint rather than ignored. Upstream MCP tool names are the installed
server's, so they follow PtcRunner.Kernel.MCPProtocol.valid_tool_name?/1;
only the public as name uses PtcRunner's own naming rule.
schema/0 is the canonical structural description shipped for editor and
human feedback. Runtime decoding remains authoritative for semantic checks
such as unique public tool names, credential references, reserved headers,
portable environment names, and the requirement that snapshot_identity
name a read mapping. MCP effects form the closed read/write operator
classification; server-supplied annotations cannot widen or narrow it.
Summary
Functions
Loads and semantically validates one host configuration.
Returns the generated JSON Schema 2020-12 contract for host configuration.
Types
@type installation() :: %{ source: :mcp, transport: transport(), tools: %{required(binary()) => tool()}, snapshot_identity: %{tool: binary(), field: binary()} | nil, installation_revision: binary(), installation_config_digest: binary(), ceilings: %{ timeout_ms: pos_integer(), max_catalog_tools: pos_integer(), max_result_bytes: pos_integer() }, data_class: :normal | :private_inspection, accepts_data: [:normal | :private_inspection] } | %{ source: :llm, model: binary(), credential: binary(), cache: boolean(), params: %{ optional(:temperature) => float(), optional(:seed) => non_neg_integer(), optional(:max_tokens) => pos_integer() }, installation_revision: binary(), installation_config_digest: binary(), ceilings: %{ max_request_bytes: pos_integer(), max_response_bytes: pos_integer(), max_calls: pos_integer() }, data_class: :normal | :private_inspection, accepts_data: [:normal | :private_inspection] } | %{ source: :llm_replay, fixtures: binary(), installation_revision: binary(), installation_config_digest: binary(), ceilings: %{ max_entries: pos_integer(), max_result_bytes: pos_integer(), max_calls: pos_integer() }, data_class: :normal | :private_inspection, accepts_data: [:normal | :private_inspection] } | %{ source: :ptc_trace_snapshot, directory: binary(), installation_revision: binary(), installation_config_digest: binary(), ceilings: %{ max_source_bytes: pos_integer(), max_result_bytes: pos_integer() } } | %{ source: :ptc_private_trace_snapshot, directory: binary(), installation_revision: binary(), installation_config_digest: binary(), ceilings: %{ max_source_bytes: pos_integer(), max_result_bytes: pos_integer() } } | %{ source: :ptc_inspection_snapshot, directory: binary(), installation_revision: binary(), installation_config_digest: binary(), ceilings: %{ max_files: pos_integer(), max_source_bytes: pos_integer(), max_result_bytes: pos_integer() } }
@type t() :: %PtcRunner.Kernel.HostConfig{ credentials: %{required(binary()) => credential()}, directory: binary(), install: %{required(binary()) => installation()}, limits: term(), path: binary(), runtime: %{stdio_launcher: binary() | nil} }
@type transport() :: %{ type: :stdio, command: binary(), cwd: binary(), args: [binary()], env: %{required(binary()) => binary()}, inherit_environment: boolean(), grace_ms: pos_integer(), stderr_bytes: non_neg_integer(), start_timeout_ms: pos_integer() } | %{ type: :streamable_http, endpoint: binary(), allow_insecure_loopback: boolean(), auth: [map()], oauth: PtcRunner.Kernel.MCPOAuth.Authority.t() | nil }