agent-devkit 0.2.0 → 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

@@ -100,10 +100,12 @@ def setup_mini_brain(
 ) -> 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,
@@ -114,11 +116,19 @@ def setup_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"):
-        return {
+        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,
@@ -127,6 +137,14 @@ def setup_mini_brain(
             "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 = (
@@ -155,6 +173,7 @@ def setup_mini_brain(
         "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."],
     }

package/runtime/cli/aikit/natural_prompt_runtime.py

@@ -3,9 +3,11 @@
 from __future__ import annotations
 
 import argparse
+import re
 from pathlib import Path
 from typing import Any
 
+from cli.aikit.agent_registry import load_agent_registry
 from cli.aikit.agent_executor import execute_plan_tasks
 from cli.aikit.capability_runtime import load_agent, run_capability
 from cli.aikit.calendar import calendar_summary, calendar_today, calendar_tomorrow
@@ -22,7 +24,7 @@ from cli.aikit.memory import napkin_context, record_usage
 from cli.aikit.model_router import build_model_plan
 from cli.aikit.module_controller import run_module_controller
 from cli.aikit.orchestrator import attach_source_to_primary_task, build_execution_plan, mark_plan_after_execution, mark_review_task
-from cli.aikit.personality import load_personality
+from cli.aikit.personality import load_personality, update_personality
 from cli.aikit.provider_wizard import missing_source_wizard
 from cli.aikit.review_gate import build_review_gate
 from cli.aikit.router import route_prompt
@@ -36,6 +38,106 @@ def effective_dry_run(args: argparse.Namespace) -> bool:
     return bool(getattr(args, "dry_run", False) or getattr(args, "global_dry_run", False))
 
 
+def parse_rename_prompt(prompt: str) -> str | None:
+    text = " ".join(prompt.strip().split())
+    patterns = [
+        r"(?i)\b(?:mude|troque|altere|renomeie)\s+(?:o\s+)?seu\s+nome\s+para\s+(.+)$",
+        r"(?i)\b(?:seu\s+nome\s+agora\s+e|seu\s+nome\s+agora\s+é)\s+(.+)$",
+        r"(?i)\b(?:teu\s+nome\s+agora\s+e|teu\s+nome\s+agora\s+é)\s+(.+)$",
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, text)
+        if not match:
+            continue
+        value = clean_requested_name(match.group(1))
+        if value:
+            return value
+    return None
+
+
+def clean_requested_name(value: str) -> str | None:
+    cleaned = " ".join(value.strip().strip("\"'`.,;:!").split())
+    if not cleaned:
+        return None
+    return cleaned[:80]
+
+
+def is_capabilities_help_prompt(prompt: str) -> bool:
+    normalized = normalize_text(prompt)
+    if normalized in {"ajuda", "help", "o que voce faz", "o que voce consegue fazer"}:
+        return True
+    capability_markers = (
+        "o que voce consegue fazer",
+        "o que voce pode fazer",
+        "como voce pode ajudar",
+        "como usar o agent",
+        "como usar voce",
+        "quais suas capacidades",
+        "quais sao suas capacidades",
+        "quais agentes voce tem",
+        "que agentes voce tem",
+    )
+    return any(marker in normalized for marker in capability_markers)
+
+
+def normalize_text(value: str) -> str:
+    replacements = str.maketrans(
+        {
+            "á": "a",
+            "à": "a",
+            "ã": "a",
+            "â": "a",
+            "é": "e",
+            "ê": "e",
+            "í": "i",
+            "ó": "o",
+            "õ": "o",
+            "ô": "o",
+            "ú": "u",
+            "ç": "c",
+        }
+    )
+    text = value.lower().translate(replacements)
+    return " ".join(re.sub(r"[^a-z0-9._:-]+", " ", text).split())
+
+
+def local_capabilities_help_response(prompt: str, *, name: str) -> dict[str, Any]:
+    registry = load_agent_registry(ROOT)
+    agents = registry.get("agents") if isinstance(registry.get("agents"), dict) else {}
+    capabilities = registry.get("capabilities") if isinstance(registry.get("capabilities"), dict) else {}
+    examples = [
+        'agent "analise o card 7914 do projeto sustentacao no azure"',
+        'agent "mude seu nome para Ianota"',
+        "agent onboard minimal",
+        "agent catalog search pr",
+        "agent mcp tools",
+        "agent memory show",
+    ]
+    response = (
+        f"Eu sou {name}. Posso operar como harness/agente local do Agent DevKit: "
+        "validar onboarding, lembrar preferencias locais, rotear pedidos para agentes especialistas, "
+        "criar wizards de configuracao quando faltar provider/source, executar capabilities deterministicas, "
+        "expor ferramentas via MCP, preparar automacoes locais e usar LLMs configuradas quando a tarefa exigir raciocinio aberto. "
+        f"Neste runtime encontrei {len(agents)} agentes e {len(capabilities)} capabilities."
+    )
+    return {
+        "kind": "agent",
+        "status": "ok",
+        "ok": True,
+        "requires_llm": False,
+        "prompt_received": True,
+        "prompt_length": len(prompt),
+        "mode": "local-capabilities-help",
+        "identity": {"name": name, "source": "local"},
+        "response": response,
+        "catalog": {
+            "agents": len(agents),
+            "capabilities": len(capabilities),
+        },
+        "next_steps": examples,
+    }
+
+
 def agent_requires_llm(args: argparse.Namespace) -> dict[str, Any]:
     prompt = " ".join(args.prompt).strip()
     return run_agent_prompt_request(
@@ -70,6 +172,21 @@ def run_agent_prompt_request(request: AgentPromptRequest) -> dict[str, Any]:
         raise DevKitError(str(exc)) from exc
     personality = load_personality()
     name = public_name(personality=personality, invoked_as=request.prog_name)
+    rename = parse_rename_prompt(prompt)
+    if rename:
+        updated = update_personality(agent_name=rename)
+        result = {
+            "kind": "agent",
+            "status": "ok",
+            "ok": True,
+            "requires_llm": False,
+            "prompt_received": True,
+            "prompt_length": len(prompt),
+            "identity": {"name": updated.get("agent_name"), "source": "local"},
+            "action": "rename",
+            "response": f"Pronto. Meu nome local agora e {updated.get('agent_name')}.",
+        }
+        return finalize_agent_session(result, session, prompt, backend=request.llm)
     if is_identity_question(prompt):
         result = {
             "kind": "agent",
@@ -82,6 +199,13 @@ def run_agent_prompt_request(request: AgentPromptRequest) -> dict[str, Any]:
             "response": local_identity_response(prompt, name=name),
         }
         return finalize_agent_session(result, session, prompt, backend=request.llm)
+    if is_capabilities_help_prompt(prompt):
+        return finalize_agent_session(
+            local_capabilities_help_response(prompt, name=name),
+            session,
+            prompt,
+            backend=request.llm,
+        )
     natural_result = dispatch_natural_operational_prompt(prompt)
     if natural_result:
         return finalize_agent_session(natural_result, session, prompt, backend=request.llm)