@andespindola/crow-skills 0.38.0 → 0.38.2

package/crow_skills/__init__.py

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

package/crow_skills/bots.py

@@ -179,6 +179,8 @@ def spawn(home, role, brief, cli=None, model=None, owner=None, cwd=None):
         "model": model,
         "owner": owner,
         "cwd": cwd or os.getcwd(),
+        "briefs": [brief],
+        "findings": [],
         "state": "working",
         "spawnedAt": broadcast.now_iso(),
         "lastAssignedAt": broadcast.now_iso(),
@@ -207,7 +209,13 @@ def assign(home, bot_id, brief, owner=None):
     pid, error = _launch(home, record, brief, resume=True)
     if error:
         raise RuntimeError(error)
-    record.update(pid=pid, state="working", brief=brief,
+    # Keep every brief, do not overwrite. The knowledge a bot holds came from
+    # the base agent, so the briefs ARE the record of what it was taught; an
+    # assign that replaced the previous one erased run 1 when run 2 arrived,
+    # and with it the only trace of why the bot knows what it knows.
+    history = list(record.get("briefs") or ([record["brief"]] if record.get("brief") else []))
+    history.append(brief)
+    record.update(pid=pid, state="working", brief=brief, briefs=history[-20:],
                   lastAssignedAt=broadcast.now_iso(),
                   runs=int(record.get("runs") or 0) + 1)
     if owner:
@@ -216,6 +224,46 @@ def assign(home, bot_id, brief, owner=None):
     return record
 
 
+def learned(home, bot_id, note):
+    """Record what a bot REPORTED BACK, as the base agent read it.
+
+    The bot keeps its own context and never touches the vault; only the base
+    agent does. So the findings have to be written down HERE by whoever read
+    the report, or they vanish with the session and the next bot of the same
+    role starts from nothing — paying again for knowledge already bought.
+
+    This is the local, machine-level record. Promoting it to the vault, so the
+    knowledge survives the machine and reaches a second one, stays the base
+    agent's job: the durable note is written through tesus, not from here.
+    """
+    note = (note or "").strip()
+    if not note:
+        raise ValueError("um aprendizado vazio não é aprendizado")
+    data = _load(home)
+    record = next((b for b in data["bots"] if b.get("id") == bot_id), None)
+    if not record:
+        raise ValueError("bot desconhecido: " + str(bot_id))
+    findings = list(record.get("findings") or [])
+    findings.append({"at": broadcast.now_iso(), "note": note})
+    record["findings"] = findings[-50:]
+    _save(home, data)
+    return record
+
+
+def knowledge(home, role):
+    """Everything known about a role, across its bots: the briefs that taught
+    them and the findings they returned. This is what seeds the NEXT bot of the
+    same role instead of briefing it from zero."""
+    role = (role or "").strip().lower()
+    briefs, findings = [], []
+    for b in _load(home)["bots"]:
+        if (b.get("role") or "").strip().lower() != role:
+            continue
+        briefs.extend(b.get("briefs") or ([b["brief"]] if b.get("brief") else []))
+        findings.extend(b.get("findings") or [])
+    return {"role": role, "briefs": briefs, "findings": findings}
+
+
 def release(home, bot_id):
     """Hand a borrowed bot back to its owner."""
     data = _load(home)

package/crow_skills/cli.py

@@ -211,7 +211,7 @@ def parser():
     child.add_argument("--follow", action="store_true", help="tail: transmitir eventos novos em JSONL até Ctrl-C")
     child = command_parser(sub, "bot", [common])
     child.add_argument("action", nargs="?", default="list",
-                       choices=("list", "spawn", "assign", "release", "stop", "prune"))
+                       choices=("list", "spawn", "assign", "release", "stop", "prune", "learned", "knowledge"))
     child.add_argument("target", nargs="?", help="assign/release/stop: id do bot")
     child.add_argument("text", nargs="*", help="assign: o novo briefing")
     child.add_argument("--role", help="spawn: a especialidade do bot (é o que permite reaproveitá-lo)")
