The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
Merge commit '64f1c02d88f02f88c90f44efe6113705494d11a6' into epic-8089-228-schema-tests
Steven Enamakel8e4b1b2166e8
diff --cc crates/openhuman-core/src/core/all.rsindex 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() -> Vecrate::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.rsindex eb84f338a1,0000000000..d11eeff8a1mode 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.rsindex 0000000000,d21f9eaa0e..a730117135mode 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.rsindex 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::DispatchCtxuse 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>(¶ms, "tier")?- .unwrap_or(crate::doctor::DoctorTier::Connect),- only: read_optional::<Vec<String>>(¶ms, "only")?.unwrap_or_default(),- skip: read_optional::<Vec<String>>(¶ms, "skip")?.unwrap_or_default(),- profile: read_optional::<String>(¶ms, "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>(¶ms, "tier")?++ .unwrap_or(crate::doctor::DoctorTier::Connect),++ only: read_optional::<Vec<String>>(¶ms, "only")?.unwrap_or_default(),++ skip: read_optional::<Vec<String>>(¶ms, "skip")?.unwrap_or_default(),++ profile: read_optional::<String>(¶ms, "profile")?,++ })+}++fn parse_models(params: Map<String, Value>) -> Result<bool, String> {+ Ok(read_optional::<bool>(¶ms, "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>(¶ms, "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.rsindex 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.mdindex 0000000000,02212fa4d2..c6e165fd66mode 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)