agent-devkit 0.1.6 → 0.3.0

package/runtime/cli/aikit/memory.py

@@ -4,6 +4,14 @@ from __future__ import annotations
 
 import re
 import shutil
+import hashlib
+import hmac
+import base64
+import io
+import json
+import os
+import tarfile
+import tempfile
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
@@ -95,12 +103,18 @@ Curated local runbook entries promoted from repeated use.
 - Keep high-value reusable notes here.
 """,
 }
+BACKUP_PACKAGE_SCHEMA_VERSION = "agent-devkit.memory-backup-package/v1"
+BACKUP_PACKAGE_ALGORITHM = "PBKDF2-HMAC-SHA256/XOR-HMAC-SHA256"
 
 
 def memory_home() -> Path:
     return app_memory_home()
 
 
+def memory_backups_home() -> Path:
+    return app_path("backups", "memory")
+
+
 def ensure_memory() -> dict[str, Any]:
     ensure_app_home()
     home = memory_home()
@@ -193,6 +207,183 @@ def show_memory(root: Path, *, agent_id: str | None = None, source_id: str | Non
     }
 
 
+def create_memory_backup(
+    *,
+    title: str | None = None,
+    encrypted: bool = False,
+    passphrase_env: str | None = None,
+) -> dict[str, Any]:
+    memory_paths = ensure_memory()
+    backups = memory_backups_home()
+    backups.mkdir(parents=True, exist_ok=True)
+    backup_id = unique_backup_id(title)
+    backup_root = backups / backup_id
+    backup_root.mkdir(parents=True, exist_ok=False)
+    backup_memory = backup_root / ("_memory-staging" if encrypted else "memory")
+    shutil.copytree(memory_home(), backup_memory)
+
+    files = backup_file_inventory(backup_memory)
+    manifest = {
+        "schema_version": "agent-devkit.memory-backup/v1",
+        "id": backup_id,
+        "title": title or "Memory backup",
+        "created_at": datetime.now(timezone.utc).isoformat(),
+        "source_home": str(memory_home()),
+        "storage": "local-filesystem",
+        "remote_upload": False,
+        "encrypted": encrypted,
+        "sensitive_local_copy": not encrypted,
+        "files": files,
+        "package": None,
+        "notes": [
+            "This is a local backup only; no remote provider upload was executed.",
+            "Remote backup must be encrypted before upload and requires explicit opt-in.",
+        ],
+    }
+    if encrypted:
+        package_path = backup_root / f"{backup_id}.adkmb"
+        passphrase = passphrase_from_env(passphrase_env)
+        write_encrypted_backup_package(package_path, backup_memory, manifest, passphrase)
+        manifest["package"] = str(package_path)
+        manifest["package_name"] = package_path.name
+        shutil.rmtree(backup_memory)
+    manifest_path = backup_root / "manifest.json"
+    manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    next_steps = [
+        f"Restore with `agent memory backup restore {backup_id} --yes`.",
+        f"Delete with `agent memory backup delete {backup_id} --yes`.",
+    ]
+    if encrypted:
+        next_steps[0] = f"Restore with `agent memory backup restore {backup_id} --passphrase-env {passphrase_env or 'AGENT_DEVKIT_BACKUP_PASSPHRASE'} --yes`."
+        next_steps.insert(1, f"Portable package: {manifest['package']}")
+    return {
+        "kind": "memory-backup",
+        "status": "created",
+        "backup": public_backup(manifest, backup_root),
+        "home": str(backups),
+        "memory_home": memory_paths["home"],
+        "next_steps": next_steps,
+    }
+
+
+def list_memory_backups() -> dict[str, Any]:
+    backups = memory_backups_home()
+    items = []
+    if backups.exists():
+        for manifest_path in sorted(backups.glob("*/manifest.json")):
+            manifest = load_backup_manifest(manifest_path)
+            if manifest:
+                items.append(public_backup(manifest, manifest_path.parent))
+    return {
+        "kind": "memory-backups",
+        "status": "ok",
+        "home": str(backups),
+        "count": len(items),
+        "items": items,
+    }
+
+
+def restore_memory_backup(
+    backup_id: str | None,
+    *,
+    yes: bool = False,
+    backup_file: str | None = None,
+    passphrase_env: str | None = None,
+) -> dict[str, Any]:
+    backup_root, manifest = require_memory_backup(backup_id, backup_file=backup_file, passphrase_env=passphrase_env)
+    payload = {
+        "kind": "memory-backup-restore",
+        "backup": public_backup(manifest, backup_root),
+        "memory_home": str(memory_home()),
+        "requires_confirmation": True,
+    }
+    if not yes:
+        return {
+            **payload,
+            "status": "planned",
+            "executed": False,
+            "next_steps": [restore_next_step(manifest, backup_file=backup_file, passphrase_env=passphrase_env)],
+        }
+
+    ensure_app_home()
+    safety_backup: str | None = None
+    with decrypted_memory_source(backup_root, manifest, passphrase_env=passphrase_env) as source_memory:
+        if memory_home().exists():
+            safety_root = memory_backups_home() / f"pre-restore-{timestamp_id()}"
+            safety_root.mkdir(parents=True, exist_ok=False)
+            shutil.copytree(memory_home(), safety_root / "memory")
+            safety_backup = str(safety_root)
+            shutil.rmtree(memory_home())
+        shutil.copytree(source_memory, memory_home())
+    return {
+        **payload,
+        "status": "restored",
+        "executed": True,
+        "safety_backup": safety_backup,
+    }
+
+
+class decrypted_memory_source:
+    def __init__(self, backup_root: Path, manifest: dict[str, Any], *, passphrase_env: str | None = None) -> None:
+        self.backup_root = backup_root
+        self.manifest = manifest
+        self.passphrase_env = passphrase_env
+        self.temp_dir: tempfile.TemporaryDirectory[str] | None = None
+
+    def __enter__(self) -> Path:
+        plain = self.backup_root / "memory"
+        if plain.exists():
+            return plain
+        package_path = package_path_from_manifest(self.backup_root, self.manifest)
+        if not package_path:
+            raise ValueError(f"memory backup has no restorable memory payload: {self.manifest.get('id')}")
+        passphrase = passphrase_from_env(self.passphrase_env)
+        self.temp_dir = tempfile.TemporaryDirectory(prefix="agent-devkit-memory-restore-")
+        target = Path(self.temp_dir.name)
+        extract_encrypted_backup_package(package_path, target, passphrase)
+        memory = target / "memory"
+        if not memory.exists():
+            raise ValueError("encrypted memory backup package did not contain memory/")
+        return memory
+
+    def __exit__(self, _exc_type: object, _exc: object, _tb: object) -> None:
+        if self.temp_dir:
+            self.temp_dir.cleanup()
+
+
+def restore_next_step(manifest: dict[str, Any], *, backup_file: str | None, passphrase_env: str | None) -> str:
+    if manifest.get("encrypted"):
+        env_name = passphrase_env or "AGENT_DEVKIT_BACKUP_PASSPHRASE"
+        if backup_file:
+            return f"Re-run with `agent memory backup restore --file {backup_file} --passphrase-env {env_name} --yes` to restore local memory."
+        return f"Re-run with `agent memory backup restore {manifest['id']} --passphrase-env {env_name} --yes` to restore local memory."
+    if backup_file:
+        return f"Re-run with `agent memory backup restore --file {backup_file} --yes` to restore local memory."
+    return f"Re-run with `agent memory backup restore {manifest['id']} --yes` to restore local memory."
+
+
+def delete_memory_backup(backup_id: str | None, *, yes: bool = False) -> dict[str, Any]:
+    backup_root, manifest = require_memory_backup(backup_id)
+    payload = {
+        "kind": "memory-backup-delete",
+        "backup": public_backup(manifest, backup_root),
+        "requires_confirmation": True,
+    }
+    if not yes:
+        return {
+            **payload,
+            "status": "planned",
+            "executed": False,
+            "next_steps": [f"Re-run with `agent memory backup delete {manifest['id']} --yes` to remove this local backup."],
+        }
+    shutil.rmtree(backup_root)
+    return {
+        **payload,
+        "status": "deleted",
+        "executed": True,
+    }
+
+
 def reset_memory(
     *,
     all_memory: bool = False,
@@ -246,6 +437,220 @@ def memory_path_payload() -> dict[str, Any]:
     return ensure_memory()
 
 
+def unique_backup_id(title: str | None) -> str:
+    base = sanitize_segment(title or "memory-backup")
+    candidate = f"{base}-{timestamp_id()}"
+    backups = memory_backups_home()
+    if not (backups / candidate).exists():
+        return candidate
+    suffix = 2
+    while (backups / f"{candidate}-{suffix}").exists():
+        suffix += 1
+    return f"{candidate}-{suffix}"
+
+
+def timestamp_id() -> str:
+    return datetime.now(timezone.utc).strftime("%Y%m%d%H%M%S")
+
+
+def backup_file_inventory(root: Path) -> list[dict[str, Any]]:
+    items: list[dict[str, Any]] = []
+    for path in sorted(item for item in root.rglob("*") if item.is_file()):
+        relative = str(path.relative_to(root))
+        data = path.read_bytes()
+        items.append(
+            {
+                "path": relative,
+                "bytes": len(data),
+                "sha256": hashlib.sha256(data).hexdigest(),
+            }
+        )
+    return items
+
+
+def public_backup(manifest: dict[str, Any], root: Path) -> dict[str, Any]:
+    files = manifest.get("files") if isinstance(manifest.get("files"), list) else []
+    return {
+        "id": manifest.get("id"),
+        "title": manifest.get("title"),
+        "created_at": manifest.get("created_at"),
+        "path": str(root),
+        "storage": manifest.get("storage"),
+        "remote_upload": manifest.get("remote_upload") is True,
+        "encrypted": manifest.get("encrypted") is True,
+        "sensitive_local_copy": manifest.get("sensitive_local_copy") is True,
+        "package": manifest.get("package"),
+        "package_name": manifest.get("package_name"),
+        "file_count": len(files),
+    }
+
+
+def require_memory_backup(
+    backup_id: str | None,
+    *,
+    backup_file: str | None = None,
+    passphrase_env: str | None = None,
+) -> tuple[Path, dict[str, Any]]:
+    if backup_file:
+        package = Path(backup_file).expanduser().resolve()
+        manifest = read_encrypted_backup_header(package, passphrase_env=passphrase_env)
+        return package.parent, manifest
+    item_id = sanitize_segment(backup_id or "")
+    if not item_id:
+        raise ValueError("memory backup requires a backup id")
+    root = memory_backups_home() / item_id
+    manifest_path = root / "manifest.json"
+    if not manifest_path.exists():
+        raise ValueError(f"memory backup not found: {item_id}")
+    manifest = load_backup_manifest(manifest_path)
+    if not manifest:
+        raise ValueError(f"invalid memory backup manifest: {item_id}")
+    return root, manifest
+
+
+def load_backup_manifest(path: Path) -> dict[str, Any] | None:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def passphrase_from_env(passphrase_env: str | None) -> str:
+    env_name = passphrase_env or "AGENT_DEVKIT_BACKUP_PASSPHRASE"
+    if not re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", env_name):
+        raise ValueError("--passphrase-env must be an environment variable name")
+    value = os.environ.get(env_name)
+    if not value:
+        raise ValueError(f"memory backup passphrase environment variable is not set: {env_name}")
+    if len(value) < 8:
+        raise ValueError("memory backup passphrase must have at least 8 characters")
+    return value
+
+
+def write_encrypted_backup_package(package_path: Path, memory_dir: Path, manifest: dict[str, Any], passphrase: str) -> None:
+    tar_bytes = memory_tar_bytes(memory_dir)
+    salt = os.urandom(16)
+    nonce = os.urandom(16)
+    key = derive_backup_key(passphrase, salt)
+    ciphertext = xor_bytes(tar_bytes, key, nonce)
+    header = {
+        "schema_version": BACKUP_PACKAGE_SCHEMA_VERSION,
+        "algorithm": BACKUP_PACKAGE_ALGORITHM,
+        "kdf": "PBKDF2-HMAC-SHA256",
+        "iterations": 200_000,
+        "salt": base64.b64encode(salt).decode("ascii"),
+        "nonce": base64.b64encode(nonce).decode("ascii"),
+        "manifest": {key: value for key, value in manifest.items() if key != "files"},
+        "files": manifest.get("files") or [],
+    }
+    header_bytes = json.dumps(header, ensure_ascii=False, sort_keys=True).encode("utf-8")
+    tag = hmac.new(key, header_bytes + ciphertext, hashlib.sha256).hexdigest()
+    envelope = {
+        "schema_version": BACKUP_PACKAGE_SCHEMA_VERSION,
+        "header": header,
+        "ciphertext": base64.b64encode(ciphertext).decode("ascii"),
+        "tag": tag,
+    }
+    package_path.write_text(json.dumps(envelope, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+
+
+def read_encrypted_backup_header(package_path: Path, *, passphrase_env: str | None = None) -> dict[str, Any]:
+    envelope = read_backup_package(package_path)
+    header = envelope["header"]
+    manifest = header.get("manifest") if isinstance(header.get("manifest"), dict) else {}
+    payload = dict(manifest)
+    payload["files"] = header.get("files") if isinstance(header.get("files"), list) else []
+    payload["encrypted"] = True
+    payload["sensitive_local_copy"] = False
+    payload["package"] = str(package_path)
+    payload["package_name"] = package_path.name
+    payload.setdefault("id", package_path.stem)
+    payload.setdefault("title", package_path.stem)
+    return payload
+
+
+def extract_encrypted_backup_package(package_path: Path, target: Path, passphrase: str) -> None:
+    envelope = read_backup_package(package_path)
+    header = envelope["header"]
+    salt = base64.b64decode(header["salt"])
+    nonce = base64.b64decode(header["nonce"])
+    ciphertext = base64.b64decode(envelope["ciphertext"])
+    key = derive_backup_key(passphrase, salt)
+    header_bytes = json.dumps(header, ensure_ascii=False, sort_keys=True).encode("utf-8")
+    expected_tag = hmac.new(key, header_bytes + ciphertext, hashlib.sha256).hexdigest()
+    if not hmac.compare_digest(expected_tag, str(envelope.get("tag") or "")):
+        raise ValueError("memory backup package integrity check failed")
+    tar_bytes = xor_bytes(ciphertext, key, nonce)
+    extract_memory_tar(tar_bytes, target)
+
+
+def read_backup_package(package_path: Path) -> dict[str, Any]:
+    if not package_path.exists():
+        raise ValueError(f"memory backup package not found: {package_path}")
+    try:
+        envelope = json.loads(package_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise ValueError(f"invalid memory backup package: {package_path}") from exc
+    if not isinstance(envelope, dict) or envelope.get("schema_version") != BACKUP_PACKAGE_SCHEMA_VERSION:
+        raise ValueError(f"unsupported memory backup package: {package_path}")
+    header = envelope.get("header")
+    if not isinstance(header, dict) or header.get("algorithm") != BACKUP_PACKAGE_ALGORITHM:
+        raise ValueError(f"unsupported memory backup package algorithm: {package_path}")
+    return envelope
+
+
+def memory_tar_bytes(memory_dir: Path) -> bytes:
+    buffer = io.BytesIO()
+    with tarfile.open(fileobj=buffer, mode="w:gz") as archive:
+        for path in sorted(item for item in memory_dir.rglob("*") if item.is_file()):
+            archive.add(path, arcname=str(Path("memory") / path.relative_to(memory_dir)))
+    return buffer.getvalue()
+
+
+def extract_memory_tar(payload: bytes, target: Path) -> None:
+    target.mkdir(parents=True, exist_ok=True)
+    with tarfile.open(fileobj=io.BytesIO(payload), mode="r:gz") as archive:
+        for member in archive.getmembers():
+            member_path = Path(member.name)
+            if member_path.is_absolute() or ".." in member_path.parts or not member.name.startswith("memory/"):
+                raise ValueError(f"unsafe path in memory backup package: {member.name}")
+            if not member.isfile():
+                continue
+            output = target / member_path
+            output.parent.mkdir(parents=True, exist_ok=True)
+            extracted = archive.extractfile(member)
+            if extracted is None:
+                continue
+            output.write_bytes(extracted.read())
+
+
+def derive_backup_key(passphrase: str, salt: bytes) -> bytes:
+    return hashlib.pbkdf2_hmac("sha256", passphrase.encode("utf-8"), salt, 200_000, dklen=32)
+
+
+def xor_bytes(payload: bytes, key: bytes, nonce: bytes) -> bytes:
+    output = bytearray()
+    counter = 0
+    for index in range(0, len(payload), 32):
+        block = payload[index : index + 32]
+        stream = hmac.new(key, nonce + counter.to_bytes(8, "big"), hashlib.sha256).digest()
+        output.extend(byte ^ stream[offset] for offset, byte in enumerate(block))
+        counter += 1
+    return bytes(output)
+
+
+def package_path_from_manifest(backup_root: Path, manifest: dict[str, Any]) -> Path | None:
+    raw = manifest.get("package")
+    if isinstance(raw, str) and raw:
+        return Path(raw).expanduser().resolve()
+    package_name = manifest.get("package_name")
+    if isinstance(package_name, str) and package_name:
+        return backup_root / package_name
+    candidates = sorted(backup_root.glob("*.adkmb"))
+    return candidates[0] if candidates else None
+
+
 def increment_bucket(bucket: dict[str, Any], key: str, now: str) -> None:
     item = bucket.setdefault(key, {"count": 0, "first_seen": now, "last_seen": now})
     item["count"] = int(item.get("count") or 0) + 1

package/runtime/cli/aikit/mini_brain.py

@@ -0,0 +1,246 @@
+"""Mini-brain local model contract and setup helpers."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from cli.aikit.llm import BACKENDS, configure_backend, doctor_backend, load_config, save_config
+from cli.aikit.ollama import ollama_pull, ollama_status
+
+
+MINI_BRAIN_CONFIG_KEY = "mini_brain"
+DEFAULT_HF_MODEL = "Qwen/Qwen3-0.6B"
+DEFAULT_OLLAMA_MODEL = "qwen3:0.6b"
+DEFAULT_PROVIDER = "ollama"
+DEFAULT_BASE_URL = "http://localhost:11434/v1"
+ALLOWED_TASKS = [
+    "setup_help",
+    "wizard_conversation",
+    "intent_classification",
+    "command_explanation",
+    "short_error_summary",
+]
+FORBIDDEN_TASKS = [
+    "external_write_decision",
+    "destructive_operation_approval",
+    "security_review_final",
+    "architecture_decision",
+    "secret_handling",
+    "final_delivery_decision",
+]
+DEFAULT_LIMITS = {
+    "max_context_chars": 6000,
+    "max_response_chars": 2000,
+    "max_llm_calls": 1,
+}
+DEFAULT_GUARDRAILS = [
+    "no_secrets",
+    "low_risk_only",
+    "no_external_writes",
+    "coordinator_review_required",
+]
+
+
+def mini_brain_contract(
+    *,
+    config: dict[str, Any] | None = None,
+    ollama_payload: dict[str, Any] | None = None,
+    ollama_backend: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    config = load_config() if config is None else config
+    stored = config.get(MINI_BRAIN_CONFIG_KEY) if isinstance(config.get(MINI_BRAIN_CONFIG_KEY), dict) else {}
+    enabled = bool(stored.get("enabled"))
+    provider = stored.get("provider") or stored.get("runtime") or DEFAULT_PROVIDER
+    hf_model = stored.get("hf_model") or stored.get("model") or DEFAULT_HF_MODEL
+    ollama_model = stored.get("ollama_model") or DEFAULT_OLLAMA_MODEL
+    ollama_payload = ollama_status() if ollama_payload is None else ollama_payload
+    ollama_backend = doctor_backend(BACKENDS["ollama"], config) if ollama_backend is None else ollama_backend
+    backend_configured = ollama_backend.get("status") == "ok"
+    runtime_available = ollama_payload.get("status") == "ok" or backend_configured
+    available = enabled and provider == DEFAULT_PROVIDER and runtime_available
+    status = "ok" if available else "disabled" if not enabled else "unavailable"
+    return {
+        "kind": "mini-brain",
+        "status": status,
+        "enabled": enabled,
+        "available": available,
+        "configured": enabled and provider == DEFAULT_PROVIDER and backend_configured,
+        "provider": provider,
+        "runtime": provider,
+        "hf_model": hf_model,
+        "model": hf_model,
+        "ollama_model": ollama_model,
+        "allowed_tasks": list_value(stored.get("allowed_tasks"), ALLOWED_TASKS),
+        "forbidden_tasks": list_value(stored.get("forbidden_tasks"), FORBIDDEN_TASKS),
+        "limits": dict_value(stored.get("limits"), DEFAULT_LIMITS),
+        "guardrails": list_value(stored.get("guardrails"), DEFAULT_GUARDRAILS),
+        "stored_secret": False,
+        "ollama": {
+            "status": ollama_payload.get("status"),
+            "daemon": (ollama_payload.get("daemon") or {}).get("status")
+            if isinstance(ollama_payload.get("daemon"), dict)
+            else None,
+            "model_count": ollama_payload.get("model_count"),
+        },
+        "backend": {
+            "status": ollama_backend.get("status"),
+            "model": ollama_backend.get("model"),
+            "base_url": ollama_backend.get("base_url"),
+        },
+    }
+
+
+def setup_mini_brain(
+    *,
+    dry_run: bool = False,
+    yes: bool = False,
+    set_default: bool = False,
+    model: str = DEFAULT_OLLAMA_MODEL,
+) -> dict[str, Any]:
+    if dry_run or not yes:
+        status = "planned" if dry_run else "needs-confirmation"
+        needs_confirmation = not dry_run and not yes
+        return {
+            "kind": "mini-brain-setup",
+            "status": status,
+            "ok": bool(dry_run),
+            "exit_code": 2 if needs_confirmation else 0,
+            "dry_run": dry_run,
+            "yes": yes,
+            "stored_secret": False,
+            "mini_brain": planned_contract(model=model),
+            "pull": ollama_pull(model, yes=False, dry_run=dry_run),
+            "next_steps": ["agent setup mini-brain --yes"],
+            "message": "Use --yes to pull Qwen3-0.6B with Ollama and enable the mini-brain.",
+        }
+
+    pull = ollama_pull(model, yes=True, dry_run=False)
+    toolchain_install = None
+    if pull.get("status") == "missing":
+        from cli.aikit.toolchain import install_toolchain
+
+        toolchain_install = install_toolchain(None, "ollama", dry_run=False, yes=True)
+        if toolchain_install.get("status") == "installed":
+            pull = ollama_pull(model, yes=True, dry_run=False)
+    if not pull.get("ok"):
+        payload = {
+            "kind": "mini-brain-setup",
+            "status": "failed",
+            "ok": False,
+            "exit_code": int(pull.get("exit_code") or 2),
+            "dry_run": False,
+            "yes": True,
+            "stored_secret": False,
+            "mini_brain": planned_contract(model=model),
+            "pull": pull,
+            "next_steps": ["Install Ollama or run agent ollama pull qwen3:0.6b --yes"],
+            "message": pull.get("message") or "Could not pull the mini-brain model.",
+        }
+        if toolchain_install:
+            payload["toolchain_install"] = toolchain_install
+            payload["next_steps"] = [
+                "Review `agent toolchain doctor ollama`.",
+                "Run `agent toolchain install ollama --yes` if you approve external installation.",
+                "Then run `agent setup mini-brain --yes` again.",
+            ]
+        return payload
+
+    existing_config = load_config()
+    existing_ollama = (
+        existing_config.get("llm", {}).get("backends", {}).get(DEFAULT_PROVIDER)
+        if isinstance(existing_config.get("llm"), dict)
+        else {}
+    )
+    existing_base_url = existing_ollama.get("base_url") if isinstance(existing_ollama, dict) else None
+    configured = configure_backend(
+        DEFAULT_PROVIDER,
+        base_url=existing_base_url or DEFAULT_BASE_URL,
+        model=model,
+        set_default=set_default,
+    )
+    config = load_config()
+    config[MINI_BRAIN_CONFIG_KEY] = stored_config(model=model)
+    written_path = save_config(config)
+    contract = mini_brain_contract(config=config)
+    return {
+        "kind": "mini-brain-setup",
+        "status": "configured",
+        "ok": True,
+        "dry_run": False,
+        "yes": True,
+        "stored_secret": False,
+        "config_path": str(written_path),
+        "mini_brain": contract,
+        "pull": pull,
+        "toolchain_install": toolchain_install,
+        "llm_configure": configured,
+        "next_steps": ["Use low-risk setup, wizard and summary prompts normally."],
+    }
+
+
+def planned_contract(*, model: str = DEFAULT_OLLAMA_MODEL) -> dict[str, Any]:
+    return {
+        "kind": "mini-brain",
+        "status": "planned",
+        "enabled": False,
+        "available": False,
+        "configured": False,
+        "provider": DEFAULT_PROVIDER,
+        "runtime": DEFAULT_PROVIDER,
+        "hf_model": DEFAULT_HF_MODEL,
+        "model": DEFAULT_HF_MODEL,
+        "ollama_model": model,
+        "allowed_tasks": list(ALLOWED_TASKS),
+        "forbidden_tasks": list(FORBIDDEN_TASKS),
+        "limits": dict(DEFAULT_LIMITS),
+        "guardrails": list(DEFAULT_GUARDRAILS),
+        "stored_secret": False,
+    }
+
+
+def stored_config(*, model: str = DEFAULT_OLLAMA_MODEL) -> dict[str, Any]:
+    return {
+        "enabled": True,
+        "provider": DEFAULT_PROVIDER,
+        "runtime": DEFAULT_PROVIDER,
+        "hf_model": DEFAULT_HF_MODEL,
+        "model": DEFAULT_HF_MODEL,
+        "ollama_model": model,
+        "allowed_tasks": list(ALLOWED_TASKS),
+        "forbidden_tasks": list(FORBIDDEN_TASKS),
+        "limits": dict(DEFAULT_LIMITS),
+        "guardrails": list(DEFAULT_GUARDRAILS),
+        "stored_secret": False,
+        "updated_at": now_iso(),
+    }
+
+
+def summarize_mini_brain(value: Any) -> dict[str, Any] | None:
+    if not isinstance(value, dict):
+        return None
+    return {
+        "status": value.get("status"),
+        "enabled": value.get("enabled") is True,
+        "available": value.get("available") is True,
+        "provider": value.get("provider"),
+        "hf_model": value.get("hf_model") or value.get("model"),
+        "ollama_model": value.get("ollama_model"),
+        "stored_secret": value.get("stored_secret") is True,
+    }
+
+
+def list_value(value: Any, default: list[str]) -> list[str]:
+    if not isinstance(value, list):
+        return list(default)
+    return [str(item) for item in value if str(item).strip()]
+
+
+def dict_value(value: Any, default: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(value, dict):
+        return dict(default)
+    return dict(value)
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()