@@ -219,6 +219,7 @@ def parser():
     child.add_argument("--cli", default="auto", help="spawn: claude, codex, gemini, devin ou auto (primeiro disponível)")
     child.add_argument("--model", help="spawn: modelo para esta unidade")
     child.add_argument("--lendable-only", action="store_true", help="list: só os ociosos que outra sessão pode pedir emprestado")
+    child.add_argument("--role-of", dest="role_of", help="knowledge: o papel cujo conhecimento acumulado você quer ler")
     child = command_parser(sub, "broadcast", [common])
     child.add_argument("action", nargs="?", default="status", choices=("status", "list", "claim", "release", "watch", "say", "reply", "inbox",
                                                                "thread", "sent", "ack", "feed"))
@@ -582,6 +583,32 @@ def ancestors(limit=16):
     return pids
 
 
+#: The human owner speaking from outside any agent session (desktop app, bare
+#: shell). Deliberately NOT one of hook.HOSTS: it is not an agent and must not
+#: be mistaken for one in the roster or the feed.
+OWNER_HOST = "owner"
+
+
+def sender_owner(args, home, cwd):
+    """Who is SENDING. Same resolution as broadcast_owner, but a caller with no
+    live-agent ancestry is the owner's own console rather than an error.
+
+    A desktop app is reparented to launchd, so it matches no session and
+    broadcast_owner returns None; `say` then dereferenced it into
+    "AttributeError: 'NoneType' object has no attribute 'get'" and the owner
+    could never speak on the channel from outside a terminal. The identity is
+    deterministic so agents can address a reply back to it.
+
+    Scoped to sending ON PURPOSE: claims, inbox, sent and ack keep requiring a
+    real session, because attributing those to a console would be wrong.
+    """
+    found = broadcast_owner(args, home, cwd)
+    if found:
+        return found
+    return {"key": broadcast.session_key(OWNER_HOST, OWNER_HOST, None), "host": OWNER_HOST,
+            "session": None, "detected": "owner"}
+
+
 def broadcast_owner(args, home, cwd):
     """The session that runs this command: --session/--host, else the live session whose CLI pid is an ancestor."""
     live = broadcast.live_sessions(home)
@@ -710,6 +737,14 @@ def bot_command(args, home):
             raise CrowError("usage", str(exc))
         out = {"bot": record, "text": "bot " + record["id"] + " (" + record["role"] + ") iniciado em " +
                str(record.get("cli")) + ", pid " + str(record.get("pid")) + " — você não ficou bloqueado"}
+        known = bots.knowledge(home, getattr(args, "role", "") or "")
+        if known["briefs"] or known["findings"]:
+            # Informs, does not inject: silently prepending it would inflate the
+            # brief, which is the very context cost this is meant to protect.
+            out["knowledge"] = {"briefs": len(known["briefs"]), "findings": len(known["findings"])}
+            out["text"] += ("\nJá há conhecimento deste papel: " + str(len(known["briefs"])) + " briefing(s) e " +
+                            str(len(known["findings"])) + " achado(s). Leia com `bot knowledge --role-of " +
+                            (getattr(args, "role", "") or "") + "` e inclua no briefing o que valer.")
         if free:
             # Not a refusal: the decision is the caller's, but spending a new
             # process while an idle specialist sits there is the waste this
@@ -736,6 +771,29 @@ def bot_command(args, home):
             raise CrowError("usage", str(exc))
         return {"bot": record, "text": "bot " + record["id"] + " " +
                 ("devolvido ao dono" if action == "release" else "encerrado")}
