agent-apprenticeship 0.1.0

package/src/agent_apprenticeship_trace/config.py

@@ -0,0 +1,609 @@
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+from pathlib import Path
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from .env import load_local_env
+from .command_discovery import resolve_command, resolve_agent_command, gui_app_hint
+from .io import read_json, write_json
+from .recipes import MODEL_PROVIDER_RECIPES, WORKER_AGENT_RECIPES
+
+
+MentorMode = Literal["model_assisted", "expert_led", "hybrid"]
+SensitiveInfoMasking = Literal["standard", "no_masking"]
+EcosystemAutoShare = Literal["manual", "ask", "automatic"]
+EvaluationMode = Literal["model-assisted", "expert-led", "hybrid"]
+DataSharingLevel = Literal["standard", "full-context"]
+
+MENTOR_MODES: tuple[str, ...] = ("model_assisted", "expert_led", "hybrid")
+SENSITIVE_INFO_MASKING_LEVELS: tuple[str, ...] = ("standard", "no_masking")
+ECOSYSTEM_AUTO_SHARE_MODES: tuple[str, ...] = ("manual", "ask", "automatic")
+EVALUATION_MODES: tuple[str, ...] = ("model-assisted", "expert-led", "hybrid")
+DATA_SHARING_LEVELS: tuple[str, ...] = ("standard", "full-context")
+DEFAULT_APP_HOME = Path("~/.agent-apprenticeship").expanduser()
+DEFAULT_PUBLIC_ECOSYSTEM_REPO = "Forsy-AI/agent-apprenticeship"
+DEFAULT_PUBLIC_ECOSYSTEM_URL = f"https://github.com/{DEFAULT_PUBLIC_ECOSYSTEM_REPO}"
+
+
+def normalize_mentor_mode(value: str | None, default: str = "model_assisted") -> str:
+    if value is None or str(value).strip() == "":
+        return default
+    normalized = str(value).strip().lower().replace("-", "_").replace(" ", "_")
+    aliases = {
+        "model": "model_assisted",
+        "model_assisted": "model_assisted",
+        "model_assisted_automated": "model_assisted",
+        "automated": "model_assisted",
+        "expert": "expert_led",
+        "expert_led": "expert_led",
+        "expert_led_manual": "expert_led",
+        "manual": "expert_led",
+        "hybrid": "hybrid",
+    }
+    normalized = aliases.get(normalized, normalized)
+    if normalized not in MENTOR_MODES:
+        raise ValueError(f"Unsupported Mentor Mode: {value}")
+    return normalized
+
+
+def mentor_mode_to_evaluation_mode(value: str | None) -> str:
+    normalized = normalize_mentor_mode(value)
+    return {
+        "model_assisted": "model-assisted",
+        "expert_led": "expert-led",
+        "hybrid": "hybrid",
+    }[normalized]
+
+
+def evaluation_mode_to_mentor_mode(value: str | None) -> str:
+    return normalize_mentor_mode(value)
+
+
+def mentor_mode_display(value: str | None) -> str:
+    normalized = normalize_mentor_mode(value)
+    return {
+        "model_assisted": "model-assisted",
+        "expert_led": "expert-led",
+        "hybrid": "hybrid",
+    }[normalized]
+
+
+def normalize_sensitive_info_masking(value: str | None, default: str = "standard") -> str:
+    if value is None or str(value).strip() == "":
+        return default
+    normalized = str(value).strip().lower().replace("-", "_").replace(" ", "_")
+    aliases = {
+        "standard": "standard",
+        "mask": "standard",
+        "masked": "standard",
+        "full": "no_masking",
+        "full_context": "no_masking",
+        "no_masking": "no_masking",
+        "none": "no_masking",
+        "off": "no_masking",
+    }
+    normalized = aliases.get(normalized, normalized)
+    if normalized not in SENSITIVE_INFO_MASKING_LEVELS:
+        raise ValueError(f"Unsupported Sensitive Info Masking setting: {value}")
+    return normalized
+
+
+def sensitive_info_masking_to_data_sharing(value: str | None) -> str:
+    return "standard" if normalize_sensitive_info_masking(value) == "standard" else "full-context"
+
+
+def data_sharing_to_sensitive_info_masking(value: str | None) -> str:
+    return normalize_sensitive_info_masking(value)
+
+
+def normalize_ecosystem_auto_share(value: str | None, default: str = "manual") -> str:
+    if value is None or str(value).strip() == "":
+        return default
+    normalized = str(value).strip().lower().replace("-", "_").replace(" ", "_")
+    aliases = {
+        "manual": "manual",
+        "off": "manual",
+        "none": "manual",
+        "ask": "ask",
+        "prompt": "ask",
+        "ask_before_sharing": "ask",
+        "share_automatically": "automatic",
+        "automatic": "automatic",
+        "auto": "automatic",
+        "on": "automatic",
+    }
+    normalized = aliases.get(normalized, normalized)
+    if normalized not in ECOSYSTEM_AUTO_SHARE_MODES:
+        raise ValueError(f"Unsupported Ecosystem Auto-Share setting: {value}")
+    return normalized
+
+
+def ecosystem_auto_share_display(value: str | None) -> str:
+    normalized = normalize_ecosystem_auto_share(value)
+    return {
+        "manual": "Manual",
+        "ask": "Ask before sharing",
+        "automatic": "Share automatically",
+    }[normalized]
+
+
+class Settings(BaseModel):
+    # Public product settings.
+    app_home: Path = DEFAULT_APP_HOME
+    worker_agent: str = "codex"
+    worker_agent_command: str | None = None
+    worker_agent_model: str | None = None
+    worker_agent_extra_args: list[str] = Field(default_factory=list)
+    model_provider: str | None = None
+    model_provider_api_key_env: str | None = None
+    model_provider_model: str | None = None
+    mentor_mode: MentorMode = "model_assisted"
+    sensitive_info_masking: SensitiveInfoMasking = "standard"
+    evaluation_mode: EvaluationMode = "model-assisted"
+    data_sharing_level: DataSharingLevel = "standard"
+    max_improvement_loops: int = 5
+    custom_worker_display_name: str | None = None
+    custom_worker_command_template: str | None = None
+    custom_worker_can_write_files: bool = True
+    apprentice_agent_readiness_status: str | None = None
+    apprentice_agent_readiness_reason: str | None = None
+    mentor_model_provider_readiness_status: str | None = None
+    mentor_model_provider_readiness_reason: str | None = None
+    ecosystem_repo: str | None = DEFAULT_PUBLIC_ECOSYSTEM_REPO
+    ecosystem_repo_path: Path | None = None
+    ecosystem_auto_share: EcosystemAutoShare = "manual"
+
+    # Compatibility settings used by the existing internal pipeline.
+    openai_api_key: str | None = None
+    openai_model: str = "gpt-5-mini"
+    worker_runner: str = "codex"
+    reviser_runner: str = "codex"
+    allow_deterministic_fallback: bool = True
+    task_timeout_seconds: int = 900
+    max_iterations: int = 3
+    codex_sandbox: str = "workspace-write"
+    llm_evaluator_enabled: bool = True
+    llm_grader_enabled: bool = True
+    llm_verifier_enabled: bool = True
+    llm_task_intake_model: str = "gpt-5-mini"
+    llm_rubric_model: str = "gpt-5-mini"
+    llm_evaluator_model: str = "gpt-5-mini"
+    llm_grader_model: str = "gpt-5-mini"
+    llm_verifier_model: str = "gpt-5-mini"
+    llm_judge_count: int = 1
+    llm_fail_closed: bool = False
+    allow_deterministic_eval_fallback: bool = True
+    rubric_mode: str = "hybrid"
+    llm_task_intake_enabled: bool = True
+    llm_rubric_generation_enabled: bool = True
+
+
+def app_home_from_env() -> Path:
+    return Path(os.getenv("AA_HOME") or DEFAULT_APP_HOME).expanduser()
+
+
+def settings_path(app_home: Path | None = None) -> Path:
+    return (app_home or app_home_from_env()) / "settings.json"
+
+
+def _bool_env(name: str, default: bool) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    return value.lower() == "true"
+
+
+def _int_env(name: str, default: int) -> int:
+    value = os.getenv(name)
+    if value is None or value == "":
+        return default
+    return int(value)
+
+
+def _stored_settings() -> dict[str, Any]:
+    # Test suites and CI often set AA_DISABLE_LOCAL_ENV to avoid reading user
+    # machine state. Honor that unless AA_HOME intentionally points at a test dir.
+    if os.getenv("AA_DISABLE_LOCAL_ENV") == "1" and not os.getenv("AA_HOME"):
+        return {}
+    path = settings_path()
+    if not path.exists():
+        return {}
+    data = read_json(path)
+    return data if isinstance(data, dict) else {}
+
+
+def default_settings(app_home: Path | None = None) -> Settings:
+    home = app_home or app_home_from_env()
+    return Settings(app_home=home, max_iterations=3)
+
+
+def get_settings(root: Path | None = None) -> Settings:
+    load_local_env(root)
+    stored = _stored_settings()
+    home = Path(os.getenv("AA_HOME") or stored.get("app_home") or DEFAULT_APP_HOME).expanduser()
+    load_local_env(home)
+
+    worker_agent = os.getenv("AA_WORKER_AGENT") or os.getenv("AA_TRACE_WORKER_AGENT") or stored.get("worker_agent") or "codex"
+    provider = os.getenv("AA_MODEL_PROVIDER") or stored.get("model_provider")
+    provider_recipe = MODEL_PROVIDER_RECIPES.get(str(provider)) if provider else None
+    provider_key_env = (
+        os.getenv("AA_MODEL_PROVIDER_API_KEY_ENV")
+        or stored.get("model_provider_api_key_env")
+        or (provider_recipe.api_key_env_var if provider_recipe else None)
+    )
+    provider_model = (
+        os.getenv("AA_MODEL_PROVIDER_MODEL")
+        or stored.get("model_provider_model")
+        or (provider_recipe.default_model if provider_recipe else None)
+    )
+
+    loops = _int_env(
+        "AA_MAX_IMPROVEMENT_LOOPS",
+        int(stored.get("max_improvement_loops") or stored.get("max_iterations") or 5),
+    )
+    legacy_iterations = _int_env("AA_MAX_ITERATIONS", int(stored.get("max_iterations") or 3))
+    openai_model = os.getenv("AA_OPENAI_MODEL", stored.get("openai_model") or "gpt-5-mini")
+    mentor_mode = normalize_mentor_mode(
+        os.getenv("AA_MENTOR_MODE")
+        or stored.get("mentor_mode")
+        or os.getenv("AA_EVALUATION_MODE")
+        or stored.get("evaluation_mode")
+        or "model_assisted"
+    )
+    sensitive_info_masking = normalize_sensitive_info_masking(
+        os.getenv("AA_SENSITIVE_INFO_MASKING")
+        or stored.get("sensitive_info_masking")
+        or os.getenv("AA_DATA_SHARING_LEVEL")
+        or stored.get("data_sharing_level")
+        or "standard"
+    )
+
+    return Settings(
+        app_home=home,
+        worker_agent=worker_agent,
+        worker_agent_command=os.getenv("AA_WORKER_AGENT_COMMAND") or stored.get("worker_agent_command"),
+        worker_agent_model=os.getenv("AA_WORKER_AGENT_MODEL") or stored.get("worker_agent_model"),
+        worker_agent_extra_args=list(stored.get("worker_agent_extra_args") or []),
+        model_provider=provider,
+        model_provider_api_key_env=provider_key_env,
+        model_provider_model=provider_model,
+        mentor_mode=mentor_mode,
+        sensitive_info_masking=sensitive_info_masking,
+        evaluation_mode=mentor_mode_to_evaluation_mode(mentor_mode),
+        data_sharing_level=sensitive_info_masking_to_data_sharing(sensitive_info_masking),
+        max_improvement_loops=loops,
+        custom_worker_display_name=os.getenv("AA_CUSTOM_WORKER_DISPLAY_NAME") or stored.get("custom_worker_display_name"),
+        custom_worker_command_template=os.getenv("AA_CUSTOM_WORKER_COMMAND_TEMPLATE") or stored.get("custom_worker_command_template"),
+        custom_worker_can_write_files=_bool_env("AA_CUSTOM_WORKER_CAN_WRITE_FILES", bool(stored.get("custom_worker_can_write_files", True))),
+        apprentice_agent_readiness_status=stored.get("apprentice_agent_readiness_status"),
+        apprentice_agent_readiness_reason=stored.get("apprentice_agent_readiness_reason"),
+        mentor_model_provider_readiness_status=stored.get("mentor_model_provider_readiness_status"),
+        mentor_model_provider_readiness_reason=stored.get("mentor_model_provider_readiness_reason"),
+        ecosystem_repo=os.getenv("AA_ECOSYSTEM_REPO") or stored.get("ecosystem_repo") or DEFAULT_PUBLIC_ECOSYSTEM_REPO,
+        ecosystem_repo_path=Path(os.getenv("AA_ECOSYSTEM_REPO_PATH") or stored.get("ecosystem_repo_path")).expanduser()
+        if (os.getenv("AA_ECOSYSTEM_REPO_PATH") or stored.get("ecosystem_repo_path"))
+        else None,
+        ecosystem_auto_share=normalize_ecosystem_auto_share(
+            os.getenv("AA_ECOSYSTEM_AUTO_SHARE") or stored.get("ecosystem_auto_share") or "manual"
+        ),
+        openai_api_key=os.getenv("OPENAI_API_KEY"),
+        openai_model=openai_model,
+        worker_runner=os.getenv("AA_WORKER_RUNNER", os.getenv("AA_TRACE_WORKER_RUNNER", stored.get("worker_runner") or worker_agent)),
+        reviser_runner=os.getenv("AA_REVISER_RUNNER", os.getenv("AA_TRACE_REVISER_RUNNER", stored.get("reviser_runner") or worker_agent)),
+        allow_deterministic_fallback=_bool_env("AA_ALLOW_DETERMINISTIC_FALLBACK", bool(stored.get("allow_deterministic_fallback", True))),
+        task_timeout_seconds=_int_env("AA_TASK_TIMEOUT_SECONDS", int(stored.get("task_timeout_seconds") or 900)),
+        max_iterations=legacy_iterations,
+        codex_sandbox=os.getenv("AA_CODEX_SANDBOX", stored.get("codex_sandbox") or "workspace-write"),
+        llm_evaluator_enabled=_bool_env("AA_LLM_EVALUATOR_ENABLED", bool(stored.get("llm_evaluator_enabled", True))),
+        llm_grader_enabled=_bool_env("AA_LLM_GRADER_ENABLED", bool(stored.get("llm_grader_enabled", True))),
+        llm_verifier_enabled=_bool_env("AA_LLM_VERIFIER_ENABLED", bool(stored.get("llm_verifier_enabled", True))),
+        llm_task_intake_model=os.getenv("AA_LLM_TASK_INTAKE_MODEL", stored.get("llm_task_intake_model") or openai_model),
+        llm_rubric_model=os.getenv("AA_LLM_RUBRIC_MODEL", stored.get("llm_rubric_model") or openai_model),
+        llm_evaluator_model=os.getenv("AA_LLM_EVALUATOR_MODEL", stored.get("llm_evaluator_model") or openai_model),
+        llm_grader_model=os.getenv("AA_LLM_GRADER_MODEL", stored.get("llm_grader_model") or openai_model),
+        llm_verifier_model=os.getenv("AA_LLM_VERIFIER_MODEL", stored.get("llm_verifier_model") or openai_model),
+        llm_judge_count=_int_env("AA_LLM_JUDGE_COUNT", int(stored.get("llm_judge_count") or 1)),
+        llm_fail_closed=_bool_env("AA_LLM_FAIL_CLOSED", bool(stored.get("llm_fail_closed", False))),
+        allow_deterministic_eval_fallback=_bool_env("AA_ALLOW_DETERMINISTIC_EVAL_FALLBACK", bool(stored.get("allow_deterministic_eval_fallback", True))),
+        rubric_mode=os.getenv("AA_RUBRIC_MODE", stored.get("rubric_mode") or "hybrid"),
+        llm_task_intake_enabled=_bool_env("AA_LLM_TASK_INTAKE_ENABLED", bool(stored.get("llm_task_intake_enabled", True))),
+        llm_rubric_generation_enabled=_bool_env("AA_LLM_RUBRIC_GENERATION_ENABLED", bool(stored.get("llm_rubric_generation_enabled", True))),
+    )
+
+
+def save_settings(settings: Settings) -> Path:
+    settings.app_home.mkdir(parents=True, exist_ok=True)
+    path = settings_path(settings.app_home)
+    data = settings.model_dump(mode="json")
+    data.pop("openai_api_key", None)
+    write_json(path, data)
+    return path
+
+
+def init_settings(app_home: Path | None = None, overwrite: bool = False) -> Path:
+    home = app_home or app_home_from_env()
+    home.mkdir(parents=True, exist_ok=True)
+    (home / "runs").mkdir(exist_ok=True)
+    path = settings_path(home)
+    if overwrite or not path.exists():
+        save_settings(default_settings(home))
+    return path
+
+
+def update_settings(**updates: Any) -> Settings:
+    settings = get_settings()
+    data = settings.model_dump()
+    clean_updates = {k: v for k, v in updates.items() if v is not None}
+    if "evaluation_mode" in clean_updates and "mentor_mode" not in clean_updates:
+        clean_updates["mentor_mode"] = evaluation_mode_to_mentor_mode(clean_updates["evaluation_mode"])
+    if "mentor_mode" in clean_updates:
+        clean_updates["mentor_mode"] = normalize_mentor_mode(clean_updates["mentor_mode"])
+        clean_updates["evaluation_mode"] = mentor_mode_to_evaluation_mode(clean_updates["mentor_mode"])
+    if "data_sharing_level" in clean_updates and "sensitive_info_masking" not in clean_updates:
+        clean_updates["sensitive_info_masking"] = data_sharing_to_sensitive_info_masking(clean_updates["data_sharing_level"])
+    if "sensitive_info_masking" in clean_updates:
+        clean_updates["sensitive_info_masking"] = normalize_sensitive_info_masking(clean_updates["sensitive_info_masking"])
+        clean_updates["data_sharing_level"] = sensitive_info_masking_to_data_sharing(clean_updates["sensitive_info_masking"])
+    if "ecosystem_auto_share" in clean_updates:
+        clean_updates["ecosystem_auto_share"] = normalize_ecosystem_auto_share(clean_updates["ecosystem_auto_share"])
+    if "worker_agent" in clean_updates and "worker_runner" not in clean_updates:
+        clean_updates["worker_runner"] = clean_updates["worker_agent"]
+        clean_updates["reviser_runner"] = clean_updates["worker_agent"]
+    data.update(clean_updates)
+    updated = Settings.model_validate(data)
+    if updated.worker_agent not in WORKER_AGENT_RECIPES:
+        raise ValueError(f"Unsupported Apprentice Agent: {updated.worker_agent}")
+    if updated.model_provider is not None and updated.model_provider not in MODEL_PROVIDER_RECIPES:
+        raise ValueError(f"Unsupported Mentor Model Provider: {updated.model_provider}")
+    if updated.evaluation_mode not in EVALUATION_MODES:
+        raise ValueError(f"Unsupported Mentor Mode: {updated.mentor_mode}")
+    if updated.data_sharing_level not in DATA_SHARING_LEVELS:
+        raise ValueError(f"Unsupported Sensitive Info Masking setting: {updated.sensitive_info_masking}")
+    if updated.mentor_mode not in MENTOR_MODES:
+        raise ValueError(f"Unsupported mentor mode: {updated.mentor_mode}")
+    if updated.sensitive_info_masking not in SENSITIVE_INFO_MASKING_LEVELS:
+        raise ValueError(f"Unsupported sensitive info masking setting: {updated.sensitive_info_masking}")
+    if updated.ecosystem_auto_share not in ECOSYSTEM_AUTO_SHARE_MODES:
+        raise ValueError(f"Unsupported Ecosystem Auto-Share setting: {updated.ecosystem_auto_share}")
+    if updated.worker_agent == "custom":
+        template = updated.custom_worker_command_template or ""
+        missing = [token for token in ("{workspace}", "{prompt_file}") if token not in template]
+        if missing:
+            raise ValueError(
+                "custom Apprentice Agent command template must include placeholders: " + ", ".join(missing)
+            )
+    if updated.max_improvement_loops < 1:
+        raise ValueError("max_improvement_loops must be at least 1")
+    updated.max_iterations = updated.max_improvement_loops
+    save_settings(updated)
+    return updated
+
+
+def model_provider_ready(settings: Settings | None = None) -> bool:
+    s = settings or get_settings()
+    if s.mentor_mode == "expert_led":
+        return True
+    return bool(mentor_model_provider_readiness(s).get("ready"))
+
+
+def configured_model_provider_ready(settings: Settings | None = None) -> bool:
+    s = settings or get_settings()
+    return bool(mentor_model_provider_readiness(s).get("ready"))
+
+
+def model_provider_display_name(settings: Settings | None = None) -> str:
+    s = settings or get_settings()
+    provider = MODEL_PROVIDER_RECIPES.get(s.model_provider or "")
+    return provider.display_name if provider else "Not configured"
+
+
+def mentor_model_provider_readiness(settings: Settings | None = None) -> dict[str, Any]:
+    s = settings or get_settings()
+    if not s.model_provider:
+        return {
+            "status": "not_ready",
+            "ready": False,
+            "reason": None,
+            "provider": None,
+            "provider_display": "Not configured",
+            "model": None,
+            "api_key_env_var": None,
+            "api_key_visible": False,
+        }
+    provider = MODEL_PROVIDER_RECIPES.get(s.model_provider)
+    env_var = s.model_provider_api_key_env or (provider.api_key_env_var if provider else None)
+    key_visible = bool(env_var and os.getenv(env_var))
+    if s.model_provider == "google" and not key_visible and os.getenv("GOOGLE_API_KEY"):
+        key_visible = True
+        env_var = "GOOGLE_API_KEY"
+    if not env_var:
+        status = "missing_api_key"
+        reason = "No API key environment variable is configured."
+    elif not key_visible:
+        status = "missing_api_key"
+        reason = f"{env_var} is not visible."
+    else:
+        status = s.mentor_model_provider_readiness_status or "untested"
+        reason = s.mentor_model_provider_readiness_reason
+        if status in {None, "missing_api_key"}:
+            status = "untested"
+    return {
+        "status": status,
+        "ready": status == "ready",
+        "reason": reason,
+        "provider": s.model_provider,
+        "provider_display": provider.display_name if provider else s.model_provider,
+        "model": s.model_provider_model or (provider.default_model if provider else None),
+        "api_key_env_var": env_var,
+        "api_key_visible": key_visible,
+    }
+
+
+def _configured_apprentice_command(settings: Settings) -> str | None:
+    if settings.worker_agent == "custom":
+        template = settings.custom_worker_command_template or ""
+        if template:
+            try:
+                parts = shlex.split(template)
+            except ValueError:
+                parts = template.split()
+            return parts[0] if parts else settings.worker_agent_command
+        return settings.worker_agent_command
+    recipe = WORKER_AGENT_RECIPES.get(settings.worker_agent)
+    return settings.worker_agent_command or (recipe.command_name if recipe else settings.worker_agent)
+
+
+def apprentice_agent_display_name(settings: Settings | None = None) -> str:
+    s = settings or get_settings()
+    recipe = WORKER_AGENT_RECIPES.get(s.worker_agent)
+    if s.worker_agent == "custom" and s.custom_worker_display_name:
+        return s.custom_worker_display_name
+    return recipe.display_name if recipe else s.worker_agent
+
+
+def apprentice_agent_readiness_status(settings: Settings | None = None) -> dict[str, Any]:
+    s = settings or get_settings()
+    command = _configured_apprentice_command(s)
+    if s.worker_agent == "custom":
+        template = s.custom_worker_command_template or ""
+        missing = [token for token in ("{workspace}", "{prompt_file}") if token not in template]
+        if missing:
+            return {
+                "status": "not_ready",
+                "ready": False,
+                "reason": "Custom Apprentice Agent command template is missing placeholders: " + ", ".join(missing),
+                "command": command,
+                "command_found": False,
+            }
+    if not command:
+        return {
+            "status": "not_ready",
+            "ready": False,
+            "reason": "Apprentice Agent command is not configured.",
+            "command": None,
+            "command_found": False,
+        }
+    _, resolved = resolve_agent_command(s.worker_agent, command)
+    if not resolved:
+        hint = gui_app_hint(s.worker_agent or "")
+        reason = f"Apprentice Agent command not found: {command}"
+        if hint:
+            reason = f"{reason}. {hint} Install or expose the headless CLI on PATH."
+        return {
+            "status": "missing_command",
+            "ready": False,
+            "reason": reason,
+            "command": command,
+            "command_found": False,
+            "command_resolved": None,
+        }
+    if s.apprentice_agent_readiness_status == "ready":
+        return {
+            "status": "ready",
+            "ready": True,
+            "reason": s.apprentice_agent_readiness_reason,
+            "command": command,
+            "command_found": True,
+            "command_resolved": resolved,
+        }
+    if s.apprentice_agent_readiness_status in {"auth_error", "quota_or_credit_error", "timeout", "failed", "not_ready"}:
+        return {
+            "status": s.apprentice_agent_readiness_status,
+            "ready": False,
+            "reason": s.apprentice_agent_readiness_reason,
+            "command": command,
+            "command_found": True,
+            "command_resolved": resolved,
+        }
+    return {
+        "status": "untested",
+        "ready": False,
+        "reason": "Command was found, but no readiness check has been recorded.",
+        "command": command,
+        "command_found": True,
+        "command_resolved": resolved,
+    }
+
+
+def _readiness_line(label: str, status: str | None, reason: str | None = None) -> str:
+    pretty = (status or "not_ready").replace("_", " ").title()
+    if status == "ready":
+        pretty = "Ready"
+    elif status == "not_ready":
+        pretty = "Not ready"
+    elif status == "missing_api_key":
+        pretty = "Not ready"
+    elif status == "missing_command":
+        pretty = "Not ready"
+    elif status == "untested":
+        pretty = "Untested"
+    suffix = f" - {reason}" if reason else ""
+    return f"{label}: {pretty}{suffix}"
+
+
+def public_settings(settings: Settings | None = None) -> dict[str, Any]:
+    s = settings or get_settings()
+    agent_status = apprentice_agent_readiness_status(s)
+    provider_status = mentor_model_provider_readiness(s)
+    return {
+        "apprentice_agent": apprentice_agent_display_name(s),
+        "apprentice_agent_status": agent_status["status"],
+        "apprentice_agent_status_reason": agent_status.get("reason"),
+        "mentor_model_provider": provider_status["provider_display"] if provider_status.get("provider") else None,
+        "mentor_model_provider_status": provider_status["status"],
+        "mentor_model_provider_status_reason": provider_status.get("reason"),
+        "mentor_model_provider_api_key_env": provider_status.get("api_key_env_var"),
+        "mentor_model_provider_api_key_visible": provider_status.get("api_key_visible"),
+        "mentor_mode": s.mentor_mode,
+        "sensitive_info_masking": s.sensitive_info_masking,
+        "max_improvement_loops": s.max_improvement_loops,
+        "ecosystem_repo": s.ecosystem_repo,
+        "ecosystem_repo_path": str(s.ecosystem_repo_path) if s.ecosystem_repo_path else None,
+        "ecosystem_auto_share": s.ecosystem_auto_share,
+        "app_home": str(s.app_home),
+    }
+
+
+def public_settings_text(settings: Settings | None = None) -> str:
+    s = settings or get_settings()
+    data = public_settings(s)
+    provider = data["mentor_model_provider"] or "Not configured"
+    lines = [
+        "Agent Apprenticeship Settings",
+        "",
+        f"Apprentice Agent: {data['apprentice_agent']}",
+        _readiness_line("Apprentice Agent Status", data["apprentice_agent_status"], data.get("apprentice_agent_status_reason")),
+        f"Mentor Model Provider: {provider}",
+        _readiness_line("Mentor Model Provider Status", data["mentor_model_provider_status"], data.get("mentor_model_provider_status_reason")),
+        f"Mentor Mode: {mentor_mode_display(data['mentor_mode'])}",
+        f"Sensitive Info Masking: {data['sensitive_info_masking']}",
+        f"Maximum Improvement Loops: {data['max_improvement_loops']}",
+        f"Public Ecosystem Repo: {data['ecosystem_repo'] or DEFAULT_PUBLIC_ECOSYSTEM_REPO}",
+        *([f"Public Ecosystem Repo Path: {data['ecosystem_repo_path']}"] if data.get("ecosystem_repo_path") else []),
+        f"Ecosystem Auto-Share: {ecosystem_auto_share_display(data['ecosystem_auto_share'])}",
+        f"App Home: {data['app_home']}",
+    ]
+    if s.mentor_mode in {"model_assisted", "hybrid"} and not configured_model_provider_ready(s):
+        lines.extend(
+            [
+                "",
+                "Model-assisted Mentor Mode needs a ready Mentor Model Provider.",
+                "Run: apprentice configure model",
+            ]
+        )
+    return "\n".join(lines)
+
+
+def debug_settings(settings: Settings | None = None) -> dict[str, Any]:
+    s = settings or get_settings()
+    data = s.model_dump(mode="json")
+    data["model_provider_ready"] = configured_model_provider_ready(s)
+    data["mentor_model_provider_readiness"] = mentor_model_provider_readiness(s)
+    data["apprentice_agent_readiness"] = apprentice_agent_readiness_status(s)
+    data.pop("openai_api_key", None)
+    return data

