Skip to content

armgit / avibe

Public Imported from GitHub
0

Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.

feat(model-hub): turn on web search services (S2b-2) (#2901)

Call White96237a0cf860
diff --git a/core/handlers/model_hub/adapter.py b/core/handlers/model_hub/adapter.py
index b8ab7f9c5..b786b6577 100644
--- a/core/handlers/model_hub/adapter.py
+++ b/core/handlers/model_hub/adapter.py
@@ -1,4 +1,4 @@
-"""Model Hub EngineAdapter interface. FINAL CONTRACT v19 (2026-10-21).
+"""Model Hub EngineAdapter interface. FINAL CONTRACT v20 (2026-10-21).
This file is the canonical adapter boundary and must remain byte-identical to
``core/handlers/model_hub/adapter.py``. The adapter owns one-Source operations:
diff --git a/core/handlers/model_hub/hosted_tools.py b/core/handlers/model_hub/hosted_tools.py
index 0804a5872..e6f0d321d 100644
--- a/core/handlers/model_hub/hosted_tools.py
+++ b/core/handlers/model_hub/hosted_tools.py
@@ -68,8 +68,8 @@ SpecLookup = Callable[[str, str, str, str], Optional[HostedToolSpec]]
UNKNOWN_ENGINE_RELEASE = "unknown-engine"
NATIVE_REPLAY_PROTOCOLS: frozenset[str] = frozenset({"anthropic", "openai_responses"})
-# S2b-2 enables this after the S6 disclosure ships. Never a user-facing toggle.
-SEARCH_SERVICES_ACTIVE: Final = False
+# S2b-2 activates the read and chain together; release with S6 disclosure. Not a user toggle.
+SEARCH_SERVICES_ACTIVE: Final = True
Assumption = Literal["assumed", "unsupported"]
diff --git a/core/handlers/model_hub/provenance.py b/core/handlers/model_hub/provenance.py
index a560e1502..f39f87bcc 100644
--- a/core/handlers/model_hub/provenance.py
+++ b/core/handlers/model_hub/provenance.py
@@ -2713,7 +2713,7 @@ class TurnCorrelationRegistry:
self.store.put(
{
- "contract_version": 19,
+ "contract_version": 20,
"turn_id": normalized_turn_id,
"ts": ts or _utc_now_iso(),
"agent": trace.agent,
diff --git a/core/handlers/model_hub/search_chain.py b/core/handlers/model_hub/search_chain.py
index 1c1a51918..9f90380ab 100644
--- a/core/handlers/model_hub/search_chain.py
+++ b/core/handlers/model_hub/search_chain.py
@@ -1,4 +1,4 @@
-"""Controller-owned mixed search chain; the dormant producer of service attempts.
+"""Controller-owned mixed search chain and producer of service attempts.
The turn freezes choices, not runtime health. Every slot is classified on the
current snapshot; a service rechecks that snapshot immediately before writing
diff --git a/core/handlers/model_hub/service.py b/core/handlers/model_hub/service.py
index 6147687e5..39afbe678 100644
--- a/core/handlers/model_hub/service.py
+++ b/core/handlers/model_hub/service.py
@@ -265,7 +265,7 @@ from .usage import (
local_usage_day,
)
-CONTRACT_VERSION = 19
+CONTRACT_VERSION = 20
def seeded_source_name(vendor: str) -> str:
@@ -388,8 +388,8 @@ def _described_as_unfit_for_agent_turns(match: Mapping[str, Any]) -> bool:
)
-AGENT_CHAIN_CONTRACT_VERSION = 19
-PROBE_RESULT_CONTRACT_VERSION = 19
+AGENT_CHAIN_CONTRACT_VERSION = 20
+PROBE_RESULT_CONTRACT_VERSION = 20
_SOURCE_DISCOVERY_TIMEOUT_SECONDS = 15
_SOURCE_PROBE_TIMEOUT_SECONDS = 60
# Background inventory refresh. The first tick doubles as the startup delay, so
@@ -1393,7 +1393,7 @@ def _runtime_payload(status: EngineStatus, *, enabled: bool) -> dict:
manager = EngineRuntimeManager()
return {
- "contract_version": 19,
+ "contract_version": 20,
"enabled": enabled,
"host_platform": status.host_platform or manager.host_platform(),
"manifest": manager.contract_manifest(),
diff --git a/docs/plans/model-hub-contracts/README.md b/docs/plans/model-hub-contracts/README.md
index 734b3447b..832656664 100644
--- a/docs/plans/model-hub-contracts/README.md
+++ b/docs/plans/model-hub-contracts/README.md
@@ -1,8 +1,15 @@
# Model Hub contracts
-Status: **contract_version 19**, 2026-10-21: dormant web-search-service readers and producer
+Status: **contract_version 20**, 2026-10-22: active web-search services (S2b-2).
+`gh-v3.2.3rc1` and `gh-v3.2.3rc2` carry v19, so activation opens v20 rather than
+changing the released event. `SEARCH_SERVICES_ACTIVE = True` activates service candidates,
+`service_vendors`, frozen turn settings and the mixed search chain together with S6 disclosure.
+The versioned mirrors advance together; persisted TurnProvenance retains v5–v19 and adds v20.
+The downgrade warning in `../web-search-services.md` §12 remains required.
+
+It builds on v19 (2026-10-21): dormant web-search-service readers and producer
(S2a/S2b-1, `../web-search-services.md` §3–5, §6.5, §8). The RC tag `gh-v3.2.2rc13`
-carries v18, so these additions open a new event rather than changing v18.
+carries v18, so those additions opened a new event rather than changing v18.
- C-1 (`../agent-core-contracts/message.schema.json`) accepts `HostedRecord.attempts[]`
(`HostedAttempt`), `HostedCost.estimate`, and a `ServiceExecutorOrigin`
(`{provider, api: "search_api", model}`) beside the released `Origin` in
@@ -18,11 +25,9 @@ carries v18, so these additions open a new event rather than changing v18.
`kind: "service"` bucket rows, `service_reported_usd` and `excluded_service_requests`
on totals and days, and `pricing.service_price_date`. Model counts never include
service requests.
-- S2b-1 adds the producer behind `SEARCH_SERVICES_ACTIVE = False`: unified service/model
- order, per-turn frozen preference/settings, bounded mapping, independently fenced service
- cooldowns and Source health, re-enable trials, sent-request metering and positive evidence.
- The flag-off runtime/read remain unchanged. S2b-2 activates only with S6 disclosure;
- the downgrade boundary of `../web-search-services.md` §12 begins when these shapes are written.
+- S2b-1 added the gated unified service/model chain: frozen preference/settings, bounded mapping,
+ independently fenced service cooldowns and Source health, re-enable trials, sent-request metering
+ and positive evidence. The flag-off runtime/read stayed unchanged in v19; S2b-2 activates in v20.
- `POST /api/models/hosted-tools/web_search/services/<source_id>/retry` clears the controller's
service cooldown and advances its generation, with a plain success response. It is available
regardless of activation and follows the existing Member management boundary.
@@ -43,9 +48,9 @@ than changing v17.
- The Tools read adds `prefer_native`, saved `services`, read-only `service_order`,
model/service candidate discriminants, service settings/health/trial/cooldown
fields, and service vendor facts.
-- Service candidates and `service_vendors` remain absent behind the single internal
- activation gate until S2. There is no new UI, service execution, placement rule,
- turn freeze or native-preference routing change in S1b.
+- S1b kept service candidates and `service_vendors` absent behind the single internal
+ activation gate, with no UI, service execution, placement rule, turn freeze or native-preference
+ routing change. S2b-2 activates them together in v20.
- The 2026-10-20 owner decision makes phase-1 web search snippet-only. This event
withdraws v17's bundled page-content request/result mappings, `content_max_chars`
and per-page price extras; Exa's included `contents.highlights`, reported-cost
@@ -64,8 +69,8 @@ It builds on v17 (2026-10-19): search-service foundations
credential custody, free checks, re-enable response and service-order persistence
shipped before search execution in `gh-v3.2.2rc12`. Its page-content metadata is
withdrawn by v18 as recorded above. Later lanes extend the current version event
-only while it is unshipped; an RC freezes its meaning. S2 activates the service
-reads and snippet-only search chain.
+only while it is unshipped; an RC freezes its meaning. S2b-2 activates the service
+read and snippet-only search chain.
Catalog metadata verified on **2026-10-21**:
- DeepSeek maps the model-facing `summary` and bills only non-empty 200 results; its
@@ -337,7 +342,7 @@ comparison. A gate may not report success by comparing stale input with itself.
## Version closure
-`contract_version` 19 must coexist in all registered version locations on the same tested head:
+`contract_version` 20 must coexist in all registered version locations on the same tested head:
- `mirror-registry.json`
- `agent-chain.schema.json`
diff --git a/docs/plans/model-hub-contracts/adapter-interface.py b/docs/plans/model-hub-contracts/adapter-interface.py
index b8ab7f9c5..b786b6577 100644
--- a/docs/plans/model-hub-contracts/adapter-interface.py
+++ b/docs/plans/model-hub-contracts/adapter-interface.py
@@ -1,4 +1,4 @@
-"""Model Hub EngineAdapter interface. FINAL CONTRACT v19 (2026-10-21).
+"""Model Hub EngineAdapter interface. FINAL CONTRACT v20 (2026-10-21).
This file is the canonical adapter boundary and must remain byte-identical to
``core/handlers/model_hub/adapter.py``. The adapter owns one-Source operations:
diff --git a/docs/plans/model-hub-contracts/agent-chain.schema.json b/docs/plans/model-hub-contracts/agent-chain.schema.json
index 755c7154d..adf8f4680 100644
--- a/docs/plans/model-hub-contracts/agent-chain.schema.json
+++ b/docs/plans/model-hub-contracts/agent-chain.schema.json
@@ -7,7 +7,7 @@
"required": ["contract_version", "backend", "model_id", "manual_override", "route_origin", "chain", "current", "supply_state"],
"additionalProperties": false,
"properties": {
- "contract_version": { "const": 19 },
+ "contract_version": { "const": 20 },
"backend": { "enum": ["claude", "codex", "opencode", "vibey"] },
"model_id": { "type": "string" },
"manual_override": {
@@ -255,7 +255,7 @@
],
"examples": [
{
- "contract_version": 19,
+ "contract_version": 20,
"backend": "codex",
"model_id": "unlisted-model",
"manual_override": null,
@@ -265,7 +265,7 @@
"supply_state": "ok"
},
{
- "contract_version": 19,
+ "contract_version": 20,
"backend": "codex",
"model_id": "gpt-5.6",
"manual_override": null,
@@ -275,7 +275,7 @@
"supply_state": "ok"
},
{
- "contract_version": 19,
+ "contract_version": 20,
"backend": "claude",
"model_id": "claude-opus-4-6",
"manual_override": null,
@@ -285,7 +285,7 @@
"supply_state": "waiting"
},
{
- "contract_version": 19,
+ "contract_version": 20,
"backend": "opencode",
"model_id": "glm-5.2",
"manual_override": { "hops": [{ "source_id": "src_relay9c1x", "model_id": "glm-5.2" }] },
@@ -295,7 +295,7 @@
"supply_state": "waiting"
},
{
- "contract_version": 19,
+ "contract_version": 20,
"backend": "codex",
"model_id": "gpt-5.6",
"manual_override": null,
@@ -305,7 +305,7 @@
"supply_state": "interrupted"
},
{
- "contract_version": 19,
+ "contract_version": 20,
"backend": "codex",
"model_id": "gpt-5.6",
"manual_override": null,
@@ -315,7 +315,7 @@
"supply_state": "interrupted"
},
{
- "contract_version": 19,
+ "contract_version": 20,
"backend": "claude",
"model_id": "claude-haiku-4-5",
"manual_override": null,
diff --git a/docs/plans/model-hub-contracts/api-response.schema.json b/docs/plans/model-hub-contracts/api-response.schema.json
index 9f3dddfd3..e85f90252 100644
--- a/docs/plans/model-hub-contracts/api-response.schema.json
+++ b/docs/plans/model-hub-contracts/api-response.schema.json
@@ -62,7 +62,7 @@
"required": ["ok", "contract_version", "probe"],
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"probe": {"$ref": "model-hub/source-probe-result.schema.json"}
}
},
@@ -161,7 +161,7 @@
"SuccessCore": {
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19}
+ "contract_version": {"const": 20}
}
},
"SourceListResponse": {
@@ -170,7 +170,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"sources": {"type": "array", "items": {"$ref": "#/definitions/SourceApi"}}
}
},
@@ -180,7 +180,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"observation": {"$ref": "model-hub/observation-result.schema.json"}
}
},
@@ -190,7 +190,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"source": {"$ref": "#/definitions/SourceApi"},
"added_to": {"type": "array", "items": {"$ref": "#/definitions/AddedTo"}},
"adopted_by": {"type": "array", "items": {"$ref": "#/definitions/AdoptedBy"}, "uniqueItems": true}
@@ -202,7 +202,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"source": {"$ref": "#/definitions/SourceApi"}
}
},
@@ -212,7 +212,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"source": {"$ref": "#/definitions/SourceApi"},
"removed_hops": {"type": "array", "items": {"$ref": "#/definitions/RouteHopRef"}},
"interrupted": {"type": "array", "items": {"$ref": "#/definitions/SupplyGap"}}
@@ -224,7 +224,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"source": {
"allOf": [
{"$ref": "#/definitions/SourceApi"},
@@ -242,7 +242,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"removed_hops": {"type": "array", "items": {"$ref": "#/definitions/RouteHopRef"}},
"interrupted": {"type": "array", "items": {"$ref": "#/definitions/SupplyGap"}}
}
@@ -253,7 +253,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"agents": {"type": "array", "items": {"$ref": "#/definitions/AgentSupplyApi"}}
}
},
@@ -263,7 +263,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"agent": {"$ref": "#/definitions/AgentSupplyApi"}
}
},
@@ -280,7 +280,7 @@
],
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"agent": {"$ref": "#/definitions/AgentSupplyApi"},
"removed_hops": {"type": "array", "items": {"$ref": "#/definitions/RouteHopRef"}, "uniqueItems": true},
"interrupted": {"type": "array", "items": {"$ref": "#/definitions/SupplyGap"}, "uniqueItems": true}
@@ -305,7 +305,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": false},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"error": {"const": "candidate_suppliers_changed"},
"detail": {"type": "string", "minLength": 1},
"changed": {
@@ -325,7 +325,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"agent": {
"type": "object",
"required": ["backend", "mode", "catalog_models"],
@@ -426,7 +426,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"candidates": {
"type": "object",
"required": ["builtin", "providers", "in_list"],
@@ -445,7 +445,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"matches": {
"type": "array",
"maxItems": 8,
@@ -479,7 +479,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"chain": {"$ref": "model-hub/agent-chain.schema.json"}
}
},
@@ -489,7 +489,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"chains": {"type": "array", "items": {"$ref": "model-hub/agent-chain.schema.json"}}
}
},
@@ -499,7 +499,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"chain": {"$ref": "model-hub/agent-chain.schema.json"},
"removed_hops": {"type": "array", "items": {"$ref": "#/definitions/RouteHopRef"}},
"interrupted": {"type": "array", "items": {"$ref": "#/definitions/SupplyGap"}}
@@ -511,7 +511,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"probe": {"$ref": "model-hub/probe-result.schema.json"}
}
},
@@ -521,7 +521,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"events": {"type": "array", "items": {"$ref": "model-hub/resolution-event.schema.json"}}
}
},
@@ -531,7 +531,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"usage": {"$ref": "model-hub/usage-summary.schema.json"}
}
},
@@ -541,7 +541,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"quota": {"$ref": "model-hub/quota-summary.schema.json"}
}
},
@@ -551,7 +551,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"hosted_tools": {"$ref": "model-hub/hosted-tools-status.schema.json"}
}
},
@@ -561,7 +561,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"flow": {
"allOf": [
{"$ref": "model-hub/oauth-flow.schema.json"},
@@ -583,7 +583,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"flow": {
"allOf": [
{"$ref": "model-hub/oauth-flow.schema.json"},
@@ -606,7 +606,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"flow": {
"allOf": [
{"$ref": "model-hub/oauth-flow.schema.json"},
@@ -631,7 +631,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19}
+ "contract_version": {"const": 20}
}
},
"RuntimeApi": {
@@ -653,7 +653,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"scan": {"$ref": "model-hub/migration-scan.schema.json"}
}
},
@@ -663,7 +663,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"applied": {"type": "integer", "minimum": 0},
"sources": {"type": "array", "items": {"$ref": "#/definitions/SourceApi"}},
"added_to": {"type": "array", "items": {"$ref": "#/definitions/AddedTo"}}
@@ -675,7 +675,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"provenance": {"$ref": "model-hub/turn-provenance.schema.json"}
}
},
@@ -686,7 +686,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"provenance": {
"anyOf": [
{"$ref": "model-hub/turn-provenance.schema.json"},
@@ -701,7 +701,7 @@
"additionalProperties": false,
"properties": {
"ok": {"const": true},
- "contract_version": {"const": 19},
+ "contract_version": {"const": 20},
"runtime": {"$ref": "#/definitions/RuntimeApi"}
}
}
diff --git a/docs/plans/model-hub-contracts/api.md b/docs/plans/model-hub-contracts/api.md
index 6752ee3e8..4c6e94996 100644
--- a/docs/plans/model-hub-contracts/api.md
+++ b/docs/plans/model-hub-contracts/api.md
@@ -8,11 +8,11 @@ credential redaction and supply-impact confirmation rules still apply; unknown
API siblings retain the Owner default.
-Status: **Normative, `contract_version` 19** — Model Hub implementations must conform, and the response conformance guard enumerates this route table and validates one real server response for every route.
+Status: **Normative, `contract_version` 20** — Model Hub implementations must conform, and the response conformance guard enumerates this route table and validates one real server response for every route.
-Success envelope: `{ok: true, contract_version: 19, ...}`.
+Success envelope: `{ok: true, contract_version: 20, ...}`.
Failure envelope:
-`{ok: false, contract_version: 19, error: <machine_code>, detail?: <i18n_key>}`.
+`{ok: false, contract_version: 20, error: <machine_code>, detail?: <i18n_key>}`.
`detail` is always a string. Structured error data lives in a named sibling.
Guarded mutation refusals specialize that envelope through
`guard-refusal.schema.json`; both report arrays are required and together form the plan
@@ -24,7 +24,7 @@ table. The contract guard requires the two endpoint sets to be identical, requir
exercised HTTP response for every registry entry, and validates that response against
the route's named schema.
-The shared envelope and every versioned nested contract carry `contract_version` 19, the
+The shared envelope and every versioned nested contract carry `contract_version` 20, the
terminal value. Supported persisted config shapes and historical TurnProvenance
remain readable; ephemeral envelopes use only the terminal version.
@@ -47,7 +47,7 @@ runtime open. Once models are configured it participates in the runtime Stop gua
| POST `/api/models/sources/<id>/reauth` | `{acknowledge_irreversible?: true}` → `{flow: OAuthFlow}` | Both Hub OAuth and `native_cli` Sources require the acknowledgement before OAuth starts. Missing or false acknowledgement returns `reauth_confirmation_required` before any adapter call. See repair rules. |
| DELETE `/api/models/sources/<id>?force=<bool>` | `{would_remove_hops?: RouteHopRef[], would_interrupt?: SupplyGap[]}` → guarded `409` or `{removed_hops, interrupted}` | A confirmed delete removes the Source from every backend Source order and Route chain in one transaction. A nonempty destructive plan commits only when the body exactly echoes the current refusal plan. |
| POST `/api/models/sources/<id>/refresh` | `{force?: boolean, would_remove_hops?: RouteHopRef[], would_interrupt?: SupplyGap[]}` → guarded Source-mutation envelope | The sole saved connectivity/discovery/recovery mutation. |
-| POST `/api/models/sources/<id>/reenable` | `{}` → `{source: Source, removed_hops: [], interrupted: [], trial_armed?: boolean}` | Tool-only `search` Source recovery. It advances the Source settlement generation without interrupting work. With a free check, `pass` clears the state, `invalid` moves to the existing invalid-key state, and `balance`, `limit` or `unknown` keep or reclassify the current state without arming a trial. A Source without a free check keeps persisted `needs_action` and arms a process-local one-shot trial, reported as `trial_armed: true`; `Source.trial_pending` is true while that trial is armed or in flight, and a repeated request returns the current trial without advancing the generation. S2's search gate owns its admission and settlement. No paid search is sent. |
+| POST `/api/models/sources/<id>/reenable` | `{}` → `{source: Source, removed_hops: [], interrupted: [], trial_armed?: boolean}` | Tool-only `search` Source recovery. It advances the Source settlement generation without interrupting work. When the catalog's free check can classify the current blocker, `pass` clears the state, `invalid` moves to the existing invalid-key state, and `balance`, `limit` or `unknown` keep or reclassify the current state without arming a trial. Without a check that can classify that blocker, the Source keeps persisted `needs_action` and arms a process-local one-shot trial, reported as `trial_armed: true`; `Source.trial_pending` is true while that trial is armed or in flight, and a repeated request returns the current trial without advancing the generation. S2's search gate owns its admission and settlement. No paid search is sent. |
| POST `/api/models/sources/<id>/probe` | `{model}` → `{probe: SourceProbeResult}` | Explicit API-key test through the managed invocation adapter, using this exact Source/model/protocol. The model must be a non-retired saved inventory row. No Agent routing, fallback, discovery, credential refresh or Source-health change. Only a successful matching credential invocation clears pending verification. Usage is metered; the total invocation deadline is 60 seconds. |
| POST `/api/models/sources/<source_id>/models` | `{model_id, display_name?, reasoning_efforts}` → `{source: Source}` | Creates one user-authored model entry. The Source identity comes only from the path. |
| PATCH `/api/models/sources/<source_id>/models/<model_id>` | `{reasoning_efforts}` → `{source: Source}` | Replaces the complete capability list only when `reasoning_efforts_source` is `user` or null, without changing identity, origin, or Routes. An `upstream` or `catalog` declaration returns HTTP 409 `source_model_tiers_managed` with its provenance in the `reasoning_efforts_source` sibling. |
@@ -73,7 +73,7 @@ runtime open. Once models are configured it participates in the runtime Stop gua
| GET `/api/models/quota` | → `{quota: QuotaSummary}` | Rate-limit windows of every hub-held subscription Source, from the vendor's own usage report, plus each Source's API-price `value` (see Subscription quota). Served from the server cache; a Source older than five minutes is re-read before answering, bounded by a short deadline, and a Source still being read is listed in `pending`. Never starts the engine. |
| POST `/api/models/quota/refresh` | → `{quota: QuotaSummary}` | Forced re-read. Rate-limited per Source to one vendor call every 30 seconds and suppressed while a Source cools down after a vendor 429; a suppressed Source returns its cached snapshot. |
| GET `/api/models/hosted-tools` | → `{hosted_tools: HostedToolsStatus}` | Models → Tools (`hosted-tools-status.schema.json`): every catalog tool with its switch (absent setting = on), its passive status from real use (`latest_ok`, current `refused[]`, per-pair `verified[]`), for a search tool the saved and effective executor order with every eligible executor candidate and its unit rates, and for `image_generate` the saved and effective default and the available image models. Memory only; nothing is probed. |
-| POST `/api/models/hosted-tools/web_search/services/<source_id>/retry` | `{}` → `{}` | Clears the controller's `(Source, service)` cooldown, advances its generation, and leaves Source health unchanged. It is valid even while search services are dormant; the Tools read is the follow-up source of truth. Member management role. |
+| POST `/api/models/hosted-tools/web_search/services/<source_id>/retry` | `{}` → `{}` | Clears the controller's `(Source, service)` cooldown, advances its generation, and leaves Source health unchanged. The Tools read is the follow-up source of truth. Member management role. |
| PUT `/api/models/hosted-tools/<tool>` | `{enabled?: boolean, executor_order?: null \| [source_id], default_model?: null \| {source_id, model_id}, prefer_native?: boolean, services?: {source_id: null \| {results?: integer \| null, enabled?: boolean \| null}}}` → `{hosted_tools: HostedToolsStatus}` | Changes one tool's settings field by field: an absent field is unchanged, `null` resets `executor_order` to automatic or `default_model` to the default. `executor_order` is for search tools and `default_model` for `image_generate`; values are saved as given, never resolved. It applies from the next turn and interrupts nothing. An unknown tool returns `404 hosted_tool_not_found`; an empty or malformed body `400 invalid_parameter`, including a null `enabled`, an id that is not a Source id (`src_…`), or a model id with surrounding whitespace. |
| POST `/api/models/hosted-tools/<tool>/clear` | `{source_id?, model_id?}` → `{hosted_tools: HostedToolsStatus}` | Clears the tool's refusals (`call` and `replay`): on one Source and model, on one Source (every model), or with `{}` on every Source. `model_id` requires `source_id`; neither is nullable, so a malformed body is refused rather than widened into a broader clear. A Source or model with nothing to clear is a no-op that answers the read. The file is written first: a failed write returns `500 state_write_failed` and changes nothing. A cleared Source is assumed again from its next request. An unknown tool returns `404 hosted_tool_not_found`; any other body `400 invalid_parameter`. |
| POST `/api/models/sources/<source_id>/evidence/clear` | `{model_id, feature: {kind: "effort", name}}` → `{source: Source}` | Clears one effort refusal of a Source's model, so the next request at that effort may reach it. A missing record is a no-op. An unknown Source returns `404 source_not_found`; a hosted-tool feature or any other body `400 invalid_parameter` (hosted refusals clear through the Tools clear); a failed write `500 state_write_failed` with nothing changed. |
@@ -84,7 +84,7 @@ runtime open. Once models are configured it participates in the runtime Stop gua
| POST `/api/models/migration/scan` | → `{scan: MigrationScan}` | Read-only. |
| POST `/api/models/migration/apply` | `{item_ids: string[], clean_api_keys?: boolean}` → `{applied, sources, added_to}` | Applies one grouped, server-owned custody transaction. It checks saved configuration and custody locally, copies API keys without upstream validation, upgrades an existing native subscription Source in place when present, and commits Source/Routes/backend mode atomically. API-key originals are kept unless cleanup was selected. Pre-exposure failure is reversible; post-exposure recovery is forward-only and keeps the backend blocked until terminalized. |
| GET `/api/models/turns/<turn_id>/provenance` | → `{provenance: TurnProvenance}` or documented absence error | Debug read for exactly attributed Hub turns. |
-| GET `/api/models/runtime/status` | → `{runtime: RuntimeDependency}` | Read-only managed engine status. The nested object carries `contract_version` 19 and persisted user intent in `enabled`; `not_started` is installed lazy-start idleness, not an alarm. |
+| GET `/api/models/runtime/status` | → `{runtime: RuntimeDependency}` | Read-only managed engine status. The nested object carries `contract_version` 20 and persisted user intent in `enabled`; `not_started` is installed lazy-start idleness, not an alarm. |
| POST `/api/models/runtime/install` | → `{runtime: RuntimeDependency}` | Idempotently starts server-owned installation. It returns and persists `installing`; reload reads the same state. Uses the existing mutation authentication and CSRF guards. |
| POST `/api/models/runtime/start` | → `{runtime: RuntimeDependency}` | Persists `enabled: true` and explicitly starts the managed engine. Service startup restores this intent; runtime availability has no separate enable-confirmation step. Uses the existing mutation authentication and CSRF guards; status reads never start it. |
| POST `/api/models/runtime/stop` | → `{runtime: RuntimeDependency}` | Explicitly stops the managed engine, persists `enabled: false`, and returns it to `not_started`. The mutation is rejected with `runtime_in_use` while any native backend is configured for Hub mode or Avibe has catalog models, so disabling the shared runtime cannot strand a configured route. An empty Avibe catalog does not keep the runtime open. |
@@ -94,7 +94,7 @@ PUT and compatibility chains/reorder share backend-default semantics and effecti
preserving all manual arrays. Exact manual order is saved through the chain resource;
DELETE restores automatic and POST preview evaluates the draft without a write.
-### Web-search settings and dormant service read (S1b)
+### Web-search settings and active service read (S2b-2)
`web_search` additionally reads `prefer_native` (true when absent), `services`
(saved partial overrides for currently search-capable Sources, not resolved defaults), and `service_order`
@@ -104,13 +104,13 @@ Extant retargeted or retired Sources are omitted from `services` while they cann
search, but their overrides (especially opt-out) stay in config for when capability
returns. Removed Sources' overrides are ignored.
-Until S2b-2 activates execution with S6 disclosure, **the read contains no service candidates and omits
-`service_vendors` entirely**. One internal `SEARCH_SERVICES_ACTIVE` switch gates
-both. Settings load and save now, but `prefer_native` does not change hop facts
-and service settings do not change the model executor chain while the flag is off. No user-facing
-activation toggle exists.
+S2b-2 activates **service candidates and `service_vendors` together with execution** through
+`SEARCH_SERVICES_ACTIVE = True`. The read supplies S4's existing UI activation predicate;
+`prefer_native`, candidate roles and result counts are frozen for each turn and govern hop facts
+and the search chain. The activation release must include S6 disclosure. No user-facing activation
+toggle exists.
-The service variant is frozen for S4/S2 in `hosted-tools-status.schema.json`:
+The service variant is defined in `hosted-tools-status.schema.json`:
`model_id` is the catalog service id; `billing: "metered"`, `relay: false`, and
`price` is the catalog list price per search, with no page-text surcharge.
`settings` holds effective `{results, enabled}`;
@@ -721,7 +721,7 @@ The terminal result of both ordinary API-key creation and OAuth creation is:
```json
{
"ok": true,
- "contract_version": 19,
+ "contract_version": 20,
"source": {
"id": "src_anthkey01",
"kind": "api_key",
@@ -831,7 +831,7 @@ Every guarded Source/inventory mutation uses the §4.5 envelope matrix and the c
```json
{
"ok": false,
- "contract_version": 19,
+ "contract_version": 20,
"error": "source_last_supplier",
"would_remove_hops": [],
"would_interrupt": [
@@ -970,7 +970,7 @@ API-key success:
```json
{
"ok": true,
- "contract_version": 19,
+ "contract_version": 20,
"source": {
"id": "src_relay9c1x",
"kind": "api_key",
@@ -983,7 +983,7 @@ API-key success:
## Tool-only Source recovery
-`POST /api/models/sources/<id>/reenable` is the recovery mutation for a tool-only `search` Source. It advances the Source's settlement generation without interrupting work. When a free check exists, `pass` clears the state, `invalid` moves it to the existing invalid-key state, and `balance`, `limit` or `unknown` keep or reclassify the current state without arming a trial. A Source without a free check preserves persisted `needs_action` and arms an in-memory one-shot trial; `Source.trial_pending` is true while the trial is armed or in flight, and a repeated request returns the current trial without advancing the generation. The response carries `trial_armed: true` when the trial is armed, and S2's search gate admits and settles it. No paid test search is sent.
+`POST /api/models/sources/<id>/reenable` is the recovery mutation for a tool-only `search` Source. It advances the Source's settlement generation without interrupting work. When the catalog's free check can classify the current blocker, `pass` clears the state, `invalid` moves it to the existing invalid-key state, and `balance`, `limit` or `unknown` keep or reclassify the current state without arming a trial. Without a check that can classify that blocker (for example, Tavily's limit-only check cannot classify a balance blocker), the Source preserves persisted `needs_action` and arms an in-memory one-shot trial; `Source.trial_pending` is true while the trial is armed or in flight, and a repeated request returns the current trial without advancing the generation. The response carries `trial_armed: true` when the trial is armed, and S2's search gate admits and settles it. No paid test search is sent.
## Source refresh and blocked-source recovery
@@ -1065,7 +1065,7 @@ Status and submit return the same terminal shape:
```json
{
"ok": true,
- "contract_version": 19,
+ "contract_version": 20,
"flow": {
"flow_id": "oaf_claude01",
"client_nonce": "ofn_01j5w8z7p4n6q2rt",
@@ -1138,9 +1138,9 @@ a valid `interrupted` chain.
```json
{
"ok": true,
- "contract_version": 19,
+ "contract_version": 20,
"chain": {
- "contract_version": 19,
+ "contract_version": 20,
"backend": "codex",
"model_id": "gpt-5.6",
"manual_override": null,
@@ -1167,7 +1167,7 @@ In Direct mode both chain and probe refuse with:
```json
{
"ok": false,
- "contract_version": 19,
+ "contract_version": 20,
"error": "direct_mode",
"detail": "models.hub.direct_mode"
}
@@ -1181,9 +1181,9 @@ A successful probe nests its result:
```json
{
"ok": true,
- "contract_version": 19,
+ "contract_version": 20,
"probe": {
- "contract_version": 19,
+ "contract_version": 20,
"backend": "claude",
"channel": "hub",
"reachable": false,
@@ -1206,7 +1206,7 @@ not-ready carries the closed i18n key `models.probe.native_cli_unavailable`.
```json
{
- "contract_version": 19,
+ "contract_version": 20,
"backend": "codex",
"channel": "native_cli",
"reachable": true,
@@ -1219,7 +1219,7 @@ not-ready carries the closed i18n key `models.probe.native_cli_unavailable`.
```json
{
- "contract_version": 19,
+ "contract_version": 20,
"backend": "codex",
"channel": "native_cli",
"reachable": false,
@@ -1235,7 +1235,7 @@ No candidate is an API error with a typed model-scoped state:
```json
{
"ok": false,
- "contract_version": 19,
+ "contract_version": 20,
"error": "probe_no_candidate",
"detail": "models.probe.no_candidate.waiting",
"supply": {
@@ -1426,7 +1426,7 @@ The store retains at most 500 exactly attributed settled turns with its existing
writes. Ambiguous attribution remains excluded; this is not a log of every upstream
request. Null means no matching retained record, including eviction. A newer served,
canceled or other record without a terminal error supersedes older error display.
-Success uses exactly `{ok: true, contract_version: 19, provenance: TurnProvenance | null}`;
+Success uses exactly `{ok: true, contract_version: 20, provenance: TurnProvenance | null}`;
there is no `success` field or envelope exception.
Local `engine_down` records may also contain `local_error_detail`, an OS-generated
@@ -1520,7 +1520,7 @@ ambiguous absence are explicit and distinguishable from an unknown turn:
```json
{
"ok": false,
- "contract_version": 19,
+ "contract_version": 20,
"error": "provenance_unavailable",
"detail": "models.provenance.direct_mode"
}
@@ -1529,7 +1529,7 @@ ambiguous absence are explicit and distinguishable from an unknown turn:
```json
{
"ok": false,
- "contract_version": 19,
+ "contract_version": 20,
"error": "provenance_unavailable",
"detail": "models.provenance.attribution_ambiguous"
}
diff --git a/docs/plans/model-hub-contracts/guard-refusal.schema.json b/docs/plans/model-hub-contracts/guard-refusal.schema.json
index 3029168ed..faca6db29 100644
--- a/docs/plans/model-hub-contracts/guard-refusal.schema.json
+++ b/docs/plans/model-hub-contracts/guard-refusal.schema.json
@@ -61,7 +61,7 @@
],
"properties": {
"ok": { "const": false },
- "contract_version": { "const": 19 },
+ "contract_version": { "const": 20 },
"error": {
"enum": [
"source_last_supplier",
@@ -116,7 +116,7 @@
"examples": [
{
"ok": false,
- "contract_version": 19,
+ "contract_version": 20,
"error": "source_model_in_route_chain",
"detail": "modelHub.errors.source_model_in_route_chain",
"would_remove_hops": [
diff --git a/docs/plans/model-hub-contracts/hosted-tools-status.schema.json b/docs/plans/model-hub-contracts/hosted-tools-status.schema.json
index 383217a5a..e6abcb36c 100644
--- a/docs/plans/model-hub-contracts/hosted-tools-status.schema.json
+++ b/docs/plans/model-hub-contracts/hosted-tools-status.schema.json
@@ -130,7 +130,7 @@
},
"ServiceExecutor": {
"type": "object",
- "description": "Dormant until S2. A search API's catalog service id occupies model_id; Source health and one-shot trial state are display facts, not a probe.",
+ "description": "A search API's catalog service id occupies model_id; Source health and one-shot trial state are display facts, not a probe.",
"required": ["kind", "source_id", "model_id", "billing", "relay", "price", "settings", "state", "trial_pending", "cooldown_until"],
"additionalProperties": false,
"properties": {
@@ -185,7 +185,7 @@
}],
"properties": {
"name": { "enum": ["web_search", "x_search"] },
- "prefer_native": { "type": "boolean", "description": "Saved preference, true when absent. S2 activates its effect on hop facts." },
+ "prefer_native": { "type": "boolean", "description": "Saved preference, true when absent; active search hops honor it." },
"services": {
"type": "object",
"description": "Saved partial overrides for currently search-capable Sources, not resolved defaults. Extant retargeted/retired Sources are omitted while incapable, but their overrides remain in config for when capability returns. Removed Sources are ignored and obsolete catalog bounds read clamped.",
@@ -193,7 +193,7 @@
"additionalProperties": { "$ref": "#/definitions/SavedServiceSettings" }
},
"service_order": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/definitions/SourceId" }, "description": "Server-owned tool-only Source creation order, skipping ids that no longer name a Source. Read-only; absent config reads as an empty list." },
- "service_vendors": { "type": "array", "items": { "$ref": "#/definitions/ServiceVendor" }, "description": "Absent until S2 activates both service reads and execution. Not a client toggle." },
+ "service_vendors": { "type": "array", "items": { "$ref": "#/definitions/ServiceVendor" }, "description": "Catalog vendors exposed with active service candidates and execution." },
"enabled": { "type": "boolean" },
"status": { "$ref": "#/definitions/Status" },
"executor_order": {
diff --git a/docs/plans/model-hub-contracts/mirror-registry.json b/docs/plans/model-hub-contracts/mirror-registry.json
index d79a68b48..269806901 100644
--- a/docs/plans/model-hub-contracts/mirror-registry.json
+++ b/docs/plans/model-hub-contracts/mirror-registry.json
@@ -1,5 +1,5 @@
{
- "contract_version": 19,
+ "contract_version": 20,
"input_generation": {
"mode": "same_run_live_files",
"external_snapshot": "content_fingerprint_required"
diff --git a/docs/plans/model-hub-contracts/observation-result.schema.json b/docs/plans/model-hub-contracts/observation-result.schema.json
index 658187c58..458aff8cf 100644
--- a/docs/plans/model-hub-contracts/observation-result.schema.json
+++ b/docs/plans/model-hub-contracts/observation-result.schema.json
@@ -16,7 +16,7 @@
],
"additionalProperties": false,
"properties": {
- "contract_version": { "const": 19 },
+ "contract_version": { "const": 20 },
"outcome": {
"enum": [
"observed",
@@ -150,7 +150,7 @@
],
"examples": [
{
- "contract_version": 19,
+ "contract_version": 20,
"outcome": "observed",
"reachable": true,
"authenticated": "authenticated",
@@ -165,7 +165,7 @@
]
},
{
- "contract_version": 19,
+ "contract_version": 20,
"outcome": "authentication_failed",
"reachable": true,
"authenticated": "rejected",
@@ -175,7 +175,7 @@
"model_metadata": []
},
{
- "contract_version": 19,
+ "contract_version": 20,
"outcome": "ambiguous",
"reachable": true,
"authenticated": "unknown",
@@ -185,7 +185,7 @@
"model_metadata": []
},
{
- "contract_version": 19,
+ "contract_version": 20,
"outcome": "unreachable",
"reachable": false,
"authenticated": "unknown",
@@ -195,7 +195,7 @@
"model_metadata": []
},
{
- "contract_version": 19,
+ "contract_version": 20,
"outcome": "adapter_error",
"reachable": null,
"authenticated": "unknown",
@@ -205,7 +205,7 @@
"model_metadata": []
},
{
- "contract_version": 19,
+ "contract_version": 20,
"outcome": "timeout",
"reachable": null,
"authenticated": "unknown",
diff --git a/docs/plans/model-hub-contracts/probe-result.schema.json b/docs/plans/model-hub-contracts/probe-result.schema.json
index 219b1a219..0d56dd1cc 100644
--- a/docs/plans/model-hub-contracts/probe-result.schema.json
+++ b/docs/plans/model-hub-contracts/probe-result.schema.json
@@ -7,7 +7,7 @@
"required": ["contract_version", "backend", "channel", "reachable", "source_id", "model_id", "latency_ms", "error"],
"additionalProperties": false,
"properties": {
- "contract_version": { "const": 19 },
+ "contract_version": { "const": 20 },
"backend": { "enum": ["claude", "codex", "opencode", "vibey"] },
"channel": { "enum": ["hub", "native_cli"] },
"reachable": { "type": "boolean" },
@@ -68,10 +68,10 @@
}
],
"examples": [
- { "contract_version": 19, "backend": "codex", "channel": "hub", "reachable": true, "source_id": "src_chatgptplus", "model_id": "gpt-5.6", "latency_ms": 412, "error": null },
- { "contract_version": 19, "backend": "claude", "channel": "hub", "reachable": false, "source_id": "src_relay9c1x", "model_id": "glm-5.2", "latency_ms": 287, "error": "models.source.needs_action.balance_exhausted" },
- { "contract_version": 19, "backend": "codex", "channel": "hub", "reachable": false, "source_id": "src_chatgptplus", "model_id": "gpt-5.6", "latency_ms": null, "error": "models.source.backoff.connection_failed" },
- { "contract_version": 19, "backend": "codex", "channel": "native_cli", "reachable": true, "source_id": "src_chatgptplus", "model_id": "gpt-5.6", "latency_ms": null, "error": null },
- { "contract_version": 19, "backend": "codex", "channel": "native_cli", "reachable": false, "source_id": "src_chatgptplus", "model_id": "gpt-5.6", "latency_ms": null, "error": "models.probe.native_cli_unavailable" }
+ { "contract_version": 20, "backend": "codex", "channel": "hub", "reachable": true, "source_id": "src_chatgptplus", "model_id": "gpt-5.6", "latency_ms": 412, "error": null },
+ { "contract_version": 20, "backend": "claude", "channel": "hub", "reachable": false, "source_id": "src_relay9c1x", "model_id": "glm-5.2", "latency_ms": 287, "error": "models.source.needs_action.balance_exhausted" },
+ { "contract_version": 20, "backend": "codex", "channel": "hub", "reachable": false, "source_id": "src_chatgptplus", "model_id": "gpt-5.6", "latency_ms": null, "error": "models.source.backoff.connection_failed" },
+ { "contract_version": 20, "backend": "codex", "channel": "native_cli", "reachable": true, "source_id": "src_chatgptplus", "model_id": "gpt-5.6", "latency_ms": null, "error": null },
+ { "contract_version": 20, "backend": "codex", "channel": "native_cli", "reachable": false, "source_id": "src_chatgptplus", "model_id": "gpt-5.6", "latency_ms": null, "error": "models.probe.native_cli_unavailable" }
]
}
diff --git a/docs/plans/model-hub-contracts/runtime-dependency.schema.json b/docs/plans/model-hub-contracts/runtime-dependency.schema.json
index 90c90c12c..b75389f90 100644
--- a/docs/plans/model-hub-contracts/runtime-dependency.schema.json
+++ b/docs/plans/model-hub-contracts/runtime-dependency.schema.json
@@ -7,7 +7,7 @@
"required": ["contract_version", "manifest", "status"],
"additionalProperties": false,
"properties": {
- "contract_version": { "const": 19 },
+ "contract_version": { "const": 20 },
"enabled": {
"type": "boolean",
"description": "Persisted user intent for the managed gateway. Fresh/default configuration is true; explicit stop persists false."
@@ -131,7 +131,7 @@
},
"examples": [
{
- "contract_version": 19,
+ "contract_version": 20,
"host_platform": "darwin-arm64",
"manifest": {
"name": "cliproxyapi",
diff --git a/docs/plans/model-hub-contracts/turn-provenance.schema.json b/docs/plans/model-hub-contracts/turn-provenance.schema.json
index be82f1b65..74b0124f1 100644
--- a/docs/plans/model-hub-contracts/turn-provenance.schema.json
+++ b/docs/plans/model-hub-contracts/turn-provenance.schema.json
@@ -36,7 +36,7 @@
"additionalProperties": false,
"properties": {
"contract_version": {
- "enum": [5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19],
+ "enum": [5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20],
"$comment": "The only versioned object written to disk, so released versions form a set rather than a constant. Historical records validate after the existing persistence-read normalization of retired reasons; tests/fixtures/model_hub/released_v5_permission_denied.json exercises that boundary, not raw-file validation. Reading preserves the writer generation and requires no new route fields. New records carry the terminal member. Other versioned objects are ephemeral envelopes pinned to that value alone.",
"description": "Generation that wrote this record. Readers retain every supported released value, apply existing retired-reason normalization independently of version, and do not require route_origin or manual_override."
},
@@ -487,7 +487,7 @@
],
"examples": [
{
- "contract_version": 19,
+ "contract_version": 20,
"turn_id": "turn_01k9x2m4",
"ts": "2026-07-29T06:32:11Z",
"agent": "claude",
@@ -512,7 +512,7 @@
"blockers": []
},
{
- "contract_version": 19,
+ "contract_version": 20,
"turn_id": "turn_01k9x33p",
"ts": "2026-07-29T06:41:02Z",
"agent": "opencode",
@@ -533,7 +533,7 @@
"blockers": []
},
{
- "contract_version": 19,
+ "contract_version": 20,
"turn_id": "turn_01k9x3zq",
"ts": "2026-07-29T06:48:20Z",
"agent": "codex",
@@ -553,7 +553,7 @@
]
},
{
- "contract_version": 19,
+ "contract_version": 20,
"turn_id": "turn_01k9x4b7",
"ts": "2026-07-29T07:02:44Z",
"agent": "claude",
@@ -573,7 +573,7 @@
"blockers": []
},
{
- "contract_version": 19,
+ "contract_version": 20,
"turn_id": "turn_modelmissing01",
"ts": "2026-09-05T17:31:10Z",
"agent": "claude",
@@ -595,7 +595,7 @@
"blockers": []
},
{
- "contract_version": 19,
+ "contract_version": 20,
"turn_id": "turn_01k9x5ca",
"ts": "2026-07-29T07:08:00Z",
"agent": "codex",
diff --git a/docs/plans/web-search-services-s1b.md b/docs/plans/web-search-services-s1b.md
index 949ed6928..27534a71c 100644
--- a/docs/plans/web-search-services-s1b.md
+++ b/docs/plans/web-search-services-s1b.md
@@ -1,4 +1,7 @@
-# S1b: settings and dormant Tools read
+# S1b: settings and prepared Tools read (historical)
+
+This records S1b's gated delivery. S2b-2 now activates the read and execution together;
+see `web-search-services.md` §9 for current release ordering.
Source of truth: `web-search-services.md` §3.2, §3.5, §8–9; S1a is merged as
`68a59d11e9dea070f5fe4d231e90d0acbc2aca64`.
diff --git a/docs/plans/web-search-services-s2a.md b/docs/plans/web-search-services-s2a.md
index eeeb1d366..ae6caa1ac 100644
--- a/docs/plans/web-search-services-s2a.md
+++ b/docs/plans/web-search-services-s2a.md
@@ -1,4 +1,7 @@
-# Web search services S2a: readers before writers
+# Web search services S2a: readers before writers (historical)
+
+This records S2a's reader-only delivery. S2b-2 now activates the producer and service read
+together; see `web-search-services.md` §9 for current release ordering.
Source of truth: [web-search-services.md](web-search-services.md), especially §4.3,
§6.5, §8 and §12. S2a is dormant: it accepts and renders the final service shapes
diff --git a/docs/plans/web-search-services-s2b.md b/docs/plans/web-search-services-s2b.md
index ce2da9a04..f939c8263 100644
--- a/docs/plans/web-search-services-s2b.md
+++ b/docs/plans/web-search-services-s2b.md
@@ -1,6 +1,25 @@
-# S2b-1: dormant search-service producer
+# S2b: search-service producer and activation
-## Change contract
+## S2b-2 activation change contract
+
+S2b-1 merged as `424b3fd`. S2b-2 sets `SEARCH_SERVICES_ACTIVE = True`: the Tools read,
+S4's existing `service_vendors` UI predicate, frozen turn choices and execution activate together.
+The retry route is now required by the client/server inventory, with no dormant exception.
+The shipped-default activation test does not monkeypatch the flag; its read and chain assertions
+must both pass. Existing producer tests run under that default, and prior dormant assertions
+now cover the active shape. No vendor request, mapping, billing or custody rule changes.
+
+Validation covers focused hosted-tools/read/chain/API tests through `hd1-test`, the UI build and
+relevant Vitest cases, with synthetic responses only. No live paid search or deployment is included.
+The release workflow owns notes (`docs/release.md`); the PR body supplies English/Chinese disclosure
+covering DeepSeek auto-enrollment/opt-out, query egress, list prices and downgrade loss (§12).
+The owner coordinates merge with S6 public disclosure; this lane does not merge.
+
+The close-out release check found `gh-v3.2.3rc1` carrying S2a/S2b-1's v19; the
+2026-10-22 recheck also found `gh-v3.2.3rc2`. Activation therefore opens v20, advances all
+version mirrors and preserves persisted TurnProvenance v5–v19 without rewriting it.
+
+## S2b-1 change contract (historical)
Implement `web-search-services.md` §§3–5 behind `SEARCH_SERVICES_ACTIVE = False`.
The flag-off chain, hop facts, frozen turn and Tools read retain their released behavior.
@@ -61,7 +80,7 @@ Local validation (2026-10-21):
- Changed Python files pass Ruff. CI owns the full suite; no runtime restart/deployment or
live-vendor/manual UI acceptance is included in this dormant change.
-## Contract version
+## S2b-1 contract version (historical)
At start, 2026-10-21: `git tag --contains 01fc7b0` returned none; latest RC release
was `gh-v3.2.2rc13`, before S2a. Recheck before first push and close-out. Use v19 while
diff --git a/docs/plans/web-search-services.md b/docs/plans/web-search-services.md
index 7866befda..44bc85b2e 100644
--- a/docs/plans/web-search-services.md
+++ b/docs/plans/web-search-services.md
@@ -675,8 +675,8 @@ One coordinated Model Hub version event under the freeze protocol (`model-hub-co
| PR | Lane | Work | Depends on |
| --- | --- | --- | --- |
| **S1a** Catalog and Sources | foundation | search vendors in the catalog; the Source UI guards for a `search` Source (no model refresh, test or add-model controls; its row says "搜索服务"); `protocol: "search"` Sources and their exclusions (the credential store accepts the protocol, the engine config renderer skips it); the protocol vocabulary split; the create and replace branch with free checks; "重新启用" (`reenable_search_source`, its free check and the armed-trial state); `service_order` maintenance on create and remove; the adapter's search call and free-check operation with custody and transport rules; opening the v17 version event | — |
-| **S1b** Settings and Tools read | foundation | no service candidate and no `service_vendors` in the read until S2 activates them; `prefer_native`, `services` (the patch semantics and load-time clamping) and `executor_order_kinds` (loaded, written with each order save, and kept across a restart); the Tools read (`executor_candidates` with `kind`, `service_vendors`, `trial_pending`) and PUT; their v17 entries | S1a |
-| **S2a** Chain readers and usage | readers | C-1 `attempts[]`, service executor origin, estimated cost and service error-code readers/writers; attempts-only hosted-activity projection and Web/IM rendering; service ledger and usage-summary readers plus the service-row write API; `mode: "service"` readers; released-shape fixtures and tests. Dormant: no chain, producer, metering call or activation. | S1a, S1b, S1c, S4 |
+| **S1b** Settings and Tools read | foundation | settings and the service-capable Tools read shape (`prefer_native`, `services`, `executor_order_kinds`, `service_order`, candidate discriminants and `service_vendors`) used by S2b; activation remained gated until the producer and disclosure | S1a |
+| **S2a** Chain readers and usage | readers | C-1 `attempts[]`, service executor origin, estimated cost and service error-code readers/writers; attempts-only hosted-activity projection and Web/IM rendering; service ledger and usage-summary readers plus the service-row write API; `mode: "service"` readers; released-shape fixtures and tests. The producer and activation remain with S2b. | S1a, S1b, S1c, S4 |
| **S2b** Chain producer and activation | gateway | Candidate chain and order placement; adapter search calls and mapping; outcomes into health/cooldowns, trial gate, positive evidence and metering writes; hop facts and turn freeze; retry route; flips `SEARCH_SERVICES_ACTIVE`. | S2a, S6's disclosure |
| ~~S3~~ | — | cancelled 2026-10-20 with page content; the card's executor label ("通过 Tavily") moves to S2 with the projection | — |
| **S1c** Content removal | foundation | removes what S1a and S1b landed for page content: the catalog's content request mapping, `content_max_chars` and `page` price extras; S1b's `services.<id>.content` (a saved key is ignored on load), the read's `settings.content` and the vendor page-text flags, with `hosted-tools-status.schema.json`, `api.md`, the UI types and the v18 entries (v19 if a release has carried v18) | S1b |
@@ -684,7 +684,7 @@ One coordinated Model Hub version event under the freeze protocol (`model-hub-co
| **S5** Frames | design | §6 frames in `design.pen` through Pencil (done: avibe-docs#73) | — |
| **S6** Public docs | docs | Models → Tools: services, order, defaults, privacy and cost, in English and Chinese. The disclosure part (an official DeepSeek Source joins the search order automatically, which data goes to each service, what it costs, and how to turn it off) publishes no later than the release that ships S2; the UI walkthrough follows S4 | the disclosure lands before or with S2 (S2 depends on it); the walkthrough follows S4 |
-The version event follows the v15 precedent in `model-hub-contracts/README.md`: S1a opened v17, S1b/S1c completed v18, and RC tag `gh-v3.2.2rc13` carries v18. S2a therefore opens v19 for reader and usage shapes; S2b may share v19 while it is unshipped, otherwise it opens v20. Before S2b, S2a is dormant and safe to release: it adds no producer, third-party request or activation. S1c's compatibility rule for removed page-content fields remains in force. S2b's activation release carries S6's disclosure, and the freeze rule means a shipped version never changes meaning.
+The version event follows the v15 precedent in `model-hub-contracts/README.md`: S1a opened v17, S1b/S1c completed v18, and RC tag `gh-v3.2.2rc13` carries v18. S2a and S2b-1 opened v19 for the readers and gated producer; `gh-v3.2.3rc1` and `gh-v3.2.3rc2` carry v19, so S2b-2 opens v20. S2b-2 activates the producer, Tools read and snippet-only search chain together with S6's disclosure; the freeze rule means a shipped version never changes meaning. S1c's compatibility rule for removed page-content fields remains in force.
## 10. Acceptance properties
diff --git a/tests/e2e/test_model_hub_runtime.py b/tests/e2e/test_model_hub_runtime.py
index 648daa666..d25565557 100644
--- a/tests/e2e/test_model_hub_runtime.py
+++ b/tests/e2e/test_model_hub_runtime.py
@@ -684,7 +684,7 @@ def test_a1_feature_flag_disables_the_complete_models_api(
assert response.status == 404, (method, path, body)
assert body == {
"ok": False,
- "contract_version": 19,
+ "contract_version": 20,
"error": "feature_disabled",
}
diff --git a/tests/e2e/test_model_hub_sources.py b/tests/e2e/test_model_hub_sources.py
index bd3da094e..9a28c461c 100644
--- a/tests/e2e/test_model_hub_sources.py
+++ b/tests/e2e/test_model_hub_sources.py
@@ -13,7 +13,7 @@ from tests.e2e.drivers.mock_llm_upstream import MockLLMUpstream
pytestmark = pytest.mark.e2e_model_hub
-CONTRACT_VERSION = 19
+CONTRACT_VERSION = 20
MENU_MODEL = "claude-sonnet-4-6"
SYNTHETIC_API_KEY = "sk-model-hub-e2e-not-real"
diff --git a/tests/scenarios/model_hub/catalog.yaml b/tests/scenarios/model_hub/catalog.yaml
index a154c4a47..0e88534d1 100644
--- a/tests/scenarios/model_hub/catalog.yaml
+++ b/tests/scenarios/model_hub/catalog.yaml
@@ -236,7 +236,7 @@ scenarios:
- tests/test_model_hub_hosted_tools_resolution.py::test_the_tools_read_states_saved_and_effective_values_and_what_real_use_showed
- tests/test_model_hub_hosted_tools_resolution.py::test_a_put_changes_only_the_fields_it_names
- tests/test_model_hub_search_settings.py::test_put_merges_absent_sources_fields_and_null_resets
- - tests/test_model_hub_search_settings.py::test_http_tools_put_and_read_preserve_patch_and_dormant_contract
+ - tests/test_model_hub_search_settings.py::test_http_tools_put_and_read_preserve_patch_and_active_contract
- tests/test_model_hub_search_settings.py::test_service_order_read_skips_removed_sources_without_rewriting_saved_order
- tests/test_model_hub_hosted_tools_resolution.py::test_a_put_refuses_what_the_contract_forbids
- tests/test_model_hub_hosted_tools_resolution.py::test_the_latest_success_is_the_newest_in_time_not_in_text
@@ -2586,7 +2586,7 @@ scenarios:
- tests/test_model_hub_service_acceptance_helpers.py::test_an_ignored_override_that_installs_the_packaged_engine_fails_the_run
- tests/test_model_hub_service_acceptance_helpers.py::test_a_selected_manifest_without_a_usable_version_fails_the_run
- id: MH-SEARCH-SERVICES-001
- name: The dormant search-service producer freezes a one-role service and model chain, bounds excerpts, fences health and cooldown independently, admits one recovery trial, and meters every sent request by observed billing facts without changing flag-off behavior
+ name: The active search-service read and producer share a one-role service and model chain, freeze turn settings, bound excerpts, fence health and cooldown independently, admit one recovery trial, and meter every sent request by observed billing facts
status: covered
kind: contract
layer: contract
@@ -2601,7 +2601,7 @@ scenarios:
- tests/test_model_hub_search_chain.py::test_health_and_cooldown_fences_each_protect_only_their_own_state
- tests/test_model_hub_search_chain.py::test_prefer_native_off_flows_through_the_hop_to_function_declaration_and_synthetic_history
- tests/test_model_hub_search_chain.py::test_retry_http_client_rpc_clears_only_the_service_fence_with_plain_success
- - tests/test_model_hub_search_chain.py::test_flag_off_retains_the_released_frozen_read_and_chain
+ - tests/test_model_hub_search_chain.py::test_search_read_and_chain_activate_together
- id: MH-HOSTED-GATEWAY-004
name: A proxied search runs one native request on the turn's first admitted executor, without an effort, and answers its canonical record and execution with the pricing module's cost and the same positive evidence a native call writes
status: covered
diff --git a/tests/test_model_hub_api.py b/tests/test_model_hub_api.py
index 26c55afec..122e2a792 100644
--- a/tests/test_model_hub_api.py
+++ b/tests/test_model_hub_api.py
@@ -1062,7 +1062,7 @@ def test_runtime_start_is_explicit_and_returns_v4_status(tmp_path):
assert adapter.start_calls == 1
assert store.config.enabled is True
assert runtime["enabled"] is True
- assert runtime["contract_version"] == 19
+ assert runtime["contract_version"] == 20
assert runtime["status"]["health"] == "ok"
_assert_valid("runtime-dependency.schema.json", runtime)
@@ -1369,7 +1369,7 @@ def test_runtime_start_crosses_the_controller_rpc_boundary(monkeypatch):
async def rpc(operation, payload=None):
calls.append((operation, payload))
- return {"contract_version": 19, "status": {"health": "ok"}}
+ return {"contract_version": 20, "status": {"health": "ok"}}
monkeypatch.setattr(model_hub_client, "_rpc", rpc)
@@ -1386,7 +1386,7 @@ def test_runtime_stop_crosses_the_controller_rpc_boundary(monkeypatch):
async def rpc(operation, payload=None):
calls.append((operation, payload))
- return {"contract_version": 19, "status": {"health": "not_started"}}
+ return {"contract_version": 20, "status": {"health": "not_started"}}
monkeypatch.setattr(model_hub_client, "_rpc", rpc)
@@ -1403,7 +1403,7 @@ def test_runtime_install_crosses_the_controller_rpc_boundary(monkeypatch):
async def rpc(operation, payload=None):
calls.append((operation, payload))
- return {"contract_version": 19, "status": {"health": "installing"}}
+ return {"contract_version": 20, "status": {"health": "installing"}}
monkeypatch.setattr(model_hub_client, "_rpc", rpc)
@@ -1421,7 +1421,7 @@ def test_runtime_dependency_ensure_crosses_the_controller_rpc_boundary(monkeypat
def rpc(operation, payload=None):
calls.append((operation, payload))
return {
- "contract_version": 19,
+ "contract_version": 20,
"changed": True,
"status": {"health": "not_started", "verified": True},
}
@@ -4873,7 +4873,7 @@ def test_agent_models_route_returns_only_picker_catalog_fields(monkeypatch):
assert response.status_code == 200
assert response.get_json() == {
"ok": True,
- "contract_version": 19,
+ "contract_version": 20,
"agent": {
"backend": "codex",
"mode": "hub",
@@ -5910,8 +5910,6 @@ def test_final_model_hub_route_surface_has_observe_refresh_and_no_saved_test_rou
def test_models_live_api_calls_only_registered_server_routes():
- from core.handlers.model_hub.hosted_tools import SEARCH_SERVICES_ACTIVE
-
source = Path("ui/src/components/settings/models/modelsApi.ts").read_text(encoding="utf-8")
live_api = source.split("export const modelsApi: ModelsApi = {", 1)[1]
path_pattern = re.compile(r"'(?P<single>/api/models/[^']*)'|`(?P<template>/api/models/[^`]*)`")
@@ -5945,15 +5943,8 @@ def test_models_live_api_calls_only_registered_server_routes():
}
assert client_routes
- # S4 prepares this one S2-owned action before the service read is activated.
- # Active reads must have the route; dormant reads have no service candidates
- # or cooldowns, so the UI cannot offer it (SearchServices.test.tsx).
- dormant_routes = (
- set()
- if SEARCH_SERVICES_ACTIVE
- else {("POST", "/api/models/hosted-tools/web_search/services/{param}/retry")}
- )
- assert client_routes <= server_routes | dormant_routes
+ assert ("POST", "/api/models/hosted-tools/web_search/services/{param}/retry") in client_routes
+ assert client_routes <= server_routes
def test_unsaved_observation_route_returns_valid_result_and_revokes_transient_ref(
@@ -6405,7 +6396,7 @@ def test_search_source_replacement_unknown_keeps_old_key_and_revokes_new_ref(tmp
("pass", None, False),
("balance", "models.source.needs_action.balance_exhausted", False),
("limit", "models.source.needs_action.spend_limit_reached", False),
- ("unknown", "models.source.needs_action.balance_exhausted", True),
+ ("unknown", "models.source.needs_action.spend_limit_reached", True),
("invalid", "models.source.needs_action.credential_revoked", True),
],
)
@@ -6418,6 +6409,7 @@ def test_search_source_reenable_free_check_keeps_or_reclassifies_state(
service, store, adapter = _service(tmp_path)
adapter.search_check_outcome = outcome
marker = "vp_" + "a" * 32
+ # Tavily's free usage check distinguishes limits, not a balance blocker.
source = ModelHubSourceConfig(
id="src_searchbalance",
kind="api_key",
@@ -6428,7 +6420,7 @@ def test_search_source_reenable_free_check_keeps_or_reclassifies_state(
billing="metered",
state=ModelHubSourceStateConfig(
status="needs_action",
- detail_key="models.source.needs_action.balance_exhausted",
+ detail_key="models.source.needs_action.spend_limit_reached",
),
models=[],
credential_ref="cred_searchbalance",
@@ -6453,19 +6445,28 @@ def test_search_source_reenable_free_check_keeps_or_reclassifies_state(
-def test_search_source_reenable_arms_without_clearing_limit(tmp_path):
[email protected](("vendor", "blocker"), [
+ ("exa", "spend_limit_reached"), # No free check.
+ ("tavily", "balance_exhausted"), # Its free check cannot classify this blocker.
+])
+def test_search_source_reenable_arms_without_clearing_blocker(tmp_path, vendor, blocker):
+ from unittest.mock import AsyncMock
+
service, store, adapter = _service(tmp_path)
+ check = AsyncMock(return_value=SearchCredentialCheck("pass"))
+ adapter.check_search_credential = check
+ detail_key = f"models.source.needs_action.{blocker}"
source = ModelHubSourceConfig(
id="src_searchtrial",
kind="api_key",
- vendor="exa",
- display_name="Exa",
+ vendor=vendor,
+ display_name=vendor,
protocol="search",
supply_channel="hub",
billing="metered",
state=ModelHubSourceStateConfig(
status="needs_action",
- detail_key="models.source.needs_action.spend_limit_reached",
+ detail_key=detail_key,
),
models=[],
credential_ref="cred_searchtrial",
@@ -6474,7 +6475,8 @@ def test_search_source_reenable_arms_without_clearing_limit(tmp_path):
result = asyncio.run(service.reenable_search_source(source.id, {}))
assert result["trial_armed"] is True
- assert result["source"]["state"]["detail_key"] == "models.source.needs_action.spend_limit_reached"
+ assert result["source"]["state"]["detail_key"] == detail_key
+ assert result["source"]["state"]["status"] == "needs_action"
assert result["source"]["trial_pending"] is True
assert service.search_reenable_trial_armed(source.id)
assert service.search_reenable_trial_pending(source.id)
@@ -6491,8 +6493,8 @@ def test_search_source_reenable_arms_without_clearing_limit(tmp_path):
service.settle_search_reenable_trial(source.id)
assert not service.search_reenable_trial_pending(source.id)
assert service.list_sources()[0]["trial_pending"] is False
- assert store.load().sources[0].state.detail_key == "models.source.needs_action.spend_limit_reached"
- assert adapter.search_check_outcome == "unknown"
+ assert store.load().sources[0].state.detail_key == detail_key
+ check.assert_not_awaited()
@pytest.mark.parametrize(("method", "suffix", "payload"), [
@@ -10150,7 +10152,7 @@ def test_runtime_start_route_requires_csrf_before_starting_engine(monkeypatch, t
assert accepted.status_code == 200
runtime = accepted.get_json()["runtime"]
assert adapter.start_calls == 1
- assert runtime["contract_version"] == 19
+ assert runtime["contract_version"] == 20
_assert_valid("runtime-dependency.schema.json", runtime)
diff --git a/tests/test_model_hub_config.py b/tests/test_model_hub_config.py
index 028a2dd09..2d6b1460e 100644
--- a/tests/test_model_hub_config.py
+++ b/tests/test_model_hub_config.py
@@ -97,7 +97,7 @@ def test_auto_detect_asks_for_responses_before_chat():
def test_unsaved_observation_schema_closes_all_terminal_shapes():
schema = _schema("observation-result.schema.json")
- assert schema["properties"]["contract_version"]["const"] == 19
+ assert schema["properties"]["contract_version"]["const"] == 20
assert tuple(schema["properties"]["outcome"]["enum"]) == tuple(
member.value for member in ObservationOutcome
)
@@ -121,7 +121,7 @@ def test_observation_terminal_authority_and_schema_accept_the_same_products():
def payload(observation: SourceObservation) -> dict:
return {
- "contract_version": 19,
+ "contract_version": 20,
"outcome": observation.outcome.value,
"reachable": observation.reachable,
"authenticated": (
@@ -737,7 +737,7 @@ def test_guard_refusal_error_requires_its_corresponding_nonempty_plan_array():
route_refusal = {
"ok": False,
- "contract_version": 19,
+ "contract_version": 20,
"error": "source_in_route_chain",
"detail": "modelHub.errors.source_in_route_chain",
"would_remove_hops": [hop],
@@ -753,7 +753,7 @@ def test_guard_refusal_error_requires_its_corresponding_nonempty_plan_array():
}
candidate_refusal = {
"ok": False,
- "contract_version": 19,
+ "contract_version": 20,
"error": "candidate_suppliers_changed",
"detail": "modelHub.errors.candidate_suppliers_changed",
"changed": {
@@ -837,7 +837,7 @@ def test_v8_mirror_registry_is_executable_and_complete():
registry = json.loads((CONTRACTS / "mirror-registry.json").read_text(encoding="utf-8"))
schemas = _mirror_schemas(registry)
- assert registry["contract_version"] == 19
+ assert registry["contract_version"] == 20
ids = [entry["id"] for entry in registry["entries"]]
assert ids
assert len(ids) == len(set(ids))
@@ -974,8 +974,8 @@ def test_model_hub_authority_closure_anchors_the_persisted_version_floor(monkeyp
"kind": "contract_version_schema_drift",
"domain": "V1",
"file": "docs/plans/model-hub-contracts/turn-provenance.schema.json",
- "values": [6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19],
- "expected": [5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19],
+ "values": [6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20],
+ "expected": [5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20],
} in result["findings"]
@@ -1286,7 +1286,7 @@ def test_v5_shape_amendments_reject_the_false_states_they_replace():
with pytest.raises(ValidationError):
chain_validator.validate(interrupted)
exact_hop = {
- "contract_version": 19,
+ "contract_version": 20,
"backend": "claude",
"model_id": "claude-opus-4-6",
"manual_override": None,
diff --git a/tests/test_model_hub_hosted_executor.py b/tests/test_model_hub_hosted_executor.py
index e156afbe4..899383a1c 100644
--- a/tests/test_model_hub_hosted_executor.py
+++ b/tests/test_model_hub_hosted_executor.py
@@ -209,8 +209,8 @@ async def test_a_proxied_search_runs_one_native_request_and_answers_its_canonica
service._admitted_executor = recorded
status, answer = await _call(service, tool, {"arguments": arguments})
assert status == 200, answer
- # Admission reads the config, which grows with use: at the chain step and again under the lock, off the loop.
- assert len(admitting_threads) == 2 and threading.main_thread() not in admitting_threads
+ # Every admission snapshot, including the active mixed-chain classification, stays off the loop.
+ assert len(admitting_threads) >= 2 and threading.main_thread() not in admitting_threads
assert service.adapter.invocations == [(executor[0], executor[1], "vibey")]
sent = service.adapter.requests[0]
assert sent.protocol == "openai_responses"
@@ -362,10 +362,10 @@ FAILED_WITH_PARTIAL = {**WEB_CALL, "status": "failed"}
@pytest.mark.asyncio
@pytest.mark.parametrize(("case", "bound", "handles", "error", "sources", "executed"), [
# No Source can run it: the record says which providers' Sources could.
- ("no_candidate", None, [], "No Source can run web search right now. Add an API key from one of Anthropic, OpenAI, xAI as a Source in Models › Sources & gateway; a key stored in Vaults is not used for this.", [], False),
- ("source_removed", (XAI, "grok-4.6"), [], "No Source can run web search right now. Add an API key from one of Anthropic, OpenAI, xAI as a Source in Models › Sources & gateway; a key stored in Vaults is not used for this.", [], False),
+ ("no_candidate", None, [], "Add a search service in Models › Tools or an API key from a vendor that offers web search", [], False),
+ ("source_removed", (XAI, "grok-4.6"), [], "the search service is unavailable", [], False),
# A new base URL or credential is a new identity, which the turn's chain was not built for.
- ("source_identity_changed", (XAI, "grok-4.6"), [], "No Source can run web search right now. Add an API key from one of Anthropic, OpenAI, xAI as a Source in Models › Sources & gateway; a key stored in Vaults is not used for this.", [], False),
+ ("source_identity_changed", (XAI, "grok-4.6"), [], "the search service is unavailable", [], False),
# The only candidate failed: its failure, and the Sources tried.
("provider_refused", (XAI, "grok-4.6"),
[InvokeHandle(_outcome(RawOutcomeKind.HTTP_ERROR, status=429, code="rate_limit_error", source_id=XAI))],
@@ -411,8 +411,8 @@ async def test_a_proxied_call_that_cannot_complete_is_a_failed_record(
# Each reason the gateway words carries the code its reader's surface shows it by (#2589).
# Which providers to add is the call's own fact: that reason has no code and is shown as written.
assert answer["record"].get("error_code") == {
- "no_candidate": None, "source_removed": None,
- "source_identity_changed": None, "provider_refused": "provider_refused",
+ "no_candidate": None, "source_removed": "service_unavailable",
+ "source_identity_changed": "service_unavailable", "provider_refused": "provider_refused",
"tool_never_ran": "search_not_run", "call_failed_with_partial_results": "search_failed",
"stream_failed_after_items": "provider_unavailable",
}[case]
@@ -1158,7 +1158,8 @@ async def test_a_call_cancelled_before_its_handle_is_still_metered(tmp_path, mon
raise InvokeCancelledError(observed)
if ended_by == "deadline":
- monkeypatch.setattr(service_module, "call_timeout", lambda _tool: 0.05)
+ from core.handlers.model_hub import search_chain
+ monkeypatch.setattr(search_chain, "call_timeout", lambda _tool: 0.05)
service.adapter.invoke = cancelled_after_admission
gateway = ModelHubTurnGateway(service)
router = ModelHubRuntimeRouter(service=service, turn_gateway=gateway)
diff --git a/tests/test_model_hub_hosted_tools_resolution.py b/tests/test_model_hub_hosted_tools_resolution.py
index 9038dda9a..868e20e0a 100644
--- a/tests/test_model_hub_hosted_tools_resolution.py
+++ b/tests/test_model_hub_hosted_tools_resolution.py
@@ -303,8 +303,8 @@ def test_a_turn_freezes_its_tools_executors_and_image_enum_and_each_hop_states_i
assert turn.tools == {"web_search", "x_search", "image_generate"}
assert turn.executors == {
"web_search": (
- ExecutorSlot("src_xai00001", "grok-fast", identity_digest(XAI)),
- ExecutorSlot("src_oai00001", "gpt-mini", identity_digest(OPENAI)),
+ ExecutorSlot("src_xai00001", "grok-fast", identity_digest(XAI), label="src_xai00001"),
+ ExecutorSlot("src_oai00001", "gpt-mini", identity_digest(OPENAI), label="src_oai00001"),
),
"x_search": (ExecutorSlot("src_xai00001", "grok-fast", identity_digest(XAI)),),
}
diff --git a/tests/test_model_hub_l3.py b/tests/test_model_hub_l3.py
index fa44512f8..2117ab5e9 100644
--- a/tests/test_model_hub_l3.py
+++ b/tests/test_model_hub_l3.py
@@ -5580,7 +5580,7 @@ def test_backend_failure_keeps_the_gateway_terminal_error_no_later_request_super
def test_released_backend_rejection_records_read_unchanged(tmp_path: Path) -> None:
"""Records the earlier bridge wrote stay as written: no reason or phase is re-derived on read."""
released = {
- "contract_version": 19,
+ "contract_version": 20,
"turn_id": "turn_released_rejection",
"ts": NOW.isoformat(),
"agent": "vibey",
@@ -7056,7 +7056,7 @@ def test_source_observation_reduces_the_order_at_the_first_authenticated_proof(
_assert_valid(
"observation-result.schema.json",
{
- "contract_version": 19,
+ "contract_version": 20,
"outcome": "adapter_error",
"reachable": True,
"authenticated": "unknown",
@@ -9590,7 +9590,7 @@ def test_native_chain_visibility_and_probe_readiness(tmp_path: Path) -> None:
probe = asyncio.run(service.probe_agent("codex", "shared-model"))
assert probe == {
- "contract_version": 19,
+ "contract_version": 20,
"backend": "codex",
"channel": "native_cli",
"reachable": True,
diff --git a/tests/test_model_hub_provenance.py b/tests/test_model_hub_provenance.py
index a8bfd5369..58a43e1bf 100644
--- a/tests/test_model_hub_provenance.py
+++ b/tests/test_model_hub_provenance.py
@@ -261,7 +261,7 @@ def test_live_recovery_snapshots_never_revive_invalid_or_terminal_owners(tmp_pat
def _record(turn_id, *, backend="claude", model=MODEL, outcome="failed_terminal"):
identity = {"source_id": "src_deleted01", "configured_model_id": "unknown-model", "channel": "hub"}
return {
- "contract_version": 19,
+ "contract_version": 20,
"turn_id": turn_id,
"ts": "2026-09-06T00:00:00Z",
"agent": backend,
@@ -299,7 +299,7 @@ def test_latest_record_is_backend_model_isolated_bounded_and_not_latest_error(tm
assert len(json.loads(path.read_text())) == 3
[email protected]("version", range(5, 11))
[email protected]("version", range(5, 21))
def test_persisted_versions_remain_readable_without_rewriting(tmp_path, version):
record = {**_record("historical"), "contract_version": version}
path = tmp_path / "provenance.json"
@@ -461,6 +461,6 @@ def test_model_history_client_rpc_http_share_nullable_read_only_result(monkeypat
f"/api/models/agents/claude/provenance?model={MODEL}", headers=csrf_headers(client, origin), base_url=origin
)
assert response.status_code == 200
- assert response.get_json() == {"ok": True, "contract_version": 19, "provenance": record}
+ assert response.get_json() == {"ok": True, "contract_version": 20, "provenance": record}
assert store.config.to_payload() == before
assert adapter.synced == []
diff --git a/tests/test_model_hub_resolution.py b/tests/test_model_hub_resolution.py
index 37b9bc212..fd92b8116 100644
--- a/tests/test_model_hub_resolution.py
+++ b/tests/test_model_hub_resolution.py
@@ -1808,7 +1808,7 @@ def test_service_accepts_authoritative_reachable_adapter_error(tmp_path):
)
assert result["observation"] == {
- "contract_version": 19,
+ "contract_version": 20,
"outcome": "adapter_error",
"reachable": True,
"authenticated": "unknown",
@@ -1839,7 +1839,7 @@ def test_unknown_adapter_error_does_not_claim_connection(tmp_path):
assert exc.value.code == "discovery_failed"
assert exc.value.detail == "modelHub.errors.adapter_error"
assert exc.value.data["observation"] == {
- "contract_version": 19,
+ "contract_version": 20,
"outcome": "adapter_error",
"reachable": None,
"authenticated": "unknown",
diff --git a/tests/test_model_hub_runtime.py b/tests/test_model_hub_runtime.py
index fa40e8604..4f0d30e56 100644
--- a/tests/test_model_hub_runtime.py
+++ b/tests/test_model_hub_runtime.py
@@ -1367,7 +1367,7 @@ def test_manifest_resolution_drives_admission_persistence_and_schema(
installer=manager,
state_store=EngineStateStore(tmp_path / "state"),
)
- projected = {"contract_version": 19, **supervisor.status()}
+ projected = {"contract_version": 20, **supervisor.status()}
schema = json.loads(
Path("docs/plans/model-hub-contracts/runtime-dependency.schema.json").read_text(
encoding="utf-8"
diff --git a/tests/test_model_hub_search_chain.py b/tests/test_model_hub_search_chain.py
index 1b14f70c9..2465f3ea7 100644
--- a/tests/test_model_hub_search_chain.py
+++ b/tests/test_model_hub_search_chain.py
@@ -30,11 +30,6 @@ ROW = {"url": "https://example.test/a", "title": "Title", "summary": "Model exce
"date": "2026-10-21", "published_date": "today", "publishedDate": "yesterday"}
[email protected](autouse=True)
-def active(monkeypatch):
- monkeypatch.setattr(hosted_tools, "SEARCH_SERVICES_ACTIVE", True)
-
-
def owner(tmp_path, vendors=("exa",), *, web=None, model=False):
service, store, adapter = _service(tmp_path)
config = _config(web)
@@ -495,16 +490,26 @@ async def test_free_check_is_joined_without_holding_the_mutation_lock(tmp_path,
@pytest.mark.asyncio
-async def test_flag_off_retains_the_released_frozen_read_and_chain(tmp_path, monkeypatch):
+async def test_search_read_and_chain_activate_together(tmp_path, monkeypatch):
+ """MH-SEARCH-SERVICES-001: shipped defaults expose the same service that the frozen turn executes.
+
+ No activation monkeypatch: a dormant producer or a separately gated read must fail here.
+ """
service = owner(tmp_path, ("exa",), web={"prefer_native": False})
- monkeypatch.setattr(hosted_tools, "SEARCH_SERVICES_ACTIVE", False)
calls = answers(monkeypatch, service, wire())
frozen = service.freeze_turn_hosted_tools(service.store.load())
- assert getattr(frozen, "prefer_native", None) is None and frozen.executors["web_search"] == ()
- assert _web(service)["executor_candidates"] == [] and "service_vendors" not in _web(service)
+ visible = _web(service)
+ assert frozen.prefer_native is False
+ assert [(slot.source_id, slot.kind, slot.results, slot.label) for slot in frozen.executors["web_search"]] == [
+ (EXA, "service", 5, "exa"),
+ ]
+ assert [(row["source_id"], row["kind"]) for row in visible["executor_candidates"]] == [(EXA, "service")]
+ assert {vendor["id"] for vendor in visible["service_vendors"]} == {"exa", "tavily", "deepseek"}
answer = await run(service, turn=frozen)
- assert not calls and "attempts" not in answer["record"]
- assert "Add an API key" in answer["record"]["error"]
+ assert len(calls) == 1 and calls[0][0] == EXA
+ assert answer["record"]["status"] == "completed"
+ assert answer["record"]["attempts"][0]["source_id"] == EXA
+ assert answer["execution"]["executor_origin"]["api"] == "search_api"
@pytest.mark.asyncio
@@ -901,8 +906,7 @@ async def test_tavily_validation_error_keeps_bounded_vendor_text_but_not_echoed_
assert "do not echo me" not in result["record"]["error"]
[email protected]("enabled", [False, True])
-def test_retry_http_client_rpc_clears_only_the_service_fence_with_plain_success(tmp_path, monkeypatch, enabled):
+def test_retry_http_client_rpc_clears_only_the_service_fence_with_plain_success(tmp_path, monkeypatch):
"""The existing route inventory checks registration, not forwarding or controller-owned state."""
from core.handlers.model_hub.rpc import dispatch_model_hub_rpc
from tests.test_model_hub_api import app, csrf_headers, save_config
@@ -910,7 +914,6 @@ def test_retry_http_client_rpc_clears_only_the_service_fence_with_plain_success(
save_config(tmp_path / "home")
service = owner(tmp_path)
- monkeypatch.setattr(hosted_tools, "SEARCH_SERVICES_ACTIVE", enabled)
source = service.store.load().sources[0]
source.state = ModelHubSourceStateConfig(status="needs_action", detail_key="models.source.needs_action.balance_exhausted")
generation = service._service_cooldowns.advance(source, "exa/search")
@@ -926,7 +929,7 @@ def test_retry_http_client_rpc_clears_only_the_service_fence_with_plain_success(
response = client.post(f"/api/models/hosted-tools/web_search/services/{EXA}/retry", json={},
headers=csrf_headers(client, "http://127.0.0.1:15131"))
assert response.status_code == 200
- assert response.get_json() == {"ok": True, "contract_version": 19}
+ assert response.get_json() == {"ok": True, "contract_version": 20}
assert calls == [("clear_service_cooldown", {"source_id": EXA, "service_id": None})]
assert not service._service_cooldowns.current(source, "exa/search", generation)
assert service.store.load().sources[0].state == source.state
diff --git a/tests/test_model_hub_search_settings.py b/tests/test_model_hub_search_settings.py
index dd62296c0..7b13d9eb1 100644
--- a/tests/test_model_hub_search_settings.py
+++ b/tests/test_model_hub_search_settings.py
@@ -1,4 +1,4 @@
-"""S1b owner coverage: persistent settings/patches and the dormant Tools read.
+"""Search settings owner coverage: persistent settings/patches and the active Tools read.
The pre-service hosted-tools tests cannot exercise catalog-dependent defaults,
clamping, role snapshots or Source-keyed patches. These tests use the real V2
@@ -112,8 +112,8 @@ async def test_mixed_order_and_role_snapshot_survive_real_v2_restart(tmp_path):
assert restarted.hosted_tools["web_search"].service_order == (TAVILY, EXA)
assert not restarted.hosted_tools["web_search"].prefer_native
assert _web(service)["executor_order"] == order
- # Dormancy keeps actual model execution unchanged, despite the saved future role map/order.
- assert _web(service)["effective_order"] == [MODEL]
+ # Active search placement keeps the deliberate model first, then named service EXA, then disabled entries.
+ assert _web(service)["effective_order"] == [MODEL, EXA, TAVILY, DEEPSEEK]
await service.set_hosted_tool("web_search", {"executor_order": None})
reset = V2ModelHubConfigStore().load().hosted_tools["web_search"].to_payload()
assert "executor_order" not in reset and "executor_order_kinds" not in reset
@@ -351,21 +351,18 @@ async def test_damaged_role_map_keeps_opt_out_across_load_write_and_reenable(tmp
@pytest.mark.asyncio
-async def test_dormant_read_and_future_service_variant_validate_without_paid_calls(tmp_path, monkeypatch):
- """One switch gates both read additions; defined service payloads do not require execution/UI activation."""
+async def test_active_service_read_validates_without_paid_calls(tmp_path):
+ """The shipped read projects service health/settings and vendor membership without a search."""
service, _, _ = _disk_service(tmp_path, _config({"services": {DEEPSEEK: {"enabled": False}}}))
- dormant = _web(service)
- assert dormant["prefer_native"] is True
- assert "service_vendors" not in dormant
- assert {row["kind"] for row in dormant["executor_candidates"]} == {"model"}
- # Check the prepared projection only. S2's ordering/chain/cooldown semantics are intentionally not exercised.
+ visible = _web(service)
+ assert visible["prefer_native"] is True
+ assert {row["kind"] for row in visible["executor_candidates"]} == {"service", "model"}
config = service.store.load()
config.sources[-1].billing = "monthly" # Model billing does not make the separate search API included.
config.sources[2].state = ModelHubSourceStateConfig(
status="needs_action", detail_key="models.source.needs_action.balance_exhausted")
service.store.save(config)
service._search_reenable_trials.add(EXA)
- monkeypatch.setattr(hosted_tools, "SEARCH_SERVICES_ACTIVE", True)
visible = _web(service)
exa = next(row for row in visible["executor_candidates"] if row["source_id"] == EXA)
assert exa == {
@@ -396,8 +393,8 @@ async def test_dormant_read_and_future_service_variant_validate_without_paid_cal
validator.validate({**exa, **changed})
-def test_http_tools_put_and_read_preserve_patch_and_dormant_contract(tmp_path, monkeypatch):
- """MH-HOSTED-004: the public route accepts new fields and returns a valid dormant envelope."""
+def test_http_tools_put_and_read_preserve_patch_and_active_contract(tmp_path, monkeypatch):
+ """MH-HOSTED-004: the public route accepts patches and returns the active service read."""
from tests.test_model_hub_api import _as_ui_client
from tests.ui_server_test_helpers import csrf_headers, save_config
from vibe import ui_server
@@ -420,7 +417,11 @@ def test_http_tools_put_and_read_preserve_patch_and_dormant_contract(tmp_path, m
registry=_api_response_registry()).validate(written)
web = written["hosted_tools"]["tools"][0]
assert web["prefer_native"] is False and web["services"] == {TAVILY: {"results": 7, "enabled": False}}
- assert "service_vendors" not in web and all(row["kind"] == "model" for row in web["executor_candidates"])
+ assert {vendor["id"] for vendor in web["service_vendors"]} == {"deepseek", "tavily", "exa"}
+ assert [(row["source_id"], row["kind"]) for row in web["executor_candidates"]] == [
+ (EXA, "service"), (DEEPSEEK, "service"), (MODEL, "model"), (TAVILY, "service"),
+ ]
+ assert web["executor_candidates"][-1]["settings"] == {"results": 7, "enabled": False}
def test_rc12_loader_preserves_tool_switch_and_orders_but_drops_service_overrides(caplog):
diff --git a/tests/test_model_hub_vibey_contract_matrix.py b/tests/test_model_hub_vibey_contract_matrix.py
index c18bad33c..a0b89ab15 100644
--- a/tests/test_model_hub_vibey_contract_matrix.py
+++ b/tests/test_model_hub_vibey_contract_matrix.py
@@ -48,13 +48,13 @@ def _fixture(kind):
# Start from a valid native response so no Hub latency constraint can
# accidentally reject the Avibe/native pairing for an unrelated cause.
return {
- "contract_version": 19, "backend": "claude", "channel": "native_cli", "reachable": True,
+ "contract_version": 20, "backend": "claude", "channel": "native_cli", "reachable": True,
"source_id": "src_fixture01", "model_id": "fixture-model", "latency_ms": None,
"error": None,
}
if kind == "chain":
return {
- "contract_version": 19, "backend": "vibey", "model_id": "fixture-model",
+ "contract_version": 20, "backend": "vibey", "model_id": "fixture-model",
"manual_override": None, "route_origin": "automatic",
"chain": [{"source_id": "src_fixture01", "model_id": "fixture-model", "channel": "hub",
"health": "healthy", "runnable": True, "reason": None, "retry_at": None}],
@@ -66,7 +66,7 @@ def _fixture(kind):
"proposed_action": "import", "selected": False,
}
return {
- "contract_version": 19, "turn_id": "turn-fixture", "ts": "2026-10-02T07:00:00Z",
+ "contract_version": 20, "turn_id": "turn-fixture", "ts": "2026-10-02T07:00:00Z",
"agent": "vibey", "requested_model_id": "fixture-model", "outcome": kind,
"failed_attempts": [{**identity, "reason": "rate_limited"}] if kind == "exhausted" else [],
"served": identity if kind == "served" else None,
diff --git a/ui/e2e/chat-interactions/interactions.spec.ts b/ui/e2e/chat-interactions/interactions.spec.ts
index 67105a5cb..75ae381d5 100644
--- a/ui/e2e/chat-interactions/interactions.spec.ts
+++ b/ui/e2e/chat-interactions/interactions.spec.ts
@@ -11,7 +11,7 @@ for (const lang of ['en', 'zh'] as const) {
if (url.origin !== 'http://127.0.0.1:5227' || route.request().method() !== 'GET') return route.abort();
if (url.pathname === `/api/models/turns/${TURN}/provenance`) {
return route.fulfill({ json: { provenance: {
- contract_version: 19, turn_id: TURN, agent: 'codex', requested_model_id: 'fixture-model',
+ contract_version: 20, turn_id: TURN, agent: 'codex', requested_model_id: 'fixture-model',
outcome: 'failed_terminal', failed_attempts: [], blockers: [],
terminal_error: { source_id: 'fixture-source', configured_model_id: 'fixture-model', reason: 'engine_down' },
} } });
diff --git a/ui/e2e/model-catalog/gatewayFixture.tsx b/ui/e2e/model-catalog/gatewayFixture.tsx
index a57e3c6ea..6cfdbd288 100644
--- a/ui/e2e/model-catalog/gatewayFixture.tsx
+++ b/ui/e2e/model-catalog/gatewayFixture.tsx
@@ -35,13 +35,13 @@ export function GatewayFixture() {
}],
};
const chains = Object.fromEntries(ids.map((model_id, index) => [modelChainKey(backend, model_id), readyRegion<AgentChain>({
- contract_version: 19, backend, model_id, route_origin: origins[index],
+ contract_version: 20, backend, model_id, route_origin: origins[index],
manual_override: origins[index] === 'manual' ? { hops: [{ source_id: source.id, model_id }] } : null,
current: { source_id: source.id, model_id }, supply_state: 'ok',
chain: [{ source_id: source.id, model_id, channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }],
})]));
const runtime = freshRuntimeProjection(readyRegion({
- contract_version: 19,
+ contract_version: 20,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: '1.0.0', source_sha: 'fixture', assets: [] },
status: { installed_version: '1.0.0', verified: true, listening: null, health: 'ok', last_check: null },
}));
diff --git a/ui/e2e/model-catalog/routeFixture.tsx b/ui/e2e/model-catalog/routeFixture.tsx
index 11faf5b38..bdd741099 100644
--- a/ui/e2e/model-catalog/routeFixture.tsx
+++ b/ui/e2e/model-catalog/routeFixture.tsx
@@ -28,7 +28,7 @@ const supply: AgentSupply = {
sources: { order: sources.map((source) => source.id), eligibility: sources.map((source) => ({ source_id: source.id, eligible: true })) },
};
const makeChain = (hops: RouteHop[], manual: boolean): AgentChain => ({
- contract_version: 19, backend, model_id: modelId,
+ contract_version: 20, backend, model_id: modelId,
manual_override: manual ? { hops } : null,
route_origin: manual ? 'manual' : origin === 'passthrough' ? 'passthrough' : 'automatic',
current: hops[0] ?? null, supply_state: hops.length ? 'ok' : 'interrupted',
diff --git a/ui/e2e/model-routing-origin.spec.ts b/ui/e2e/model-routing-origin.spec.ts
index 60ee5e970..93261fc40 100644
--- a/ui/e2e/model-routing-origin.spec.ts
+++ b/ui/e2e/model-routing-origin.spec.ts
@@ -102,7 +102,7 @@ test('MH-ROUTING-007 follow-defaults switch, undo, cancel, and save preserve exp
would_remove_hops: [{ backend: gateway.backend, menu_model: gateway.model, ...manual.hops[0], position: 1 }],
would_interrupt: [],
};
- expect(await refused.json()).toMatchObject({ ok: false, contract_version: 19, error: 'source_in_route_chain', ...plan });
+ expect(await refused.json()).toMatchObject({ ok: false, contract_version: 20, error: 'source_in_route_chain', ...plan });
expect((await api.agentChain(gateway.backend, gateway.model)).manual_override).toEqual(manual);
// The one question is its own modal over the chain the user was editing.
const guard = hub.dialogTitled(copy('guard.title.saveRoute', { menuModel: gateway.model }));
diff --git a/ui/e2e/onboarding-fidelity/hub-ownership.spec.ts b/ui/e2e/onboarding-fidelity/hub-ownership.spec.ts
index da620ea55..97431a511 100644
--- a/ui/e2e/onboarding-fidelity/hub-ownership.spec.ts
+++ b/ui/e2e/onboarding-fidelity/hub-ownership.spec.ts
@@ -92,7 +92,7 @@ for (const width of [1200, 390]) {
if (path === '/api/models/runtime/status') return answer({
ok: true,
runtime: {
- contract_version: 19, enabled: true, host_platform: 'linux',
+ contract_version: 20, enabled: true, host_platform: 'linux',
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: 'fixture', source_sha: 'a'.repeat(40), assets: [] },
status: { installed_version: 'fixture', verified: true, health: 'ok' },
},
diff --git a/ui/e2e/onboarding-fidelity/pm-main-flow.spec.ts b/ui/e2e/onboarding-fidelity/pm-main-flow.spec.ts
index f90fdb7f1..4c8b3a039 100644
--- a/ui/e2e/onboarding-fidelity/pm-main-flow.spec.ts
+++ b/ui/e2e/onboarding-fidelity/pm-main-flow.spec.ts
@@ -18,7 +18,7 @@ for (const [width,chosen] of [[1200,"claude"],[390,"claude"],[1200,"codex"]] as
const config=()=>({version:'v2',mode:'self_host',setup_completed:completed,setup_state:{needs_setup:!completed},capabilities:{model_hub:{enabled:true}},platforms:{primary:'slack',enabled:[]},runtime:{},agents:Object.fromEntries(['claude','codex','opencode'].map(b=>[b,{enabled:b!=='opencode',cli_path:b}])),agent:{default_cwd:'/fixture/work'},model_hub:{enabled:true,runtime_default_applied:true}});
const source={id:'src_fixture',kind:'api_key',vendor:'openai',display_name:'Fixture source',protocol:'openai_chat',supply_channel:'hub',billing:'metered',state:{status:'active'},masked_credential:'fixture-only',models:hops.map(h=>({id:h.model_id,display_name:h.model_id==='gpt-5'?'GPT-5':undefined,origin:'discovered',reasoning_efforts:[],reasoning_efforts_source:null})),last_discovered_at:null};
const supply=(b:string)=>({backend:b,cli_present:true,mode:'hub',menu_kind:'fixed',sources:{order:[source.id],eligibility:[{source_id:source.id,eligible:true}]},routes:{},builtin_models:[],catalog_models:[],menu:null,model_supply:[],named_agents:[{name:b,effective_model_id:agent(b).model,supply_status:saved[b].length?'ok':'unavailable'}],supply_status:saved[b].length?'ok':'unavailable'});
- const chain=(b:string,hs=saved[b])=>({contract_version:19,backend:b,model_id:agent(b).model,manual_override:hs.length?{hops:hs}:null,route_origin:hs.length?'manual':'automatic',current:hs[0]??null,chain:hs.map(h=>({...h,channel:'hub',health:'healthy',runnable:true,reason:null,retry_at:null})),supply_state:hs.length?'ok':'unavailable'});
+ const chain=(b:string,hs=saved[b])=>({contract_version:20,backend:b,model_id:agent(b).model,manual_override:hs.length?{hops:hs}:null,route_origin:hs.length?'manual':'automatic',current:hs[0]??null,chain:hs.map(h=>({...h,channel:'hub',health:'healthy',runnable:true,reason:null,retry_at:null})),supply_state:hs.length?'ok':'unavailable'});
await page.addInitScript(()=>localStorage.setItem('i18nextLng','en'));
await page.route(`${ORIGIN}/api/**`,async route=>{
const req=route.request(),path=new URL(req.url()).pathname;
@@ -34,7 +34,7 @@ for (const [width,chosen] of [[1200,"claude"],[390,"claude"],[1200,"codex"]] as
}
if(path==='/api/agents')return answer({ok:true,default_agent_name:defaultName,agents:[agent('claude'),agent('codex')]});
if(/^\/api\/agents\/(claude|codex)$/.test(path))return answer({ok:true,agent:agent(path.split('/').at(-1)!),default_agent_name:defaultName});
- if(path==='/api/models/runtime/status')return answer({ok:true,runtime:{contract_version:19,enabled:true,host_platform:'linux',manifest:{name:'cliproxyapi',resolution:'resolved',version:'fixture',source_sha:'a'.repeat(40),assets:[]},status:{installed_version:'fixture',verified:true,health:'ok'}}});
+ if(path==='/api/models/runtime/status')return answer({ok:true,runtime:{contract_version:20,enabled:true,host_platform:'linux',manifest:{name:'cliproxyapi',resolution:'resolved',version:'fixture',source_sha:'a'.repeat(40),assets:[]},status:{installed_version:'fixture',verified:true,health:'ok'}}});
if(path==='/api/models/sources')return answer({ok:true,sources:[source]});
if(path==='/api/models/agents')return answer({ok:true,agents:[supply('claude'),supply('codex')]});
if(/\/api\/models\/agents\/(claude|codex)\/chains$/.test(path)){
diff --git a/ui/e2e/onboarding-fidelity/provider-support.ts b/ui/e2e/onboarding-fidelity/provider-support.ts
index 07af8d3a3..05f12357b 100644
--- a/ui/e2e/onboarding-fidelity/provider-support.ts
+++ b/ui/e2e/onboarding-fidelity/provider-support.ts
@@ -129,7 +129,7 @@ const CONFIG = {
/** Installed, verified and serving: the screen's `gatewayIntent` reads `running` and
* starts no install, which is the state every proof below is about something else. */
const RUNTIME = {
- contract_version: 19,
+ contract_version: 20,
enabled: true,
host_platform: 'darwin',
manifest: {
diff --git a/ui/e2e/onboarding-fidelity/support.ts b/ui/e2e/onboarding-fidelity/support.ts
index c060a49ec..a2e32235a 100644
--- a/ui/e2e/onboarding-fidelity/support.ts
+++ b/ui/e2e/onboarding-fidelity/support.ts
@@ -87,7 +87,7 @@ export async function serveProduct(page: Page) {
const backend = new URL(route.request().url()).pathname.split('/')[4];
return route.fulfill({ json: { ok: true, agent: { backend, mode: 'direct', sources: { order: [], eligibility: [] }, routes: {}, builtin_models: [], catalog_models: [], named_agents: [], menu: null, model_supply: [], supply_status: 'unavailable' } } });
});
- await page.route('**/api/models/runtime/status', (route) => route.fulfill({ json: { ok: true, runtime: { contract_version: 19, enabled: true, host_platform: 'linux', manifest: { name: 'cliproxyapi', resolution: 'resolved', version: 'fixture', source_sha: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', assets: [] }, status: { installed_version: 'fixture', verified: true, health: 'ok' } } } }));
+ await page.route('**/api/models/runtime/status', (route) => route.fulfill({ json: { ok: true, runtime: { contract_version: 20, enabled: true, host_platform: 'linux', manifest: { name: 'cliproxyapi', resolution: 'resolved', version: 'fixture', source_sha: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', assets: [] }, status: { installed_version: 'fixture', verified: true, health: 'ok' } } } }));
await page.route(`${ORIGIN}/status`, (route) => route.fulfill({ json: { state: 'running' } }));
await page.route('**/api/backend/*/connection', (route) => route.fulfill({ json: { ok: true, backend: new URL(route.request().url()).pathname.split('/').at(-2), installed: true, enabled: true, auth: 'none', application: 'applied', ready: false, entry_eligible: false } }));
await page.route('**/api/config', (route) => route.fulfill({ json: CONFIG }));
diff --git a/ui/e2e/workbench-general/geometry.spec.ts b/ui/e2e/workbench-general/geometry.spec.ts
index b0fc69432..7d88233df 100644
--- a/ui/e2e/workbench-general/geometry.spec.ts
+++ b/ui/e2e/workbench-general/geometry.spec.ts
@@ -48,7 +48,7 @@ const MODEL_HUB_AGENT = {
};
const MODEL_HUB_RUNTIME = {
- contract_version: 19,
+ contract_version: 20,
enabled: true,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: 'fixture', source_sha: 'f'.repeat(40), assets: [] },
status: { installed_version: 'fixture', verified: true, listening: { host: '127.0.0.1', port: 43123 }, health: 'ok' },
diff --git a/ui/src/components/onboarding/AssistantSetup.test.tsx b/ui/src/components/onboarding/AssistantSetup.test.tsx
index 99e2db3cd..4086fe665 100644
--- a/ui/src/components/onboarding/AssistantSetup.test.tsx
+++ b/ui/src/components/onboarding/AssistantSetup.test.tsx
@@ -50,7 +50,7 @@ const hubAgent = (enabled = true) => ({
system_prompt: null, created_at: '', metadata: { builtin_default: true },
});
const hubChain = (modelId: string) => ({
- contract_version: 19, backend: 'claude', model_id: 'opus-5',
+ contract_version: 20, backend: 'claude', model_id: 'opus-5',
manual_override: { hops: [{ source_id: 'src_a', model_id: modelId }] },
route_origin: 'manual', current: { source_id: 'src_a', model_id: modelId },
chain: [{ source_id: 'src_a', model_id: modelId, channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }],
@@ -354,7 +354,7 @@ describe('assistant installation presentation', () => {
mock.api.getVibeAgent.mockResolvedValue({ ok: true, agent });
mock.models.listSources.mockResolvedValue([]);
const chain = {
- contract_version: 19, backend: 'claude', model_id: 'opus-5',
+ contract_version: 20, backend: 'claude', model_id: 'opus-5',
manual_override: { hops: [{ source_id: 'src_a', model_id: 'opus-5' }, { source_id: 'src_b', model_id: 'opus-5' }] },
route_origin: 'manual', current: { source_id: 'src_a', model_id: 'opus-5' },
chain: [
diff --git a/ui/src/components/onboarding/BuiltinAssistant.test.tsx b/ui/src/components/onboarding/BuiltinAssistant.test.tsx
index e9fe20d3c..9cf7fceca 100644
--- a/ui/src/components/onboarding/BuiltinAssistant.test.tsx
+++ b/ui/src/components/onboarding/BuiltinAssistant.test.tsx
@@ -65,7 +65,7 @@ const vibeyAgent = (model: string | null) => ({
system_prompt: null, created_at: '', metadata: { builtin_default: true, lock_delete: true },
});
const chain = (modelId: string) => ({
- contract_version: 19, backend: 'vibey', model_id: modelId,
+ contract_version: 20, backend: 'vibey', model_id: modelId,
manual_override: null, route_origin: 'automatic', current: { source_id: 'src_openai', model_id: modelId },
chain: [{ source_id: 'src_openai', model_id: modelId, channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }],
supply_state: 'ok',
diff --git a/ui/src/components/onboarding/providers/ProvidersScreen.test.tsx b/ui/src/components/onboarding/providers/ProvidersScreen.test.tsx
index 918c27768..7c2e8d71f 100644
--- a/ui/src/components/onboarding/providers/ProvidersScreen.test.tsx
+++ b/ui/src/components/onboarding/providers/ProvidersScreen.test.tsx
@@ -79,7 +79,7 @@ const supply = (over: Partial<AgentSupply> & { backend: AgentSupply['backend'] }
});
const runtimeOf = (health: RuntimeHealth, over: Partial<RuntimeDependency> = {}): RuntimeDependency => ({
- contract_version: 19,
+ contract_version: 20,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: '1.0.0', source_sha: 'sha', assets: [] },
status: { verified: true, health },
...over,
diff --git a/ui/src/components/onboarding/providers/providerStage.test.ts b/ui/src/components/onboarding/providers/providerStage.test.ts
index 2196f9ac5..ed332b87e 100644
--- a/ui/src/components/onboarding/providers/providerStage.test.ts
+++ b/ui/src/components/onboarding/providers/providerStage.test.ts
@@ -660,7 +660,7 @@ describe('adoptionBackend', () => {
});
const runtime = (health: RuntimeHealth, over: Partial<RuntimeDependency> = {}): RuntimeDependency => ({
- contract_version: 19,
+ contract_version: 20,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: '1.0.0', source_sha: 'sha', assets: [] },
status: { verified: true, health },
...over,
diff --git a/ui/src/components/settings/models/AgentCard.test.tsx b/ui/src/components/settings/models/AgentCard.test.tsx
index 1755f1ec6..7424d0a92 100644
--- a/ui/src/components/settings/models/AgentCard.test.tsx
+++ b/ui/src/components/settings/models/AgentCard.test.tsx
@@ -17,7 +17,7 @@ import { freshRuntimeProjection } from './runtimeLifecycle';
import type { AgentSupply, RuntimeDependency, Source } from './types';
const runtime: RuntimeDependency = {
- contract_version: 19,
+ contract_version: 20,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: '1.0.0', source_sha: 'fixture', assets: [] },
status: { installed_version: '1.0.0', verified: true, listening: null, health: 'ok', last_check: null },
};
@@ -414,7 +414,7 @@ describe('AgentCard', () => {
['zh', 'Backup → claude-opus-4-6(已自动切换)', '打开 claude-opus-4-6 的路由 · Backup → claude-opus-4-6(已自动切换)'],
] as const)('derives and announces takeover from the exact current hop in %s', (lng, mappingCopy, accessibleName) => {
const key = modelChainKey('claude', 'claude-opus-4-6');
- render(<I18nextProvider i18n={localeInstance(lng)}><AgentCard agents={[hubAgent]} sources={[source('src_a', 'Primary'), source('src_b', 'Backup')]} chains={{ [key]: readyRegion({ manual_override: {hops:[{source_id:'src_a',model_id:'claude-opus-4-6'},{source_id:'src_b',model_id:'claude-opus-4-6'}]}, route_origin: "manual" as const, contract_version: 19, backend: 'claude', model_id: 'claude-opus-4-6', current: { source_id: 'src_b', model_id: 'claude-opus-4-6' }, chain: [{ source_id: 'src_a', model_id: 'claude-opus-4-6', channel: 'hub', health: 'cooldown', runnable: false, reason: null, retry_at: '2099-01-01T00:00:00Z' }, { source_id: 'src_b', model_id: 'claude-opus-4-6', channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }], supply_state: 'ok' }) }} pendingBackends={new Set()} switchFailures={new Set()} connectingBackend={null} onConnectHub={vi.fn()} onSwitchDirect={vi.fn()} onOpenOrder={vi.fn()} onOpenRoute={vi.fn()} onProbeSettled={vi.fn()} /></I18nextProvider>);
+ render(<I18nextProvider i18n={localeInstance(lng)}><AgentCard agents={[hubAgent]} sources={[source('src_a', 'Primary'), source('src_b', 'Backup')]} chains={{ [key]: readyRegion({ manual_override: {hops:[{source_id:'src_a',model_id:'claude-opus-4-6'},{source_id:'src_b',model_id:'claude-opus-4-6'}]}, route_origin: "manual" as const, contract_version: 20, backend: 'claude', model_id: 'claude-opus-4-6', current: { source_id: 'src_b', model_id: 'claude-opus-4-6' }, chain: [{ source_id: 'src_a', model_id: 'claude-opus-4-6', channel: 'hub', health: 'cooldown', runnable: false, reason: null, retry_at: '2099-01-01T00:00:00Z' }, { source_id: 'src_b', model_id: 'claude-opus-4-6', channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }], supply_state: 'ok' }) }} pendingBackends={new Set()} switchFailures={new Set()} connectingBackend={null} onConnectHub={vi.fn()} onSwitchDirect={vi.fn()} onOpenOrder={vi.fn()} onOpenRoute={vi.fn()} onProbeSettled={vi.fn()} /></I18nextProvider>);
expect(screen.getByText(/Backup/)).toBeTruthy();
expect(screen.getByTitle(mappingCopy)).toBeTruthy();
expect(screen.getByRole('button', { name: accessibleName })).toBeTruthy();
@@ -434,7 +434,7 @@ describe('AgentCard', () => {
sources={[source('src_b', 'Backup source')]}
chains={{
[key]: readyRegion({ manual_override: {hops:[{source_id:'src_b',model_id:'routed-opus'}]}, route_origin: "manual" as const,
- contract_version: 19,
+ contract_version: 20,
backend: 'claude',
model_id: 'claude-opus-4-6',
current: { source_id: 'src_b', model_id: 'routed-opus' },
@@ -467,7 +467,7 @@ describe('AgentCard', () => {
it('does not call a later current hop takeover unless the head is unavailable for cooldown', () => {
const key = modelChainKey('claude', 'claude-opus-4-6');
- render(<I18nextProvider i18n={i18n}><AgentCard agents={[hubAgent]} sources={[source('src_a', 'Primary'), source('src_b', 'Backup')]} chains={{ [key]: readyRegion({ manual_override: {hops:[{source_id:'src_a',model_id:'claude-opus-4-6'},{source_id:'src_b',model_id:'claude-opus-4-6'}]}, route_origin: "manual" as const, contract_version: 19, backend: 'claude', model_id: 'claude-opus-4-6', current: { source_id: 'src_b', model_id: 'claude-opus-4-6' }, chain: [{ source_id: 'src_a', model_id: 'claude-opus-4-6', channel: 'native_cli', health: 'healthy', runnable: false, reason: 'native_cli_unavailable', retry_at: null }, { source_id: 'src_b', model_id: 'claude-opus-4-6', channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }], supply_state: 'ok' }) }} pendingBackends={new Set()} switchFailures={new Set()} connectingBackend={null} onConnectHub={vi.fn()} onSwitchDirect={vi.fn()} onOpenOrder={vi.fn()} onOpenRoute={vi.fn()} onProbeSettled={vi.fn()} /></I18nextProvider>);
+ render(<I18nextProvider i18n={i18n}><AgentCard agents={[hubAgent]} sources={[source('src_a', 'Primary'), source('src_b', 'Backup')]} chains={{ [key]: readyRegion({ manual_override: {hops:[{source_id:'src_a',model_id:'claude-opus-4-6'},{source_id:'src_b',model_id:'claude-opus-4-6'}]}, route_origin: "manual" as const, contract_version: 20, backend: 'claude', model_id: 'claude-opus-4-6', current: { source_id: 'src_b', model_id: 'claude-opus-4-6' }, chain: [{ source_id: 'src_a', model_id: 'claude-opus-4-6', channel: 'native_cli', health: 'healthy', runnable: false, reason: 'native_cli_unavailable', retry_at: null }, { source_id: 'src_b', model_id: 'claude-opus-4-6', channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }], supply_state: 'ok' }) }} pendingBackends={new Set()} switchFailures={new Set()} connectingBackend={null} onConnectHub={vi.fn()} onSwitchDirect={vi.fn()} onOpenOrder={vi.fn()} onOpenRoute={vi.fn()} onProbeSettled={vi.fn()} /></I18nextProvider>);
expect(screen.getByText(/Backup/)).toBeTruthy();
expect(screen.queryByText(/takeover/i)).toBeNull();
});
@@ -475,7 +475,7 @@ describe('AgentCard', () => {
it('hides current and takeover projections while the runtime is stopped', () => {
const key = modelChainKey('claude', 'claude-opus-4-6');
const stopped = { ...runtime, status: { ...runtime.status, health: 'down' as const } };
- render(<I18nextProvider i18n={i18n}><RuntimeAgentCard runtime={freshRuntimeProjection(readyRegion(stopped))} agents={[hubAgent]} sources={[source('src_a', 'Primary'), source('src_b', 'Backup')]} chains={{ [key]: readyRegion({ manual_override: {hops:[{source_id:'src_a',model_id:'claude-opus-4-6'},{source_id:'src_b',model_id:'claude-opus-4-6'}]}, route_origin: "manual" as const, contract_version: 19, backend: 'claude', model_id: 'claude-opus-4-6', current: { source_id: 'src_b', model_id: 'claude-opus-4-6' }, chain: [{ source_id: 'src_a', model_id: 'claude-opus-4-6', channel: 'hub', health: 'cooldown', runnable: false, reason: null, retry_at: '2099-01-01T00:00:00Z' }, { source_id: 'src_b', model_id: 'claude-opus-4-6', channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }], supply_state: 'ok' }) }} pendingBackends={new Set()} switchFailures={new Set()} connectingBackend={null} onConnectHub={vi.fn()} onSwitchDirect={vi.fn()} onOpenModels={vi.fn()} onOpenOrder={vi.fn()} onOpenRoute={vi.fn()} onProbeSettled={vi.fn()} /></I18nextProvider>);
+ render(<I18nextProvider i18n={i18n}><RuntimeAgentCard runtime={freshRuntimeProjection(readyRegion(stopped))} agents={[hubAgent]} sources={[source('src_a', 'Primary'), source('src_b', 'Backup')]} chains={{ [key]: readyRegion({ manual_override: {hops:[{source_id:'src_a',model_id:'claude-opus-4-6'},{source_id:'src_b',model_id:'claude-opus-4-6'}]}, route_origin: "manual" as const, contract_version: 20, backend: 'claude', model_id: 'claude-opus-4-6', current: { source_id: 'src_b', model_id: 'claude-opus-4-6' }, chain: [{ source_id: 'src_a', model_id: 'claude-opus-4-6', channel: 'hub', health: 'cooldown', runnable: false, reason: null, retry_at: '2099-01-01T00:00:00Z' }, { source_id: 'src_b', model_id: 'claude-opus-4-6', channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }], supply_state: 'ok' }) }} pendingBackends={new Set()} switchFailures={new Set()} connectingBackend={null} onConnectHub={vi.fn()} onSwitchDirect={vi.fn()} onOpenModels={vi.fn()} onOpenOrder={vi.fn()} onOpenRoute={vi.fn()} onProbeSettled={vi.fn()} /></I18nextProvider>);
expect(screen.queryByText(/Backup/)).toBeNull();
expect(screen.queryByText(/takeover/i)).toBeNull();
@@ -487,7 +487,7 @@ describe('AgentCard', () => {
const onOpenModels = vi.fn();
const key = modelChainKey('claude', 'claude-opus-4-6');
const directAgent: AgentSupply = { ...hubAgent, mode: 'direct', sources: null, routes: null, supply_status: null, model_supply: null };
- render(<I18nextProvider i18n={i18n}><AgentCard agents={[directAgent]} sources={[source('src_a', 'Primary'), source('src_b', 'Backup')]} chains={{ [key]: readyRegion({ manual_override: {hops:[{source_id:'src_a',model_id:'claude-opus-4-6'},{source_id:'src_b',model_id:'claude-opus-4-6'}]}, route_origin: "manual" as const, contract_version: 19, backend: 'claude', model_id: 'claude-opus-4-6', current: { source_id: 'src_b', model_id: 'claude-opus-4-6' }, chain: [{ source_id: 'src_a', model_id: 'claude-opus-4-6', channel: 'hub', health: 'cooldown', runnable: false, reason: null, retry_at: '2099-01-01T00:00:00Z' }, { source_id: 'src_b', model_id: 'claude-opus-4-6', channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }], supply_state: 'ok' }) }} pendingBackends={new Set()} switchFailures={new Set()} connectingBackend={null} onConnectHub={vi.fn()} onSwitchDirect={vi.fn()} onOpenModels={onOpenModels} onOpenOrder={vi.fn()} onOpenRoute={vi.fn()} onProbeSettled={vi.fn()} /></I18nextProvider>);
+ render(<I18nextProvider i18n={i18n}><AgentCard agents={[directAgent]} sources={[source('src_a', 'Primary'), source('src_b', 'Backup')]} chains={{ [key]: readyRegion({ manual_override: {hops:[{source_id:'src_a',model_id:'claude-opus-4-6'},{source_id:'src_b',model_id:'claude-opus-4-6'}]}, route_origin: "manual" as const, contract_version: 20, backend: 'claude', model_id: 'claude-opus-4-6', current: { source_id: 'src_b', model_id: 'claude-opus-4-6' }, chain: [{ source_id: 'src_a', model_id: 'claude-opus-4-6', channel: 'hub', health: 'cooldown', runnable: false, reason: null, retry_at: '2099-01-01T00:00:00Z' }, { source_id: 'src_b', model_id: 'claude-opus-4-6', channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null }], supply_state: 'ok' }) }} pendingBackends={new Set()} switchFailures={new Set()} connectingBackend={null} onConnectHub={vi.fn()} onSwitchDirect={vi.fn()} onOpenModels={onOpenModels} onOpenOrder={vi.fn()} onOpenRoute={vi.fn()} onProbeSettled={vi.fn()} /></I18nextProvider>);
expect(screen.queryByText(/Adjust priority/i)).toBeNull();
expect(screen.queryByRole('button', { name: /route chain/i })).toBeNull();
expect(screen.queryByText(/Backup/)).toBeNull();
diff --git a/ui/src/components/settings/models/BackendSupplyModeCard.test.tsx b/ui/src/components/settings/models/BackendSupplyModeCard.test.tsx
index 5c88bf424..042af51da 100644
--- a/ui/src/components/settings/models/BackendSupplyModeCard.test.tsx
+++ b/ui/src/components/settings/models/BackendSupplyModeCard.test.tsx
@@ -34,7 +34,7 @@ const CLAUDE_KEY: MigrationItem = {
};
const RUNTIME: RuntimeDependency = {
- contract_version: 19,
+ contract_version: 20,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: '1', source_sha: 'a'.repeat(40), assets: [] },
status: { installed_version: '1', verified: true, health: 'ok' },
};
diff --git a/ui/src/components/settings/models/RouteChainDialog.directEdit.test.tsx b/ui/src/components/settings/models/RouteChainDialog.directEdit.test.tsx
index 8789c42ce..faaf39f1e 100644
--- a/ui/src/components/settings/models/RouteChainDialog.directEdit.test.tsx
+++ b/ui/src/components/settings/models/RouteChainDialog.directEdit.test.tsx
@@ -17,7 +17,7 @@ const sources: Source[] = ['a', 'b'].map((id) => ({
}));
const hops = sources.map((source) => ({ source_id: source.id, model_id: 'gpt-test' }));
const makeChain = (backend: AgentSupply['backend'], routeOrigin: 'automatic' | 'passthrough' | 'manual'): AgentChain => ({
- contract_version: 19, backend, model_id: 'gpt-test', route_origin: routeOrigin,
+ contract_version: 20, backend, model_id: 'gpt-test', route_origin: routeOrigin,
manual_override: routeOrigin === 'manual' ? { hops } : null,
current: hops[0], supply_state: 'ok',
chain: hops.map((hop) => ({ ...hop, channel: 'hub', health: 'healthy', runnable: true, reason: null, retry_at: null })),
diff --git a/ui/src/components/settings/models/RouteChainDialog.test.tsx b/ui/src/components/settings/models/RouteChainDialog.test.tsx
index 02bdede96..aaa150a27 100644
--- a/ui/src/components/settings/models/RouteChainDialog.test.tsx
+++ b/ui/src/components/settings/models/RouteChainDialog.test.tsx
@@ -57,7 +57,7 @@ const sources: Source[] = [
},
];
const chain: AgentChain = { manual_override: {hops:[{source_id:"src_a",model_id:"claude-opus-5"},{source_id:"src_b",model_id:"opus-5"}]}, route_origin: "manual" as const,
- contract_version: 19,
+ contract_version: 20,
backend: "claude",
model_id: "opus-5",
current: { source_id: "src_b", model_id: "opus-5" },
diff --git a/ui/src/components/settings/models/RouteRecordedTurn.test.tsx b/ui/src/components/settings/models/RouteRecordedTurn.test.tsx
index 97d3f3b39..d83235b20 100644
--- a/ui/src/components/settings/models/RouteRecordedTurn.test.tsx
+++ b/ui/src/components/settings/models/RouteRecordedTurn.test.tsx
@@ -15,7 +15,7 @@ import { PERSISTED_TURN_CONTRACT_VERSIONS } from './types';
import type { RouteHop, TurnProvenance } from './types';
const record: TurnProvenance = {
- contract_version: 19, turn_id: 'turn-recorded', ts: '2026-09-05T15:00:00Z', agent: 'codex', requested_model_id: 'requested-model',
+ contract_version: 20, turn_id: 'turn-recorded', ts: '2026-09-05T15:00:00Z', agent: 'codex', requested_model_id: 'requested-model',
outcome: 'failed_terminal', failed_attempts: [], served: null, canceled_attempt: null, model_supply_state: null, blockers: [],
terminal_error: { source_id: 'src_historical', configured_model_id: 'historical-model', channel: 'hub', reason: 'invalid_parameter', stream_started: false, http_status: 404, upstream_error_code: 'model_not_found' },
};
diff --git a/ui/src/components/settings/models/RuntimeNotStartedAction.test.tsx b/ui/src/components/settings/models/RuntimeNotStartedAction.test.tsx
index 3e31e06d5..1c2c782f3 100644
--- a/ui/src/components/settings/models/RuntimeNotStartedAction.test.tsx
+++ b/ui/src/components/settings/models/RuntimeNotStartedAction.test.tsx
@@ -31,7 +31,7 @@ const runtime = (
? 'unresolved' as const
: hostPlatform === 'linux-amd64' ? 'unsupported' as const : 'resolved' as const;
return {
- contract_version: 19,
+ contract_version: 20,
...(hostPlatform === undefined ? {} : { host_platform: hostPlatform }),
manifest: resolution === 'unresolved'
? { name: 'cliproxyapi', resolution, assets: [] }
diff --git a/ui/src/components/settings/models/SearchServices.test.tsx b/ui/src/components/settings/models/SearchServices.test.tsx
index b60ad527f..3133cac88 100644
--- a/ui/src/components/settings/models/SearchServices.test.tsx
+++ b/ui/src/components/settings/models/SearchServices.test.tsx
@@ -1,5 +1,5 @@
// @vitest-environment jsdom
-// S4's owning UI boundaries: activation must not leak dormant settings; mixed
+// Search service UI boundaries: active reads expose the service controls; mixed
// order and Source settings must write only the intended field; the shared add
// dialog must use read membership (not a vendor-name guess) and Source create
// settlement. Released Tools/Source tests only cover model executors.
@@ -16,7 +16,7 @@ import { createSourceCollectionReadAuthority } from './collectionReadAuthority';
import { ApiCallError, modelsApi } from './modelsApi';
import type { SourceMutationSettlement, TrackSourceMutation } from './mutationSettlement';
import { readyRegion } from './regionRead';
-import { ACTIVE_SEARCH, INACTIVE_SEARCH, SEARCH_SOURCES } from './searchServices.fixtures';
+import { ACTIVE_SEARCH, SEARCH_SOURCES } from './searchServices.fixtures';
import { SourceDetailPanel } from './SourceDetailPanel';
import { SourcesCard } from './SourcesCard';
import { ToolsTab } from './ToolsTab';
@@ -72,25 +72,20 @@ const newVendors = (): HostedWebSearchToolStatus => ({
afterEach(() => { cleanup(); vi.restoreAllMocks(); localStorage.clear(); });
describe('search service activation and mixed order', () => {
- it.each(['en', 'zh'])('keeps the inactive Tools, Sources entry points and detail unchanged in %s', async (lng) => {
+ it.each(['en', 'zh'])('exposes service order, native preference and add entry points on the active read in %s', async (lng) => {
const locale = i18n.cloneInstance({ lng });
const view = render(wrap(<>
- <ToolsTab read={readyRegion({ tools: [INACTIVE_SEARCH] })} sources={SEARCH_SOURCES} pending={new Set()} onSave={vi.fn()} onClear={vi.fn()} onRetry={vi.fn()} />
- <SourcesCard read={readyRegion(SEARCH_SOURCES)} onRetry={vi.fn()} onOpenSource={vi.fn()} onAddApiKey={vi.fn()} onAddSubscription={vi.fn()} searchTool={INACTIVE_SEARCH} onAddSearchService={vi.fn()} />
+ <ToolsTab read={readyRegion({ tools: [ACTIVE_SEARCH] })} sources={SEARCH_SOURCES} pending={new Set()} onSave={vi.fn()} onClear={vi.fn()} onRetry={vi.fn()} />
+ <SourcesCard read={readyRegion(SEARCH_SOURCES)} onRetry={vi.fn()} onOpenSource={vi.fn()} onAddApiKey={vi.fn()} onAddSubscription={vi.fn()} searchTool={ACTIVE_SEARCH} onAddSearchService={vi.fn()} />
</>, lng));
- expect(screen.getByText(locale.t('settings.models.tools.subtitle'))).toBeTruthy();
- expect(screen.getAllByRole('switch')).toHaveLength(1);
- expect(screen.queryByText(locale.t('settings.models.searchServices.order'))).toBeNull();
- expect(screen.queryByText(locale.t('settings.models.searchServices.addProvider'))).toBeNull();
- expect(screen.queryByText(locale.t('settings.models.searchServices.add'))).toBeNull();
+ expect(screen.getByText(locale.t('settings.models.searchServices.subtitle'))).toBeTruthy();
+ expect(screen.getAllByRole('switch')).toHaveLength(2);
+ expect(screen.getByRole('heading', { name: locale.t('settings.models.searchServices.order') })).toBeTruthy();
+ expect(screen.getByRole('button', { name: locale.t('settings.models.searchServices.addProvider') })).toBeTruthy();
+ expect(screen.getByRole('button', { name: locale.t('settings.models.searchServices.add') })).toBeTruthy();
await userEvent.click(screen.getByRole('button', { name: new RegExp(`^${locale.t('settings.models.tools.advanced.label')}`) }));
- expect(screen.getByText(locale.t('settings.models.tools.order.title'))).toBeTruthy();
- expect(view.container.querySelectorAll('[data-executor]')).toHaveLength(1);
- view.unmount();
- detail(SEARCH_SOURCES[3], INACTIVE_SEARCH);
- expect(screen.queryByRole('switch')).toBeNull();
- expect(screen.getByText('deepseek-chat')).toBeTruthy();
- expect(screen.getByRole('button', { name: 'Manage DeepSeek' })).toBeTruthy();
+ expect(screen.getAllByRole('list', { name: locale.t('settings.models.searchServices.order') })).toHaveLength(1);
+ expect(view.container.querySelectorAll('[data-executor]')).toHaveLength(4);
});
it('shows mixed rows above Advanced, disables opted-out reordering, and saves preference/order independently', async () => {
@@ -189,7 +184,6 @@ describe('search Source detail', () => {
it.each([
['listed', ACTIVE_SEARCH, true],
- ['dormant', INACTIVE_SEARCH, false],
['unlisted', { ...ACTIVE_SEARCH, executor_candidates: ACTIVE_SEARCH.executor_candidates.filter((row) => row.source_id !== 'src_exa000001') }, false],
] as const)('MH-USAGE-038: reads this month only for a %s search service, apart from the Usage tab', async (_, tool, listed) => {
const { readUsage, onOpenUsage } = detail(SEARCH_SOURCES[1], tool);
diff --git a/ui/src/components/settings/models/SettingsModelsPage.render.test.tsx b/ui/src/components/settings/models/SettingsModelsPage.render.test.tsx
index afadeccde..9de48c8a4 100644
--- a/ui/src/components/settings/models/SettingsModelsPage.render.test.tsx
+++ b/ui/src/components/settings/models/SettingsModelsPage.render.test.tsx
@@ -49,7 +49,7 @@ const manifest = {
} satisfies RuntimeManifest;
const runtime: RuntimeDependency = {
- contract_version: 19,
+ contract_version: 20,
manifest,
status: { installed_version: '1', verified: true, health: 'ok' },
};
@@ -120,7 +120,7 @@ const takeoverAgent: AgentSupply = {
};
const takeoverChain: AgentChain = { manual_override: {hops:[{source_id:'src_head',model_id:'gpt-5.6-sol'},{source_id:'src_relay',model_id:'gpt-5.6-sol'}]}, route_origin: "manual" as const,
- contract_version: 19,
+ contract_version: 20,
backend: 'codex',
model_id: 'gpt-5.6-sol',
current: { source_id: 'src_relay', model_id: 'gpt-5.6-sol' },
@@ -224,7 +224,7 @@ const routedHubAgent: AgentSupply = {
const routedChain: AgentChain = {
manual_override: { hops: [{ source_id: retainedSource.id, model_id: routedModelId }] },
route_origin: 'manual' as const,
- contract_version: 19,
+ contract_version: 20,
backend: 'claude',
model_id: routedModelId,
current: { source_id: retainedSource.id, model_id: routedModelId },
diff --git a/ui/src/components/settings/models/SourceDetailPanel.test.tsx b/ui/src/components/settings/models/SourceDetailPanel.test.tsx
index f5cd61fb8..edf76857b 100644
--- a/ui/src/components/settings/models/SourceDetailPanel.test.tsx
+++ b/ui/src/components/settings/models/SourceDetailPanel.test.tsx
@@ -1330,7 +1330,7 @@ describe('SourceDetailPanel', () => {
// Still bounded well below a hung render.
}, 15_000);
- it.each([false, true])('runs the dedicated re-enable action with search services active=%s and holds an armed trial', async (active) => {
+ it('runs the dedicated re-enable action on the active service read and holds an armed trial', async () => {
const blockedSearch: Source = {
...SEARCH_SOURCES[0],
protocol: 'search',
@@ -1347,7 +1347,7 @@ describe('SourceDetailPanel', () => {
const onSource = vi.fn().mockResolvedValue(undefined);
const trackMutation: TrackSourceMutation = (work) => work(blockedSearch, settlement({ source: onSource }));
- const panel = (current: Source) => <I18nextProvider i18n={i18n}><CommittedPanel source={current} hostedTools={active ? readyRegion({ tools: [ACTIVE_SEARCH] }) : undefined} trackMutation={trackMutation} onReauth={noReauth} /></I18nextProvider>;
+ const panel = (current: Source) => <I18nextProvider i18n={i18n}><CommittedPanel source={current} hostedTools={readyRegion({ tools: [ACTIVE_SEARCH] })} trackMutation={trackMutation} onReauth={noReauth} /></I18nextProvider>;
const view = render(panel(blockedSearch));
await userEvent.click(screen.getByRole('button', { name: /^Re-enable$|^重新启用$/i }));
await waitFor(() => expect(reenable).toHaveBeenCalledWith(blockedSearch.id));
diff --git a/ui/src/components/settings/models/SupplyGraph.test.ts b/ui/src/components/settings/models/SupplyGraph.test.ts
index 67660ddae..1c5cf0b08 100644
--- a/ui/src/components/settings/models/SupplyGraph.test.ts
+++ b/ui/src/components/settings/models/SupplyGraph.test.ts
@@ -7,7 +7,7 @@ import { buildSupplyRelations as buildRelations } from './supplyRelations';
import type { AgentChain, AgentSupply, RuntimeDependency, Source } from './types';
const runtime: RuntimeDependency = {
- contract_version: 19,
+ contract_version: 20,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: '1.0.0', source_sha: 'fixture', assets: [] },
status: { installed_version: '1.0.0', verified: true, listening: null, health: 'ok', last_check: null },
};
@@ -47,7 +47,7 @@ const agent: AgentSupply = {
};
const chain = (current: string, headHealth: AgentChain['chain'][number]['health'] = 'healthy', headRunnable = true, reason: AgentChain['chain'][number]['reason'] = null): AgentChain => ({ manual_override: {hops:[{source_id:'native',model_id:'model-a'},{source_id:'relay',model_id:'model-a'},{source_id:'unused',model_id:'model-a'}]}, route_origin: "manual" as const,
- contract_version: 19,
+ contract_version: 20,
backend: 'claude',
model_id: 'model-a',
current: { source_id: current, model_id: 'model-a' },
diff --git a/ui/src/components/settings/models/apiFailure.test.ts b/ui/src/components/settings/models/apiFailure.test.ts
index 3f48174a3..fa546c5e4 100644
--- a/ui/src/components/settings/models/apiFailure.test.ts
+++ b/ui/src/components/settings/models/apiFailure.test.ts
@@ -33,7 +33,7 @@ afterEach(() => {
describe('apiFailure — whether the route named the failure', () => {
it('posts installation to the dedicated runtime route', async () => {
const runtime = {
- contract_version: 19,
+ contract_version: 20,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: '1', source_sha: 'sha', assets: [] },
status: { installed_version: null, verified: false, listening: null, health: 'installing', last_check: null },
} as const;
diff --git a/ui/src/components/settings/models/gatewayAdoption.test.ts b/ui/src/components/settings/models/gatewayAdoption.test.ts
index 69527194b..8bf0bf5b7 100644
--- a/ui/src/components/settings/models/gatewayAdoption.test.ts
+++ b/ui/src/components/settings/models/gatewayAdoption.test.ts
@@ -14,7 +14,7 @@ const agent = (mode: AgentSupply['mode']): AgentSupply => ({
});
const runtime = (health: RuntimeDependency['status']['health']): RuntimeDependency => ({
- contract_version: 19,
+ contract_version: 20,
manifest: { name: 'cliproxyapi', resolution: 'resolved', version: '1', source_sha: 'a'.repeat(40), assets: [] },
status: { installed_version: health === 'not_installed' ? null : '1', verified: health !== 'not_installed', health },
});
diff --git a/ui/src/components/settings/models/routeProjectionReconciliation.test.ts b/ui/src/components/settings/models/routeProjectionReconciliation.test.ts
index ba9824d7c..fea87e377 100644
--- a/ui/src/components/settings/models/routeProjectionReconciliation.test.ts
+++ b/ui/src/components/settings/models/routeProjectionReconciliation.test.ts
@@ -24,7 +24,7 @@ const source: Source = {
};
const report: RouteReport = {
chain: {
- contract_version: 19,
+ contract_version: 20,
backend: "claude",
model_id: "模型/opus",
manual_override: null,
diff --git a/ui/src/components/settings/models/runtimeLifecycle.test.ts b/ui/src/components/settings/models/runtimeLifecycle.test.ts
index f60cb08a8..2db5c0376 100644
--- a/ui/src/components/settings/models/runtimeLifecycle.test.ts
+++ b/ui/src/components/settings/models/runtimeLifecycle.test.ts
@@ -11,7 +11,7 @@ const asset = (platform: 'darwin-arm64' | 'linux-amd64') => ({
});
const runtime = (resolution: 'resolved' | 'unresolved' | 'unsupported'): RuntimeDependency => ({
- contract_version: 19,
+ contract_version: 20,
host_platform: 'darwin-arm64',
manifest: resolution === 'unresolved'
? { name: 'cliproxyapi', resolution, assets: [] }
diff --git a/ui/src/components/settings/models/searchServices.fixtures.ts b/ui/src/components/settings/models/searchServices.fixtures.ts
index ec2d2b197..4dc33531c 100644
--- a/ui/src/components/settings/models/searchServices.fixtures.ts
+++ b/ui/src/components/settings/models/searchServices.fixtures.ts
@@ -36,9 +36,3 @@ export const ACTIVE_SEARCH: HostedWebSearchToolStatus = {
{ id: 'exa', name: 'Exa', results_max: 10, price: price(7), free_tier: null, source_ids: ['src_exa000001'], facts: { tool_only: true, auto_enroll: false, free_check: false } },
],
};
-
-export const INACTIVE_SEARCH: HostedWebSearchToolStatus = {
- name: 'web_search', enabled: true, prefer_native: false, services: {}, service_order: [], executor_order: null,
- status: ACTIVE_SEARCH.status, effective_order: ['src_claude001'],
- executor_candidates: [ACTIVE_SEARCH.executor_candidates[2]],
-};
diff --git a/ui/src/components/settings/models/searchServices.ts b/ui/src/components/settings/models/searchServices.ts
index a2aed1015..7d24c4d4f 100644
--- a/ui/src/components/settings/models/searchServices.ts
+++ b/ui/src/components/settings/models/searchServices.ts
@@ -1,6 +1,6 @@
import type { HostedSearchServiceVendor, HostedToolsStatus, HostedWebSearchToolStatus } from './types';
-/** One activation signal across Tools, Sources and detail. S2 activates the read and execution together. */
+/** One read signal across Tools, Sources and detail; S2b-2 activates service reads and execution together. */
export const searchServicesActive = (tool: HostedWebSearchToolStatus | null | undefined): boolean =>
tool?.service_vendors !== undefined;
diff --git a/ui/src/components/settings/models/types.ts b/ui/src/components/settings/models/types.ts
index a722933a3..2327546fb 100644
--- a/ui/src/components/settings/models/types.ts
+++ b/ui/src/components/settings/models/types.ts
@@ -10,8 +10,8 @@
// and the PR records the server implementation and feature-flag activation
// edge. The client never synthesizes a fallback payload shape.
-export const CONTRACT_VERSION = 19 as const;
-export const PERSISTED_TURN_CONTRACT_VERSIONS = [5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19] as const;
+export const CONTRACT_VERSION = 20 as const;
+export const PERSISTED_TURN_CONTRACT_VERSIONS = [5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20] as const;
export const AGENT_CHAIN_CONTRACT_VERSION = CONTRACT_VERSION;
export const PROBE_RESULT_CONTRACT_VERSION = CONTRACT_VERSION;
@@ -1160,7 +1160,7 @@ export type HostedServiceListPrice = HostedToolListPrice & { unit: 'search' };
/** Effective settings. Saved settings and PUT patches keep omitted fields absent instead. */
export type HostedSearchServiceSettings = { results: number; enabled: boolean };
-/** Defined now, but the server lists no service candidate until S2 activates the chain. */
+/** A search-service candidate in the active mixed search chain. */
export type HostedServiceExecutorCandidate = {
kind: 'service';
source_id: string;
@@ -1213,7 +1213,7 @@ export type HostedWebSearchToolStatus = HostedSearchToolBase & {
/** Server-owned creation order; clients never write this back. */
service_order: string[];
executor_candidates: HostedExecutorCandidate[];
- /** Absent until S2 activates service reads and the search chain together. */
+ /** Present on the active web-search read; older server reads may omit it. */
service_vendors?: HostedSearchServiceVendor[];
};