@andespindola/crow-skills 0.38.0 → 0.38.1

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.1"

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/crow-skills",
-  "version": "0.38.0",
+  "version": "0.38.1",
   "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": "5c2d124b8f54ae50df371268045f54ba0e08e8cdb27f2141773bfb80fba661b1"
     },
     "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,
@@ -148,7 +148,7 @@
     "package.json": {
       "executable": false,
       "kind": "file",
-      "sha256": "265a2446df8eae2939ab60a804b38f572ad20c2987b47076fe068d026fccbe46"
+      "sha256": "64e8d706972b11b51c6decc284fa11abb151d87e977e43723eb3849d1f409d87"
     },
     "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,
@@ -971,7 +971,7 @@
       "sha256": "160c814085dfdbe93e0166f2a773345dd1436f07a63dbf58d447f3f7674dc759"
     }
   },
-  "revision": "95525c9fb9d566810a61b8465cd7536ce5599c08",
+  "revision": "b86c3ef157a305468fa37ce18f84cca40dc1b11d",
   "schema_version": 1,
-  "version": "0.38.0"
+  "version": "0.38.1"
 }

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