@andespindola/crow-skills 0.24.0 → 0.26.0

package/crow_skills/cli.py

@@ -17,6 +17,7 @@ from . import progress
 from . import projection
 from . import resources
 from . import machine
+from . import mcp
 from . import ui
 from .agents import (AGENTS, destinations, inventory, legacy_shared_dir,
                       refuse_implausible_destination, refuse_store_as_cli_dir)
@@ -81,6 +82,9 @@ COMMANDS = {
     "resources": ("Memória, pressão, agentes em execução, paralelismo recomendado e processos órfãos de ferramentas de agente.",
                   ["crow-skills resources", "crow-skills resources --exec-prefix", "crow-skills resources --orphans",
                    "crow-skills resources --orphans --kill --dry-run", "crow-skills resources --orphans --kill --yes"]),
+    "mcp": ("Gerencia adaptadores nativos e ciclo de vida MCP local, sem varrer ferramentas autenticadas.",
+            ["crow-skills mcp status --json", "crow-skills mcp plan --hosts codex,claude --json",
+             "crow-skills mcp apply --hosts claude --yes", "crow-skills mcp restore --hosts claude --yes"]),
     "autoupdate": ("Agenda a atualização diária e no login (o mesmo fluxo de upgrade) ou roda agora.",
                    ["crow-skills autoupdate on --yes", "crow-skills autoupdate status", "crow-skills autoupdate run --yes"]),
     "rollback": ("Desfaz uma transação concluída (skills e o guia ligado a ela).", ["crow-skills rollback --transaction <id> --yes"]),
@@ -228,6 +232,11 @@ def parser():
     child.add_argument("--kill", action="store_true",
                        help="Com --orphans: encerrar as árvores órfãs (TERM, carência, KILL só se preciso); exige --yes ou confirmação")
     child.add_argument("--older-than", help="Com --orphans: idade mínima da raiz (ex.: 30m, 2h, 1d; padrão 30m ou o do resources.json)")
+    child = command_parser(sub, "mcp", [common])
+    child.add_argument("action", nargs="?", default="status", choices=("status", "plan", "apply", "restore"))
+    child.add_argument("--runtime", help="Caminho absoluto do crow_mcp.py da skill instalada")
+    child.add_argument("--restartable", default="", help="Servidores reinicializáveis explicitamente autorizados, separados por vírgula")
+    child.add_argument("--hosts", help="Escopo explícito: codex,claude,devin,claude-desktop,agents")
     child = command_parser(sub, "autoupdate", [common])
     child.add_argument("action", choices=("on", "off", "status", "run"))
     child.add_argument("--git-pull", action="store_true", help="on: também atualizar um checkout git limpo em main/master (git pull --ff-only)")
@@ -370,9 +379,9 @@ def guide_sync(args, home, store, command, targets, plan, source):
         after = sorted((set(guide.managed_skills(agent, home, store)) | added) - removed)
         if mech["kind"] == "toml" and guide.tomllib is None:
             report["skipped"].append({"agent": agent, "reason": "Python 3.11+ (tomllib) é necessário para editar config.toml; guia não alterado."})
-        elif "crow-behaviour" in after and (record or command != "uninstall"):
+        elif {"crow-behaviour", "crow-uny-mcp"} & set(after) and (record or command != "uninstall"):
             actions[agent], skills_after[agent] = "install", after
-        elif record and "crow-behaviour" in removed:
+        elif record and {"crow-behaviour", "crow-uny-mcp"} & set(removed):
             actions[agent] = "uninstall"
         elif record and "crow-behaviour" not in after:
             report["skipped"].append({"agent": agent, "reason": "crow-behaviour ausente; guia mantido. Confira crow-skills guide status."})
@@ -993,6 +1002,8 @@ SKILL_STATE_WORDS = {
     "modificada": "editada no disco",
     "desativada": "instalada, mas desabilitada",
     "ausente": "registrada e não encontrada no disco",
+    "via_uniflow": "projetada do seu store do Uniflow (gerenciada em --agents uniflow)",
+    "link_externo": "link no store do Uniflow para fora dele",
     "nao_gerenciada": "não gerenciada por este CLI",
     "indeterminada": "não foi possível ler o destino",
 }
@@ -1013,7 +1024,16 @@ def skill_state(row, source):
         return "desativada"
     if status == "missing":
         return "ausente"
-    if status in ("unmanaged", "absent", "external_link", "uniflow_link"):
+    if status == "uniflow_link":
+        # Projeção SAUDÁVEL do store do Uniflow: é a topologia normal de quem instala em uniflow e
+        # deixa os CLIs lerem de lá, e o resto do CLI já a conta como instalada (group_coverage).
+        # Chamar isso de "não gerenciada" assustava sem motivo — 33 skills em 4 agentes, aqui.
+        # Projeção quebrada, desabilitada ou para pacote não gerenciado não chega como uniflow_link:
+        # unmanaged_projections() a reescreve antes (modified/disabled/unmanaged).
+        return "via_uniflow"
+    if status == "external_link":
+        return "link_externo"
+    if status in ("unmanaged", "absent"):
         return "nao_gerenciada"
     return "indeterminada"  # "unsafe" e qualquer estado novo: nunca contado como em dia
 
@@ -1069,7 +1089,9 @@ def skills_command(args, home, store):
     """Somente leitura: versão e estado de cada skill instalada, contra a fonte atual."""
     source = Source(getattr(args, "source", DEFAULT_SOURCE), getattr(args, "ref", "HEAD"))
     targets = scope(args, home, read=True)
-    rows = store.status(targets)
+    # A mesma correção que status/doctor aplicam: projeção do Uniflow quebrada, desabilitada ou para
+    # pacote não gerenciado não pode passar por projeção saudável.
+    rows = unmanaged_projections(store, home, store.status(targets))
     items = {}
     for row in rows:
         if not row.get("name"):
@@ -1163,6 +1185,108 @@ def help_command(args, home, topic=None):
     return {"topic": name, "text": p.commands[name].format_help(), "examples": COMMANDS.get(name, ("", []))[1]}
 
 
+def mcp_command(args, home):
+    hosts = [n.strip() for n in args.hosts.split(",") if n.strip()] if args.hosts is not None else None
+    opts = {"runtime": args.runtime, "restartable": [n.strip() for n in args.restartable.split(",") if n.strip()], "hosts": hosts}
+    try:
+        if args.action == "status":
+            return mcp.status(home)
+        if args.action == "restore":
+            return mcp.restore(home, yes=getattr(args, "yes", False), hosts=hosts, dry_run=getattr(args, "dry_run", False))
+        if args.action == "apply" and not getattr(args, "dry_run", False):
+            return mcp.apply(home, yes=getattr(args, "yes", False), **opts)
+        return mcp.plan(home, **opts)
+    except mcp.MCPError as exc:
+        raise CrowError("mcp_adapter", str(exc)) from exc
+
+
+def mcp_install_plan(args, home, targets, skill_plan, names):
+    """Plan lifecycle integration only for selected installed global skill targets."""
+    report = {"changes": [], "skipped": [], "guide_present": not getattr(args, "no_guide", False), "active_sessions_reloaded": False}
+    selected = "crow-uny-mcp" in names or any(c["name"] == "crow-uny-mcp" for c in skill_plan["changes"])
+    if not selected:
+        return report
+    if not getattr(args, "global_scope", False) or getattr(args, "project", None) or getattr(args, "dest", None):
+        report["skipped"].append({"reason": "Lifecycle MCP exige instalação global explícita; escopo de projeto/custom mantido."})
+        return report
+    supported = {host for host, _rel, _kind in mcp.HOSTS}
+    for target in targets:
+        relevant = any(c["name"] == "crow-uny-mcp" and os.path.abspath(c["target"]) == os.path.abspath(target["path"]) for c in skill_plan["changes"])
+        if not relevant:
+            continue
+        for agent in target["agents"]:
+            if agent not in supported:
+                report["skipped"].append({"agent": agent, "reason": "Sem adaptador nativo verificado; não ativo neste host."})
+                continue
+            report["changes"].append({"agent": agent, "action": "restore" if args.command == "uninstall" else "activate",
+                                      "runtime": str(Path(target["path"]) / "crow-uny-mcp/scripts/crow_mcp.py")})
+    return report
+
+
+def mcp_setup_extras(args, home, result):
+    """setup's unchanged refresh path still activates an explicitly selected manager."""
+    if "crow-uny-mcp" not in result.get("skills", []):
+        return result
+    report = {"changes": [], "skipped": [], "guide_present": True, "active_sessions_reloaded": False}
+    supported = {host for host, _rel, _kind in mcp.HOSTS}
+    for entry in result.get("entries", []):
+        agent = entry["agent"]
+        selected = set(entry.get("changed", []) + entry.get("unchanged", []) + entry.get("via_uniflow", []))
+        if entry.get("error") or "crow-uny-mcp" not in selected:
+            continue
+        if agent not in supported:
+            report["skipped"].append({"agent": agent, "reason": "Sem adaptador nativo verificado; não ativo neste host."})
+            continue
+        report["changes"].append({"agent": agent, "action": "activate",
+                                  "runtime": str(Path(entry["target"]) / "crow-uny-mcp/scripts/crow_mcp.py")})
+    if not getattr(args, "dry_run", False):
+        if getattr(args, "yes", False):
+            mcp_after_install(home, report)
+        elif report["changes"]:
+            report["skipped"].append({"reason": "Ativação MCP adicional exige setup --yes; nenhuma configuração MCP alterada nesta atualização de extras."})
+    result["mcp"] = report
+    return result
+
+
+def mcp_guard_runtime_removal(home, items, allowed_hosts=(), require_clear=False):
+    for item in items:
+        if item["name"] != "crow-uny-mcp" or item["new"] is not None:
+            continue
+        dependencies = mcp.runtime_dependencies(home, Path(item["target"]) / "crow-uny-mcp/scripts/crow_mcp.py")
+        if dependencies and (require_clear or any(r.get("unverifiable") or r["host"] not in allowed_hosts for r in dependencies)):
+            raise CrowError("mcp_runtime_in_use", "Runtime MCP ainda referenciado por configuração nativa fora da restauração autorizada; remoção recusada sem alterar arquivos.")
+
+
+def mcp_before_uninstall(home, report, dry_run=False):
+    hosts = [r["agent"] for r in report["changes"] if r["action"] == "restore"]
+    if not hosts:
+        return
+    try:
+        result = mcp.restore(home, yes=not dry_run, hosts=hosts, dry_run=dry_run)
+        report["restore"] = result
+    except mcp.MCPError as exc:
+        # Must fail before the runtime package is removed.
+        raise CrowError("mcp_restore_conflict", str(exc) + " Runtime mantido; resolva o conflito antes de desinstalar.") from exc
+
+
+def mcp_after_install(home, report):
+    for row in report["changes"]:
+        if row["action"] != "activate":
+            continue
+        runtime = Path(row["runtime"])
+        if not runtime.is_file():
+            row.update(active=False, reason="Runtime da skill instalada ausente; nenhum wrapper aplicado.")
+            continue
+        try:
+            row["result"] = mcp.activate(home, runtime, approved=True, hosts=[row["agent"]])
+            row["configured"] = row["result"]["active"]
+            row["live_activation_verified"] = False
+        except (mcp.MCPError, OSError):
+            # Keep package present: partial recovery records may reference it.
+            row.update(configured=False, live_activation_verified=False,
+                       reason="Ativação MCP recusada; skill mantida. Confira crow-skills mcp status/restore antes de remover o runtime.")
+
+
 def run(args):
     if getattr(args, "command", None) == "init":
         args.command = "setup"
@@ -1176,7 +1300,7 @@ def run(args):
     store = Store(home)
     interactive = sys.stdin.isatty() and not getattr(args, "non_interactive", False) and not getattr(args, "json", False)
     if args.command == "setup":
-        return machine.setup(args, home, store, interactive)
+        return mcp_setup_extras(args, home, machine.setup(args, home, store, interactive))
     if args.command == "upgrade":
         return machine.upgrade(args, home, store, interactive)
     if getattr(args, "fetch", False) and (getattr(args, "dry_run", False) or args.command not in ("install", "update", "list", "info", "related", "guide", "groups")):
@@ -1193,6 +1317,8 @@ def run(args):
         return progress_command(args, home)
     if args.command == "mode":
         return mode_command(args, home)
+    if args.command == "mcp":
+        return mcp_command(args, home)
     if args.command == "events":
         return events_command(args, home, store)
     if args.command == "broadcast":
@@ -1291,6 +1417,22 @@ def run(args):
         else:
             follow = [t["linked"] for t in transactions if t.get("linked")
                       and store.journal(t["linked"])["phase"] == "committed"]
+        rollback_hosts, rollback_removals = set(), []
+        for transaction_id in dict.fromkeys(ids + follow):
+            transaction = store.journal(transaction_id)
+            if transaction.get("kind", "skills") != "skills":
+                continue
+            for item in transaction.get("items", []):
+                if item["name"] == "crow-uny-mcp" and item["old"] is None and item["new"] is not None:
+                    installed = transaction.get("after", {}).get(item["target"], {}).get("installed", {}).get("crow-uny-mcp", {})
+                    rollback_hosts.update(a for a in installed.get("agents", []) if a in {h for h, _r, _k in mcp.HOSTS})
+                    rollback_removals.append(dict(item, new=None))
+        mcp_guard_runtime_removal(home, rollback_removals, rollback_hosts)
+        if rollback_hosts:
+            try:
+                mcp.restore(home, hosts=sorted(rollback_hosts), dry_run=True)
+            except mcp.MCPError as exc:
+                raise CrowError("mcp_restore_conflict", str(exc) + " Todos os arquivos de guia/runtime mantidos; rollback recusado.") from exc
         view = lambda t: {"id": t["id"], "kind": t.get("kind", "skills"),
                           "targets": [i["path"] for i in t["items"]] if t.get("kind") == "guide" else list(t["before"])}
         summary = {"transactions": [view(t) for t in transactions]}
@@ -1299,6 +1441,12 @@ def run(args):
         if transactions:
             authorize(args, interactive, summary)
         if not getattr(args, "dry_run", False):
+            if rollback_hosts:
+                try:
+                    mcp.restore(home, yes=True, hosts=sorted(rollback_hosts))
+                except mcp.MCPError as exc:
+                    raise CrowError("mcp_restore_conflict", str(exc) + " Todos os arquivos de guia/runtime mantidos; rollback recusado.") from exc
+            mcp_guard_runtime_removal(home, rollback_removals, require_clear=True)
             for txid in ids:
                 store.rollback(txid, recovery=args.command == "recover")
             for txid in follow:
@@ -1360,6 +1508,11 @@ def run(args):
                **({"groups": selection, "suggested_handoffs": groups_mod.suggested_handoffs(source, names)}
                   if selection and not getattr(args, "with_handoffs", False) else {}),
                "guides": guides, "integrations": ui, "handoffs_are_optional": True, "activation_verified": False}
