agent-devkit 0.1.5 → 0.2.0

package/runtime/cli/aikit/acceptance.py

@@ -0,0 +1,166 @@
+"""Objective acceptance criteria contract for Agent DevKit work."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+
+ACCEPTANCE_SECTIONS: list[dict[str, Any]] = [
+    {
+        "id": "contract",
+        "name": "Contrato",
+        "questions": [
+            "Qual superficie publica sera criada, alterada ou preservada?",
+            "Quais entradas, saidas, erros e limites ficam documentados?",
+        ],
+        "required": [
+            "manifest_or_public_api",
+            "inputs_outputs",
+            "error_contract",
+        ],
+    },
+    {
+        "id": "behavior",
+        "name": "Comportamento",
+        "questions": [
+            "Qual fluxo principal deve funcionar para o usuario ou agente chamador?",
+            "Quais tarefas conhecidas devem ser deterministicamente automatizadas?",
+        ],
+        "required": [
+            "happy_path",
+            "known_failure_modes",
+            "deterministic_scope",
+        ],
+    },
+    {
+        "id": "security",
+        "name": "Seguranca",
+        "questions": [
+            "Quais permissoes, escritas externas ou dados sensiveis podem ser tocados?",
+            "Quais guardrails impedem vazamento de segredo ou acao destrutiva?",
+        ],
+        "required": [
+            "permission_policy",
+            "secret_handling",
+            "external_write_policy",
+        ],
+    },
+    {
+        "id": "compatibility",
+        "name": "Compatibilidade",
+        "questions": [
+            "Quais comandos, aliases, manifests ou hosts existentes precisam continuar funcionando?",
+            "A mudanca exige migracao ou aceita comportamento legado?",
+        ],
+        "required": [
+            "backward_compatibility",
+            "migration_notes",
+            "host_compatibility",
+        ],
+    },
+    {
+        "id": "validation",
+        "name": "Validacao",
+        "questions": [
+            "Quais testes ou comandos focados provam o comportamento novo?",
+            "Quais validacoes manuais ou de CLI precisam ser executadas?",
+        ],
+        "required": [
+            "focused_tests",
+            "cli_smoke_test",
+            "validation_evidence",
+        ],
+    },
+    {
+        "id": "out_of_scope",
+        "name": "Fora de escopo",
+        "questions": [
+            "O que foi deliberadamente deixado para outro item?",
+            "Quais riscos residuais permanecem aceitos temporariamente?",
+        ],
+        "required": [
+            "deferred_items",
+            "residual_risks",
+        ],
+    },
+]
+
+
+GLOBAL_ACCEPTANCE_CRITERIA: list[str] = [
+    "A mudanca preserva o Agent DevKit como agente principal e trata agentes internos como modulos especialistas.",
+    "A implementacao privilegia automacoes deterministicas para tarefas conhecidas e usa LLM apenas quando decisao, conversa ou revisao exigem raciocinio aberto.",
+    "A instalacao continua simples, sem dependencia obrigatoria de host, LLM profissional ou servico externo especifico.",
+    "Contratos publicos ficam versionados em codigo ou manifesto, nao apenas em docs locais ignorados pelo Git.",
+    "Escritas externas, segredos e acoes destrutivas permanecem bloqueadas por padrao ou exigem permissao explicita.",
+]
+
+
+CHANGE_TYPE_ACCEPTANCE: dict[str, list[str]] = {
+    "agent": [
+        "Inclui agent.yaml valido, README, AGENTS.md e ownership claro do dominio.",
+        "Define capabilities publicas sem depender de contexto grande carregado por padrao.",
+        "Explicita quando usa runner deterministico, LLM externo, mini brain local ou intervencao humana.",
+    ],
+    "capability": [
+        "Inclui capability.yaml com entrada, saida, write_policy e runner quando executavel.",
+        "Mantem conhecimento detalhado sob demanda em knowledge/ ou templates/ da propria capability.",
+        "Tem validacao focada que exercita o caminho principal via agent run quando aplicavel.",
+    ],
+    "runner": [
+        "Recebe argumentos estruturados e retorna resultado estruturado ou erro explicito.",
+        "Evita parse textual fragil quando houver API, JSON, YAML ou biblioteca adequada.",
+        "Redige stdout, stderr e artefatos antes de persistir dados que possam conter segredos.",
+    ],
+    "integration": [
+        "Fica encapsulada em infra/integrations/<provider>/ ou camada global equivalente quando o provider for compartilhado.",
+        "Separa dry-run, leitura, escrita local e escrita externa.",
+        "Documenta autenticacao, variaveis de ambiente e modo offline quando existir.",
+    ],
+    "host_plugin": [
+        "Mantem adaptador fino para o host e delega logica de produto ao runtime do Agent DevKit.",
+        "Preserva compatibilidade com CLI e MCP quando a funcao tambem fizer sentido fora do host.",
+        "Nao torna Codex, Claude, OpenClaw, OpenCode ou outro host dependencia obrigatoria da instalacao base.",
+    ],
+    "core_change": [
+        "Atualiza contratos publicos, validadores e saida humana quando a semantica do runtime mudar.",
+        "Mantem compatibilidade de comandos publicos ou documenta migracao objetiva.",
+        "Inclui testes focados cobrindo a nova regra central e pelo menos um smoke test de CLI quando aplicavel.",
+    ],
+}
+
+
+DEFINITION_OF_DONE: list[str] = [
+    "Contrato, comportamento, seguranca, compatibilidade, validacao e fora de escopo foram avaliados.",
+    "A mudanca tem teste ou comando focado que prova o comportamento principal.",
+    "A saida publica continua compreensivel para humano e consumivel por automacao quando houver modo JSON.",
+    "Nenhum segredo, path local sensivel ou dependencia externa obrigatoria foi introduzido sem contrato.",
+    "Riscos residuais e itens adiados ficaram explicitos na spec, PR ou resposta de entrega.",
+]
+
+
+def acceptance_sections() -> list[str]:
+    """Return canonical acceptance section identifiers."""
+    return [section["id"] for section in ACCEPTANCE_SECTIONS]
+
+
+def change_type_acceptance() -> dict[str, list[str]]:
+    """Return acceptance criteria grouped by change type."""
+    return deepcopy(CHANGE_TYPE_ACCEPTANCE)
+
+
+def acceptance_model() -> dict[str, Any]:
+    """Return the canonical acceptance model exposed by public architecture output."""
+    return {
+        "schema_version": "ai-devkit.acceptance/v1",
+        "sections": deepcopy(ACCEPTANCE_SECTIONS),
+        "global_criteria": list(GLOBAL_ACCEPTANCE_CRITERIA),
+        "change_types": [
+            {
+                "id": change_type,
+                "criteria": list(criteria),
+            }
+            for change_type, criteria in CHANGE_TYPE_ACCEPTANCE.items()
+        ],
+        "definition_of_done": list(DEFINITION_OF_DONE),
+    }

package/runtime/cli/aikit/agent_executor.py

@@ -0,0 +1,89 @@
+"""Execution helpers for multi-agent plans."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from cli.aikit.write_policy import (
+    is_autonomous_safe_write_policy,
+    normalize_write_policy,
+    write_policy_public_fields,
+)
+
+
+RunCapability = Callable[[dict[str, Any], str, list[str]], dict[str, Any]]
+LoadAgent = Callable[[str], dict[str, Any]]
+
+
+def execute_plan_tasks(
+    plan: dict[str, Any],
+    *,
+    load_agent: LoadAgent,
+    run_capability: RunCapability,
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    executed: list[dict[str, Any]] = []
+    blocked: list[dict[str, Any]] = []
+    for task in plan.get("specialist_tasks") or []:
+        if not task.get("primary"):
+            continue
+        if not task.get("executable"):
+            blocked.append(blocked_task(task, "Capability has no executable runner."))
+            continue
+        if not is_autonomous_safe_write_policy(task.get("write_policy")):
+            blocked.append(blocked_task(task, "Capability requires explicit confirmation for external write effects."))
+            continue
+        try:
+            agent = load_agent(str(task["agent_id"]))
+            result = run_capability(agent, str(task["capability_id"]), list(task.get("args") or []))
+        except Exception as exc:  # pragma: no cover - converted to user-facing payload.
+            blocked.append(blocked_task(task, str(exc)))
+            continue
+        item = public_task_result(task, result)
+        if result.get("ok"):
+            executed.append(item)
+        else:
+            blocked.append(item)
+    return executed, blocked
+
+
+def public_task_result(task: dict[str, Any], result: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "id": task.get("id"),
+        "task_id": task.get("task_id") or task.get("id"),
+        "agent_id": task.get("agent_id"),
+        "capability_id": task.get("capability_id"),
+        "role": task.get("role"),
+        "depends_on": list(task.get("depends_on") or []),
+        "handoff": task.get("handoff") if isinstance(task.get("handoff"), dict) else {},
+        "status": result.get("status"),
+        "ok": bool(result.get("ok")),
+        "provider": task.get("provider"),
+        "write_policy": normalize_write_policy(task.get("write_policy")),
+        "write_policy_metadata": task_write_policy_metadata(task),
+        "result": result,
+    }
+
+
+def blocked_task(task: dict[str, Any], reason: str) -> dict[str, Any]:
+    return {
+        "id": task.get("id"),
+        "task_id": task.get("task_id") or task.get("id"),
+        "agent_id": task.get("agent_id"),
+        "capability_id": task.get("capability_id"),
+        "role": task.get("role"),
+        "depends_on": list(task.get("depends_on") or []),
+        "handoff": task.get("handoff") if isinstance(task.get("handoff"), dict) else {},
+        "status": "blocked",
+        "ok": False,
+        "provider": task.get("provider"),
+        "write_policy": normalize_write_policy(task.get("write_policy")),
+        "write_policy_metadata": task_write_policy_metadata(task),
+        "reason": reason,
+    }
+
+
+def task_write_policy_metadata(task: dict[str, Any]) -> dict[str, Any]:
+    metadata = task.get("write_policy_metadata")
+    if isinstance(metadata, dict):
+        return metadata
+    return write_policy_public_fields(task.get("write_policy"))["write_policy_metadata"]

package/runtime/cli/aikit/agent_registry.py

@@ -0,0 +1,319 @@
+"""Agent and capability registry helpers for orchestration."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from cli.aikit.write_policy import normalize_write_policy, write_policy_public_fields
+
+
+def load_agent_registry(root: Path) -> dict[str, Any]:
+    agents_dir = root / "agents"
+    agents: dict[str, dict[str, Any]] = {}
+    capabilities: dict[str, dict[str, Any]] = {}
+    runtime_roles: dict[str, str] = {}
+    if not agents_dir.exists():
+        return {"agents": agents, "capabilities": capabilities, "runtime_roles": runtime_roles}
+    provider_map = load_provider_capability_map(root)
+    for agent_path in sorted(path for path in agents_dir.iterdir() if path.is_dir()):
+        manifest_path = agent_path / "agent.yaml"
+        if not manifest_path.exists():
+            continue
+        agent = read_yaml(manifest_path)
+        agent_id = str(agent.get("id") or agent_path.name)
+        agent["id"] = agent_id
+        agent["path"] = str(agent_path.relative_to(root))
+        agent["capabilities_index"] = {}
+        for capability_path in sorted((agent_path / "capabilities").glob("*/capability.yaml")):
+            capability = read_yaml(capability_path)
+            capability_id = str(capability.get("id") or capability_path.parent.name)
+            short_id = capability_id.rsplit(".", 1)[-1]
+            runtime = normalize_runtime(capability.get("runtime"))
+            provider_resolution = resolve_capability_provider(agent_id, short_id, capability, runtime, provider_map)
+            source_contract = normalize_source_contract(capability.get("source"), runtime=runtime)
+            public_capability = {
+                "id": capability_id,
+                "short_id": short_id,
+                "agent_id": agent_id,
+                "name": capability.get("name") or short_id,
+                "purpose": compact(str(capability.get("purpose") or "")),
+                "routing": normalize_routing(capability.get("routing")),
+                "runtime": runtime,
+                "runner": ((capability.get("entrypoint") or {}).get("runner")),
+                "provider": provider_resolution.get("provider"),
+                "provider_resolution": provider_resolution,
+                "source": source_contract,
+                "source_contract": source_contract,
+                "write_policy": normalize_write_policy(capability.get("write_policy")),
+                "write_policy_raw": capability.get("write_policy"),
+                **write_policy_public_fields(capability.get("write_policy")),
+                "inputs": capability.get("inputs") or {},
+                "outputs": capability.get("outputs") or {},
+                "integration": capability.get("integration") or {},
+                "requires": capability.get("requires") or {},
+                "has_runner": bool(((capability.get("entrypoint") or {}).get("runner"))),
+                "path": str(capability_path.parent.relative_to(root)),
+            }
+            agent["capabilities_index"][short_id] = public_capability
+            capabilities[f"{agent_id}/{short_id}"] = public_capability
+        public = public_agent(agent)
+        agents[agent_id] = public
+        runtime_role = public.get("runtime_role") if isinstance(public.get("runtime_role"), dict) else {}
+        role_kind = str(runtime_role.get("kind") or "").strip()
+        if role_kind:
+            runtime_roles.setdefault(role_kind, agent_id)
+    return {"agents": agents, "capabilities": capabilities, "runtime_roles": runtime_roles}
+
+
+def public_agent(agent: dict[str, Any]) -> dict[str, Any]:
+    surface = agent.get("agent_surface") if isinstance(agent.get("agent_surface"), dict) else {}
+    return {
+        "id": agent.get("id"),
+        "name": agent.get("name") or agent.get("id"),
+        "kind": agent.get("kind"),
+        "status": agent.get("status"),
+        "version": agent.get("version"),
+        "purpose": compact(str(agent.get("purpose") or "")),
+        "routing": normalize_routing(agent.get("routing")),
+        "runtime_role": normalize_runtime_role(agent.get("runtime_role")),
+        "agent_mode": normalize_agent_mode(agent.get("agent_mode")),
+        "depends_on_agents": list(agent.get("depends_on_agents") or []),
+        "orchestrated_agents": list(surface.get("orchestrated_agents") or []),
+        "capabilities": list(agent.get("capabilities") or []),
+        "capabilities_index": dict(agent.get("capabilities_index") or {}),
+        "write_policy": normalize_agent_write_policy(agent.get("write_policy")),
+        "write_policy_raw": agent.get("write_policy"),
+        "write_policy_metadata": normalize_agent_write_policy_metadata(agent.get("write_policy")),
+        "path": agent.get("path"),
+    }
+
+
+def find_capability(registry: dict[str, Any], agent_id: str, capability_id: str) -> dict[str, Any] | None:
+    return (registry.get("capabilities") or {}).get(f"{agent_id}/{capability_id}")
+
+
+def read_yaml(path: Path) -> dict[str, Any]:
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    return data if isinstance(data, dict) else {}
+
+
+def compact(value: str, *, limit: int = 240) -> str:
+    text = " ".join(value.split())
+    if len(text) <= limit:
+        return text
+    return text[: limit - 3].rstrip() + "..."
+
+
+def normalize_agent_write_policy(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {str(key): normalize_write_policy(policy) for key, policy in value.items()}
+    if value:
+        return normalize_write_policy(value)
+    return value
+
+
+def normalize_agent_write_policy_metadata(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {str(key): write_policy_public_fields(policy)["write_policy_metadata"] for key, policy in value.items()}
+    if value:
+        return write_policy_public_fields(value)["write_policy_metadata"]
+    return value
+
+
+def normalize_routing(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        return {}
+    return {
+        "aliases": normalize_routing_strings(value.get("aliases")),
+        "anchors": normalize_routing_strings(value.get("anchors")),
+        "domains": normalize_routing_strings(value.get("domains")),
+        "entities": normalize_routing_strings(value.get("entities")),
+        "intents": normalize_routing_strings(value.get("intents")),
+        "keywords": normalize_routing_strings(value.get("keywords")),
+        "examples": normalize_routing_strings(value.get("examples")),
+        "priority": value.get("priority", 0),
+    }
+
+
+def normalize_routing_strings(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [item.strip() for item in value if isinstance(item, str) and item.strip()]
+
+
+def normalize_runtime_role(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        return {}
+    kind = str(value.get("kind") or "").strip()
+    if not kind:
+        return {}
+    role: dict[str, Any] = {"kind": kind}
+    description = str(value.get("description") or "").strip()
+    if description:
+        role["description"] = compact(description)
+    return role
+
+
+def normalize_agent_mode(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        return {}
+    mode_type = str(value.get("type") or "").strip()
+    if not mode_type:
+        return {}
+    can_call_llm = value.get("can_call_llm")
+    normalized_llm: bool | str = False if can_call_llm is False else str(can_call_llm if can_call_llm is not None else "optional")
+    return {
+        "type": mode_type,
+        "max_steps": positive_int(value.get("max_steps"), default=5),
+        "max_specialists": positive_int(value.get("max_specialists"), default=5),
+        "max_llm_calls": positive_int(value.get("max_llm_calls"), default=0, allow_zero=True),
+        "timeout_seconds": positive_int(value.get("timeout_seconds"), default=300),
+        "can_call_capabilities": value.get("can_call_capabilities") is True,
+        "can_call_llm": normalized_llm,
+        "can_request_user_input": value.get("can_request_user_input") is True,
+        "external_writes": value.get("external_writes") is True,
+        "allowed_capabilities": normalize_string_list(value.get("allowed_capabilities")),
+        "stop_conditions": normalize_string_list(value.get("stop_conditions")),
+    }
+
+
+def positive_int(value: Any, *, default: int, allow_zero: bool = False) -> int:
+    try:
+        parsed = int(value)
+    except (TypeError, ValueError):
+        return default
+    if allow_zero and parsed == 0:
+        return 0
+    return parsed if parsed > 0 else default
+
+
+def normalize_string_list(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [str(item).strip() for item in value if str(item).strip()]
+
+
+def normalize_runtime(value: Any) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        return {}
+    runtime: dict[str, Any] = {}
+    provider = str(value.get("provider") or "").strip()
+    if provider:
+        runtime["provider"] = provider
+    source = value.get("source") if isinstance(value.get("source"), dict) else None
+    if source:
+        normalized_source: dict[str, Any] = {"enabled": source.get("enabled") is True}
+        for key in ("args", "env"):
+            mapping = source.get(key)
+            if isinstance(mapping, dict):
+                normalized_source[key] = {
+                    str(item_key): str(item_value)
+                    for item_key, item_value in mapping.items()
+                    if str(item_key).strip() and str(item_value).strip()
+                }
+        runtime["source"] = normalized_source
+    return runtime
+
+
+def normalize_source_contract(value: Any, *, runtime: dict[str, Any] | None = None) -> dict[str, Any]:
+    if isinstance(value, dict):
+        return normalize_declared_source_contract(value, origin="source")
+    runtime_source = (runtime or {}).get("source") if isinstance(runtime, dict) else None
+    if isinstance(runtime_source, dict):
+        normalized = normalize_declared_source_contract(runtime_source, origin="runtime.source")
+        if "supported" not in normalized and "enabled" in normalized:
+            normalized["supported"] = bool(normalized["enabled"])
+        if "enabled" not in normalized and "supported" in normalized:
+            normalized["enabled"] = bool(normalized["supported"])
+        return normalized
+    return {"enabled": False, "supported": False, "args": {}, "env": {}}
+
+
+def normalize_declared_source_contract(value: dict[str, Any], *, origin: str) -> dict[str, Any]:
+    enabled = value.get("enabled")
+    supported = value.get("supported")
+    is_enabled = enabled is True or supported is True
+    contract: dict[str, Any] = {
+        "enabled": is_enabled,
+        "supported": is_enabled,
+        "args": normalize_string_map(value.get("args")),
+        "env": normalize_string_map(value.get("env")),
+        "origin": origin,
+    }
+    mappings = value.get("mappings")
+    if mappings is None:
+        mappings = value.get("apply")
+    if isinstance(mappings, list):
+        normalized_mappings = []
+        for item in mappings:
+            if not isinstance(item, dict):
+                continue
+            field = str(item.get("field") or item.get("name") or "").strip()
+            if not field:
+                continue
+            arg = str(item.get("arg") or "").strip()
+            env = str(item.get("env") or "").strip()
+            mapping: dict[str, str] = {"field": field}
+            if arg:
+                contract["args"][field] = arg
+                mapping["arg"] = arg
+            if env:
+                contract["env"][field] = env
+                mapping["env"] = env
+            if len(mapping) > 1:
+                normalized_mappings.append(mapping)
+        contract["mappings"] = normalized_mappings
+    return contract
+
+
+def normalize_string_map(value: Any) -> dict[str, str]:
+    if not isinstance(value, dict):
+        return {}
+    return {
+        str(item_key): str(item_value)
+        for item_key, item_value in value.items()
+        if str(item_key).strip() and str(item_value).strip()
+    }
+
+
+def resolve_capability_provider(
+    agent_id: str,
+    short_id: str,
+    capability: dict[str, Any],
+    runtime: dict[str, Any],
+    provider_map: dict[str, str],
+) -> dict[str, Any]:
+    if runtime.get("provider"):
+        return {"provider": str(runtime["provider"]), "source": "runtime", "inferred": False}
+    requires = capability.get("requires") if isinstance(capability.get("requires"), dict) else {}
+    providers = requires.get("providers") if isinstance(requires.get("providers"), list) else []
+    if providers and isinstance(providers[0], dict) and providers[0].get("id"):
+        return {"provider": str(providers[0]["id"]), "source": "requires", "inferred": False}
+    integration = capability.get("integration") if isinstance(capability.get("integration"), dict) else {}
+    if integration.get("provider"):
+        return {"provider": str(integration["provider"]), "source": "integration", "inferred": False}
+    provider = provider_map.get(f"{agent_id}/{short_id}") or provider_map.get(agent_id)
+    if provider:
+        return {"provider": provider, "source": "provider-registry", "inferred": True}
+    return {"provider": None, "source": "none", "inferred": False}
+
+
+def load_provider_capability_map(root: Path) -> dict[str, str]:
+    providers_dir = root / "providers"
+    provider_map: dict[str, str] = {}
+    if not providers_dir.is_dir():
+        return provider_map
+    for provider_path in sorted(providers_dir.glob("*.yaml")):
+        provider = read_yaml(provider_path)
+        provider_id = str(provider.get("id") or "").strip()
+        capabilities = provider.get("capabilities") if isinstance(provider.get("capabilities"), dict) else {}
+        if not provider_id or not capabilities:
+            continue
+        for declared in list(capabilities.get("read") or []) + list(capabilities.get("write") or []):
+            declared_id = str(declared or "").strip()
+            if declared_id:
+                provider_map.setdefault(declared_id, provider_id)
+    return provider_map

package/runtime/cli/aikit/app_home.py

@@ -3,12 +3,16 @@
 from __future__ import annotations
 
 import os
+import shutil
 from pathlib import Path
+from typing import Any
 
 
+CANONICAL_APP_HOME_ENV = "AGENT_DEVKIT_HOME"
 APP_HOME_ENV = "AI_DEVKIT_CONFIG_HOME"
 LEGACY_APP_HOME_ENV = "AIKIT_CONFIG_HOME"
-DEFAULT_APP_HOME_NAME = ".ai-devkit"
+DEFAULT_APP_HOME_NAME = ".agent-devkit"
+LEGACY_DEFAULT_APP_HOME_NAME = ".ai-devkit"
 
 APP_DIRS = (
     "bin",
@@ -27,12 +31,93 @@ APP_DIRS = (
 
 def app_home() -> Path:
     """Return the configured Agent DevKit home directory."""
-    raw = os.environ.get(APP_HOME_ENV) or os.environ.get(LEGACY_APP_HOME_ENV)
+    raw = os.environ.get(CANONICAL_APP_HOME_ENV) or os.environ.get(APP_HOME_ENV) or os.environ.get(LEGACY_APP_HOME_ENV)
     if raw:
         return Path(raw).expanduser().resolve()
+    canonical = canonical_default_app_home()
+    legacy = legacy_default_app_home()
+    if canonical.exists():
+        return canonical
+    if legacy.exists():
+        return legacy
+    return canonical
+
+
+def canonical_default_app_home() -> Path:
     return (Path.home() / DEFAULT_APP_HOME_NAME).resolve()
 
 
+def legacy_default_app_home() -> Path:
+    return (Path.home() / LEGACY_DEFAULT_APP_HOME_NAME).resolve()
+
+
+def app_home_status() -> dict[str, Any]:
+    explicit_env = active_home_env()
+    canonical = canonical_default_app_home()
+    legacy = legacy_default_app_home()
+    home = app_home()
+    status = "canonical"
+    if explicit_env:
+        status = "env"
+    elif home == legacy:
+        status = "legacy-default-detected"
+    elif not canonical.exists() and not legacy.exists():
+        status = "canonical-default"
+    return {
+        "kind": "app-home-status",
+        "status": status,
+        "home": str(home),
+        "canonical_home": str(canonical),
+        "legacy_home": str(legacy),
+        "active_env": explicit_env,
+        "canonical_exists": canonical.exists(),
+        "legacy_exists": legacy.exists(),
+        "migration_available": not explicit_env and legacy.exists() and not canonical.exists(),
+        "migration_command": "agent config migrate-home",
+    }
+
+
+def active_home_env() -> dict[str, str] | None:
+    for name in (CANONICAL_APP_HOME_ENV, APP_HOME_ENV, LEGACY_APP_HOME_ENV):
+        value = os.environ.get(name)
+        if value:
+            return {"name": name, "value": str(Path(value).expanduser().resolve())}
+    return None
+
+
+def migrate_default_home(*, dry_run: bool = False) -> dict[str, Any]:
+    source = legacy_default_app_home()
+    destination = canonical_default_app_home()
+    payload: dict[str, Any] = {
+        "kind": "home-migration",
+        "source": str(source),
+        "destination": str(destination),
+        "dry_run": dry_run,
+        "executed": False,
+    }
+    if destination.exists():
+        return {**payload, "status": "not-needed", "message": "Canonical Agent DevKit home already exists."}
+    if not source.exists():
+        return {**payload, "status": "not-needed", "message": "Legacy AI DevKit home was not found."}
+    if dry_run:
+        return {**payload, "status": "planned", "message": "Legacy home would be migrated to canonical Agent DevKit home."}
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        source.rename(destination)
+        method = "rename"
+    except OSError:
+        shutil.copytree(source, destination)
+        shutil.rmtree(source)
+        method = "copytree"
+    return {
+        **payload,
+        "status": "migrated",
+        "executed": True,
+        "method": method,
+        "message": "Legacy home migrated to canonical Agent DevKit home.",
+    }
+
+
 def app_path(*parts: str) -> Path:
     return app_home().joinpath(*parts)