windcode 0.1.0__py3-none-any.whl

windcode/__init__.py

@@ -0,0 +1,6 @@
+"""Windcode public package."""
+
+from windcode.sdk import Windcode
+
+__all__ = ["Windcode"]
+__version__ = "0.1.0"

windcode/__main__.py

@@ -0,0 +1,4 @@
+from windcode.cli import main
+
+if __name__ == "__main__":
+    main()

windcode/auth/__init__.py

@@ -0,0 +1,11 @@
+from windcode.auth.store import (
+    CredentialStore,
+    CredentialStoreError,
+    FileCredentialStore,
+)
+
+__all__ = [
+    "CredentialStore",
+    "CredentialStoreError",
+    "FileCredentialStore",
+]

windcode/auth/store.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Protocol, TypedDict, cast
+from uuid import uuid4
+
+from platformdirs import user_data_path
+
+
+class CredentialStoreError(RuntimeError):
+    """Raised when credentials cannot be persisted safely."""
+
+
+class CredentialStore(Protocol):
+    def get(self, credential_id: str) -> str | None: ...
+
+    def set(self, credential_id: str, secret: str) -> None: ...
+
+    def delete(self, credential_id: str) -> None: ...
+
+
+class ApiCredential(TypedDict):
+    type: str
+    key: str
+
+
+class FileCredentialStore:
+    """OpenCode-style API credentials stored in the user's data directory."""
+
+    def __init__(self, path: Path | None = None) -> None:
+        self.path = (path or user_data_path("windcode") / "auth.json").expanduser().resolve()
+
+    def _read(self) -> dict[str, ApiCredential]:
+        try:
+            raw: object = json.loads(self.path.read_text(encoding="utf-8"))
+        except FileNotFoundError:
+            return {}
+        except (OSError, json.JSONDecodeError) as exc:
+            raise CredentialStoreError("无法读取 Windcode 凭据文件") from exc
+        if not isinstance(raw, dict):
+            raise CredentialStoreError("Windcode 凭据文件格式无效")
+        values = cast(dict[object, object], raw)
+        credentials: dict[str, ApiCredential] = {}
+        for credential_id, value in values.items():
+            if not isinstance(credential_id, str):
+                continue
+            if not isinstance(value, dict):
+                continue
+            record = cast(dict[object, object], value)
+            credential_type = record.get("type")
+            key = record.get("key")
+            if credential_type == "api" and isinstance(key, str):
+                credentials[credential_id] = {"type": "api", "key": key}
+        return credentials
+
+    def get(self, credential_id: str) -> str | None:
+        credential = self._read().get(credential_id)
+        return credential["key"] if credential is not None else None
+
+    def set(self, credential_id: str, secret: str) -> None:
+        values = self._read()
+        values[credential_id] = {"type": "api", "key": secret}
+        self._write(values)
+
+    def delete(self, credential_id: str) -> None:
+        values = self._read()
+        if values.pop(credential_id, None) is not None:
+            self._write(values)
+
+    def _write(self, values: Mapping[str, ApiCredential]) -> None:
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+            os.chmod(self.path.parent, 0o700)
+            temporary = self.path.with_suffix(f"{self.path.suffix}.tmp-{uuid4().hex}")
+            try:
+                descriptor = os.open(temporary, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+                with os.fdopen(descriptor, "w", encoding="utf-8") as stream:
+                    json.dump(dict(values), stream, ensure_ascii=True, indent=2, sort_keys=True)
+                    stream.write("\n")
+                    stream.flush()
+                    os.fsync(stream.fileno())
+                temporary.replace(self.path)
+                os.chmod(self.path, 0o600)
+            finally:
+                temporary.unlink(missing_ok=True)
+        except OSError as exc:
+            raise CredentialStoreError("无法写入 Windcode 凭据文件") from exc

windcode/cli.py

@@ -0,0 +1,181 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from windcode.config import AppConfig, ConfigError, PermissionMode, load_config
+
+
+@dataclass(frozen=True, slots=True)
+class CLIOptions:
+    workspace: Path
+    config_file: Path | None
+    model: str | None
+    resume_session: str | None
+    permission_mode: PermissionMode | None
+    sandbox_enabled: bool | None
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="windcode", description="Terminal coding agent")
+    parser.add_argument("workspace", nargs="?", type=Path, default=Path.cwd())
+    parser.add_argument("--config", type=Path, help="explicit TOML configuration file")
+    parser.add_argument("--model", help="provider alias or model override")
+    parser.add_argument("--resume", metavar="SESSION_ID", help="resume an existing session")
+    parser.add_argument(
+        "--permission-mode",
+        choices=tuple(mode.value for mode in PermissionMode),
+        help="initial permission mode",
+    )
+    parser.add_argument(
+        "--sandbox",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="enable or explicitly disable the Linux tool sandbox",
+    )
+    return parser
+
+
+def parse_options(argv: Sequence[str] | None = None) -> CLIOptions:
+    namespace = build_parser().parse_args(argv)
+    raw_mode = namespace.permission_mode
+    return CLIOptions(
+        workspace=namespace.workspace.expanduser().resolve(),
+        config_file=namespace.config,
+        model=namespace.model,
+        resume_session=namespace.resume,
+        permission_mode=PermissionMode(raw_mode) if raw_mode is not None else None,
+        sandbox_enabled=namespace.sandbox,
+    )
+
+
+def resolve_config(options: CLIOptions) -> AppConfig:
+    overrides: dict[str, object] = {}
+    if options.permission_mode is not None:
+        overrides["permission"] = {"mode": options.permission_mode.value}
+    if options.sandbox_enabled is not None:
+        overrides["sandbox"] = {"enabled": options.sandbox_enabled}
+    return load_config(
+        options.workspace,
+        explicit_file=options.config_file,
+        overrides=overrides,
+    )
+
+
+def build_extensions_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="windcode extensions")
+    parser.add_argument(
+        "action", choices=("list", "inspect", "install", "enable", "disable", "reload", "trust")
+    )
+    parser.add_argument("target", nargs="?")
+    parser.add_argument("--workspace", type=Path, default=Path.cwd())
+    parser.add_argument("--config", type=Path)
+    parser.add_argument("--enable", action="store_true", help="enable a plugin while installing")
+    parser.add_argument("--untrust", action="store_true", help="remove workspace trust")
+    parser.add_argument("--json", action="store_true", dest="json_output")
+    return parser
+
+
+async def _run_extensions(argv: Sequence[str]) -> int:
+    namespace = build_extensions_parser().parse_args(argv)
+    workspace: Path = namespace.workspace.expanduser().resolve()
+    if not workspace.is_dir():  # noqa: ASYNC240 - CLI setup happens before concurrent work
+        raise ConfigError(workspace, "workspace is not a directory")
+    config = load_config(workspace, explicit_file=namespace.config)
+    from windcode.sdk import Windcode
+
+    async with Windcode.open(config, workspace=workspace) as client:
+        action = str(namespace.action)
+        target = None if namespace.target is None else str(namespace.target)
+        if action == "list":
+            value: object = await client.list_extensions()
+        elif action == "inspect":
+            if target is None:
+                raise ConfigError("extensions inspect", "TARGET is required")
+            value = await client.inspect_extension(target)
+        elif action == "install":
+            if target is None:
+                raise ConfigError("extensions install", "PATH is required")
+            value = await client.install_extension(Path(target), enable=bool(namespace.enable))
+        elif action in {"enable", "disable"}:
+            if target is None:
+                raise ConfigError(f"extensions {action}", "TARGET is required")
+            value = await client.set_extension_enabled(target, action == "enable")
+        elif action == "trust":
+            trust_target = (
+                workspace if target is None else Path(target).expanduser().resolve()  # noqa: ASYNC240
+            )
+            value = await client.trust_extension_workspace(
+                trust_target, not bool(namespace.untrust)
+            )
+        else:
+            value = await client.reload_extensions()
+        if namespace.json_output:
+            from dataclasses import asdict, is_dataclass
+
+            payload = (
+                [asdict(item) for item in value]
+                if isinstance(value, tuple)
+                else asdict(value)
+                if is_dataclass(value)
+                else value
+            )
+            print(json.dumps(payload, default=str, sort_keys=True))
+        else:
+            if isinstance(value, tuple):
+                for item in value:
+                    print(getattr(item, "capability_id", str(item)))
+            else:
+                print(value)
+    return 0
+
+
+def run(argv: Sequence[str] | None = None) -> int:
+    arguments = tuple(sys.argv[1:] if argv is None else argv)
+    if arguments and arguments[0] == "extensions":
+        try:
+            return asyncio.run(_run_extensions(arguments[1:]))
+        except ConfigError as exc:
+            print(f"windcode: {exc}", file=sys.stderr)
+            return 2
+        except KeyError as exc:
+            print(f"windcode: {exc}", file=sys.stderr)
+            return 3
+        except ValueError as exc:
+            print(f"windcode: {exc}", file=sys.stderr)
+            return 4
+        except OSError as exc:
+            print(f"windcode: {exc}", file=sys.stderr)
+            return 5
+    try:
+        options = parse_options(arguments)
+        if not options.workspace.is_dir():
+            raise ConfigError(options.workspace, "workspace is not a directory")
+        config = resolve_config(options)
+    except ConfigError as exc:
+        print(f"windcode: {exc}", file=sys.stderr)
+        return 2
+
+    from windcode.tui import WindcodeApp
+
+    app = WindcodeApp(
+        config,
+        workspace=options.workspace,
+        model=options.model,
+        session_id=options.resume_session,
+        permission_mode=(
+            options.permission_mode.value if options.permission_mode is not None else None
+        ),
+        config_file=options.config_file,
+    )
+    app.run()
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    raise SystemExit(run(argv))