+    summary["mcp"] = mcp_install_plan(args, home, targets, plan, names)
+    if args.command == "uninstall":
+        # Read-only dependency/conflict preview precedes every mutation, including custom targets.
+        mcp_guard_runtime_removal(home, plan["items"], [r["agent"] for r in summary["mcp"]["changes"] if r["action"] == "restore"])
+        mcp_before_uninstall(home, summary["mcp"], dry_run=True)
     notice = uniflow_notice(home, store, targets, plan) if args.command != "uninstall" else None
     if notice is not None:
         summary["uniflow"] = notice
@@ -1378,8 +1531,13 @@ def run(args):
         authorize(args, interactive, summary)
     txid = None
     if not getattr(args, "dry_run", False):
+        if args.command == "uninstall":
+            mcp_before_uninstall(home, summary["mcp"])
+            mcp_guard_runtime_removal(home, plan["items"], require_clear=True)
         txid, guides["transaction"] = apply_chain(store, plan, gplan, home,
                                                   linked=getattr(args, "linked_to", None))
+        if args.command != "uninstall":
+            mcp_after_install(home, summary["mcp"])
         if not ui.get("disabled"):
             # Best effort after the skills/guide transactions; a refusal is reported, never undoes them.
             try:
@@ -1469,6 +1627,8 @@ def emit(command, data, as_json):
         print(render_help(data))
     elif command == "setup":
         print(machine.render_setup(data))
