@andespindola/crow-skills 0.8.0 → 0.9.0

package/README.md

@@ -2,7 +2,7 @@
 
 Skills com escopo explícito, conhecimento especializado preservado e fluxos comuns reutilizáveis.
 
-**Versão 0.8.0** ([mudanças](CHANGELOG.md)): `crow-skills mode on|off` liga e desliga a crow-behaviour em todas as sessões e CLIs (Claude Code, Codex, Gemini CLI, Antigravity, Devin) a partir do próximo prompt, com `/crow on|off` dentro da sessão e o indicador `▸▸ crow on` na status line; a crow-behaviour mostra o progresso como a lista de agentes do host (`● main`, `○ dono  atividade`); `crow-skills events` publica um barramento de eventos dos hooks para terminais; `crow-skills autoupdate on` atualiza o CLI e as skills gerenciadas todo dia e no login. A 0.7.1 trouxe as correções da revalidação no Codex às skills especialistas; a 0.7.0 tornou o Uniflow agente de instalação (`--agents uniflow`); a 0.6.1 passou a mostrar o progresso da crow-behaviour na própria conversa; a 0.6.0 trouxe as regras de entrega das 32 skills especialistas, a partir da [validação no Codex](docs/evaluations/2026-10-26-codex.md).
+**Versão 0.9.0** ([mudanças](CHANGELOG.md)): as skills controlam a memória da máquina: `crow-skills resources` mede memória, pressão e os CLIs de agente em execução e recomenda quantos agentes, jobs pesados e workers rodar em paralelo; a crow-behaviour consulta essa recomendação antes de cada fan-out (sob `warn` reduz, sob `critical` segue sequencial), limita workers de builds e testes, reutiliza um dev server por projeto e encerra o que abriu, e 15 especialistas que sobem processos pesados ganharam a regra correspondente; o hook de prompt e as status lines só avisam quando a máquina está sob pressão. A 0.8.0 trouxe `crow-skills mode on|off`, que liga e desliga a crow-behaviour em todas as sessões e CLIs (Claude Code, Codex, Gemini CLI, Antigravity, Devin) a partir do próximo prompt, com `/crow on|off` dentro da sessão e o indicador `▸▸ crow on` na status line; a crow-behaviour mostra o progresso como a lista de agentes do host (`● main`, `○ dono  atividade`); `crow-skills events` publica um barramento de eventos dos hooks para terminais; `crow-skills autoupdate on` atualiza o CLI e as skills gerenciadas todo dia e no login. A 0.7.1 trouxe as correções da revalidação no Codex às skills especialistas; a 0.7.0 tornou o Uniflow agente de instalação (`--agents uniflow`); a 0.6.1 passou a mostrar o progresso da crow-behaviour na própria conversa; a 0.6.0 trouxe as regras de entrega das 32 skills especialistas, a partir da [validação no Codex](docs/evaluations/2026-10-26-codex.md).
 
 **Reconstrução em andamento.** A primeira versão com 32 contratos genéricos não atende à preservação de capacidades solicitada. Não use esse número nem o mapeamento por categoria como prova de substituição das originais. A revisão passa a abranger cada definição e seus recursos, modos e dependências, sem número fixo de skills ou limite artificial de linhas. Veja [critérios e progresso](docs/reconstruction.md).
 
