Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

Merge commit '64f1c02d88f02f88c90f44efe6113705494d11a6' into epic-8089-228-schema-tests

Steven Enamakel8e4b1b2166e8
diff --cc crates/openhuman-core/src/core/all.rs
index b4f5708714,ffc9180b79..a1c6fabe77
--- a/crates/openhuman-core/src/core/all.rs
+++ b/crates/openhuman-core/src/core/all.rs
@@@ -380,10 -407,10 +380,10 @@@ fn build_registered_controllers() -> Ve
crate::core::subsystem::all_subsystems_registered_controllers(),
);
// Diagnostic tools
- push(
+ push_entries(
&mut controllers,
DomainGroup::Platform,
- crate::platform::doctor::all_doctor_controller_entries(),
- crate::doctor::all_doctor_registered_controllers(),
++ crate::doctor::all_doctor_controller_entries(),
);
// User-authored hooks — inspect, reload, and test-fire `hooks.json` entries.
push(
diff --cc crates/openhuman-core/src/core/all_doctor_controller_tests.rs
index eb84f338a1,0000000000..d11eeff8a1
mode 100644,000000..100644
--- a/crates/openhuman-core/src/core/all_doctor_controller_tests.rs
+++ b/crates/openhuman-core/src/core/all_doctor_controller_tests.rs
@@@ -1,98 -1,0 +1,122 @@@
+use super::*;
+
+#[test]
+fn raw_doctor_platform_registry_matches_its_independent_contract() {
+ let contract = super::registry_test_support::BoundFamilyWireContract {
+ namespaces: &["doctor"],
+ group: DomainGroup::Platform,
+ methods: &[
+ ("doctor.report", "openhuman.doctor_report"),
+ ("doctor.models", "openhuman.doctor_models"),
+ ],
+ };
+ super::registry_test_support::verify_family_contract(
+ registry(),
+ internal_registry(),
+ &contract,
- &crate::platform::doctor::doctor_parameter_contracts(),
++ &crate::doctor::doctor_parameter_contracts(),
+ )
+ .expect("raw Doctor entries retain their ordered wire contracts");
+ let entries: Vec<_> = registry()
+ .iter()
+ .filter(|row| row.controller.schema.namespace == "doctor")
+ .collect();
+ let use_cache = TypeSchema::Option(Box::new(TypeSchema::Bool));
++ let report_inputs = [
++ (
++ "tier",
++ TypeSchema::Option(Box::new(TypeSchema::Enum {
++ variants: vec!["static", "connect", "live"],
++ })),
++ false,
++ ),
++ (
++ "only",
++ TypeSchema::Option(Box::new(TypeSchema::Array(Box::new(TypeSchema::String)))),
++ false,
++ ),
++ (
++ "skip",
++ TypeSchema::Option(Box::new(TypeSchema::Array(Box::new(TypeSchema::String)))),
++ false,
++ ),
++ (
++ "profile",
++ TypeSchema::Option(Box::new(TypeSchema::String)),
++ false,
++ ),
++ ];
+ assert_eq!(
- crate::core::all::verify_wire_fields(&entries[0].controller.schema.inputs, &[]),
++ crate::core::all::verify_wire_fields(&entries[0].controller.schema.inputs, &report_inputs,),
+ Ok(())
+ );
+ assert_eq!(
+ crate::core::all::verify_wire_fields(
+ &entries[0].controller.schema.outputs,
+ &[("report", TypeSchema::Ref("DoctorReport"), true)]
+ ),
+ Ok(())
+ );
+ assert_eq!(
+ crate::core::all::verify_wire_fields(
+ &entries[1].controller.schema.inputs,
+ &[("use_cache", use_cache, false)]
+ ),
+ Ok(())
+ );
+ assert_eq!(
+ crate::core::all::verify_wire_fields(
+ &entries[1].controller.schema.outputs,
+ &[("report", TypeSchema::Ref("ModelProbeReport"), true)]
+ ),
+ Ok(())
+ );
+}
+
+#[test]
+fn raw_doctor_decoders_ignore_unknown_fields_and_keep_boolean_types_strict() {
+ use serde_json::json;
+
+ let entries: Vec<_> = registry()
+ .iter()
+ .filter(|row| row.controller.schema.namespace == "doctor")
+ .map(|row| row.controller.clone())
+ .collect();
+ let report = entries
+ .iter()
+ .find(|entry| entry.schema.method_name() == "doctor.report")
+ .expect("raw doctor.report entry");
+ report
+ .decode_params(Map::from_iter([
+ ("use_cache".into(), json!("not a boolean")),
+ ("nested_extra".into(), json!({"ignored":[1, false]})),
+ ]))
- .expect("doctor.report ignores the entire parameter map");
++ .expect("doctor.report ignores unknown fields and parses declared fields");
+
+ let models = entries
+ .iter()
+ .find(|entry| entry.schema.method_name() == "doctor.models")
+ .expect("raw doctor.models entry");
+ models
+ .decode_params(Map::from_iter([
+ ("use_cache".into(), json!(false)),
+ ("extra_scalar".into(), json!(true)),
+ ("nested_extra".into(), json!({"ignored":true})),
+ ]))
+ .expect("doctor.models ignores undeclared fields");
+
+ for invalid in [
+ json!("false"),
+ json!(1),
+ json!([]),
+ json!({"enabled":false}),
+ ] {
+ let error = models
+ .decode_params(Map::from_iter([("use_cache".into(), invalid)]))
+ .expect_err("use_cache accepts only JSON booleans or null");
+ assert!(
+ error.starts_with("invalid 'use_cache':"),
+ "invalid model flag keeps its parser prefix: {error}"
+ );
+ }
+}
diff --cc crates/openhuman-core/src/doctor/mod.rs
index 0000000000,d21f9eaa0e..a730117135
mode 000000,100644..100644
--- a/crates/openhuman-core/src/doctor/mod.rs
+++ b/crates/openhuman-core/src/doctor/mod.rs
@@@ -1,0 -1,84 +1,85 @@@
+ //! Native diagnostic checks for configuration, workspace, and runtime health.
+
+ pub(crate) mod checks;
+ mod contract;
+ mod core;
+ pub mod ops;
+ pub mod profile;
+ pub mod registry;
+ mod runner;
+ mod schemas;
+ pub mod tools;
+
+ pub use contract::{
+ ComponentId, DoctorCheck, DoctorConfigSource, DoctorCtx, DoctorOptions, DoctorReport,
+ DoctorSummary, DoctorTier, Finding, FindingSeverity, ValueSource,
+ };
+ pub use core::{ModelProbeEntry, ModelProbeOutcome, ModelProbeReport, ModelProbeSummary};
+ pub use ops::*;
+ pub use registry::{
- register_check_source, register_check_source_in, registered_checks_for, DoctorCheckSource,
++ DoctorCheckSource, register_check_source, register_check_source_in, registered_checks_for,
+ };
++pub(crate) use schemas::all_controller_entries as all_doctor_controller_entries;
+ pub use schemas::{
+ all_controller_schemas as all_doctor_controller_schemas,
+ all_registered_controllers as all_doctor_registered_controllers,
+ };
+
+ #[cfg(test)]
+ #[path = "config_file_tests.rs"]
+ mod config_file_red_tests;
+
+ #[cfg(test)]
+ #[path = "config_provenance_tests.rs"]
+ mod config_provenance_red_tests;
+
+ #[cfg(test)]
+ #[path = "config_semantics_tests.rs"]
+ mod config_semantics_red_tests;
+
+ #[cfg(test)]
+ #[path = "inference_config_tests.rs"]
+ mod inference_config_red_tests;
+
+ #[cfg(test)]
+ #[path = "embeddings_config_tests.rs"]
+ mod embeddings_config_red_tests;
+
+ #[cfg(test)]
+ #[path = "checks/config_file_tests.rs"]
+ mod config_file_tests;
+
+ #[cfg(test)]
+ #[path = "runner_tests.rs"]
+ mod runner_tests;
+
+ #[cfg(test)]
+ #[path = "connectivity_tests.rs"]
+ mod connectivity_tests;
+
+ #[cfg(test)]
+ #[path = "checks/config_provenance_tests.rs"]
+ mod config_provenance_tests;
+
+ #[cfg(test)]
+ #[path = "checks/inference_tests.rs"]
+ mod inference_config_tests;
+
+ #[cfg(test)]
+ #[path = "inference_catalog_tests.rs"]
+ mod inference_catalog_tests;
+
+ #[cfg(test)]
+ #[path = "inference_auth_error_tests.rs"]
+ mod inference_auth_error_tests;
+
+ #[cfg(test)]
+ #[path = "inference_model_catalog_tests.rs"]
+ mod inference_model_catalog_tests;
+
+ #[cfg(test)]
+ #[path = "inference_catalog_test_support.rs"]
+ mod inference_catalog_test_support;
+
+ #[cfg(test)]
+ pub(crate) mod test_support;
diff --cc crates/openhuman-core/src/doctor/schemas.rs
index 5536484563,fa803196a0..7de7dff1ad
--- a/crates/openhuman-core/src/doctor/schemas.rs
+++ b/crates/openhuman-core/src/doctor/schemas.rs
@@@ -2,12 -2,8 +2,12 @@@ use crate::core::runtime::DispatchCtx
use serde::de::DeserializeOwned;
use serde_json::{Map, Value};
-use crate::core::all::{ControllerFuture, RegisteredController};
+use crate::config::Config;
+ use crate::core::Outcome;
+use crate::core::all::{
+ BoundRegisteredController, ControllerEntry, ControllerFuture, ControllerTask,
+ RegisteredController,
+};
- use crate::core::Outcome;
use crate::core::{ControllerSchema, FieldSchema, TypeSchema};
pub fn all_controller_schemas() -> Vec<ControllerSchema> {
@@@ -85,44 -100,27 +116,55 @@@ pub fn schemas(function: &str) -> Contr
}
}
- fn handle_report(ctx: DispatchCtx, _params: Map<String, Value>) -> ControllerFuture {
- report_controller().invoke(ctx, _params)
+ fn handle_report(ctx: DispatchCtx, params: Map<String, Value>) -> ControllerFuture {
- Box::pin(async move {
- let options = crate::doctor::DoctorOptions {
- tier: read_optional::<crate::doctor::DoctorTier>(&params, "tier")?
- .unwrap_or(crate::doctor::DoctorTier::Connect),
- only: read_optional::<Vec<String>>(&params, "only")?.unwrap_or_default(),
- skip: read_optional::<Vec<String>>(&params, "skip")?.unwrap_or_default(),
- profile: read_optional::<String>(&params, "profile")?,
- };
- to_json(crate::doctor::ops::doctor_report_for_dispatch(&ctx, options).await?)
- })
++ report_controller().invoke(ctx, params)
}
fn handle_models(ctx: DispatchCtx, params: Map<String, Value>) -> ControllerFuture {
+ models_controller().invoke(ctx, params)
+}
+
+fn report_controller() -> BoundRegisteredController {
- BoundRegisteredController::after_gate(schemas("report"), load_config, parse_report, run_report)
++ BoundRegisteredController::typed(schemas("report"), parse_report, run_report)
+}
+
+fn models_controller() -> BoundRegisteredController {
- BoundRegisteredController::after_gate(schemas("models"), load_config, parse_models, run_models)
++ BoundRegisteredController::after_gate(
++ schemas("models"),
++ config_for_dispatch,
++ parse_models,
++ run_models,
++ )
+}
+
- fn load_config(ctx: DispatchCtx) -> ControllerTask<Config> {
- Box::pin(async move { ctx.load_config().await })
++fn config_for_dispatch(ctx: DispatchCtx) -> ControllerTask<Config> {
++ Box::pin(async move { crate::doctor::ops::config_for_dispatch(&ctx).await })
+}
+
- fn parse_report(_params: Map<String, Value>) -> Result<(), String> {
- Ok(())
++fn parse_report(params: Map<String, Value>) -> Result<crate::doctor::DoctorOptions, String> {
++ Ok(crate::doctor::DoctorOptions {
++ tier: read_optional::<crate::doctor::DoctorTier>(&params, "tier")?
++ .unwrap_or(crate::doctor::DoctorTier::Connect),
++ only: read_optional::<Vec<String>>(&params, "only")?.unwrap_or_default(),
++ skip: read_optional::<Vec<String>>(&params, "skip")?.unwrap_or_default(),
++ profile: read_optional::<String>(&params, "profile")?,
++ })
+}
+
+fn parse_models(params: Map<String, Value>) -> Result<bool, String> {
+ Ok(read_optional::<bool>(&params, "use_cache")?.unwrap_or(true))
+}
+
- fn run_report(_ctx: DispatchCtx, config: Config, (): ()) -> ControllerFuture {
- Box::pin(async move { to_json(crate::platform::doctor::rpc::doctor_report(&config).await?) })
++fn run_report(ctx: DispatchCtx, options: crate::doctor::DoctorOptions) -> ControllerFuture {
+ Box::pin(async move {
- let config = crate::doctor::ops::config_for_dispatch(&ctx).await?;
- let use_cache = read_optional::<bool>(&params, "use_cache")?.unwrap_or(true);
- to_json(crate::doctor::ops::doctor_models(&config, use_cache).await?)
++ to_json(crate::doctor::ops::doctor_report_for_dispatch(&ctx, options).await?)
+ })
}
+fn run_models(_ctx: DispatchCtx, config: Config, use_cache: bool) -> ControllerFuture {
- Box::pin(async move {
- to_json(crate::platform::doctor::rpc::doctor_models(&config, use_cache).await?)
- })
++ Box::pin(async move { to_json(crate::doctor::ops::doctor_models(&config, use_cache).await?) })
+}
+
fn read_optional<T: DeserializeOwned>(
params: &Map<String, Value>,
key: &str,
diff --cc crates/openhuman-core/src/doctor/schemas_tests.rs
index b2afb4f8e9,383f31e5bd..b8ad3c42a3
--- a/crates/openhuman-core/src/doctor/schemas_tests.rs
+++ b/crates/openhuman-core/src/doctor/schemas_tests.rs
@@@ -69,107 -47,25 +73,145 @@@ fn model_parser_rejects_non_boolean_cac
}
#[test]
- fn report_parser_ignores_the_entire_parameter_map() {
-fn read_optional_returns_none_for_null() {
- let mut m = Map::new();
- m.insert("use_cache".into(), Value::Null);
- let result: Option<bool> = read_optional(&m, "use_cache").unwrap();
- assert!(result.is_none());
++fn report_parser_applies_defaults_and_ignores_unknown_fields() {
+ let params = Map::from_iter([
+ ("use_cache".into(), Value::String("wrong type".into())),
+ (
+ "unknown_nested".into(),
+ serde_json::json!({"ignored":[1, false]}),
+ ),
+ ]);
- parse_report(params).expect("doctor.report ignores every supplied parameter");
++ let options = parse_report(params).expect("unknown fields are ignored");
++ assert_eq!(options.tier, crate::doctor::DoctorTier::Connect);
++ assert!(options.only.is_empty());
++ assert!(options.skip.is_empty());
++ assert!(options.profile.is_none());
+ }
+
+ #[test]
-fn read_optional_returns_some_for_value() {
- let mut m = Map::new();
- m.insert("use_cache".into(), Value::Bool(true));
- let result: Option<bool> = read_optional(&m, "use_cache").unwrap();
- assert_eq!(result, Some(true));
++fn report_parser_preserves_typed_options_and_null_defaults() {
++ let params = Map::from_iter([
++ ("tier".into(), serde_json::json!("live")),
++ ("only".into(), serde_json::json!(["memory", "config"])),
++ ("skip".into(), Value::Null),
++ ("profile".into(), Value::Null),
++ ]);
++ let options = parse_report(params).unwrap();
++ assert_eq!(options.tier, crate::doctor::DoctorTier::Live);
++ assert_eq!(options.only, ["memory", "config"]);
++ assert!(options.skip.is_empty());
++ assert!(options.profile.is_none());
+ }
+
+ #[test]
-fn read_optional_errors_on_wrong_type() {
- let mut m = Map::new();
- m.insert("use_cache".into(), Value::String("yes".into()));
- let err = read_optional::<bool>(&m, "use_cache").unwrap_err();
- assert!(err.contains("invalid"));
++fn report_parser_rejects_invalid_declared_options() {
++ for (key, value) in [
++ ("tier", serde_json::json!("unknown")),
++ ("only", serde_json::json!("memory")),
++ ("skip", serde_json::json!([false])),
++ ("profile", serde_json::json!(false)),
++ ] {
++ let error = parse_report(Map::from_iter([(key.into(), value)])).unwrap_err();
++ assert!(error.starts_with(&format!("invalid '{key}':")), "{error}");
++ }
+}
+
+async fn runtime_doctor_entries() -> Vec<crate::core::all::ControllerEntry> {
+ use crate::core::runtime::{CoreContext, DomainSet};
+
+ CoreContext::scope(CoreContext::for_test(DomainSet::full(), None), async {
+ crate::core::all::all_registered_controllers()
+ .into_iter()
+ .filter(|entry| entry.schema.namespace == "doctor")
+ .collect()
+ })
+ .await
+}
+
+#[tokio::test]
- async fn doctor_controllers_load_config_before_parsing_and_parse_before_running() {
++async fn report_options_parse_before_dispatch_config_and_models_gate_before_parsing() {
+ use crate::config::test_env::EnvVarGuard;
+ use crate::core::runtime::{CoreContext, DispatchCtx, DomainSet};
+ use serde_json::json;
+
+ let tmp = tempfile::tempdir().unwrap();
+ std::fs::create_dir(tmp.path().join("config.toml")).unwrap();
+ let _env = EnvVarGuard::workspace_async(tmp.path()).await;
+ let entries = runtime_doctor_entries().await;
+ assert_eq!(entries.len(), 2, "both runtime Doctor entries exist");
+ let ctx = DispatchCtx::new(CoreContext::for_test(DomainSet::full(), None));
+
+ let report = entries
+ .iter()
+ .find(|entry| entry.schema.method_name() == "doctor.report")
+ .expect("runtime doctor.report entry");
+ let report_error = report
+ .invoke(
+ ctx.clone(),
- Map::from_iter([("unexpected".into(), json!({"ignored":true}))]),
++ Map::from_iter([("tier".into(), json!("invalid"))]),
+ )
+ .await
- .expect_err("invalid config stops diagnostics before the report runner");
++ .expect_err("invalid options fail before the report resolves config");
+ assert!(
- report_error.contains("is a directory") || report_error.contains("not a file"),
- "report config gate error: {report_error}"
++ report_error.starts_with("invalid 'tier':"),
++ "{report_error}"
+ );
+
+ let models = entries
+ .iter()
+ .find(|entry| entry.schema.method_name() == "doctor.models")
+ .expect("runtime doctor.models entry");
+ let malformed = Map::from_iter([("use_cache".into(), json!("false"))]);
+ let gate_error = models
+ .invoke(ctx, malformed.clone())
+ .await
+ .expect_err("config gate runs before model parameter parsing");
+ assert!(
+ gate_error.contains("is a directory") || gate_error.contains("not a file"),
+ "models config gate error: {gate_error}"
+ );
+ assert!(!gate_error.starts_with("invalid 'use_cache':"));
+
+ let valid_ctx = DispatchCtx::new(CoreContext::for_test_with_config(
+ DomainSet::full(),
+ crate::config::Config::default(),
+ ));
+ let parse_error = models
+ .invoke(valid_ctx, malformed)
+ .await
+ .expect_err("invalid cache flag stops before the model probe runner");
+ assert!(
+ parse_error.starts_with("invalid 'use_cache':"),
+ "models parser error: {parse_error}"
+ );
+}
+
+pub(crate) fn doctor_parameter_contracts() -> Vec<crate::core::all::ControllerParamContract> {
+ use serde_json::json;
+
+ vec![
+ crate::core::all::ControllerParamContract {
+ method: "doctor.report",
+ required: &[],
- optional: &[],
- examples: vec![json!({})],
++ optional: &["tier", "only", "skip", "profile"],
++ examples: vec![
++ json!({}),
++ json!({"tier":"static"}),
++ json!({"only":["config"]}),
++ json!({"skip":["memory"]}),
++ json!({"profile":"work"}),
++ ],
+ },
+ crate::core::all::ControllerParamContract {
+ method: "doctor.models",
+ required: &[],
+ optional: &["use_cache"],
+ examples: vec![
+ json!({}),
+ json!({"use_cache":null}),
+ json!({"use_cache":true}),
+ json!({"use_cache":false}),
+ ],
+ },
+ ]
}
diff --cc docs/specs/doctor.md
index 0000000000,02212fa4d2..c6e165fd66
mode 000000,100644..100644
--- a/docs/specs/doctor.md
+++ b/docs/specs/doctor.md
@@@ -1,0 -1,357 +1,357 @@@
+ # Doctor v2 contract
+
+ This is the maintainer contract for the OpenHuman doctor framework and the
+ checks delivered by the doctor epic. It defines stable check ids and report
-semantics before the legacy `platform/doctor` code moves. The core owns checks,
++semantics for the `doctor` domain. The core owns checks,
+ the registry, runner, and RPC surface; `openhuman-cli` owns command parsing,
+ rendering, and process exit codes; `openhuman-tinyhumans` owns hosted checks.
+
+ The intended user outcome is a report that says whether the selected
+ configuration is ready to run, what was inspected, and what an operator can do
+ about each finding. Doctor does not persist configuration or application-state
+ changes; local filesystem write probes use temporary files and clean them up.
+ This contract borrows OpenClaw's stable check identifiers,
+ structured findings, advisory JSON mode, and threshold-based lint behavior.
+ Wire fields remain snake case to match the existing RPC contract. This contract
+ does not adopt OpenClaw's repair operation: this epic adds no repair command.
+
+ ## Goals and non-goals
+
+ The doctor validates configuration semantics and provenance, profile-specific
+ runtime readiness, configured local and hosted components, and outbound
+ connections. Checks are selectable by stable id and have an explicit cost tier.
+ The report is a versioned JSON API shared by RPC, CLI, the agent tool, and the
+ Settings diagnostics surface.
+
+ This epic does not add `--fix`, prompts, config rewrites, migrations, token
+ generation, or other repair side effects. A finding always has a human-readable
+ `fix_hint`, but that hint is guidance for a later explicit operator action.
+ Checks do not make billable inference or embedding calls, or write scratch
+ memory, unless the caller opts into the `live` tier.
+
+ ## Check contract
+
+ The Rust API and serialized JSON use snake case. A check is registered with a
+ stable id, category, cost tier, and optional component gate. Its detector is
+ asynchronous and returns findings for that check:
+
+ ```rust
+ DoctorCheck {
+ id: "<area>/<name>[/<qualifier>...]",
+ category: "<display category>",
+ tier: DoctorTier::Static | DoctorTier::Connect | DoctorTier::Live,
+ component_gate: Option<ComponentId>,
+ async fn detect(&self, ctx: &DoctorCtx) -> Vec<Finding>,
+ }
+ ```
+
+ Ids are lowercase ASCII segments separated by `/`, with at least an area and
+ name (`area/name`). Each segment is nonempty and contains only lowercase ASCII
+ letters, digits, `_`, or `-`. Additional segments are allowed for checks
+ scoped to a role or provider, such as
+ `inference/live/chat`. They are API identifiers used by `--only`, `--skip`, the
+ RPC filters, and downstream consumers. Once released, an id is never renamed
+ or reused for different behavior; a replacement gets a new id and the old one
+ remains recognizable for at least one schema lifetime. IDs are matched
+ exactly. Prefixes, globs, and category names are not selectors.
+
+ `static` checks may read and probe the local filesystem, but do not open network
+ connections. Temporary local write probes must be cleaned up. `connect` checks
+ may make bounded, read-only network requests and are the default; they do not
+ make billable calls or persist state. `live` checks may make billable model or
+ embedding calls and may write disposable scratch memory; they run only when
+ explicitly requested. A requested tier is a ceiling: `static` runs static
+ checks, `connect` runs static and connect checks, and `live` runs all three
+ tiers.
+
+ The runner applies the active `ComponentSet` gate before calling a detector.
+ A gated-off component produces a `skipped` finding and is listed in
+ `checks_skipped`. Checks above the requested tier are also listed as skipped.
+ An id omitted by `--only` or named by a valid `--skip` is filtered out and is
+ not reported as a failed check. The runner uses bounded concurrency (at most
+ eight checks at once), a timeout for every detector (5 seconds for static,
+ 10 seconds for connect, 60 seconds for live), and a stable registry order in
+ the report regardless of completion order. Timeout and detector failures are
+ `error` findings; one failure does not prevent other selected checks from
+ finishing. A timed-out detector is cancelled where the async operation supports
+ cancellation.
+
+ Detectors may return an empty vector when the check is clean. The runner turns
+ an empty result into one `pass` finding so `checks_run` and severity totals
+ still distinguish a successful check from an unobserved one. Detectors that
+ find multiple conditions emit one finding for each condition. This permits a
+ clean config check to return no findings, as required by the config leaves.
+
+ ### Finding
+
+ ```json
+ {
+ "check_id": "config/unknown-key",
+ "severity": "warn",
+ "message": "Unknown config key `memroy`; did you mean `memory`?",
+ "fix_hint": "Rename the key to `memory` and rerun doctor.",
+ "config_path": "memroy",
+ "value_source": "file",
+ "duration_ms": 4,
+ "affects": ["settings.configure_ai"]
+ }
+ ```
+
+ | Field | Contract |
+ | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+ | `check_id` | Required stable id of the check that produced the finding. |
+ | `severity` | `pass`, `info`, `warn`, `error`, or `skipped`. |
+ | `message` | Short operator-facing result, with no secret or config value. |
+ | `fix_hint` | Required next step. Use “No action required.” for `pass`; explain how to rerun or enable a skipped check. |
+ | `config_path` | Optional config key path or source file path. `config/source` may name the loaded config and `.env` paths; other checks normally use a logical config key path. |
+ | `value_source` | Optional `cli`, `env`, `dotenv`, `file`, or `default`, when a finding concerns a resolved value. |
+ | `duration_ms` | Elapsed detector time, repeated consistently on findings from one check. A check skipped before execution reports `0`. |
+ | `affects` | Zero or more stable `about_app` capability ids, such as `channels.connect_platform` or `local_ai.configure_provider`. |
+
+ The report must not contain credentials, tokens, secret material, raw config
+ values, request or response bodies, or user-authored content. Redact endpoint
+ credentials and query parameters before forming messages. A detector that
+ cannot safely summarize an error reports its class and a safe recovery hint,
+ not the original error string. `value_source` records provenance only; it
+ never carries the value.
+
+ ## Report schema v2
+
+ The RPC method remains `openhuman.doctor_report`; the existing `doctor_models`
+ method and `doctor_health` / `doctor_models` tool names also remain stable.
+ `doctor_report` accepts `{ "tier", "only", "skip", "profile" }` and returns:
+
+ ```json
+ {
+ "schema_version": 2,
+ "profile": "desktop-default",
+ "config_source": "profile",
+ "profile_layout_version": 2,
+ "config_resolution_source": "active_user.toml",
+ "tier": "connect",
+ "checks_run": ["config/parse"],
+ "checks_skipped": ["inference/live/chat"],
+ "findings": [
+ {
+ "check_id": "config/parse",
+ "severity": "pass",
+ "message": "The config file parsed successfully.",
+ "fix_hint": "No action required.",
+ "duration_ms": 4,
+ "affects": []
+ },
+ {
+ "check_id": "inference/live/chat",
+ "severity": "skipped",
+ "message": "This live check was not requested.",
+ "fix_hint": "Rerun doctor with --live to run this check.",
+ "duration_ms": 0,
+ "affects": []
+ }
+ ],
+ "summary": { "pass": 1, "info": 0, "warn": 0, "error": 0, "skipped": 1 },
+ "ok": true
+ }
+ ```
+
+ `checks_run` and `checks_skipped` are ordered arrays of check ids. A check
+ selected by the caller but gated off or above the requested tier is in
+ `checks_skipped`; checks outside an `only` selection and checks named by `skip`
+ are absent. `summary` counts findings by severity. `ok` is false exactly when
+ the report contains an `error`; warnings remain advisory, and a skipped check
+ does not by itself make the report unhealthy. The CLI's lint threshold is
+ separate from this field.
+
+ `profile` is the effective profile id, when the host has one, and `null`
+ otherwise. `config_source` is always the source kind (`profile` or `tenant`),
+ not a tenant credential or filesystem path. `profile_layout_version` is `1`
+ or `2` when a desktop profile layout was selected; `config_resolution_source`
+ is the stable directory-selection label, such as `OPENHUMAN_WORKSPACE`,
+ `active_workspace.toml`, `active_user.toml`, `default`, or `--profile`. These
+ optional fields are omitted when unknown and for SaaS tenant contexts. The
+ `config/source` info finding
+ reports the loaded config and `.env` paths, directory resolution source,
+ profile layout version when applicable, and whether CLI `--model` or
+ `--provider` overrides are active. It does not report config values or
+ credentials. It also reports `.env` variables shadowed by existing process
+ environment values without including their values.
+
+ The selection validator is a reserved runner check, `doctor/selection`. An
+ unknown id supplied to either `only` or `skip` adds an `error` finding under
+ `doctor/selection`, with a hint to use a registered exact id. Do not echo an
+ unknown selector into the message. Valid selected checks still run. The
+ reserved check is not itself selectable and does not count as a detector in
+ `checks_run`.
+
+ ## Tier and selection inputs
+
+ The RPC accepts optional `tier`, `only`, `skip`, and `profile` fields. An
+ omitted tier means `connect`; omitted lists are empty. `only` and `skip` are
+ repeatable at the CLI and contain exact ids. If `only` is present, only those
+ registered checks run; `skip` then removes checks from that set. Duplicate ids
+ are collapsed. An unregistered id is a report finding rather than a transport
+ error, so callers receive useful results for the valid ids in the same request.
+
+ `--live` selects the `live` ceiling. It does not change the tier of each check
+ or imply repair. The doctor does not infer consent to billable work from a
+ profile setting.
+
+ ## CLI contract
+
+ The command is implemented only in `crates/openhuman-cli`; the core contains
+ no CLI parser or renderer. It calls `openhuman.doctor_report` through the
+ `openhuman-rpc` facade and maps options to the RPC parameters above.
+
+ | Invocation | Output and exit behavior |
+ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+ | `openhuman-core doctor` | Human-readable table; exit `0` after a report is produced. |
+ | `openhuman-core doctor --json` | JSON report; advisory mode exits `0` after a report is produced, regardless of findings. |
+ | `openhuman-core doctor --lint` | Human-readable findings; exit `0` if none meet the threshold, `1` if any do, `2` if parsing or execution fails before a report is produced. |
+ | `openhuman-core doctor --lint --json` | Same threshold and exit behavior as lint, with JSON output. |
+
+ `--severity-min` accepts `info`, `warn`, or `error` and defaults to `error`.
+ The threshold controls both printed findings and the lint result. `pass` and
+ `skipped` never meet it. `--only <id>` and `--skip <id>` may be repeated;
+ `--live` selects the live tier, and `--profile <id>` selects the effective
+ profile where the host permits it. In SaaS, an authenticated tenant always uses
+ its forced config and storage scope. An operator may use `--profile <id>` to
+ target another tenant; a tenant caller may target only itself. The host checks
+ that permission before doctor reads config or credentials. Argument syntax
+ errors exit `2` before
+ the RPC call.
+
+ The CLI does not add fields to the RPC report. Human output is a rendering of
+ the same findings and includes the severity, check id, message, and fix hint.
+ JSON uses the same report in every surface.
+
+ ## Profile semantics
+
+ On desktop, a requested profile id resolves through `ProfileLayout`. Doctor
+ loads that profile's configuration and credentials for inspection without
+ changing the active profile, writing profile state, or changing process-wide
+ configuration. With no explicit id, it uses the currently selected profile.
+ The report's `profile` is the effective id and `config_source` is `profile`.
+
+ In SaaS, doctor runs against a forced tenant configuration and storage scope.
+ Without `profile`, the context is the authenticated tenant. An operator may
+ select another tenant by id; an ordinary tenant caller may select only itself.
+ The host authorizes this before doctor reads any config or credential. The
+ report uses `config_source: "tenant"` and includes no tenant secret.
+ Profile-scoped reads use the selected context rather than process-global
+ lookup helpers.
+
+ ## Check registration and hosted checks
+
+ Built-in checks register in the core registry. The core exposes both
+ process-default `register_check_source(source)` and per-`CoreContext`
+ `register_check_source_in` registration through `CoreBuilder::extensions`, so a
+ host can supply checks without a dependency from core back to that host.
+ `openhuman-tinyhumans` registers its backend, identity, socket, API URL, and
+ managed-inference checks through this seam. Profile-aware or tenant-aware
+ sources use context-scoped registration; context-independent sources may use
+ the process-default registration. At report start, malformed or duplicate ids
+ are rejected before any selected detector executes. Hosted ids use the same
+ lowercase slash-separated segment grammar and are unique across sources. A
+ source may register zero checks when its host capability is absent.
+
+ The doctor stays in the existing `DomainGroup::Platform` registration group.
-Moving its Rust module from `platform/doctor` to the top-level `doctor` domain
-does not add a new runtime domain group. `subsystems.status` remains a separate
++Its Rust module lives at the top-level `doctor` domain without adding a new
++runtime domain group. `subsystems.status` remains a separate
+ wire projection: it reports driver bindings, health, and capabilities, while
+ doctor findings include stable check ids, severity, guidance, provenance, and
+ timing. A doctor check may consume subsystem status as evidence, but it does
+ not reuse `SubsystemStatus` as a finding.
+
+ ## Check inventory
+
+ The paths below are the implementation-owned probe locations under
+ `crates/openhuman-core/src/doctor/` (and `crates/openhuman-tinyhumans/src/doctor/`
+ for hosted checks). Function names are stable implementation targets. The
+ implementation leaves add final source-line links when their functions land;
+ this contract is written before those files exist. IDs and any severity/status
+ called out by a leaf's Scope or Acceptance criteria are normative. Where a leaf
+ does not specify a severity, its implementation must choose one consistent with
+ the finding and cover it in that leaf's tests.
+
+ | Check id | Tier | Probe function | Owning leaf | Required severity or status | Minimum fix hint |
+ | ------------------------------------ | ------- | --------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+ | `config/parse` | static | `doctor/checks/config.rs::parse` | #492 | `error` on parse failure or corruption recovery, including `.bak` fallback. | Repair `config.toml`; review and restore a valid backup if recovery occurred. |
+ | `config/unknown-key` | static | `doctor/checks/config.rs::unknown_key` | #492 | `warn` per ignored key, with a did-you-mean suggestion where available. | Rename the key to the suggested supported field. |
+ | `config/legacy-key` | static | `doctor/checks/config.rs::legacy_key` | #492 | `info` per migrated legacy key. | Update the config to the current key name. |
+ | `config/env-override` | static | `doctor/checks/config.rs::env_override` | #493 | `warn` if env overrides an explicit file value; otherwise `info`. | Set the intended value in one source and remove the shadowed override. |
+ | `config/source` | static | `doctor/checks/config.rs::source` | #493 | `info`. | No action required; use the reported source when diagnosing precedence. |
+ | `config/runtime-settings` | static | `doctor/checks/runtime_settings.rs::runtime_settings` | #506 | `warn` for ignored fallback providers, incomplete model routes or delegate models, or no channel when channels are enabled. | Remove ignored settings or complete the reported configuration path. |
+ | `inference/provider-ref` | static | `doctor/checks/inference.rs::provider_ref` | #494 | `error` for unresolved provider references. | Select a registered provider and fix the reported config path. |
+ | `inference/construct` | static | `doctor/checks/inference.rs::construct` | #494 | `error` when a configured role cannot be constructed, including missing BYOK credentials. | Correct provider settings and configure its required credential. |
+ | `inference/temperature` | static | `doctor/checks/inference.rs::temperature` | #494 | Finding for invalid settings; severity is not specified by the leaf. | Set a supported temperature for the configured role. |
+ | `embeddings/config` | static | `doctor/checks/embeddings.rs::config` | #494 | Finding for invalid or inconsistent settings; severity is not specified by the leaf. | Configure a provider, model, and dimension that agree. |
+ | `components/referenced-but-disabled` | static | `doctor/checks/components.rs::referenced_but_disabled` | #495 | `warn` when config references a disabled component. | Enable the component or remove dependent configuration. |
+ | `modules/source-fallback` | static | `doctor/checks/modules.rs::source_fallback` | #495 | Leaf-defined; include the source fallback detail. | Configure the intended module source explicitly. |
+ | `modules/override-invalid` | static | `doctor/checks/modules.rs::override_invalid` | #495 | Leaf-defined for an invalid override. | Correct or remove the invalid module override. |
+ | `storage/url` | static | `doctor/checks/storage.rs::url` | #495 | `error` when the storage scheme's driver is unavailable in this build. | Use a supported URL scheme and enable its driver. |
+ | `workspace/action-dir` | static | `doctor/checks/workspace.rs::action_dir` | #495 | `error` when the configured action directory is not writable. | Create the directory or grant the process write access. |
+ | `secrets/master-key-env` | static | `doctor/checks/secrets.rs::master_key_env` | #495 | `error` when both master-key environment variables are set. | Keep only the intended master-key source configured. |
+ | `network/proxy` | static | `doctor/checks/network.rs::proxy` | #495 | Leaf-defined by the existing proxy validator. | Correct the proxy configuration reported by the validator. |
+ | `memory/root` | static | `doctor/checks/memory.rs::root` | #495 | Leaf-defined by the existing memory-root validator. | Correct the memory root path reported by the validator. |
+ | `profile/exists` | static | `doctor/profile.rs::exists` | #490 | `error` for a missing profile, unknown layout marker, or invalid profile config. | Select an existing profile with a supported layout and valid config. |
+ | `profile/provisioned` | connect | `doctor/profile.rs::provisioned` | #491 | `error` for an unprovisioned tenant profile. | Provision the tenant profile before running doctor. |
+ | `workspace/writable` | static | `doctor/checks/workspace.rs::writable` | #506 | `error` when the workspace write probe fails. | Grant write access to the workspace directory. |
+ | `workspace/layout` | static | `doctor/checks/workspace.rs::layout` | #506 | Leaf-defined for missing `memory/`, `SYSTEM.md`, or low disk space. | Create or repair the reported workspace entry or free disk space. |
+ | `runtime/environment` | static | `doctor/checks/runtime.rs::environment` | #506 | Leaf-defined for git, curl, shell, or home environment checks. | Install or configure the named local prerequisite. |
+ | `runtime/agent-sdk` | connect | `doctor/checks/runtime.rs::agent_sdk` | #506 | Leaf-defined for the Claude Agent SDK version probe. | Install or configure the agent SDK binary, then rerun doctor. |
+ | `memory/binding` | static | `doctor/checks/memory.rs::binding` | #498 | Leaf-defined for the selected memory binding. | Select an available memory driver. |
+ | `memory/health` | connect | `doctor/checks/memory.rs::health` | #498 | `error` when the bound engine is down. | Restore the memory driver's availability and rerun doctor. |
+ | `storage/connect` | connect | `doctor/checks/storage.rs::connect` | #498 | `error` when the read-only open fails; never migrate. | Make the configured storage reachable and retry the check. |
+ | `storage/layout` | connect | `doctor/checks/storage.rs::layout` | #498 | `warn` when a storage layout migration is pending. | Apply the documented migration using the normal storage upgrade path. |
+ | `secrets/keyring` | connect | `doctor/checks/secrets.rs::keyring` | #498 | `skipped` for a non-interactive macOS keychain probe. | Run interactively or configure an available keyring backend. |
+ | `embeddings/configured-model` | connect | `doctor/checks/embeddings.rs::configured_model` | #509 | Non-Ollama providers are `skipped`; probe the configured Ollama URL. | Start the configured service or correct its base URL and model. |
+ | `modules/<id>` | connect | `doctor/checks/modules.rs::module_status` | #499 | Failed/Unsupported=`error`; Disabled=`skipped`; Available/Ready=`pass`. | Repair or enable the named module source and verify its digest pin. |
+ | `mcp/<server>` | connect | `doctor/checks/mcp.rs::server_status` | #499 | `error` when a configured server fails to connect; `skipped` when `components.mcp` is disabled. | Start the server or correct its connection settings. |
+ | `skills/discovery` | static | `doctor/checks/skills.rs::discovery` | #499 | `warn` for a malformed skill manifest. | Repair the manifest at the reported path. |
+ | `skills/github-preflight` | connect | `doctor/checks/skills.rs::github_preflight` | #499 | Runs only when a skill requires it; failure severity is leaf-defined. | Resolve the reported GitHub access or repository issue. |
+ | `sandbox/backend` | connect | `doctor/checks/sandbox.rs::backend` | #499 | `error` when the configured Docker backend is unavailable. | Install or start Docker, or select an available sandbox backend. |
+ | `channels/<provider>` | connect | `doctor/checks/channels.rs::provider_health` | #500 | `error` on provider health timeout; `skipped` when its component is disabled. | Restore the channel provider connection and retry. |
+ | `integrations/composio` | connect | `doctor/checks/integrations.rs::composio` | #500 | `skipped` when its component is disabled; otherwise leaf-defined. | Reconnect Composio or correct its endpoint configuration. |
+ | `voice/stt` | connect | `doctor/checks/voice.rs::stt` | #500 | `skipped` when `components.voice` is disabled; otherwise leaf-defined. | Enable voice or configure an available speech-to-text provider. |
+ | `voice/tts` | connect | `doctor/checks/voice.rs::tts` | #500 | `skipped` when `components.voice` is disabled; otherwise leaf-defined. | Enable voice or configure an available text-to-speech provider. |
+ | `search/<provider>` | connect | `doctor/checks/search.rs::provider_status` | #500 | `warn` when provider status is `NeedsKey`; `skipped` when its component is disabled. | Configure the provider key named in the finding. |
+ | `wallet/status` | connect | `doctor/checks/wallet.rs::status` | #500 | `skipped` when its component is disabled; otherwise leaf-defined. | Configure the wallet safely or disable the unused wallet feature. |
+ | `backend/reachable` | connect | `openhuman-tinyhumans/src/doctor/backend.rs::reachable` | #496 | `error` when backend is down; dependent hosted checks are `skipped`. | Check the configured backend URL and network access. |
+ | `backend/credential` | connect | `openhuman-tinyhumans/src/doctor/backend.rs::credential` | #496 | `error` for an expired JWT (`SESSION_EXPIRED`). | Sign in again through the supported auth flow. |
+ | `backend/identity` | connect | `openhuman-tinyhumans/src/doctor/backend.rs::identity` | #496 | Healthy result passes; failure severity is leaf-defined. | Check tenant identity and access through the supported auth flow. |
+ | `backend/socket` | connect | `openhuman-tinyhumans/src/doctor/backend.rs::socket` | #496 | Healthy result passes; failure severity is leaf-defined. | Check backend socket availability and network policy. |
+ | `backend/api-url` | static | `openhuman-tinyhumans/src/doctor/backend.rs::api_url` | #496 | Healthy result passes; failure severity is leaf-defined. | Set a valid backend API URL for this profile. |
+ | `inference/managed-catalog` | connect | `openhuman-tinyhumans/src/doctor/inference.rs::managed_catalog` | #496 | Healthy result passes; failure severity is leaf-defined. | Check the managed inference catalog and tenant access. |
+ | `inference/model-in-catalog` | connect | `doctor/checks/inference.rs::model_in_catalog` | #497 | `warn` when a configured model is absent; `skipped` if provider has no `/models` route. | Select a listed model or verify provider catalog support. |
+ | `inference/auth-errors` | connect | `doctor/checks/inference.rs::auth_errors` | #497 | `error` per provider in the auth error snapshot. | Resolve provider authentication or access. |
+ | `inference/live/<role>` | live | `doctor/checks/inference_live.rs::role_completion` | #501 | `error` for a provider 401; other failures are categorized as auth/quota/unavailable. | Check the role's provider access and model configuration. |
+ | `embeddings/live` | live | `doctor/checks/embeddings_live.rs::embed` | #502 | `error` on embed failure or configured/actual dimension mismatch. | Check embedding access and configured vector dimensions. |
+ | `memory/roundtrip` | live | `doctor/checks/memory_live.rs::roundtrip` | #502 | `error` on roundtrip failure, including insufficient credits. | Check memory-driver write/fetch/delete access and billing. |
+
+ The IDs above are normative names from the leaves' Scope and Acceptance
+ criteria. Dynamic segments use the canonical identifier supplied by their
+ owner; they are safe single path segments, never arbitrary display text.
+ `config/temperature` appears only in #488's selector test and is a `FakeCheck`
+ fixture id, not a built-in inventory entry. The former daemon-state check has
+ no v2 id: #325 deletes it because its state file is never written.
+
+ For #491 tenant checks, `profile/provisioned` covers provision and lease
+ readiness, while `backend/credential`, `inference/provider-ref`, and
+ `storage/connect` report credential, provider-settings, and storage-scope
+ readiness within the forced tenant context. A tenant caller cannot use
+ `profile` to inspect another tenant; an authorized operator may select one.
+ Authorization is checked before doctor reads config or credentials.
+
+ `memory/roundtrip` uses doctor-scoped disposable content and must always forget
+ it, including after a fetch failure. If cleanup fails, the report names the
+ cleanup failure without including test content. Static checks may use bounded
+ temporary local write probes, but must not persist configuration or repair
+ application state. Connect checks may add read-only network probes but do not
+ make billable calls or write remote state.
+
+ ## Implementation references
+
+ - Existing doctor being replaced: `crates/openhuman-core/src/doctor/`
+ - Existing subsystem status projection: `crates/openhuman-core/src/core/subsystem/status.rs`
+ - Capability ids: `crates/openhuman-core/src/platform/about_app/`
+ - OpenClaw reference: [structured health-check contract](https://github.com/openclaw/openclaw/blob/main/docs/cli/doctor/health-contract.md), [lint mode and selectors](https://github.com/openclaw/openclaw/blob/main/docs/cli/doctor/lint.md), and [running doctor](https://github.com/openclaw/openclaw/blob/main/docs/cli/doctor/running.md)