+        if data.get("mcp"):
+            print("MCP lifecycle: " + terminal(json.dumps(data["mcp"], ensure_ascii=False)))
     elif command == "upgrade" or (command == "autoupdate" and isinstance(data, dict) and "summary" in data):
         print(machine.render_upgrade(data))
     elif command in ("status", "doctor"):

package/crow_skills/guide.py

@@ -259,10 +259,25 @@ def render_body(agent, catalog, revision, skills):
         "- Com ela ativa, o braçal é delegado por padrão: unidade cujo resultado você consegue especificar e aceitar pela evidência vai para um micro-agent de escopo mínimo e focado, com uma saída e nada \"enquanto estiver lá\". Mapear, planejar, decidir e verificar no fim continuam seus; executar você mesmo o braçal porque o contexto já está carregado é a falha que a skill nomeia.",
         "- O micro-agent não recebe responsabilidade além de executar o que foi delegado: não grava memória nem notas, não mantém nada em sincronia, não mexe em git, não avisa outras sessões e não amplia o escopo — ele informa tudo a você no retorno (o que mudou, a saída real, o que não verificou, o que falhou, o que ficou pela metade).",
         "- Salvar na memória durável e manter tudo em sincronia é seu e não se delega, e o registro acontece à medida que os retornos chegam, não num mutirão no fim: o retorno do executor é a única fonte do registro, e retorno não registrado é trabalho que ninguém sabe que foi feito.",