@@ -30,7 +30,7 @@ Exemplos:
 O pacote de cada skill é somente sua pasta em `skills/`. O [CLI crow-skills](docs/cli.md) instala cópias completas e versionadas em agentes/escopos explícitos, com preview, saída JSON, detecção de conflitos e recuperação. Requer Python 3.10+; Git para fontes em clone, Node 18+ para o launcher npm; mutações em macOS/Linux. A distribuição npm privada `@andespindola/crow-skills` inclui um snapshot completo das skills, sem clone ou hooks que as instalem automaticamente. No [Uniflow](docs/cli.md#uniflow), `--agents uniflow --global` grava as skills no store dele (`~/.config/uniflow/skills`), sem tocar no resto da configuração. Em `--global`, instalar a crow-behaviour também grava o guia aditivo do agente (claude, codex, gemini, devin) para usar as skills; `--no-guide` desliga. As integrações de interface (status lines do Claude Code, do Codex e do Antigravity, hooks do modo crow em cada CLI, comando `/crow`, segmento tmux) seguem o mesmo fluxo, preservando a configuração existente; `--no-integrations` desliga. O [barramento de eventos](docs/events.md) e a atualização automática (`crow-skills autoupdate on`) estão no [CLI](docs/cli.md).
 
 ```sh
-npm install -g @andespindola/crow-skills@0.8.0
+npm install -g @andespindola/crow-skills@0.9.0
 crow-skills mode
 crow-skills progress
 ./bin/crow-skills list

package/crow_skills/__init__.py

@@ -1,3 +1,3 @@
 """Portable, local-first installer for the crow-skills catalogue."""
 
-__version__ = "0.8.0"
+__version__ = "0.9.0"

package/crow_skills/cli.py

@@ -12,6 +12,7 @@ from . import guide
 from . import hook
 from . import integrations
 from . import progress
+from . import resources
 from .agents import AGENTS, destinations, inventory
 from .source import CrowError, Source, valid_name
 from .storage import Store, checked
@@ -77,6 +78,9 @@ def parser():
     child.add_argument("action", nargs="?", default="snapshot", choices=("snapshot", "tail"))
     child.add_argument("--limit", type=int, default=50, help="tail: quantos eventos (padrão 50; 0 = todos os retidos)")
     child.add_argument("--follow", action="store_true", help="tail: transmitir eventos novos em JSONL até Ctrl-C")
+    child = sub.add_parser("resources", parents=[common],
+                           help="Memória, pressão, agentes em execução e paralelismo recomendado (somente leitura)")
+    child.add_argument("--no-processes", action="store_true", help="Não varrer os processos dos CLIs de agente (mais rápido)")
     child = sub.add_parser("autoupdate", parents=[common], help="Atualização diária e no login do crow-skills e das skills gerenciadas")
     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)")
@@ -460,6 +464,10 @@ def run(args):
         return mode_command(args, home)
     if args.command == "events":
         return events_command(args, home, store)
+    if args.command == "resources":
+        data = resources.probe(home, processes=not args.no_processes)
+        data["text"] = resources.render(data)
+        return data
     if args.command == "autoupdate":
         return autoupdate_command(args, home, store, interactive)
     if args.command in ("status", "doctor"):
@@ -586,6 +594,8 @@ def emit(command, data, machine):
     elif command == "progress":
         if data is not None:
             print(data["text"] or "crow: nenhuma execução registrada neste diretório.")
+    elif command == "resources":
+        print(data["text"])
     elif command == "mode":
         print(data["indicator"] + " — " + data["applies"])
     elif command == "events":

package/crow_skills/events.py

@@ -11,7 +11,7 @@ import json
 import sys
 import time
 
-from . import autoupdate, hook, progress
+from . import autoupdate, hook, progress, resources
 from .source import CrowError
 
 SNAPSHOT_SCHEMA = "crow-snapshot/1"
@@ -29,7 +29,7 @@ def ledger_runs(home, cwds):
             runs.append({"id": run["id"], "title": run["title"], "host": run["host"], "cwd": run["cwd"], "status": run["status"],
                          "session": run["session"].get("id"), "path": run["path"], "updatedAt": run.get("updatedAt"),
                          "done": info["done"], "failed": info["failed"], "total": info["total"], "running": info["running"],
-                         "progress": info["progress"],
+                         "progress": info["progress"], "resources": run.get("resources"),
                          "agents": [{"owner": progress.owner_label(u["owner"]), "unit": u["id"], "activity": u["title"]}
                                     for u in run["units"] if u["status"] == "running"]})
     return runs
@@ -54,9 +54,25 @@ def snapshot(home, store):
     except CrowError as exc:
         update = {"enabled": None, "error": exc.code}
     mode = hook.read_mode(home)
+    try:
+        machine = resources_field(home)
+    except Exception:  # noqa: BLE001 - the snapshot never fails because of the probe
+        machine = None
     return {"schema": SNAPSHOT_SCHEMA, "generatedAt": datetime.now(timezone.utc).isoformat(timespec="seconds"),
             "mode": {k: mode[k] for k in ("mode", "updatedAt", "updatedBy", "source")}, "indicator": hook.indicator(mode["mode"]),
-            "sessions": live, "runs": runs, "autoupdate": update}
+            "sessions": live, "runs": runs, "autoupdate": update, "resources": machine}
+
+
+def resources_field(home):
+    """crow-resources/1 subset for terminals: memory, pressure and the recommendation.
+
+    Added in 0.9.0 without changing crow-snapshot/1: consumers that do not know the
+    field ignore it; the field carries its own schema for future changes.
+    """
+    data = resources.probe(home, processes=False, use_cache=True)
+    return {"schema": data["schema"], "generatedAt": data["generatedAt"], "cached": data["cached"],
+            "memory": data["memory"], "pressure": {"level": data["pressure"]["level"], "reasons": data["pressure"]["reasons"]},
+            "recommendation": data["recommendation"], "alert": resources.alert(data), "segment": resources.segment(data)}
 
 
 def render(data, unicode=True):
@@ -75,6 +91,12 @@ def render(data, unicode=True):
                                      unicode, counts=False)
         lines.append(("✓ " if unicode else "ok ") + str(run["done"]) + "/" + str(run["total"]) + "  " + run["title"])
     update = data["autoupdate"]
+    machine = data.get("resources")
+    if machine and machine.get("alert"):
+        rec = machine["recommendation"]
+        lines.append("")
+        lines.append("memória: " + (machine["segment"] or "") + " · pressão " + machine["pressure"]["level"] + " · " + rec["mode"] +
+                     " (até " + str(rec["maxParallelAgents"]) + " agente(s), " + str(rec["maxParallelHeavyJobs"]) + " job(s) pesado(s))")
     lines.append("")
     lines.append("autoupdate: " + ("ligado" if update.get("enabled") else "desligado") +
                  ((" · última execução " + str(update["lastRun"]["startedAt"]) + (" ok" if update["lastRun"]["ok"] else " com falha"))

package/crow_skills/hook.py

@@ -13,6 +13,11 @@ permission mode, event type, tool name, counters and timestamps.
 
   crow_hook.py hook --host claude|codex|gemini|agy|devin --event NAME [--home DIR]
   crow_hook.py mode on|off|status [--home DIR] [--by HOST] [--json]
+
+On a prompt event the hook also appends one memory line to the context, only
+when the machine is under pressure or the recommended parallelism is not
+"parallel" (crow_resources.py, copied beside this file; cached for a few
+seconds, so most prompts cost one small file read).
 """
 from datetime import datetime, timezone
 import hashlib
@@ -152,6 +157,53 @@ def context_line(mode):
             "explicitamente neste pedido. Religar: /crow on ou crow-skills mode on.")
 
 
+# --- machine resources ------------------------------------------------------------------
+
+_RESOURCES = None
+
+
+def resources_module():
+    """The resource probe: the package module, or crow_resources.py beside this file.
+
+    Loaded by path because the hooks run with ``python -I`` (the script's directory is
+    not on sys.path). None when it is missing: the hook then adds nothing.
+    """
+    global _RESOURCES
+    if _RESOURCES is None:
+        _RESOURCES = False
+        try:
+            if __package__:
+                from . import resources as module  # type: ignore[attr-defined]
+                _RESOURCES = module
+            else:
+                import importlib.util
+                here = Path(os.path.abspath(__file__)).parent
+                for name in ("crow_resources.py", "resources.py"):
+                    path = here / name
+                    if path.is_file() and not path.is_symlink():
+                        spec = importlib.util.spec_from_file_location("crow_resources", path)
+                        module = importlib.util.module_from_spec(spec)
+                        # Bytecode is cached in __pycache__ beside it (~5 ms less per prompt);
+                        # the integrations uninstall removes that directory with the scripts.
+                        spec.loader.exec_module(module)
+                        _RESOURCES = module
+                        break
+        except Exception:  # noqa: BLE001 - a broken probe never breaks the hook
+            _RESOURCES = False
+    return _RESOURCES or None
+
+
+def resource_hint(home):
+    """The one-line memory hint, or None (no pressure, no probe, or any failure)."""
+    module = resources_module()
+    if module is None:
+        return None
+    try:
+        return module.hint(module.probe(home, processes=False, use_cache=True))
+    except Exception:  # noqa: BLE001
+        return None
+
+
 # --- event bus ----------------------------------------------------------------------------
 
 def append_event(home, event):
@@ -472,7 +524,11 @@ def handle(host, raw, payload, home, env=None):
         update_session(home, dict(stamped, event="other"), {"modeSeen": stamp, "mode": current["mode"]})
     if raw == "SessionStart":
         return output_for(host, raw, system=system) if system else None
-    return output_for(host, raw, context=context_line(current["mode"]), system=system)
+    context = context_line(current["mode"])
+    memory = resource_hint(home)
+    if memory:
+        context += "\n" + memory
+    return output_for(host, raw, context=context, system=system)
 
 
 def update_metrics(home, host, payload):

package/crow_skills/integrations.py

@@ -55,6 +55,7 @@ OWNERS = {"claude-statusline": ("claude",), "claude-hooks": ("claude",), "claude
           "gemini-hooks": ("gemini",), "gemini-command": ("gemini",), "agy-hooks": ("gemini",), "agy-statusline": ("gemini",),
           "devin-hooks": ("devin",), "tmux-status": ("claude", "codex", "gemini", "devin")}
 HOOK_SCRIPT = "crow_hook.py"
+RESOURCES_SCRIPT = "crow_resources.py"
 COMMAND_HEADER = "Gerenciado por crow-skills (comando /crow). Não edite; use crow-skills integrations."
 BEGIN = "# >>> crow-skills integrations (gerenciado; use crow-skills integrations uninstall) >>>"
 END = "# <<< crow-skills integrations <<<"
@@ -117,6 +118,37 @@ def hook_source():
     return (Path(__file__).resolve().parent / "hook.py").read_bytes()
 
 
+def resources_script_path(store):
+    return root(store) / RESOURCES_SCRIPT
+
+
+def resources_source():
+    return (Path(__file__).resolve().parent / "resources.py").read_bytes()
+
+
+def remove_bytecode(store):
+    """__pycache__ beside the copied scripts (written when the status line imports crow_hook):
+    removed with them, only when it holds nothing but their bytecode."""
+    cache = root(store) / "__pycache__"
+    if cache.is_symlink() or not cache.is_dir():
+        return
+    names = ("crow_progress.", "crow_hook.", "crow_resources.")
+    entries = list(cache.iterdir())
+    if all(e.is_file() and not e.is_symlink() and e.name.startswith(names) and e.suffix == ".pyc" for e in entries):
+        try:
+            for entry in entries:
+                entry.unlink()
+            cache.rmdir()
+        except OSError:
+            pass  # a hook wrote bytecode meanwhile: the directory stays, nothing else is touched
+
+
+def scripts(store):
+    """(installed path, source bytes) of every script the hooks and status lines run."""
+    return ((script_path(store), script_source()), (hook_script_path(store), hook_source()),
+            (resources_script_path(store), resources_source()))
+
+
 def quoted_ok(*paths):
     return all(not re.search(r"[\"'\\$`\n]", str(p)) for p in paths)
 