+    if action == "learned":
+        # The bot keeps its own context and never writes to the vault; whoever
+        # read its report records the finding here, or it dies with the session.
+        note = " ".join(getattr(args, "text", []) or []).strip()
+        if not getattr(args, "target", None) or not note:
+            raise CrowError("usage", "learned precisa do id do bot e do que ele reportou.")
+        try:
+            record = bots.learned(home, args.target, note)
+        except ValueError as exc:
+            raise CrowError("usage", str(exc))
+        return {"bot": record,
+                "text": "registrado no bot " + record["id"] + " (" + str(len(record.get("findings") or [])) +
+                        " achado(s)). Isto é local: promova ao vault o que for durável."}
+    if action == "knowledge":
+        role = getattr(args, "role_of", None) or getattr(args, "target", None)
+        if not role:
+            raise CrowError("usage", "knowledge precisa do papel: --role-of <papel>.")
+        data = bots.knowledge(home, role)
+        n_b, n_f = len(data["briefs"]), len(data["findings"])
+        return {**data,
+                "text": ("papel \"" + data["role"] + "\": " + str(n_b) + " briefing(s) e " + str(n_f) +
+                         " achado(s) acumulados" if n_b or n_f else
+                         "papel \"" + data["role"] + "\": nada acumulado ainda")}
     if action == "prune":
         return bots.prune(home)
     raise CrowError("usage", "ação de bot desconhecida: " + str(action))
@@ -819,7 +877,9 @@ def broadcast_command(args, home):
             raise CrowError("not_found", "Nenhuma mensagem endereçada a esta sessão com esse(s) id(s) (expirada, inexistente, ou enviada por você).")
         return {"schema": broadcast.MESSAGES_SCHEMA, "messages": acked,
                 "text": "leitura confirmada: " + ", ".join(str(m.get("id")) for m in acked)}
-    owner = broadcast_owner(args, home, cwd)
+    # Sending is the one path where a caller outside any agent session is
+    # legitimate: it is the owner talking from their own console.
+    owner = sender_owner(args, home, cwd) if action in ("say", "reply") else broadcast_owner(args, home, cwd)
     if action in ("say", "reply"):
         reply_to = getattr(args, "reply_to", None)
         targets = list(args.targets)
@@ -833,6 +893,14 @@ def broadcast_command(args, home):
             ttl = broadcast.parse_ttl(args.ttl) if args.ttl else None
         except ValueError:
             raise CrowError("usage", "--ttl inválido: use 30m, 2h, 90s (máximo 24h).") from None
+        if not isinstance(owner, dict) or not owner.get("key"):
+            # send_message dereferences the sender inside a dict literal, so a
+            # missing one surfaced as "AttributeError: 'NoneType' object has no
+            # attribute 'get'". Guarded HERE, not in broadcast.py: that module
+            # deliberately carries no dependency on source/CrowError, and adding
+            # one closes an import cycle through hook.py (measured: 52 tests).
+            raise CrowError("usage", "Remetente desconhecido: informe --session/--host "
+                                     "ou envie a partir de uma sessão viva.")
         try:
             record = broadcast.send_message(home, " ".join(targets), owner, to=args.to, ttl=ttl, cwd=cwd,
                                             reply_to=reply_to, wake=not getattr(args, "no_wake", False))

package/crow_skills/mcp.py

@@ -534,15 +534,46 @@ def _identity(pid):
         return None
 
 
+_NAMES_READER = None
+
+
+def _served_names():
+    """pid -> server name, borrowed from the runtime module.
+
+    This module deliberately spawns nothing; it reaches the process table the
+    same way it reaches process identity, through crow_mcp.py.
+    """
+    global _NAMES_READER
+    try:
+        if _NAMES_READER is None:
+            spec = importlib.util.spec_from_file_location("crow_mcp_status_names", _runtime())
+            module = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(module)
+            _NAMES_READER = module.serving_names
+        return _NAMES_READER() or {}
+    except (OSError, ValueError, ImportError, AttributeError):
+        return {}
+
+
 def status(home):
     home = _home(home)
     result = plan(home)
     result.update(action="status", configuredManaged=sum(r["managed"] for r in result["servers"]))
     snapshots = []
     directory = _state(home) / "instances"
+    served = _served_names()
+    stale = 0
     if directory.exists():
         _safe(directory, home)
