Skip to content

Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.

fix(cli): publish usable connection-test help and request examples (#168)

澄潭c65b6b8a48d2
diff --git a/contracts/cli/contract-set.v1.json b/contracts/cli/contract-set.v1.json
index 9a0b570a..6782fc22 100644
--- a/contracts/cli/contract-set.v1.json
+++ b/contracts/cli/contract-set.v1.json
@@ -1,5 +1,5 @@
{
- "descriptor_digest": "sha256:67f113c402eff903feaab4969759d519a737fa7d225a0409320300272cdc6ba5",
+ "descriptor_digest": "sha256:a07f0fba88c73d351be68cd0a845ac2499a22212246fe276fcf4973d424f0972",
"files": {
"agent-check-request.v1.schema.json": "sha256:fbd9e9b19282a5ed8c3e30b5ae16538bc01318a70e4bb7c7a55e8e0472553feb",
"agent-launch-descriptor-request.v1.schema.json": "sha256:28f2f9d2d7f9a1618bea0f13383002429bc9e0ff56166cbee86958a245d0fd48",
@@ -10,7 +10,7 @@
"console-launch-request.v1.schema.json": "sha256:bb201709ef64e99036a97d5879a32a8e4e3a9517010e1041def223e723e7f385",
"console-token-create.v1.schema.json": "sha256:10cc9b80ed0bec4a5ca80e098cf0ee94710eedd7dfce292cf4a8770a11be78ec",
"console-token-revoke.v1.schema.json": "sha256:fbec29753f6effd3c854bff57984b3c3932ac5b6f2345e52151e353c15933b36",
- "coverage-manifest.v1.json": "sha256:82d5506c313b47eb1684b4be0dd0cd2ccdae53e0bfb092dcba7b26503d4ae048",
+ "coverage-manifest.v1.json": "sha256:1660122311b4831139e8aeae8d79e16fa27e232b24c24f65a4a6d3df573ce73f",
"delegation-cancel-request.v1.schema.json": "sha256:0822c53fc16acfcd618fbef66410939f33f634313389a6df4705f414a468b878",
"delegation-continue-request.v1.schema.json": "sha256:da2f81607f37d154a0fa698a107b37d4b0e9d5a03693dcbcc41e0b7e65db5b93",
"delegation-get-request.v1.schema.json": "sha256:85b29839c1c508018ebe40e4b2bb5c1dce7c3a87c27efa30b196b2d1b6658471",
@@ -24,14 +24,14 @@
"local-control-hello.v2.schema.json": "sha256:32fbce882152a886b79bd139d3b4e459b48d94e0634e56ccb189b2c9971ad772",
"local-control.v2.schema.json": "sha256:4b654de90cd6e333b3953379e5b2e1c5125f1dcbe307b7c7c73f12bb2032d18c",
"machine-envelope.v2.schema.json": "sha256:23e019a3d024ae302a44105caff4ec95d3fb409a29f936dea1360e543ae6abd6",
- "manifest.v1.json": "sha256:09bfe295d41859efc1e44c19fcba92808ad4abcd54e5e781f30a8eda3e162b84",
+ "manifest.v1.json": "sha256:64af54a17623c0a84bc43d3ce366ffcb923ee3c8b47777a271fc16414ff15059",
"operation-cancel-request.v1.schema.json": "sha256:0071cbcf27de3bfb7f6644478fe2b73bb5387ebe33db93629ff5672959e8495f",
"operation-lookup.v1.schema.json": "sha256:0fbaaa15b0e75b4186979bdd856bed0485d55a4bd33a33f3caf3bd92e01a7850",
"plan-content-change.v2.schema.json": "sha256:b67a57ca076002e341c7a74a1b8d505819ed20ee6a028354c8e6d2c5ff475f47",
"plan-draft-change.v1.schema.json": "sha256:cbf6f1ff62fbf04e659c69342a509bbf2b2acc21b3426c3a8e4e138e26cf58c3",
"plan-editor.v2.schema.json": "sha256:85084c42de1e8d7be3b84401a47ec5e15406431dfad983cd3b48718e93533fe1",
"plan-lifecycle-change.v1.schema.json": "sha256:23700c0ea1fbc9834e653c4edc8268e346912270c92be4904f9759426f641562",
- "planned-manifest.v1.json": "sha256:68d5d426cdae3d13e706686ce6025cb309d44aef75d3a6c512a5838ab41c72a0",
+ "planned-manifest.v1.json": "sha256:596204593333a199466a8bb6dcc4c76627dfc737231e2a2f5c3ace9c80a8b525",
"prepare-discovered-model-connection-request.v1.schema.json": "sha256:4451d8d7d06160f399d683bc3987ac2bd458af09994e4e0d989687667f6af1bd",
"publication-checkpoint-change.v1.schema.json": "sha256:b130577cdae0f1e5dc9f736b8b6f40f22555b4750b4604fdc76c4b65d5b96aa3",
"session-list-query.v1.schema.json": "sha256:1f71a89fc019b59c3499708c0760b694b8cb8532028b56d98702cd3b2721cd44",
diff --git a/contracts/cli/coverage-manifest.v1.json b/contracts/cli/coverage-manifest.v1.json
index 6040ede7..cacb233a 100644
--- a/contracts/cli/coverage-manifest.v1.json
+++ b/contracts/cli/coverage-manifest.v1.json
@@ -1289,7 +1289,7 @@
}
}
],
- "descriptor_digest": "sha256:67f113c402eff903feaab4969759d519a737fa7d225a0409320300272cdc6ba5",
+ "descriptor_digest": "sha256:a07f0fba88c73d351be68cd0a845ac2499a22212246fe276fcf4973d424f0972",
"schema_version": {
"major": 1,
"minor": 0
diff --git a/contracts/cli/manifest.v1.json b/contracts/cli/manifest.v1.json
index 34b6daf1..1d0337e8 100644
--- a/contracts/cli/manifest.v1.json
+++ b/contracts/cli/manifest.v1.json
@@ -5,7 +5,7 @@
},
"product_contract_revision": "487a807c8dc25cfb24e8b097882cd3bb9716a009",
"proposal_map_revision": "ab4da93cc49c6ec56a01e046230411ff1ca82300",
- "descriptor_digest": "sha256:67f113c402eff903feaab4969759d519a737fa7d225a0409320300272cdc6ba5",
+ "descriptor_digest": "sha256:a07f0fba88c73d351be68cd0a845ac2499a22212246fe276fcf4973d424f0972",
"visibility": "release",
"commands": [
{
@@ -1294,14 +1294,16 @@
"help": {
"purpose": "Run one explicit bounded connection probe, with inference only when requested.",
"usage": "hiroute compute connection test (--request-stdin | --request-file <PATH>) --output json",
- "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin selects native, registered, discovered, or saved with its strict nested request. Credentials are referenced only through a protected-input candidate; plaintext credential fields are rejected. The explicit probe may contact the configured provider and may consume quota when an inference model is selected.",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. The top-level JSON wrapper is {kind, request}. Choose registered for a catalog option such as OpenRouter, with expected_catalog copied from compute connection options; native contains request.draft for a custom API. discovered and saved retain their own strict nested requests. schema show --command-id compute.connection.test --include-schema provides complete native/registered templates and prerequisite guidance. Credentials are referenced only through a protected-input candidate; plaintext credential fields are rejected. The explicit probe may contact the configured provider and may consume quota when an inference model is selected.",
"effects": "Runs one explicit bounded source check. It keeps protected input in daemon memory and does not persist source state until the separate Preview/Apply flow.",
"network_and_model_use": "Contacts only the explicitly selected, typed endpoint. Inventory checks make no inference call; selecting an inference model may send one bounded model request and consume provider quota.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
"output": "One hiroute.machine-envelope/v2 JSON object on stdout; diagnostics belong on stderr.",
"exit_status": "0 success/accepted; 2 usage; 3 conflict/blocker; 4 capability denied; 5 not found; 6 unavailable; 7 action required; 8 needs attention.",
"examples": [
- "hiroute compute connection test --non-interactive --output json"
+ "hiroute compute connection test --request-stdin --output json < native-request.json",
+ "hiroute compute connection test --request-file registered-request.json --output json",
+ "hiroute schema show --command-id compute.connection.test --include-schema --output json"
],
"see_also": [
"hiroute schema show --command-id compute.connection.test"
diff --git a/contracts/cli/planned-manifest.v1.json b/contracts/cli/planned-manifest.v1.json
index ba22dc18..cbd3223e 100644
--- a/contracts/cli/planned-manifest.v1.json
+++ b/contracts/cli/planned-manifest.v1.json
@@ -5,7 +5,7 @@
},
"product_contract_revision": "487a807c8dc25cfb24e8b097882cd3bb9716a009",
"proposal_map_revision": "ab4da93cc49c6ec56a01e046230411ff1ca82300",
- "descriptor_digest": "sha256:67f113c402eff903feaab4969759d519a737fa7d225a0409320300272cdc6ba5",
+ "descriptor_digest": "sha256:a07f0fba88c73d351be68cd0a845ac2499a22212246fe276fcf4973d424f0972",
"visibility": "planned",
"commands": [
{
@@ -1763,14 +1763,16 @@
"help": {
"purpose": "Run one explicit bounded connection probe, with inference only when requested.",
"usage": "hiroute compute connection test (--request-stdin | --request-file <PATH>) --output json",
- "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. --request-stdin selects native, registered, discovered, or saved with its strict nested request. Credentials are referenced only through a protected-input candidate; plaintext credential fields are rejected. The explicit probe may contact the configured provider and may consume quota when an inference model is selected.",
+ "arguments_and_options": "JSON input: choose exactly one of --request-stdin or --request-file <PATH>. Both read one bounded UTF-8 JSON request with the same strict typed parser; unknown fields, duplicate members, trailing JSON, repeated/mixed sources and human-option mixtures are rejected before Local Control. A file must be regular; relative paths resolve from the current directory (prefix option-shaped filenames with ./). Existing command byte limits and separate protected-input/capability channels remain unchanged. The top-level JSON wrapper is {kind, request}. Choose registered for a catalog option such as OpenRouter, with expected_catalog copied from compute connection options; native contains request.draft for a custom API. discovered and saved retain their own strict nested requests. schema show --command-id compute.connection.test --include-schema provides complete native/registered templates and prerequisite guidance. Credentials are referenced only through a protected-input candidate; plaintext credential fields are rejected. The explicit probe may contact the configured provider and may consume quota when an inference model is selected.",
"effects": "Runs one explicit bounded source check. It keeps protected input in daemon memory and does not persist source state until the separate Preview/Apply flow.",
"network_and_model_use": "Contacts only the explicitly selected, typed endpoint. Inventory checks make no inference call; selecting an inference model may send one bounded model request and consume provider quota.",
"automation": "Use stable command_id, status, typed data, warnings[].code, and next_actions[].command_id; never parse display text.",
"output": "One hiroute.machine-envelope/v2 JSON object on stdout; diagnostics belong on stderr.",
"exit_status": "0 success/accepted; 2 usage; 3 conflict/blocker; 4 capability denied; 5 not found; 6 unavailable; 7 action required; 8 needs attention.",
"examples": [
- "hiroute compute connection test --non-interactive --output json"
+ "hiroute compute connection test --request-stdin --output json < native-request.json",
+ "hiroute compute connection test --request-file registered-request.json --output json",
+ "hiroute schema show --command-id compute.connection.test --include-schema --output json"
],
"see_also": [
"hiroute schema show --command-id compute.connection.test"
diff --git a/crates/application-api/src/command_schemas.rs b/crates/application-api/src/command_schemas.rs
index abc13db5..c0c2691c 100644
--- a/crates/application-api/src/command_schemas.rs
+++ b/crates/application-api/src/command_schemas.rs
@@ -345,12 +345,17 @@ pub fn command_schemas(command_id: &str) -> Option<CommandSchemasV1> {
request,
response,
examples: examples(command_id),
- example_guidance: "Examples show syntax. Resolve resource IDs from current queries. For Apply, copy the exact Preview spec/change, digest and expected revisions; keep one submission key. Example digests and revisions do not authorize writes.",
+ example_guidance: if command_id == "compute.connection.test" {
+ "Templates show syntax, not a successful check. Save the native template as native-request.json or the registered template as registered-request.json. For a registered option, run hiroute compute connection options --output json, choose an option with registered_check_available=true, and replace the entire request.expected_catalog with data.catalog from that response. Register the credential with hiroute protected-input register --candidate <REF> --secret-fd <FD> --output json; after registered=true, use that REF for request.input_candidate.candidate_ref and the matching candidate_ref (request.candidate_ref for registered, request.draft.candidate_ref for native), with input_candidate.candidate_revision=1 for this protected-input protocol. Use your own lineage_ref/check_id and edit_revision for this check. Native API templates also require your actual endpoint, protocol profile and authentication semantics. Keep secret bytes in the separate protected-input channel. inference_model_id=null performs no model inference; a selected inference model can consume quota. Read the result's reachability, authentication, directory and inference fields: a successful command or selectable candidate does not establish provider verification. For a key-authenticated option with neither an inventory path nor a selected inference model, no remote probe runs; reachability=not_run, authentication=unknown, directory=not_run and inference=not_run leave connectivity and the API key unverified. The current bundled OpenRouter template follows this path. Catalog example digests/revisions are placeholders and cannot authorize a check."
+ } else {
+ "Examples show syntax. Resolve resource IDs from current queries. For Apply, copy the exact Preview spec/change, digest and expected revisions; keep one submission key. Example digests and revisions do not authorize writes."
+ },
})
}
fn examples(command_id: &str) -> Vec<Value> {
match command_id {
+ "compute.connection.test" => connection_test_examples(),
"decision.services.apply" => {
let change = json!({"id":"service/example", "expected_revision":0, "service":{
"id":"service/example","revision":1,"name":"Example decision service",
@@ -374,6 +379,61 @@ fn examples(command_id: &str) -> Vec<Value> {
}
}
+fn connection_test_examples() -> Vec<Value> {
+ let candidate = json!({
+ "candidate_ref":"candidate/native/example", "candidate_revision":1
+ });
+ vec![
+ json!({
+ "kind":"native",
+ "request":{
+ "draft":{
+ "inference_model_id":null,
+ "candidate_ref":"candidate/native/example",
+ "lineage_ref":"lineage/native/example",
+ "display_name":"My API",
+ "existing_source_id":null,
+ "edit_revision":1,
+ "check_id":"check/native/example-1",
+ "base_url":"https://provider.example/v1",
+ "base_kind":"api_root",
+ "request_path_override":null,
+ "inventory_path_override":null,
+ "protocol":"responses",
+ "protocol_profile_id":"profile/custom/responses",
+ "protocol_profile_revision":1,
+ "authentication":{"kind":"bearer"},
+ "configuration_revision":1,
+ "models":[]
+ },
+ "input_candidate":candidate
+ }
+ }),
+ json!({
+ "kind":"registered",
+ "request":{
+ "connection_option_id":"openrouter.free.global.v1",
+ "display_name":"OpenRouter Free",
+ "expected_catalog":{
+ "product_release":"replace-from-current-options",
+ "catalog_binding_id":"replace-from-current-options",
+ "release_sequence":1,
+ "connector_registry_digest":format!("sha256:{}", "0".repeat(64)),
+ "model_data_digest":format!("sha256:{}", "0".repeat(64)),
+ "cross_reference_digest":format!("sha256:{}", "0".repeat(64))
+ },
+ "candidate_ref":"candidate/native/example",
+ "lineage_ref":"lineage/native/example",
+ "edit_revision":1,
+ "check_id":"check/native/example-1",
+ "input_candidate":candidate,
+ "models":[],
+ "inference_model_id":null
+ }
+ }),
+ ]
+}
+
fn observation_request(views: &[&str]) -> Value {
let mut result = schema::<ObservationReadRequestV2>(false);
if let Some(variants) = result
diff --git a/crates/application-api/src/commands/help.rs b/crates/application-api/src/commands/help.rs
index 3fc3e6f2..cab61efc 100644
--- a/crates/application-api/src/commands/help.rs
+++ b/crates/application-api/src/commands/help.rs
@@ -202,6 +202,13 @@ pub(super) fn network_and_model_use(command_id: &str, kind: CommandKind) -> &'st
}
}
pub(super) fn examples(command_id: &str, joined_path: &str) -> Vec<String> {
+ if command_id == "compute.connection.test" {
+ return vec![
+ example(command_id, joined_path),
+ "hiroute compute connection test --request-file registered-request.json --output json".into(),
+ "hiroute schema show --command-id compute.connection.test --include-schema --output json".into(),
+ ];
+ }
if command_id == "decision.services.apply" {
return vec![
"hiroute decision services apply --request-file preview-request.json --output json # Preview: schema_version and spec".into(),
@@ -213,6 +220,7 @@ pub(super) fn examples(command_id: &str, joined_path: &str) -> Vec<String> {
}
pub(super) fn example(command_id: &str, joined_path: &str) -> String {
match command_id {
+ "compute.connection.test" => "hiroute compute connection test --request-stdin --output json < native-request.json".into(),
"compute.connection.login" => "printf '%s' '{\"action\":\"start\",\"provider\":\"claude\"}' | hiroute compute connection login --request-stdin --output json".to_owned(),
"worker.executors" => "hiroute worker executors --output json".to_owned(),
"worker.dependencies.discover" => {
diff --git a/crates/application-api/src/protocol.rs b/crates/application-api/src/protocol.rs
index 3751c824..88f84082 100644
--- a/crates/application-api/src/protocol.rs
+++ b/crates/application-api/src/protocol.rs
@@ -1182,7 +1182,7 @@ pub(crate) fn command_arguments(command_id: &str) -> String {
"agents.check" => "Configuration, native-authentication and collaboration are bounded local checks admitted by the owner-only same-UID transport and make no upstream model call. Live requires --target JSON containing context_id, surface, expected_applied_revision and client_model_ids, --allow-model-call and a separately delivered one-shot capability bound to that target. Targets are forbidden on local checks; provider, credential, prompt and URL overrides are forbidden.".to_owned(),
"compute.connection.preview" => "--request-stdin accepts exactly one registered v1 projection, compute-management v2 save/edit, or subscription-check v2 preview request. The optional edit action is rename (display_name), append_models (checked candidate; preserves existing models), remove_models (saved source; selected refs are removals), or delete (saved source; no selected refs). Omitting edit retains released save semantics. Referenced models, including disabled routes and retained versions, cannot be deleted. Preview has no durable side effect and returns the exact digest and revisions required by Apply.".to_owned(),
"compute.connection.apply" => "--request-stdin accepts only the exact preview spec, digest, revisions, and a non-empty idempotency key. Same-UID Local Control reproduces the plan; replay uses the original key and changed payloads are rejected.".to_owned(),
- "compute.connection.test" => "--request-stdin selects native, registered, discovered, or saved with its strict nested request. Credentials are referenced only through a protected-input candidate; plaintext credential fields are rejected. The explicit probe may contact the configured provider and may consume quota when an inference model is selected.".to_owned(),
+ "compute.connection.test" => "The top-level JSON wrapper is {kind, request}. Choose registered for a catalog option such as OpenRouter, with expected_catalog copied from compute connection options; native contains request.draft for a custom API. discovered and saved retain their own strict nested requests. schema show --command-id compute.connection.test --include-schema provides complete native/registered templates and prerequisite guidance. Credentials are referenced only through a protected-input candidate; plaintext credential fields are rejected. The explicit probe may contact the configured provider and may consume quota when an inference model is selected.".to_owned(),
"compute.connection.login" => "--request-stdin accepts list/start with provider codex or claude; status/cancel/forget with an exact login_ref; callback with login_ref and input_candidate. Register callback text first with protected-input register --candidate <callback_input_candidate.candidate_ref> --secret-fd <FD>. OAuth codes, tokens, callback URLs and credential paths are rejected in ordinary request JSON. Start returns a browser URL; successful login still requires subscription check, model selection and save.".to_owned(),
"compute.connection.authorize" => "--request-stdin reads one exact subscription result operation or releases one exact validation. Starting authorization still uses connection Preview/Apply, including revision, digest, and idempotency checks.".to_owned(),
"decision.services.list" => "No request body or secret material. Returns the latest saved version of each service; published plans retain their exact immutable version.".to_owned(),
diff --git a/crates/cli/tests/connection_test_examples.rs b/crates/cli/tests/connection_test_examples.rs
new file mode 100644
index 00000000..0aac9f6f
--- /dev/null
+++ b/crates/cli/tests/connection_test_examples.rs
@@ -0,0 +1,215 @@
+//! Exercise the installed connection-test help and request examples as a caller sees them.
+use serde_json::{Value, json};
+use std::{
+ collections::BTreeSet,
+ io::Write,
+ path::Path,
+ process::{Command, Output, Stdio},
+};
+
+fn invoke(root: &Path, args: &[&str], input: &[u8]) -> Output {
+ let root = root.canonicalize().unwrap();
+ let mut child = Command::new(env!("CARGO_BIN_EXE_hiroute"))
+ .args(args)
+ .current_dir(&root)
+ .env("HOME", &root)
+ .env("HIROUTE_RUNTIME_DIR", &root)
+ .env_remove("XDG_STATE_HOME")
+ .env_remove("XDG_DATA_HOME")
+ .env_remove("XDG_RUNTIME_DIR")
+ .stdin(Stdio::piped())
+ .stdout(Stdio::piped())
+ .stderr(Stdio::piped())
+ .spawn()
+ .unwrap();
+ child.stdin.take().unwrap().write_all(input).unwrap();
+ child.wait_with_output().unwrap()
+}
+
+fn contract(root: &Path) -> Value {
+ let output = invoke(
+ root,
+ &[
+ "schema",
+ "show",
+ "--command-id",
+ "compute.connection.test",
+ "--include-schema",
+ "--output",
+ "json",
+ ],
+ b"",
+ );
+ assert!(output.status.success());
+ serde_json::from_slice::<Value>(&output.stdout).unwrap()["data"].clone()
+}
+
+#[test]
+fn published_connection_test_commands_declare_their_request_source() {
+ let root = tempfile::tempdir().unwrap();
+ let contract = contract(root.path());
+ let examples = contract["descriptor"]["help"]["examples"]
+ .as_array()
+ .unwrap();
+ let commands: Vec<_> = examples
+ .iter()
+ .filter_map(Value::as_str)
+ .filter(|example| example.starts_with("hiroute compute connection test "))
+ .collect();
+ assert!(!commands.is_empty());
+ for example in commands {
+ assert!(
+ example.contains("--request-file ")
+ || (example.contains("--request-stdin ") && example.contains(" < ")),
+ "published example omits its request source: {example}"
+ );
+ }
+}
+
+#[test]
+fn published_native_and_registered_examples_execute_the_displayed_commands() {
+ let root = tempfile::tempdir().unwrap();
+ let contract = contract(root.path());
+ let requests = contract["schemas"]["examples"].as_array().unwrap();
+ let kinds: BTreeSet<_> = requests
+ .iter()
+ .map(|request| request["kind"].as_str().unwrap())
+ .collect();
+ assert_eq!(kinds, BTreeSet::from(["native", "registered"]));
+ for request in requests {
+ let kind = request["kind"].as_str().unwrap();
+ let inference_path = if kind == "native" {
+ "/request/draft/inference_model_id"
+ } else {
+ "/request/inference_model_id"
+ };
+ assert_eq!(request.pointer(inference_path), Some(&Value::Null));
+ let file = root.path().join(format!("{kind}-request.json"));
+ std::fs::write(file, serde_json::to_vec(request).unwrap()).unwrap();
+ }
+
+ let help = invoke(
+ root.path(),
+ &["compute", "connection", "test", "--help"],
+ b"",
+ );
+ assert!(help.status.success());
+ let help = String::from_utf8(help.stdout).unwrap();
+ let mut executed = BTreeSet::new();
+ for example in contract["descriptor"]["help"]["examples"]
+ .as_array()
+ .unwrap()
+ {
+ let example = example.as_str().unwrap();
+ assert!(help.contains(example));
+ let mut args: Vec<_> = example.split_ascii_whitespace().collect();
+ assert_eq!(args.remove(0), "hiroute");
+ let mut input = Vec::new();
+ let document = if let Some(index) = args.iter().position(|arg| *arg == "<") {
+ assert_eq!(index + 2, args.len());
+ let document = args[index + 1];
+ input = std::fs::read(root.path().join(document)).unwrap();
+ args.truncate(index);
+ Some(document)
+ } else {
+ args.iter()
+ .position(|arg| *arg == "--request-file")
+ .map(|index| args[index + 1])
+ };
+ let output = invoke(root.path(), &args, &input);
+ if let Some(document) = document {
+ assert_eq!(
+ output.status.code(),
+ Some(6),
+ "{example}: {}",
+ String::from_utf8_lossy(&output.stdout)
+ );
+ let envelope: Value = serde_json::from_slice(&output.stdout).unwrap();
+ assert_eq!(envelope["error"]["code"], "DAEMON_UNAVAILABLE");
+ executed.insert(document.to_owned());
+ } else {
+ assert!(output.status.success(), "{example}");
+ }
+ }
+ assert_eq!(
+ executed,
+ BTreeSet::from([
+ "native-request.json".to_owned(),
+ "registered-request.json".to_owned()
+ ])
+ );
+ let guidance = contract["schemas"]["example_guidance"].as_str().unwrap();
+ for prerequisite in [
+ "compute connection options",
+ "protected-input register",
+ "expected_catalog",
+ "inference_model_id",
+ "reachability=not_run",
+ "authentication=unknown",
+ "directory=not_run",
+ "inference=not_run",
+ ] {
+ assert!(
+ guidance.contains(prerequisite),
+ "missing prerequisite: {prerequisite}"
+ );
+ }
+}
+
+#[test]
+fn reported_invalid_connection_requests_have_safe_actionable_diagnostics() {
+ let root = tempfile::tempdir().unwrap();
+ let flat = serde_json::to_vec(&json!({
+ "schema":"hiroute.compute-connection-test-request/v1", "kind":"native",
+ "connection_option_id":"openrouter.free.global.v1",
+ "endpoint_profile_id":"endpoint.openrouter.free.global.v1", "endpoint_profile_revision":1,
+ "authentication":{"kind":"provider_api_key", "input_ref":{"candidate":"PRIVATE_INPUT_MARKER"}},
+ "probe":{"kind":"inventory", "model_selection":{"mode":"none"}}
+ })).unwrap();
+ let cases = [
+ (
+ vec!["--non-interactive", "--output", "json"],
+ b"".as_slice(),
+ ),
+ (vec!["--request-stdin", "--output", "json"], b"".as_slice()),
+ (vec!["--request-stdin", "--output", "json"], flat.as_slice()),
+ (
+ vec!["--request-stdin", "--output", "json"],
+ br#"{"schema":"hiroute.compute-connection-test-request/v1"}"#.as_slice(),
+ ),
+ (
+ vec!["--request-stdin", "--output.json"],
+ br#"{"schema":"hiroute.compute-connection-test-request/v1"}"#.as_slice(),
+ ),
+ (
+ vec!["--request-stdin", "--output", "json"],
+ br#"{"kind":"registered"}"#.as_slice(),
+ ),
+ ];
+ for (options, input) in cases {
+ for rich in [false, true] {
+ let mut args = vec!["compute", "connection", "test"];
+ args.extend(options.iter().copied());
+ if rich {
+ args.push("--error-details");
+ }
+ let output = invoke(root.path(), &args, input);
+ assert_eq!(output.status.code(), Some(2));
+ let envelope: Value = serde_json::from_slice(&output.stdout).unwrap();
+ assert_eq!(envelope["error"]["code"], "INVALID_ARGUMENTS");
+ assert_eq!(envelope["status"], "usage_error");
+ if rich {
+ assert!(envelope["data"]["diagnostic"]["path"].is_string());
+ assert!(envelope["data"]["diagnostic"]["category"].is_string());
+ }
+ let stderr = String::from_utf8_lossy(&output.stderr);
+ assert!(stderr.contains(
+ "hiroute schema show --command-id compute.connection.test --include-schema"
+ ));
+ for bytes in [&output.stdout, &output.stderr] {
+ assert!(bytes.len() < 4096);
+ assert!(!String::from_utf8_lossy(bytes).contains("PRIVATE_INPUT_MARKER"));
+ }
+ }
+ }
+}
diff --git a/crates/cli/tests/management_contracts.rs b/crates/cli/tests/management_contracts.rs
index 1257709f..6404677b 100644
--- a/crates/cli/tests/management_contracts.rs
+++ b/crates/cli/tests/management_contracts.rs
@@ -77,6 +77,7 @@ fn installed_full_schemas_are_offline_complete_and_opt_in() {
"compute.connection.preview",
"compute.connection.apply",
"compute.connection.authorize",
+ "compute.connection.test",
"routing.options",
"routing.list",
"routing.show",
diff --git a/crates/daemon/tests/publication_process.rs b/crates/daemon/tests/publication_process.rs
index e5dfcae9..60bc40ef 100644
--- a/crates/daemon/tests/publication_process.rs
+++ b/crates/daemon/tests/publication_process.rs
@@ -78,6 +78,13 @@ fn real_process_native_model_save_publishes_and_reaches_gateway() {
run_script("model_connections_product.py");
}
+/// Execute both published recipes against the current catalog without mistaking local
+/// candidate preparation for provider reachability or credential verification.
+#[test]
+fn real_process_connection_test_examples_report_unverified_openrouter() {
+ run_script("connection_test_examples_product.py");
+}
+
#[test]
fn real_process_custom_http_save_recheck_and_validation_errors() {
run_script("custom_http_product.py");
diff --git a/crates/daemon/tests/support/connection_test_examples_product.py b/crates/daemon/tests/support/connection_test_examples_product.py
new file mode 100644
index 00000000..3aa83991
--- /dev/null
+++ b/crates/daemon/tests/support/connection_test_examples_product.py
@@ -0,0 +1,81 @@
+"""Run the documented OpenRouter recipes through the real CLI and daemon."""
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from publication_product import Product
+
+
+def recipe(repository, filename, heading):
+ document = (repository / 'docs' / filename).read_text()
+ section = document.split(heading + '\n', 1)[1]
+ return section.split('```sh\n', 1)[1].split('\n```', 1)[0]
+
+
+def main(repository):
+ product = Product(repository)
+ try:
+ product.start()
+ before = product.public_cli('compute list')[1]['data']['sources']
+ documents = [
+ ('standalone-cli.md', '## Test a catalog API connection'),
+ ('standalone-cli.zh-CN.md', '## 测试目录中的 API 连接'),
+ ]
+ recipes = [recipe(product.repo, *document) for document in documents]
+ assert recipes[0] == recipes[1], 'translated recipes have diverged'
+ # Deliberately invalid: a local candidate must not imply the key was accepted.
+ token = 'invalid-openrouter-recipe-regression-key'
+ product.secrets.add(token)
+ key_file = product.root / 'private-key'
+ key_file.write_text(token)
+ key_file.chmod(0o600)
+ for index, script in enumerate(recipes):
+ temporary = product.root / ('recipe-' + str(index))
+ temporary.mkdir(mode=0o700)
+ environment = dict(product.env, TMPDIR=str(temporary),
+ PATH=str(product.bin) + os.pathsep + product.env['PATH'])
+ script = script.replace("KEY_FILE='/absolute/private/openrouter-key'",
+ 'KEY_FILE=' + str(key_file))
+ result = subprocess.run(['/bin/sh'], input=script.encode(), env=environment,
+ cwd=product.project, capture_output=True, timeout=45)
+ product.outputs.extend([result.stdout, result.stderr])
+ assert result.returncode == 0, (result.returncode, result.stdout, result.stderr)
+ directories = list(temporary.iterdir())
+ assert len(directories) == 1, directories
+ work = directories[0]
+ envelope = json.loads((work / 'result.json').read_text())
+ assert envelope['status'] == 'succeeded', envelope
+ check = envelope['data']
+ expected = {'reachability': 'not_run', 'authentication': 'unknown',
+ 'directory': 'not_run', 'inference': 'not_run'}
+ assert {name: check[name] for name in expected} == expected, check
+ assert check['inventory_path'] is None and check['pages_read'] == 0, check
+ assert check['candidate']['models'], check
+ request = json.loads((work / 'registered-request.json').read_text())
+ assert request['kind'] == 'registered', request
+ assert request['request']['connection_option_id'] == 'openrouter.free.global.v1'
+ assert request['request']['inference_model_id'] is None
+ # Successful commands and catalog models are insufficient verification evidence.
+ assert b'Remote connectivity and API key were not verified.' in result.stdout, result.stdout
+ guidance = json.loads((work / 'contract.json').read_text())['data']['schemas']['example_guidance']
+ for name, value in expected.items():
+ assert name + '=' + value in guidance, (name, guidance)
+ assert (name + '=' + value).encode() in result.stdout, result.stdout
+ # The EXIT trap releases the input: replaying the same request must now fail.
+ replay_code, replay = product.public_cli('compute connection test', request,
+ success=False)
+ assert replay_code != 0 and replay['status'] != 'succeeded', replay
+ assert product.public_cli('compute list')[1]['data']['sources'] == before
+ for path in work.iterdir():
+ product.outputs.append(path.read_bytes())
+ print(json.dumps({'scenario': documents[index][0], 'state': 'green',
+ 'remote_verification': 'not_run', 'protected_input': 'released'}),
+ flush=True)
+ finally:
+ product.close()
+
+
+if __name__ == '__main__':
+ main(Path(sys.argv[1]))
diff --git a/docs/code-map/architecture.md b/docs/code-map/architecture.md
index a026e537..678975bc 100644
--- a/docs/code-map/architecture.md
+++ b/docs/code-map/architecture.md
@@ -55,6 +55,12 @@ CLI JSON request sources (`--request-file` / `--request-stdin`) share the bounde
[strict input reader](../../crates/cli/src/request_input.rs). Command codecs retain
typed intent, selector and byte-limit ownership; see the [CLI input guide](../../crates/cli/INPUT.md)
and [production argv regressions](../../crates/cli/tests/request_input.rs).
+Connection-test help and native/registered templates come from
+[Application API](../../crates/application-api/src/command_schemas.rs); the
+[installed-example regression](../../crates/cli/tests/connection_test_examples.rs)
+executes the displayed commands with those request documents. The
+[real-process recipe regression](../../crates/daemon/tests/support/connection_test_examples_product.py)
+checks their current-catalog results and protected-input cleanup through CLI/daemon.
[Quickstart and Preview convenience inputs](../../crates/cli/src/quickstart.rs) compose existing
queries and transactions. They use [Application authoring options](../../crates/application/src/routing/editor_options.rs)
diff --git a/docs/standalone-cli.md b/docs/standalone-cli.md
index 0fef0c24..fe2f6691 100644
--- a/docs/standalone-cli.md
+++ b/docs/standalone-cli.md
@@ -232,6 +232,100 @@ response is a `hiroute.machine-envelope/v2`. Automation reads `status`, `data`,
The JSON examples below are ordinary credential-free files. `jq` is used only to demonstrate
field extraction and is not a HiRoute dependency.
+## Test a catalog API connection
+
+`compute connection test` requires a JSON input source and a nested `{kind, request}`
+body. Use `registered` for an offered catalog option such as OpenRouter; use `native`
+with `request.draft` for a custom API. `--non-interactive` does not supply a request.
+The installed full schema includes both templates in `data.schemas.examples` and
+explains their prerequisites in `data.schemas.example_guidance`. Full schema/template
+discovery requires `--include-schema`; v0.3.1 returns descriptors only.
+
+With the service ready, Python 3 installed and a private mode-0600 file containing
+only your OpenRouter API key, replace `KEY_FILE` below. The script obtains the exact
+catalog from the running service and builds the registered template. The current
+bundled OpenRouter option has no remote directory probe. With `inference_model_id=null`,
+the check sends no request to OpenRouter: it prepares a candidate from bundled facts
+without verifying connectivity or the API key. It does not save a source.
+It attempts to release its protected input on exit and retains separate result/error
+files for diagnosis. Only references enter ordinary JSON; the key stays on FD 3.
+
+```sh
+(
+set -eu
+umask 077
+KEY_FILE='/absolute/private/openrouter-key'
+work=$(mktemp -d)
+candidate="candidate/native/openrouter-$(python3 -c 'import uuid; print(uuid.uuid4().hex)')"
+hiroute schema show --command-id compute.connection.test --include-schema --output json > "$work/contract.json"
+hiroute compute connection options --output json > "$work/options.json"
+hiroute protected-input register --candidate "$candidate" --secret-fd 3 --output json \
+ 3< "$KEY_FILE" > "$work/input.json"
+trap 'hiroute protected-input release --candidate "$candidate" --output json >&2 || echo "Retry releasing this candidate if cleanup failed: $candidate" >&2' EXIT
+python3 - "$work" "$candidate" > "$work/registered-request.json" <<'PY'
+import json, pathlib, sys
+work, candidate = pathlib.Path(sys.argv[1]), sys.argv[2]
+contract = json.loads((work / 'contract.json').read_text())
+options = json.loads((work / 'options.json').read_text())
+registration = json.loads((work / 'input.json').read_text())
+if any(x.get('status') != 'succeeded' for x in (contract, options, registration)):
+ raise SystemExit('Read contract.json, options.json and input.json for the failed prerequisite')
+if registration.get('data', {}).get('registered') is not True:
+ raise SystemExit('Protected input was not registered')
+option_id = 'openrouter.free.global.v1'
+option = next((x for x in options['data']['options']
+ if x['connection_option_id'] == option_id), None)
+if option is None or not option.get('registered_check_available', False):
+ raise SystemExit('The current catalog does not offer this registered check')
+body = next(x for x in contract['data']['schemas']['examples'] if x['kind'] == 'registered')
+request = body['request']
+request.update(connection_option_id=option_id, expected_catalog=options['data']['catalog'],
+ candidate_ref=candidate, lineage_ref='lineage/native/' + candidate.rsplit('/', 1)[1],
+ check_id='check/native/' + candidate.rsplit('/', 1)[1], edit_revision=1,
+ input_candidate={'candidate_ref': candidate, 'candidate_revision': 1},
+ models=[], inference_model_id=None)
+print(json.dumps(body, indent=2))
+PY
+set +e
+hiroute compute connection test --request-stdin --output json \
+ < "$work/registered-request.json" > "$work/result.json" 2> "$work/stderr.txt"
+rc=$?
+set -e
+cat "$work/result.json"
+cat "$work/stderr.txt" >&2
+if [ "$rc" -eq 0 ]; then
+python3 - "$work/result.json" <<'PY'
+import json, sys
+check = json.load(open(sys.argv[1]))['data']
+fields = ('reachability', 'authentication', 'directory', 'inference')
+print('Remote check results: ' + ', '.join(name + '=' + check[name] for name in fields))
+if check['reachability'] == 'not_run' and check['authentication'] == 'unknown':
+ print('Remote connectivity and API key were not verified.')
+PY
+fi
+printf 'connection-test exit code: %s; result files: %s\n' "$rc" "$work"
+exit "$rc"
+)
+```
+
+Read `data.reachability`, `data.authentication`, `data.directory` and `data.inference`
+in the result. For the current bundled OpenRouter option this recipe reports
+`reachability=not_run`, `authentication=unknown`, `directory=not_run` and
+`inference=not_run`. Exit code 0 / `status=succeeded` means the command completed;
+it does not establish provider verification. Catalog models or a selectable candidate
+do not establish it either. A remote check requires an explicitly selected supported
+probe; selecting an inference model can consume quota.
+
+The protected-input registration protocol uses `candidate_revision=1` for a newly
+registered credential. This is distinct from revisions returned by a completed model
+check. Keep `expected_catalog` as the whole current `data.catalog` object. A catalog
+mismatch requires fetching current options and rebuilding the check; template digests
+are placeholders. The same request can be sent with
+`--request-file "$work/registered-request.json"` instead of stdin redirection.
+For custom APIs, save the `native` template as `native-request.json` and supply the
+actual endpoint/protocol facts and protected-input reference; the next section shows
+a complete manually declared-model request.
+
## Connect a Native API model source
Credentials can be registered only through a protected file descriptor. Never put a key in
diff --git a/docs/standalone-cli.zh-CN.md b/docs/standalone-cli.zh-CN.md
index faffd6d2..63a31bed 100644
--- a/docs/standalone-cli.zh-CN.md
+++ b/docs/standalone-cli.zh-CN.md
@@ -252,6 +252,94 @@ hiroute compute connection test --help
以下示例中的 JSON 都是不含凭据的普通文件。`jq` 仅用于演示提取字段,不是 HiRoute 依赖。
+## 测试目录中的 API 连接
+
+`compute connection test` 需要 JSON 输入来源和嵌套的 `{kind, request}` 请求体。
+OpenRouter 等当前目录提供的选项使用 `registered`;自定义 API 使用 `native`,其配置放在
+`request.draft`。`--non-interactive` 不能代替请求输入。完整的已安装 schema 在
+`data.schemas.examples` 中提供两种模板,`data.schemas.example_guidance` 说明前置条件。
+完整 schema/模板发现需要 `--include-schema`;v0.3.1 只返回命令描述。
+
+确认服务已就绪、本机已安装 Python 3,并准备好只包含 OpenRouter API Key 的私密文件
+(权限 0600),然后替换下方的 `KEY_FILE`。脚本从运行中的服务取得准确目录并构造
+registered 模板。当前内置 OpenRouter 选项没有远端目录探测路径;
+`inference_model_id=null` 时不会向 OpenRouter 发请求,只根据内置目录准备候选,
+不验证连通性或 API Key,也不保存来源。
+退出时会尝试释放本次受保护输入,并保留独立的结果和错误文件供排查。
+普通 JSON 中只有引用,Key 通过 FD 3 单独传递。
+
+```sh
+(
+set -eu
+umask 077
+KEY_FILE='/absolute/private/openrouter-key'
+work=$(mktemp -d)
+candidate="candidate/native/openrouter-$(python3 -c 'import uuid; print(uuid.uuid4().hex)')"
+hiroute schema show --command-id compute.connection.test --include-schema --output json > "$work/contract.json"
+hiroute compute connection options --output json > "$work/options.json"
+hiroute protected-input register --candidate "$candidate" --secret-fd 3 --output json \
+ 3< "$KEY_FILE" > "$work/input.json"
+trap 'hiroute protected-input release --candidate "$candidate" --output json >&2 || echo "Retry releasing this candidate if cleanup failed: $candidate" >&2' EXIT
+python3 - "$work" "$candidate" > "$work/registered-request.json" <<'PY'
+import json, pathlib, sys
+work, candidate = pathlib.Path(sys.argv[1]), sys.argv[2]
+contract = json.loads((work / 'contract.json').read_text())
+options = json.loads((work / 'options.json').read_text())
+registration = json.loads((work / 'input.json').read_text())
+if any(x.get('status') != 'succeeded' for x in (contract, options, registration)):
+ raise SystemExit('Read contract.json, options.json and input.json for the failed prerequisite')
+if registration.get('data', {}).get('registered') is not True:
+ raise SystemExit('Protected input was not registered')
+option_id = 'openrouter.free.global.v1'
+option = next((x for x in options['data']['options']
+ if x['connection_option_id'] == option_id), None)
+if option is None or not option.get('registered_check_available', False):
+ raise SystemExit('The current catalog does not offer this registered check')
+body = next(x for x in contract['data']['schemas']['examples'] if x['kind'] == 'registered')
+request = body['request']
+request.update(connection_option_id=option_id, expected_catalog=options['data']['catalog'],
+ candidate_ref=candidate, lineage_ref='lineage/native/' + candidate.rsplit('/', 1)[1],
+ check_id='check/native/' + candidate.rsplit('/', 1)[1], edit_revision=1,
+ input_candidate={'candidate_ref': candidate, 'candidate_revision': 1},
+ models=[], inference_model_id=None)
+print(json.dumps(body, indent=2))
+PY
+set +e
+hiroute compute connection test --request-stdin --output json \
+ < "$work/registered-request.json" > "$work/result.json" 2> "$work/stderr.txt"
+rc=$?
+set -e
+cat "$work/result.json"
+cat "$work/stderr.txt" >&2
+if [ "$rc" -eq 0 ]; then
+python3 - "$work/result.json" <<'PY'
+import json, sys
+check = json.load(open(sys.argv[1]))['data']
+fields = ('reachability', 'authentication', 'directory', 'inference')
+print('Remote check results: ' + ', '.join(name + '=' + check[name] for name in fields))
+if check['reachability'] == 'not_run' and check['authentication'] == 'unknown':
+ print('Remote connectivity and API key were not verified.')
+PY
+fi
+printf 'connection-test exit code: %s; result files: %s\n' "$rc" "$work"
+exit "$rc"
+)
+```
+
+请查看结果中的 `data.reachability`、`data.authentication`、`data.directory` 和
+`data.inference`。当前内置 OpenRouter 选项执行此流程会返回
+`reachability=not_run`、`authentication=unknown`、`directory=not_run` 和
+`inference=not_run`。退出码 0 / `status=succeeded` 仅表示命令完成,不能证明服务已验证;
+目录中有模型或候选可选择也不能证明这一点。远端验证需要显式选择受支持的探测方式;
+选择推理模型可能消耗配额。
+
+受保护输入登记协议对新登记凭据使用 `candidate_revision=1`,它与模型检查完成后返回的候选
+版本不同。`expected_catalog` 必须完整复制当前的 `data.catalog`;目录不匹配时,重新获取
+options 并构造检查,模板中的摘要仅为占位。相同请求也可通过
+`--request-file "$work/registered-request.json"` 传入,替代 stdin 重定向。
+自定义 API 可将 `native` 模板保存为 `native-request.json`,填写真实 endpoint、协议事实
+和受保护输入引用;下一节给出了手工声明模型的完整请求。
+
## 接入 Native API 模型来源
凭据只能通过受保护 FD 登记。不要把 Key 放进 argv、环境变量、普通 JSON、日志或 Agent 对话:
diff --git a/e2e/product/schema/contract-set.v1.json b/e2e/product/schema/contract-set.v1.json
index e888f03b..265fc50e 100644
--- a/e2e/product/schema/contract-set.v1.json
+++ b/e2e/product/schema/contract-set.v1.json
@@ -1,10 +1,10 @@
{
- "descriptor_digest": "sha256:67f113c402eff903feaab4969759d519a737fa7d225a0409320300272cdc6ba5",
+ "descriptor_digest": "sha256:a07f0fba88c73d351be68cd0a845ac2499a22212246fe276fcf4973d424f0972",
"files": {
"dependency-gate.v1.json": "sha256:b8ac81155266dca921f159d1cfabec6605f2e4bab0320ad6b23a3dbee51e6fa1",
"product-action.v1.schema.json": "sha256:faf815b27fd292e564a7d51de20c5a2825abbe710315a2364a9932ae3b5e4b7e",
"product-oracle-evidence.v1.schema.json": "sha256:faab6582bf3fba307b0f9f2949c51726409a209b0fa62e847114e0c6301038c6",
- "product-oracle-manifest.v1.json": "sha256:a0cbb10cc03a42b6752c54076198bf4acfccfbcefc20264e8af42e19b06874bd",
+ "product-oracle-manifest.v1.json": "sha256:fccbfb2ac7d3dbae43b4e2886ab10e60e375f545ff40403020c13c9d0fa5e21d",
"product-result.v1.schema.json": "sha256:72fc76be77572e40eed7516754911b45fdc9d55a8c089ba74c21427a33809def"
},
"schema_version": {
diff --git a/e2e/product/schema/product-oracle-manifest.v1.json b/e2e/product/schema/product-oracle-manifest.v1.json
index 4edfbe33..c62af1b1 100644
--- a/e2e/product/schema/product-oracle-manifest.v1.json
+++ b/e2e/product/schema/product-oracle-manifest.v1.json
@@ -1,5 +1,5 @@
{
- "descriptor_digest": "sha256:67f113c402eff903feaab4969759d519a737fa7d225a0409320300272cdc6ba5",
+ "descriptor_digest": "sha256:a07f0fba88c73d351be68cd0a845ac2499a22212246fe276fcf4973d424f0972",
"expected_red_reasons": [],
"planned_commands": [
"console.open",
diff --git a/issue-spec/specs/shared-client-access/spec.md b/issue-spec/specs/shared-client-access/spec.md
index 8e7454bc..218f2e0d 100644
--- a/issue-spec/specs/shared-client-access/spec.md
+++ b/issue-spec/specs/shared-client-access/spec.md
@@ -272,6 +272,13 @@ For the Quickstart and its supported branches, HiRoute SHALL expose navigable fa
- **WHEN** a caller has the installed CLI but no source checkout or validation artifacts and requests help/schema for a Quickstart command
- **THEN** the caller can determine required fields, enums, request wrappers and a valid minimal input; examples identify the queries supplying dynamic references.
+#### Scenario: Follow the published API connection-test examples
+
+- **WHEN** a caller reads installed help and full schemas to test a catalog option or custom API
+- **THEN** help commands specify an actual JSON input source and request document, and the schemas provide complete `registered` and `native` templates with their strict nested wrappers. Registered guidance obtains the complete expected catalog from current connection options and credentials through protected-input registration. Custom API guidance identifies caller-supplied endpoint/protocol facts. Templates select no inference model by default and distinguish syntactic validity from a successful provider check.
+- **AND** missing input, a flattened request or malformed command options retain usage-error semantics and give bounded corrective guidance without exposing credentials or echoing the raw request.
+- **AND** guidance distinguishes command completion and catalog candidate availability from provider verification. For a key-authenticated option with neither a supported inventory path nor an explicitly selected inference model, the check performs no remote probe; `reachability=not_run`, `authentication=unknown`, `directory=not_run` and `inference=not_run` leave connectivity and credentials unverified. Published recipes explain these results and do not claim remote verification from exit code 0 or a successful envelope.
+
#### Scenario: Prepare defaults without copying a sample
- **WHEN** a caller chooses fixed-model or smart-saving authoring and current candidates
@@ -294,6 +301,7 @@ For the Quickstart and its supported branches, HiRoute SHALL expose navigable fa
Source SPEC comments:
- https://github.com/higress-group/HiRoute/issues/125#issuecomment-6206259606
+- https://github.com/higress-group/HiRoute/issues/162
### Requirement: One canonical management Skill guides complete generic CLI journeys
diff --git a/scripts/ci-shards.py b/scripts/ci-shards.py
index 6a44b54a..232e5ce0 100755
--- a/scripts/ci-shards.py
+++ b/scripts/ci-shards.py
@@ -36,6 +36,7 @@ INTEGRATION_SHARDS = {
("hiroute-platform", "windows_read_lease"),
("hiroute-platform", "job_windows"),
("hiroute-platform", "windows_scm_owner"),
+ ("hiroute-cli", "connection_test_examples"),
("hiroute-cli", "contracts"),
("hiroute-cli", "desktop_locator"),
("hiroute-cli", "management_contracts"),