@@ -825,7 +857,7 @@ def sync(store, home, wanted, dry_run=False, python=None):
     with (nullcontext() if dry_run else store.lock()):
         if not dry_run and any(set(OWNERS[n]) & set(wanted) for n in NAMES):
             private_dir(root(store))
-            for script, source in ((script_path(store), script_source()), (hook_script_path(store), hook_source())):
+            for script, source in scripts(store):
                 if not script.exists() or sha(script.read_bytes()) != sha(source):
                     write_atomic(checked(script), source, 0o644)
         # Removals first and in reverse order, then installs in order: two integrations that
@@ -859,9 +891,10 @@ def sync(store, home, wanted, dry_run=False, python=None):
             if after != state:
                 atomic_json(state_path(store), after)
             if not after["integrations"]:
-                for script in (script_path(store), hook_script_path(store)):
+                for script in (script_path(store), hook_script_path(store), resources_script_path(store)):
                     if script.exists():
                         script.unlink()
+                remove_bytecode(store)
     for key in ("changes", "skipped"):
         report[key].sort(key=lambda c: NAMES.index(c["integration"]) if c["integration"] in NAMES else 99)
     report["dry_run"] = dry_run

package/crow_skills/progress.py

@@ -83,7 +83,7 @@ def validate(data):
            "status": data.get("status") if data.get("status") in ("running",) + FINISHED else "running",
            "startedAt": data.get("startedAt"), "updatedAt": data.get("updatedAt"), "endedAt": data.get("endedAt"),
            "session": data.get("session") if isinstance(data.get("session"), dict) else {},