-        for path in sorted(directory.glob("runtime-*.json"))[:200]:
+        # Newest first. This used to be sorted(glob)[:200], i.e. by FILENAME —
+        # and filenames start with a pid, so the window was arbitrary. Measured
+        # on a real machine: 1402 records on disk, the 200 read held 142
+        # "stopped" and exactly 2 live pids, while `ps` showed 25 live servers.
+        # The observations described mostly dead processes and missed the ones
+        # actually running, which is worse than reporting nothing.
+        files = sorted(directory.glob("runtime-*.json"), key=lambda f: f.stat().st_mtime, reverse=True)
+        stale = max(0, len(files) - 200)
+        for path in files[:200]:
             try:
                 data = json.loads(_read(path, home))
                 # Registry entries are observations, never authority to signal PIDs.
@@ -561,10 +592,28 @@ def status(home):
                     row[live_key] = current is not None
                     row[verified_key] = current is not None and isinstance(recorded, (tuple, list)) and tuple(recorded) == tuple(current)
                 row["source"] = "runtime-reported"
+                # Which server this is, when its process is still around.
+                name = served.get(data.get("pid"))
+                if name:
+                    row["name"] = name
                 snapshots.append(row)
             except (OSError, ValueError):
                 continue
     result["runtimeObservations"] = snapshots
+    # Aggregates, so a caller can say "N of M alive" instead of counting
+    # configured entries and calling it a measurement.
+    alive = sorted({r["name"] for r in snapshots if r.get("name") and r.get("pidAlive")})
+    result["aliveManaged"] = len(alive)
+    result["aliveNames"] = alive
+    result["staleRuntimeRecords"] = stale
+    # Warm-up caches are reported, never deleted here: dropping one forces a
+    # cold start, which is a behaviour change and the owner's decision.
+    try:
+        caches = list(directory.glob("metadata-*.json")) if directory.exists() else []
+        result["warmupCaches"] = len(caches)
+        result["warmupCacheBytes"] = sum(c.stat().st_size for c in caches)
+    except OSError:
+        pass
     result["liveSessionsReloaded"] = False
     return result
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/crow-skills",
-  "version": "0.38.0",
+  "version": "0.38.2",
   "description": "Versioned, complementary agent skills with a protected multi-agent installer",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {

package/release.json

@@ -28,7 +28,7 @@
     "crow_skills/__init__.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "b83bfadfc540ccf6b59b8a1e5f283191d67f3fd4ca1bbd76934a9a45f0917658"
+      "sha256": "7765d89d0c3b7dd8b7d765a61e6a507429a1b2f7710fae47b1d014183fb87e40"
     },
     "crow_skills/__main__.py": {
       "executable": false,
@@ -48,7 +48,7 @@
     "crow_skills/bots.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "4e01f1ae95ce5feed897146ad7c61250494845d2409da009044fce2272df9463"
+      "sha256": "b6119c6974d06152b3462c67368b0fd81d4be389419838eebf3c5007e421a10d"
     },
     "crow_skills/broadcast.py": {
       "executable": false,
@@ -58,7 +58,7 @@
     "crow_skills/cli.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "04f2c49af4888fc5d8a1b28aee4b6b591ee64d2c38ef0f463800f79f7afc28c7"
+      "sha256": "7fdd9af628596e8b7abc111b9277cc6498f5a68e6bdab9421e9aec35c0374ab3"
     },
     "crow_skills/events.py": {
       "executable": false,
@@ -93,7 +93,7 @@
     "crow_skills/mcp.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "a7de34a4f31d6b48ce640fca8b2a9086bd780d3d1d2aa953263e1caaa5c717d2"
+      "sha256": "cf88b7c1fa188eda74c43e6da17198b7b285cc97706d2003ddf7fbe6d8dd5c99"
     },
     "crow_skills/npm_entry.py": {
       "executable": false,
@@ -148,7 +148,7 @@
     "package.json": {
       "executable": false,
       "kind": "file",
-      "sha256": "265a2446df8eae2939ab60a804b38f572ad20c2987b47076fe068d026fccbe46"
+      "sha256": "9c066a2aa80bb4a853faf9ec8c9d5e0887884e4541539f5e61c62dd369c715b3"
     },
     "skills/crow-accessibility/SKILL.md": {
       "executable": false,
@@ -213,7 +213,7 @@
     "skills/crow-behaviour/SKILL.md": {
       "executable": false,
       "kind": "file",
-      "sha256": "f8e0f38537875772027868c2112071f38a8c7a699295bec057bf64e6c2930999"
+      "sha256": "e7f2cdb1acf214e78be8f8b7c27c013e591478df7ac99addd3e0891cbc0d13b9"
     },
     "skills/crow-behaviour/agents/openai.yaml": {
       "executable": false,
@@ -968,10 +968,10 @@
     "skills/crow-uny-mcp/scripts/crow_mcp.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "160c814085dfdbe93e0166f2a773345dd1436f07a63dbf58d447f3f7674dc759"
+      "sha256": "7dd3660097c3afeadb58357939b51da518a4da7cf2d7e684c2618b22f6c4a87b"
     }
   },
-  "revision": "95525c9fb9d566810a61b8465cd7536ce5599c08",
+  "revision": "11982e7c39ba1b449a442f8deb6468d5a27d26f4",
   "schema_version": 1,
-  "version": "0.38.0"
+  "version": "0.38.2"
 }