package/src/agent_apprenticeship_trace/contract_diagnostics.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .env import redact_secrets
+from .io import write_json
+
+
+EXPECTED_AGENT_CONTRACT = ["agent_trace.json", "actual_outputs.json", "artifacts/"]
+
+
+def build_contract_diagnostics(
+    attempt_dir: Path,
+    *,
+    command: list[str] | str,
+    working_directory: Path,
+    agent_display_name: str,
+    prompt: str | None = None,
+) -> dict[str, Any]:
+    command_value: list[str] | str
+    if isinstance(command, list):
+        command_value = ["<prompt>" if prompt is not None and part == prompt else redact_secrets(str(part)) for part in command]
+    else:
+        command_value = redact_secrets(command)
+    expected = {
+        "agent_trace.json": attempt_dir / "agent_trace.json",
+        "actual_outputs.json": attempt_dir / "actual_outputs.json",
+        "artifacts/": attempt_dir / "artifacts",
+    }
+    missing = [name for name, path in expected.items() if not path.exists()]
+    top_level = sorted(p.name + ("/" if p.is_dir() else "") for p in attempt_dir.iterdir()) if attempt_dir.exists() else []
+    likely_cause = (
+        f"{agent_display_name} ran but did not write the Agent Apprenticeship output contract "
+        "in the current task workspace."
+        if missing
+        else f"{agent_display_name} wrote the expected output contract."
+    )
+    if missing and any(name in {"stdout.txt", "stderr.txt", "final_message.txt"} for name in top_level):
+        likely_cause += " Inspect stdout/stderr/final_message for setup, auth, or unsupported headless-mode details."
+    diagnostics = {
+        "command_used": command_value,
+        "working_directory": str(working_directory),
+        "expected_files": EXPECTED_AGENT_CONTRACT,
+        "missing_expected_files": missing,
+        "top_level_files_found": top_level,
+        "stdout_ref": "stdout.txt",
+        "stderr_ref": "stderr.txt",
+        "final_message_ref": "final_message.txt",
+        "likely_cause": likely_cause,
+    }
+    write_json(attempt_dir / "contract_diagnostics.json", diagnostics)
+    return diagnostics
+
+
+def diagnostics_text(diagnostics: dict[str, Any]) -> str:
+    lines = [
+        "Agent Apprenticeship output-contract diagnostics",
+        f"Command used: {diagnostics.get('command_used')}",
+        f"Working directory: {diagnostics.get('working_directory')}",
+        "Expected files: " + ", ".join(diagnostics.get("expected_files") or []),
+        "Missing expected files: " + (", ".join(diagnostics.get("missing_expected_files") or []) or "none"),
+        "Top-level files found: " + (", ".join(diagnostics.get("top_level_files_found") or []) or "none"),
+        f"stdout: {diagnostics.get('stdout_ref')}",
+        f"stderr: {diagnostics.get('stderr_ref')}",
+        f"final message: {diagnostics.get('final_message_ref')}",
+        f"Likely cause: {diagnostics.get('likely_cause')}",
+    ]
+    return "\n".join(lines) + "\n"