-           "phases": [], "units": []}
+           "phases": [], "units": [], "resources": resources_decision(data.get("resources"))}
     for phase in phases:
         if isinstance(phase, dict) and isinstance(phase.get("id"), str):
             run["phases"].append({"id": phase["id"], "title": safe(phase.get("title") or phase["id"]),
@@ -107,6 +107,42 @@ def validate(data):
     return run
 
 
+RESOURCE_MODES = ("parallel", "reduced", "sequential")
+RESOURCE_LEVELS = ("normal", "warn", "critical", "unknown")
+RESOURCE_SOURCES = ("probe", "os", "assumed")
+
+
+def resources_decision(value):
+    """The optional run-level ``resources`` field (0.9.0): the parallelism decision recorded
+    before a fan-out. Ledgers without it, or with an invalid one, read as None."""
+    if not isinstance(value, dict) or value.get("mode") not in RESOURCE_MODES:
+        return None
+
+    def count(key):
+        number = value.get(key)
+        return number if isinstance(number, int) and not isinstance(number, bool) and 0 <= number <= 256 else None
+
+    return {"mode": value["mode"], "pressure": value.get("pressure") if value.get("pressure") in RESOURCE_LEVELS else None,
+            "source": value.get("source") if value.get("source") in RESOURCE_SOURCES else None,
+            "maxParallelAgents": count("maxParallelAgents"), "maxParallelHeavyJobs": count("maxParallelHeavyJobs"),
+            "maxWorkersPerJob": count("maxWorkersPerJob"),
+            "checkedAt": value.get("checkedAt") if isinstance(value.get("checkedAt"), str) else None,
+            "note": safe(value.get("note") or "", 160)}
+
+
+def resources_line(decision, unicode=True):
+    if not decision:
+        return ""
+    parts = [decision["mode"]]
+    if decision["maxParallelAgents"] is not None:
+        parts.append(("≤" if unicode else "<=") + str(decision["maxParallelAgents"]) + " agente(s)")
+    if decision["maxParallelHeavyJobs"] is not None:
+        parts.append(("≤" if unicode else "<=") + str(decision["maxParallelHeavyJobs"]) + " job(s) pesado(s)")
+    if decision["pressure"]:
+        parts.append("pressão " + decision["pressure"])
+    return "recursos: " + (" · " if unicode else " - ").join(parts) + (" (" + decision["note"] + ")" if decision["note"] else "")
+
+
 def load(path):
     path = Path(path)
     if path.is_symlink() or not path.is_file() or path.stat().st_size > MAX_LEDGER:
@@ -515,6 +551,8 @@ def render(run, usage=None, now=None, color=False, unicode=True, width=20):
              bar(info["progress"], width, unicode) + " " + str(int(info["progress"] * 100)).rjust(3) + "%  " +
              str(info["done"]) + "/" + str(info["total"]) + " unidades" +
              (" - " + str(info["failed"]) + " falha(s)" if info["failed"] else "") + "  " + token_text(usage, unicode)]
+    if run.get("resources"):
+        lines.append(paint("dim", resources_line(run["resources"], unicode)))
     lines += ["", *agent_rows(run, unicode, counts=False), ""]
     phase_ids = [p["id"] for p in run["phases"]]
     groups = [(p, [u for u in run["units"] if u["phase"] == p["id"]]) for p in run["phases"]]
@@ -649,6 +687,18 @@ def mode_text(home, unicode=True):
         return ""
 
 
+def memory_text(home, unicode=True):
+    """'mem ▲ 85% ×2' when the machine is under pressure or parallelism is reduced; else ''."""
+    hook = hook_module()
+    module = hook.resources_module() if hook is not None and hasattr(hook, "resources_module") else None
+    if module is None:
+        return ""
+    try:
+        return module.segment(module.probe(home, processes=False, use_cache=True), unicode)
+    except Exception:  # noqa: BLE001 - the probe never breaks a status line
+        return ""
+
+
 def statusline(home, stdin_text, chain=None, host="claude"):
     """Status line for Claude Code and Antigravity (agy).
 
@@ -684,7 +734,7 @@ def statusline(home, stdin_text, chain=None, host="claude"):
         except (OSError, subprocess.SubprocessError):
             previous = ""
     run = select(discover(cwd, home), cwd, strict=True, session=session)
-    parts = [p for p in (mode_text(home),) if p]
+    parts = [p for p in (mode_text(home), memory_text(home)) if p]
     rows = []
     if active(run):
         if run["host"] == "claude" and host == "claude" and not run["session"].get("id") and session:
@@ -711,12 +761,12 @@ def statusline(home, stdin_text, chain=None, host="claude"):
 
 
 def tmux_segment(home, cwd):
-    mode = mode_text(home)
+    head = " · ".join(p for p in (mode_text(home), memory_text(home)) if p)
     run = select(discover(cwd, home), cwd, strict=True)
     if not active(run):
-        return mode
+        return head.replace("#", "##")
     text = compact(run, tokens(run, home), unicode=True, width=8)
-    return ((mode + " · " if mode else "") + text).replace("#", "##")
+    return ((head + " · " if head else "") + text).replace("#", "##")
 
 
 def main(argv=None):