package/skills/crow-behaviour/SKILL.md

@@ -62,6 +62,7 @@ Quando `crow-model-level` estiver instalada, o nível de cada unidade delegada
 - **O braçal é delegado por padrão, não por escolha sua.** Uma unidade é braçal quando você consegue especificar o resultado e aceitá-lo pela evidência, sem ver o caminho: a edição que você já decidiu, a varredura com critério fechado, a reescrita mecânica, a coleta de evidência, rodar um comando e relatar o que saiu, levantar como uma coisa funciona hoje. Se é preciso decidir no meio do caminho, não é braçal — é desenho, e é seu. Executar você mesmo uma unidade braçal porque "o contexto já está carregado" é a falha característica desta skill: troca o seu contexto, que é o recurso escasso e não se recupera, por trabalho que qualquer executor faria, e o briefing que você economizou custa menos do que o contexto que você gastou.
 - Ao delegar execução, descubra quem é o micro-agent em vez de presumir: `crow_micro.py probe` — com `codex` disponível e autenticado, os micro-agents são do codex; sem ele, são os do próprio CLI. Ao micro-agent vai só o braçal já especificado; mapear, planejar, desenhar e verificar no fim continuam seus. Leia [micro-agents](references/micro-agents.md).
 - **Micro-agent ou bot autônomo: decida pela natureza da demanda, não por hábito.** Resultado que você especifica e aceita pela evidência, dentro do turno, é **micro-agent** — efêmero, você verifica e descarta. Demanda que persiste além do turno, dispara por evento e precisa de estado próprio entre execuções é **bot autônomo** — um processo que sobrevive à sessão, com memória externa própria e gatilho; ele não lembra, relê o que gravou e reconstrói o contexto a cada disparo. Micro-agent é o default; bot só quando a persistência ou o gatilho de evento é a essência da demanda, não um "seria bom ter". Bot e micro-agent usam igualmente o crow-broadcast e a mesma fronteira de autonomia desta skill; o criador continua responsável por ambos, verifica o resultado e age quando qualquer um fica ocioso.