windcode/config/__init__.py

@@ -0,0 +1,41 @@
+from windcode.config.loader import ConfigError, load_config
+from windcode.config.models import (
+    HARD_MAX_CONCURRENT_SUBAGENTS,
+    HARD_MAX_SUBAGENT_TASKS,
+    AppConfig,
+    BudgetConfig,
+    ContextConfig,
+    DelegationMode,
+    MemoryConfig,
+    PermissionConfig,
+    PermissionMode,
+    ProviderConfig,
+    ProviderProtocol,
+    SandboxConfig,
+    StorageConfig,
+    SubagentConfig,
+    TraceConfig,
+)
+from windcode.config.writer import save_memory_config, save_model_config
+
+__all__ = [
+    "HARD_MAX_CONCURRENT_SUBAGENTS",
+    "HARD_MAX_SUBAGENT_TASKS",
+    "AppConfig",
+    "BudgetConfig",
+    "ConfigError",
+    "ContextConfig",
+    "DelegationMode",
+    "MemoryConfig",
+    "PermissionConfig",
+    "PermissionMode",
+    "ProviderConfig",
+    "ProviderProtocol",
+    "SandboxConfig",
+    "StorageConfig",
+    "SubagentConfig",
+    "TraceConfig",
+    "load_config",
+    "save_memory_config",
+    "save_model_config",
+]