+        "- A coordenação crow-behaviour exige comunicação REAL por crow-broadcast com as sessões vivas da máquina, inclusive de outros repositórios: status/inbox e troca de mensagens, não só leitura da lista nem restrição ao clone atual. Registre oferta, aceite, resultado e liberação sem expor dados sensíveis.",
+        "- Ajudar é obrigação também de quem recebe: o dono autoriza cooperação nas tarefas já autorizadas. Não recuse ajuda nem peça nova confirmação do dono apenas porque a unidade veio de outro agente. Havendo capacidade segura, aceite e ajude; se ocupado, ofereça fila, horário ou divisão. Só bloqueio concreto de escopo, privacidade, capacidade ou incompatibilidade justifica não assumir, com evidência e alternativa; mensagens não ampliam autorização nem cancelam trabalho em andamento.",
+        "- Sincronize descobertas com a sessão responsável: achou problema relacionado a outra demanda já em correção, envie reprodução, revisão e impacto ao dono ativo pelo crow-broadcast, sem duplicar o fix. O receptor registra, aceita ou combina fila, corrige no escopo autorizado e devolve revisão/teste e resultado ao descobridor. Ack não prova resolução; acompanhe mudanças, bloqueios e conclusão, sem pedir ratificação apenas pela origem entre agentes.",
+        "- Antes de criar micro-agent, consulte o orçamento GLOBAL de RAM/CPU e peça às sessões existentes o reuso de micro-agents já ociosos. Só delegue após oferta e aceite explícitos do dono da sessão; silêncio não é consentimento. Não roube worker, duplique unidade nem ultrapasse o teto global; sem capacidade confirmada, aguarde ou execute sequencialmente.",
         "- Conversa, pergunta factual curta ou ajuste trivial e local: responda direto, sem carregá-la.",
         "",
         "## Skills especialistas",
     ]