+- **O conhecimento do bot é seu para guardar, não dele.** A memória do bot é apartada e perecível: ela morre com a sessão e envelhece quando ele fica ocioso. O que ele sabe veio de você, no briefing — ele é consumidor do conhecimento, nunca o guardião. Então, antes de criar um bot de um papel que já existiu, **leia o que já foi acumulado** (`crow-skills bot knowledge --role-of <papel>`) e inclua no briefing o que valer, em vez de ensinar de novo o que já foi pago. Quando o bot reporta, **registre o que ele devolveu** (`crow-skills bot learned <id> "<o que apurou>"`): o retorno não registrado é conhecimento que ninguém mais tem. Esse registro é local e mecânico; **promover ao durável é seu**, pela memória do dono, porque o bot não toca o vault — só você toca. Destile, não acumule: nota que cresce a cada briefing recria, em outro lugar, o custo de contexto que a delegação existe para cortar. E trate o retorno como alegação a julgar antes de virar registro, não como verdade.
 - Leia [adaptação ao runtime](references/orchestration.md) ao escolher workflow, subagentes ou execução sequencial. Não presuma nomes de ferramentas, paralelismo ou suporte a isolamento. Se o host exigir opt-in explícito do usuário para orquestração programável, esta skill não é esse opt-in: peça o opt-in da ferramenta, nunca permissão para aplicar esta skill, e sem ele siga com subagentes ou sequencialmente.
 
 ### 2. Planeje para produzir e verificar

package/skills/crow-uny-mcp/scripts/crow_mcp.py

@@ -133,6 +133,72 @@ if sys.platform == "darwin":
         pass
 
 
+def prune_runtime_records(state_dir, keep_hours=24):
+    """Drop runtime records whose process is gone and that are no longer fresh.
+
+    Nothing ever removed these. Measured on a real machine: 1402 records, 1148
+    of them older than a day. They are tiny (0.4 MB), but the status reader
+    takes a bounded window over them, so the dead ones crowded out every live
+    server — it reported 2 live pids while 25 servers were running. Pruned by
+    whoever creates them; a reader must stay read-only. Metadata caches are
+    deliberately NOT touched: discarding a warm-up cache changes behaviour by
+    forcing cold starts, which is the owner's call, not hygiene.
+    """
+    removed = 0
+    try:
+        directory = Path(state_dir)
+        cutoff = time.time() - keep_hours * 3600
+        for path in directory.glob("runtime-*.json"):
+            try:
+                if path.stat().st_mtime > cutoff:
+                    continue
+                data = json.loads(path.read_text())
+                pid = data.get("pid")
+                if isinstance(pid, int) and not isinstance(pid, bool) and process_identity(pid) is not None:
+                    continue  # still alive: not ours to remove
+                path.unlink()
+                removed += 1
+            except (OSError, ValueError):
+                continue
+    except OSError:
+        return removed
+    return removed
+
+
+def serving_names():
+    """pid -> public name of every live `crow_mcp.py serve` on this machine.
+
+    The runtime registry records state and pids but not the server's NAME, so a
+    reader could only report anonymous liveness. The name is on the command
+    line; this is the one place allowed to look, because the status module
+    deliberately spawns nothing and borrows helpers from here.
+    """
+    names = {}
+    try:
+        out = subprocess.run(["/bin/ps", "-axo", "pid=,command="],
+                             capture_output=True, text=True, timeout=10)
+    except (OSError, subprocess.SubprocessError):
+        return names
+    if out.returncode != 0:
+        return names
+    for line in out.stdout.splitlines():
+        text = line.strip()
+        if "crow_mcp.py" not in text or " serve" not in text:
+            continue
+        head, _, rest = text.partition(" ")
+        try:
+            pid = int(head)
+        except ValueError:
+            continue
+        parts = rest.split()
+        if "--name" in parts:
+            try:
+                names[pid] = parts[parts.index("--name") + 1]
+            except IndexError:
+                continue
+    return names
+
+
 def process_identity(pid):
     """Kernel start identity, not PID alone or second-granularity ps time."""
     try:
@@ -173,6 +239,9 @@ class Proxy:
         self.input_fd, self.output_fd = input_fd, output_fd
         self.store = PrivateStore(options.state_dir)
         self.registry = "runtime-" + str(os.getpid()) + "-" + uuid.uuid4().hex + ".json"
+        # Clean up after the ones that came before: this is the layer that
+        # creates the records, so it is the layer that retires them.
+        prune_runtime_records(options.state_dir)
         self.sel = selectors.DefaultSelector()
         self.sel.register(input_fd, selectors.EVENT_READ, "host")
         os.set_blocking(output_fd, False)