windcode/config/loader.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import copy
+import tomllib
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, cast
+
+from platformdirs import user_config_path
+from pydantic import ValidationError
+
+from windcode.config.models import AppConfig
+
+
+class ConfigError(ValueError):
+    def __init__(self, source: Path | str, message: str) -> None:
+        self.source = source
+        super().__init__(f"{source}: {message}")
+
+
+def _deep_merge(base: dict[str, Any], overlay: Mapping[str, Any]) -> dict[str, Any]:
+    merged = copy.deepcopy(base)
+    for key, value in overlay.items():
+        previous = merged.get(key)
+        if isinstance(previous, dict) and isinstance(value, Mapping):
+            merged[key] = _deep_merge(
+                cast(dict[str, Any], previous), cast(Mapping[str, Any], value)
+            )
+        else:
+            merged[key] = copy.deepcopy(value)
+    return merged
+
+
+def _read_toml(path: Path, *, required: bool) -> dict[str, Any]:
+    if not path.exists():
+        if required:
+            raise ConfigError(path, "configuration file does not exist")
+        return {}
+    try:
+        with path.open("rb") as stream:
+            return tomllib.load(stream)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise ConfigError(path, str(exc)) from exc
+
+
+def load_config(
+    workspace: Path,
+    *,
+    user_file: Path | None = None,
+    project_file: Path | None = None,
+    explicit_file: Path | None = None,
+    overrides: Mapping[str, Any] | None = None,
+) -> AppConfig:
+    workspace = workspace.expanduser().resolve()
+    default_user = user_config_path("windcode") / "config.toml"
+    default_project = workspace / ".windcode" / "config.toml"
+    layers: list[tuple[Path | str, dict[str, Any]]] = [
+        (
+            user_file or default_user,
+            _read_toml(user_file or default_user, required=user_file is not None),
+        ),
+        (
+            project_file or default_project,
+            _read_toml(project_file or default_project, required=project_file is not None),
+        ),
+    ]
+    if explicit_file is not None:
+        layers.append((explicit_file, _read_toml(explicit_file, required=True)))
+    if overrides is not None:
+        layers.append(("explicit overrides", dict(overrides)))
+
+    merged: dict[str, Any] = {}
+    project_mcp_servers: set[str] = set()
+    disabled_aliases: set[str] = set()
+    last_source: Path | str = "built-in defaults"
+    for layer_index, (source, layer) in enumerate(layers):
+        if layer:
+            if layer_index == 1:
+                raw_extensions = layer.get("extensions")
+                if isinstance(raw_extensions, Mapping):
+                    extension_values = cast(Mapping[object, object], raw_extensions)
+                    raw_mcp = extension_values.get("mcp_servers")
+                    if isinstance(raw_mcp, Mapping):
+                        mcp_values = cast(Mapping[object, object], raw_mcp)
+                        project_mcp_servers.update(str(server_id) for server_id in mcp_values)
+            raw_disabled = layer.get("disabled_providers", [])
+            raw_enabled = layer.get("enabled_providers", [])
+            if not isinstance(raw_disabled, list) or not isinstance(raw_enabled, list):
+                raise ConfigError(source, "provider enable/disable lists must be arrays")
+            disabled_aliases.update(str(alias) for alias in cast(list[object], raw_disabled))
+            disabled_aliases.difference_update(
+                str(alias) for alias in cast(list[object], raw_enabled)
+            )
+            merged = _deep_merge(merged, layer)
+            last_source = source
+    merged.pop("disabled_providers", None)
+    merged.pop("enabled_providers", None)
+    if project_mcp_servers:
+        raw_extensions = merged.setdefault("extensions", {})
+        if isinstance(raw_extensions, dict):
+            raw_extensions["project_mcp_servers"] = sorted(project_mcp_servers)
+    if disabled_aliases and isinstance(merged.get("providers"), dict):
+        providers = cast(dict[str, Any], merged["providers"])
+        for alias in disabled_aliases:
+            providers.pop(alias, None)
+        if merged.get("primary_provider") in disabled_aliases:
+            merged.pop("primary_provider", None)
+        fallback = merged.get("fallback_chain")
+        if isinstance(fallback, list):
+            fallback_values = cast(list[object], fallback)
+            merged["fallback_chain"] = [
+                alias for alias in fallback_values if str(alias) not in disabled_aliases
+            ]
+    try:
+        return AppConfig.model_validate(merged)
+    except ValidationError as exc:
+        raise ConfigError(last_source, str(exc)) from exc