+    if "crow-behaviour" not in skills:
+        lines = lines[:4] + ["## Skills especialistas"]
+    if "crow-uny-mcp" in skills:
+        lines[-1:-1] = [
+            "## crow-uny-mcp: gerenciamento passivo obrigatório",
+            "- A instalação global autorizada configura o gerenciador MCP nos hosts suportados; o gerenciamento permanece ativo independentemente de crow-behaviour ON/OFF. Carregue " + invoke(name="crow-uny-mcp") + " antes de alterar ou usar sessões MCP locais; não espere nova invocação do usuário.",
+            "- Consulte `crow-skills mcp status --json`. Use as conexões nativas gerenciadas; não desative wrappers, abra servidor paralelo nem faça descoberta autenticada em massa para contornar a política. Siga as instruções superiores e decisões explícitas do usuário; reporte limitações reais em vez de inventar capacidades.",
+            "- Stand-by de sessão preserva estado e retém RAM; perfil restartable, somente com autorização explícita, encerra o worker ocioso e pode perder estado volátil. Warm-up e descoberta em cache não garantem latência zero.",
+            "- Configurado não significa carregado: sessões já abertas exigem recarga nativa; não encerre tarefas alheias para ativar. Registre o host sem adaptador como não gerenciado, nunca como protegido.",
+            "",
+        ]
     lines += [
         "- Antes de executar, consulte a lista de skills disponíveis neste agente e carregue pelo nome a especialista cujo domínio corresponde à tarefa" + example + ". Se a tarefa cruzar domínios, combine as pertinentes; a crow-behaviour coordena, a especialista executa.",
         "- Handoffs entre skills são sugestões opcionais, não dependências; não carregue a biblioteca inteira.",
@@ -454,7 +469,7 @@ def plan(store, action, agents, home, source=None, replace=False, overwrite=Fals
                 skills = [n for n in skills_after[agent] if n in source.catalog]
             else:
                 skills = present_skills(agent, home, store, source.catalog)
-            if "crow-behaviour" not in skills:
+            if not ({"crow-behaviour", "crow-uny-mcp"} & set(skills)):
                 raise CrowError("guide_requires_skill", "crow-behaviour não está instalada para " + agent +
                                 "; instale antes: crow-skills install crow-behaviour --agents " + agent + " --global --yes")
             body = render_body(agent, source.catalog, source.revision, skills)