feat(inference): verify endpoints before saving routes

[pimlock]

🏗️ build-from-issue-agent

Closes #273

Summary

Verify inference endpoints by default during openshell inference set and openshell inference update so invalid routes are rejected before persistence. Keep an explicit --no-verify opt-out for endpoints that are not up yet, and return structured validation details when verification succeeds.

Why This Shape

• Verification now runs by default so the common path catches broken inference configuration early.
• --no-verify is the single explicit escape hatch for rollouts where the endpoint is expected to come up later.
• The server suggests retrying with --no-verify when validation fails and the route still needs to be saved.
• The validation timeout is increased to 15 seconds so slow or cold endpoints are less likely to fail spuriously during verification.

Changes Made

• proto/inference.proto: keep no_verify on SetClusterInferenceRequest so clients can disable the default verification pass when needed.
• crates/openshell-server/src/inference.rs: verify by default unless no_verify is set, raise timeout to 15 seconds, and map validation failures to actionable next steps.
• crates/openshell-router/src/backend.rs and crates/openshell-router/src/lib.rs: own provider-specific validation request shaping, auth/header behavior, and structured validation failure classification in the router/shared backend layer.
• crates/openshell-cli/src/main.rs: remove the explicit --verify flag and keep --no-verify as the user-facing opt-out on inference set / inference update.
• crates/openshell-cli/src/run.rs: send the no_verify override and print validated endpoints in a grouped list format.
• python/openshell/sandbox.py and python/openshell/sandbox_test.py: simplify Python helper support to no_verify=True only.
• docs/inference/configure.md and architecture/inference-routing.md: document verify-by-default behavior and the --no-verify opt-out.

Deviations from Plan

• No new e2e/ tests were added; coverage stays in focused server, CLI, router, and Python tests.
• Validation request shaping was moved into the router/backend layer rather than staying in the server so provider-specific call semantics live with the code that already owns them.

Tests Added

• Unit: RUSTC_WRAPPER= cargo test -p openshell-router backend::tests -- --nocapture
• Integration: RUSTC_WRAPPER= cargo test -p openshell-server inference::tests -- --nocapture, RUSTC_WRAPPER= cargo test -p openshell-cli inference_ -- --nocapture
• Python: uv run pytest python/openshell/sandbox_test.py -k inference -v
• E2E: N/A

Documentation Updated

• architecture/inference-routing.md: document default verification, router-owned validation logic, and the no_verify override.
• docs/inference/configure.md: explain verify-by-default behavior and when to retry with --no-verify.

Verification

• Focused router tests passing
• Focused server tests passing
• Focused CLI tests passing
• Focused Python helper tests passing
• Full mise run pre-commit green in this checkout

Verification Notes

I rebased this branch onto current origin/main and re-ran focused verification. Full mise run pre-commit is still not included here because the checkout has unrelated untracked local directories (.worktrees/, .agents/skills/debug-inference/) outside this PR scope.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-03-16 02:37 UTC

[pimlock]

🏗️ build-from-issue-agent

Updated the PR per follow-up discussion:

• verification is now opt-in via --verify instead of default-on
• the response now carries structured validated_endpoints metadata rather than single validated_url / validated_protocol fields
• the CLI shows a Configuring inference... spinner while the request is in flight and prints validated endpoint details when the server reports them

This keeps existing scripts on the current default behavior while still supporting explicit validation and richer success reporting.