windcode/config/models.py

@@ -0,0 +1,203 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Annotated, Literal, Self
+
+from pydantic import AliasChoices, BaseModel, ConfigDict, Field, model_validator
+
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class ProviderProtocol(StrEnum):
+    ANTHROPIC_MESSAGES = "anthropic_messages"
+    OPENAI_RESPONSES = "openai_responses"
+    OPENAI_COMPATIBLE = "openai_compatible"
+
+
+class ProviderConfig(StrictModel):
+    protocol: ProviderProtocol
+    model: str = Field(min_length=1)
+    provider_id: str | None = Field(default=None, min_length=1, pattern=r"^[a-z0-9][a-z0-9_-]*$")
+    api_key_env: str | None = Field(default=None, min_length=1, pattern=r"^[A-Za-z_][A-Za-z0-9_]*$")
+    credential_id: str | None = Field(
+        default=None, min_length=1, pattern=r"^[A-Za-z0-9][A-Za-z0-9_.-]*$"
+    )
+    base_url: str | None = None
+
+    @model_validator(mode="after")
+    def validate_credentials(self) -> Self:
+        if self.api_key_env is None and self.credential_id is None:
+            raise ValueError("provider requires api_key_env or credential_id")
+        return self
+
+
+class BudgetConfig(StrictModel):
+    max_model_steps: int = Field(default=40, ge=1)
+    max_tool_calls: int = Field(default=100, ge=1)
+    max_runtime_seconds: float = Field(default=1800.0, gt=0)
+    shell_timeout_seconds: float = Field(default=120.0, gt=0)
+
+
+HARD_MAX_SUBAGENT_TASKS = 16
+HARD_MAX_CONCURRENT_SUBAGENTS = 8
+
+
+class DelegationMode(StrEnum):
+    EXPLICIT = "explicit"
+    PROACTIVE = "proactive"
+
+
+class SubagentConfig(StrictModel):
+    mode: DelegationMode = DelegationMode.EXPLICIT
+    max_tasks: int = Field(default=8, ge=1, le=HARD_MAX_SUBAGENT_TASKS)
+    max_concurrent: int = Field(default=4, ge=1, le=HARD_MAX_CONCURRENT_SUBAGENTS)
+    max_model_steps: int = Field(default=20, ge=1)
+    max_tool_calls: int = Field(default=50, ge=1)
+    max_runtime_seconds: float = Field(default=900.0, gt=0)
+    max_total_model_steps: int = Field(default=80, ge=1)
+    max_total_tool_calls: int = Field(default=200, ge=1)
+
+    @model_validator(mode="after")
+    def validate_aggregate_limits(self) -> Self:
+        if self.max_concurrent > self.max_tasks:
+            raise ValueError("max_concurrent cannot exceed max_tasks")
+        if self.max_total_model_steps < self.max_model_steps:
+            raise ValueError("max_total_model_steps cannot be below max_model_steps")
+        if self.max_total_tool_calls < self.max_tool_calls:
+            raise ValueError("max_total_tool_calls cannot be below max_tool_calls")
+        return self
+
+
+class PermissionMode(StrEnum):
+    PLAN = "plan"
+    DEFAULT = "default"
+    ACCEPT_EDITS = "accept_edits"
+    FULL_ACCESS = "full_access"
+
+
+class PermissionConfig(StrictModel):
+    mode: PermissionMode = PermissionMode.DEFAULT
+
+
+class SandboxConfig(StrictModel):
+    enabled: bool = True
+    network_enabled: bool = False
+
+
+class ContextConfig(StrictModel):
+    window_tokens: int = Field(default=128_000, ge=1_024)
+    compaction_threshold: float = Field(default=0.8, gt=0.0, lt=1.0)
+    preserve_recent_turns: int = Field(default=8, ge=1)
+    max_tool_result_chars: int = Field(default=20_000, ge=1_000)
+
+
+class TraceConfig(StrictModel):
+    enabled: bool = True
+    include_tool_arguments: bool = False
+    include_transient_events: bool = False
+    retention_days: int = Field(default=14, ge=1, le=3_650)
+    max_total_mb: int = Field(default=100, ge=1, le=100_000)
+
+
+class StorageConfig(StrictModel):
+    project_state_root: str | None = None
+    user_storage_root: str | None = None
+
+
+class MemoryConfig(StrictModel):
+    enabled: bool = True
+    extraction_enabled: bool = True
+    recall_limit: int = Field(default=5, ge=1, le=20)
+    recall_max_chars: int = Field(default=12_000, ge=1_000, le=100_000)
+    baseline_max_records: int = Field(default=30, ge=1, le=200)
+    baseline_max_chars: int = Field(default=6_000, ge=1_000, le=100_000)
+    extraction_max_chars: int = Field(default=20_000, ge=1_000, le=200_000)
+    extraction_max_output_tokens: int = Field(default=600, ge=128, le=4_096)
+    candidate_retention_days: int = Field(default=90, ge=1, le=3_650)
+    stale_after_days: int = Field(default=30, ge=1, le=3_650)
+    user_profile_enabled: bool = True
+    project_knowledge_enabled: bool = True
+    experience_enabled: bool = True
+    sop_enabled: bool = True
+    reference_enabled: bool = True
+
+
+class EnvironmentReference(StrictModel):
+    env: str = Field(min_length=1, pattern=r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+class CredentialReference(StrictModel):
+    credential: str = Field(min_length=1, pattern=r"^[A-Za-z0-9][A-Za-z0-9_.-]*$")
+
+
+SecretReference = Annotated[
+    EnvironmentReference | CredentialReference, Field(union_mode="left_to_right")
+]
+
+
+class McpStdioConfig(StrictModel):
+    transport: Literal["stdio"] = "stdio"
+    enabled: bool = Field(default=True, validation_alias=AliasChoices("enable", "enabled"))
+    command: str = Field(min_length=1)
+    args: tuple[str, ...] = ()
+    cwd: str | None = Field(default=None, min_length=1)
+    env: dict[str, SecretReference] = Field(default_factory=dict[str, SecretReference])
+    required: bool = False
+
+
+class McpHttpConfig(StrictModel):
+    transport: Literal["streamable_http"]
+    enabled: bool = Field(default=True, validation_alias=AliasChoices("enable", "enabled"))
+    url: str = Field(min_length=1, pattern=r"^https?://")
+    headers: dict[str, SecretReference] = Field(default_factory=dict[str, SecretReference])
+    required: bool = False
+
+
+McpServerConfig = Annotated[McpStdioConfig | McpHttpConfig, Field(union_mode="left_to_right")]
+
+
+class ExtensionConfig(StrictModel):
+    enabled: bool = False
+    direct_tool_limit: int = Field(default=24, ge=0, le=256)
+    connect_timeout_seconds: float = Field(default=10.0, gt=0, le=300)
+    call_timeout_seconds: float = Field(default=60.0, gt=0, le=3600)
+    hook_timeout_seconds: float = Field(default=10.0, gt=0, le=300)
+    max_metadata_bytes: int = Field(default=65_536, ge=1_024, le=1_048_576)
+    max_content_bytes: int = Field(default=1_048_576, ge=1_024, le=16_777_216)
+    max_scan_depth: int = Field(default=8, ge=1, le=32)
+    max_scan_entries: int = Field(default=10_000, ge=1, le=100_000)
+    skill_roots: tuple[str, ...] = ()
+    mcp_servers: dict[str, McpServerConfig] = Field(default_factory=dict[str, McpServerConfig])
+    project_mcp_servers: frozenset[str] = Field(default_factory=frozenset, exclude=True)
+
+
+class AppConfig(StrictModel):
+    providers: dict[str, ProviderConfig] = Field(default_factory=dict[str, ProviderConfig])
+    primary_provider: str | None = None
+    fallback_chain: tuple[str, ...] = ()
+    budgets: BudgetConfig = Field(default_factory=BudgetConfig)
+    permission: PermissionConfig = Field(default_factory=PermissionConfig)
+    sandbox: SandboxConfig = Field(default_factory=SandboxConfig)
+    context: ContextConfig = Field(default_factory=ContextConfig)
+    trace: TraceConfig = Field(default_factory=TraceConfig)
+    storage: StorageConfig = Field(default_factory=StorageConfig)
+    memory: MemoryConfig = Field(default_factory=MemoryConfig)
+    subagents: SubagentConfig = Field(default_factory=SubagentConfig)
+    extensions: ExtensionConfig = Field(default_factory=ExtensionConfig)
+
+    @model_validator(mode="after")
+    def validate_provider_chain(self) -> Self:
+        if self.primary_provider is None:
+            if self.fallback_chain:
+                raise ValueError("fallback_chain requires primary_provider")
+            return self
+
+        chain = (self.primary_provider, *self.fallback_chain)
+        missing = [name for name in chain if name not in self.providers]
+        if missing:
+            raise ValueError(f"provider chain references unknown providers: {', '.join(missing)}")
+        if len(set(chain)) != len(chain):
+            raise ValueError("provider chain contains a duplicate or cycle")
+        return self