@andespindola/crow-skills 0.37.0 → 0.38.1

package/crow_skills/__init__.py

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

package/crow_skills/autoupdate.py

@@ -115,12 +115,23 @@ def real_home(home):
 # --- scheduler files ---------------------------------------------------------------------------
 
 def search_path(launcher):
-    dirs = [os.path.dirname(launcher)]
+    """PATH for the scheduled run.
+
+    Order matters and used to be wrong: directories discovered with
+    shutil.which were appended before the curated list, so on a Mac with
+    Homebrew Python the plist ended up with /usr/bin AHEAD of
+    /opt/homebrew/bin. Under launchd that resolves python3 to the system 3.9,
+    and the launcher aborts with "Python 3.10+ é necessário" — which is why the
+    agent fired daily and failed silently for days. The curated directories now
+    come first, and CROW_SKILLS_PYTHON (see scheduler_files) pins the
+    interpreter outright so no PATH ordering can break it again.
+    """
+    dirs = [os.path.dirname(launcher), "/opt/homebrew/bin", "/usr/local/bin"]
     for tool in ("node", "python3", "git", "brew", "npm"):
         found = shutil.which(tool)
         if found:
             dirs.append(os.path.dirname(found))
-    dirs += ["/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin"]
+    dirs += ["/usr/bin", "/bin"]
     return ":".join(dict.fromkeys(d for d in dirs if d))
 
 
@@ -130,7 +141,13 @@ def scheduler_files(kind, store, home, launcher):
     args = [launcher, "autoupdate", "run", "--yes", "--json"]
     if kind == "launchd":
         plist = {"Label": LABEL, "ProgramArguments": args, "RunAtLoad": True, "StartCalendarInterval": DAILY,
-                 "EnvironmentVariables": {"PATH": search_path(launcher)}, "StandardOutPath": log, "StandardErrorPath": log,
+                 "EnvironmentVariables": {"PATH": search_path(launcher),
+                                          # Pin the interpreter: this process is
+                                          # running on it, so it satisfies the
+                                          # launcher's 3.10+ requirement by
+                                          # construction, whatever PATH holds.
+                                          "CROW_SKILLS_PYTHON": sys.executable},
+                 "StandardOutPath": log, "StandardErrorPath": log,
                  "ProcessType": "Background", "LowPriorityIO": True, "Nice": 10}
         return {Path(home) / "Library" / "LaunchAgents" / (LABEL + ".plist"): plistlib.dumps(plist, sort_keys=True)}
     if kind == "systemd":
@@ -139,7 +156,9 @@ def scheduler_files(kind, store, home, launcher):
         command = " ".join('"' + a + '"' if " " in a else a for a in args)
         base = Path(home) / ".config" / "systemd" / "user"
         service = (HEADER + "\n[Unit]\nDescription=crow-skills autoupdate\n\n[Service]\nType=oneshot\n"
-                   "Environment=PATH=" + search_path(launcher) + "\nExecStart=" + command + "\nNice=10\n")
+                   "Environment=PATH=" + search_path(launcher) +
+                   "\nEnvironment=CROW_SKILLS_PYTHON=" + sys.executable +
+                   "\nExecStart=" + command + "\nNice=10\n")
         timer = (HEADER + "\n[Unit]\nDescription=crow-skills autoupdate (diário e no login)\n\n[Timer]\nOnCalendar=daily\n"
                  "OnStartupSec=5min\nPersistent=true\nRandomizedDelaySec=30min\nUnit=" + UNIT + ".service\n\n"
                  "[Install]\nWantedBy=timers.target\n")

package/crow_skills/bots.py

@@ -0,0 +1,367 @@
+"""Independent specialist bots.
+
+Every way an agent could get help until now BLOCKED the agent that asked:
+the host's own subagent tool makes the parent await the result, and
+`crow_micro.py run` shells out with `subprocess.run(..., timeout=...)`. A
+blocked base agent is not merely slow, it is unreachable: while it waits it
+answers no broadcast, accepts no new demand, updates no state and can lend
+nothing. That is why a machine full of "working" agents coordinates so little.
+
+A bot here is a DETACHED process with an identity. The caller gets a handle
+back immediately and keeps working. The bot registers itself through the
+ordinary crow hooks, so it shows up as a real session with its own key — the
+hooks are never stripped, because an agent spawned without them runs invisible
+to everything that is supposed to watch it.
+
+Idle costs nothing. Each bot pins a session id at spawn, so finishing a unit
+lets the process EXIT while its conversation stays on disk; more work resumes
+that same session (`claude --resume`, `codex exec resume`). An idle bot is a
+row in a registry, not a parked process holding memory — which is what makes
+lending one cheaper than spawning another.
+"""
+
+import json
+import os
+import subprocess
+import time
+import uuid
+from pathlib import Path
+
+from . import broadcast
+from .storage import atomic_json, ensure_dir
+
+#: A bot that has not been touched for this long is stale: its conversation is
+#: still on disk, but the world it reasoned about has moved on. Staleness, not
+#: memory, is the limit on keeping bots around, since an idle one costs no RAM.
+STALE_SECONDS = 2 * 60 * 60
+
+REGISTRY_SCHEMA = "crow-bots/1"
+
+#: Bot lifecycle. "working" means a process is live; "idle" means no process
+#: and a resumable session; "lent" is idle but promised to another owner.
+STATES = ("working", "idle", "lent", "gone")
+
+
+def registry_path(home):
+    return broadcast.state_dir(home) / "bots.json"
+
+
+def logs_dir(home):
+    return Path(home) / ".local" / "state" / "crow-skills" / "bots"
+
+
+def _load(home):
+    data = broadcast.read_json(registry_path(home)) or {}
+    if data.get("schema") != REGISTRY_SCHEMA:
+        return {"schema": REGISTRY_SCHEMA, "bots": []}
+    data.setdefault("bots", [])
+    return data
+
+
+def _save(home, data):
+    path = registry_path(home)
+    ensure_dir(path.parent)
+    atomic_json(path, data)
+
+
+def _alive(pid):
+    if not pid:
+        return False
+    try:
+        os.kill(int(pid), 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except (TypeError, ValueError):
+        return False
+    return True
+
+
+def resolve_cli(name=None, home=None):
+    """Which runner to use. `auto` takes the first one actually installed, so a
+    machine with only devin still spawns bots without being configured."""
+    chain = ("claude", "codex", "gemini", "devin")
+    wanted = (name or "auto").strip().lower()
+    candidates = chain if wanted in ("", "auto") else (wanted,)
+    home = Path(home or Path.home())
+    for cli in candidates:
+        for base in ("/opt/homebrew/bin", "/usr/local/bin",
+                     str(home / ".npm-global/bin"), str(home / ".local/bin")):
+            path = Path(base) / cli
+            if path.exists():
+                return cli, str(path)
+    return None, None
+
+
+def _argv(cli, binary, brief, session_id, model=None, resume=False):
+    """The command line for one unit of work, pinning or resuming the session.
+
+    Pinning matters as much as detaching: without a stable session id the bot
+    cannot be given a second task later, so it would have to be respawned from
+    nothing every time — exactly the cost that borrowing is meant to avoid.
+    """
+    if cli == "claude":
+        argv = [binary, "-p", brief,
+                "--permission-mode", "bypassPermissions",
+                "--output-format", "stream-json", "--verbose"]
+        argv += ["--resume", session_id] if resume else ["--session-id", session_id]
+        if model:
+            argv += ["--model", model]
+        return argv
+    if cli == "codex":
+        argv = [binary, "exec"]
+        argv += ["resume", session_id, brief] if resume else [brief]
+        argv += ["--dangerously-bypass-approvals-and-sandbox"]
+        if model:
+            argv += ["-m", model]
+        return argv
+    if cli == "gemini":
+        return [binary, "-p", brief, "--yolo"]
+    if cli == "devin":
+        return [binary, "-p", brief, "--permission-mode", "dangerous",
+                "--respect-workspace-trust", "false"]
+    return None
+
+
+def _launch(home, record, brief, resume):
+    """Start the process DETACHED and return at once.
+
+    start_new_session puts the bot in its own process group, so it neither dies
+    with the caller's terminal nor takes signals meant for it.
+    """
+    cli, binary = resolve_cli(record.get("cli"), home)
+    if not binary:
+        return None, "nenhum CLI de agente encontrado nesta máquina"
+    argv = _argv(cli, binary, brief, record["session"], record.get("model"), resume=resume)
+    if not argv:
+        return None, "CLI sem modo não interativo conhecido: " + str(cli)
+
+    log = logs_dir(home) / (record["id"] + ".log")
+    ensure_dir(log.parent)
+    env = dict(os.environ)
+    # The hooks read these and stamp the session, which is what turns a loose
+    # process into a bot with a parent, a role and a place in the tree.
+    env.update(CROW_BOT_ID=record["id"],
+               CROW_BOT_OWNER=record.get("owner") or "",
+               CROW_BOT_ROLE=record.get("role") or "")
+    # NOTE: the agent's own settings and hooks are deliberately left intact.
+    # Stripping them (`--setting-sources ""`) makes the bot invisible to the
+    # very roster that is supposed to supervise it.
+    try:
+        handle = open(log, "ab")
+    except OSError:
+        handle = subprocess.DEVNULL
+    try:
+        proc = subprocess.Popen(argv, cwd=record.get("cwd") or str(Path.home()),
+                                env=env, stdin=subprocess.DEVNULL,
+                                stdout=handle, stderr=subprocess.STDOUT,
+                                start_new_session=True)
+    except OSError as exc:
+        return None, "falha ao iniciar o bot: " + str(exc)
+    return proc.pid, None
+
+
+def spawn(home, role, brief, cli=None, model=None, owner=None, cwd=None):
+    """Create a specialist bot and hand the caller its id, without waiting."""
+    role = (role or "").strip()
+    brief = (brief or "").strip()
+    if not role:
+        raise ValueError("um bot precisa de papel: é o que permite reaproveitá-lo depois")
+    if not brief:
+        raise ValueError("um bot precisa de briefing")
+    record = {
+        "id": uuid.uuid4().hex[:10],
+        "session": str(uuid.uuid4()),
+        "role": role,
+        "brief": brief,
+        "cli": (cli or "auto"),
+        "model": model,
+        "owner": owner,
+        "cwd": cwd or os.getcwd(),
+        "briefs": [brief],
+        "findings": [],
+        "state": "working",
+        "spawnedAt": broadcast.now_iso(),
+        "lastAssignedAt": broadcast.now_iso(),
+        "lentTo": None,
+        "runs": 1,
+    }
+    pid, error = _launch(home, record, brief, resume=False)
+    if error:
+        raise RuntimeError(error)
+    record["pid"] = pid
+    record["cli"] = resolve_cli(record["cli"], home)[0]
+    data = _load(home)
+    data["bots"].append(record)
+    _save(home, data)
+    return record
+
+
+def assign(home, bot_id, brief, owner=None):
+    """Give more work to an existing bot by resuming its pinned session."""
+    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))
+    if _alive(record.get("pid")):
+        raise RuntimeError("o bot " + bot_id + " ainda está trabalhando; não empilhe tarefas nele")
+    pid, error = _launch(home, record, brief, resume=True)
+    if error:
+        raise RuntimeError(error)
+    # 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:
+        record["lentTo"] = None if owner == record.get("owner") else owner
+    _save(home, data)
+    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)
+    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))
+    record["lentTo"] = None
+    _save(home, data)
+    return record
+
+
+def stop(home, bot_id):
+    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))
+    pid = record.get("pid")
+    if _alive(pid):
+        try:
+            os.killpg(os.getpgid(int(pid)), 15)
+        except (OSError, ProcessLookupError):
+            pass
+    record["state"] = "gone"
+    _save(home, data)
+    return record
+
+
+def _age(stamp):
+    try:
+        return time.time() - time.mktime(time.strptime((stamp or "")[:19], "%Y-%m-%dT%H:%M:%S"))
+    except (ValueError, TypeError):
+        return None
+
+
+def listing(home, now=None):
+    """Every bot with its REAL state, derived from the process, not from what
+    was written when it was created."""
+    now = now or time.time()
+    data = _load(home)
+    out = []
+    changed = False
+    for record in data["bots"]:
+        if record.get("state") == "gone":
+            continue
+        working = _alive(record.get("pid"))
+        state = "working" if working else ("lent" if record.get("lentTo") else "idle")
+        if record.get("state") != state:
+            record["state"] = state
+            changed = True
+        age = _age(record.get("lastAssignedAt"))
+        row = dict(record)
+        row["state"] = state
+        row["ageSeconds"] = int(age) if age is not None else None
+        # Idle costs no memory, so the thing that disqualifies a bot for reuse
+        # is a conversation too old to still be about the current world.
+        row["stale"] = bool(age is not None and not working and age > STALE_SECONDS)
+        row["lendable"] = bool(state == "idle" and not row["stale"])
+        out.append(row)
+    if changed:
+        _save(home, data)
+    return out
+
+
+def lendable(home, now=None):
+    """Idle, fresh bots another session may borrow instead of spawning one."""
+    return [b for b in listing(home, now) if b.get("lendable")]
+
+
+def prune(home, keep_hours=24):
+    """Drop records whose process is gone and whose session is long stale."""
+    data = _load(home)
+    before = len(data["bots"])
+    cutoff = keep_hours * 3600
+    kept = []
+    for record in data["bots"]:
+        age = _age(record.get("lastAssignedAt"))
+        if record.get("state") == "gone" or (age is not None and age > cutoff and not _alive(record.get("pid"))):
+            continue
+        kept.append(record)
+    data["bots"] = kept
+    _save(home, data)
+    return {"removed": before - len(kept), "kept": len(kept)}
+
+
+def render(rows):
+    if not rows:
+        return "Nenhum bot. Antes de criar um, veja se outra sessão tem um ocioso: crow-skills bot list --json"
+    lines = []
+    for b in rows:
+        mark = {"working": "●", "idle": "○", "lent": "→"}.get(b["state"], "·")
+        age = b.get("ageSeconds")
+        when = ("há " + str(int(age // 60)) + "min") if age is not None else "—"
+        extra = []
+        if b.get("lentTo"):
+            extra.append("emprestado a " + str(b["lentTo"])[:10])
+        if b.get("stale"):
+            extra.append("contexto velho")
+        lines.append("  " + mark + " " + b["id"] + "  " + (b.get("role") or "?")[:28].ljust(28) +
+                     (b.get("cli") or "?").ljust(7) + b["state"].ljust(8) + when +
+                     ("  · " + ", ".join(extra) if extra else ""))
+    return "\n".join(lines)

package/crow_skills/cli.py

@@ -7,6 +7,7 @@ import sys
 
 from . import __version__
 from . import autoupdate
+from . import bots
 from . import broadcast
 from . import events
 from . import groups as groups_mod
@@ -74,6 +75,10 @@ COMMANDS = {
              ["crow-skills mode", "crow-skills mode off", "crow-skills mode on"]),
     "events": ("Barramento de eventos dos hooks (crow-event/1) para terminais.",
                ["crow-skills events", "crow-skills events tail --limit 20", "crow-skills events tail --follow"]),
+    "bot": ("Bots especialistas independentes: criar sem bloquear, reaproveitar o ocioso, emprestar entre sessões.",
+            ["crow-skills bot list", "crow-skills bot spawn --role revisor-sql --brief \"revise o diff de migrations\"",
+             "crow-skills bot assign 9f2a1c \"agora valide o rollback\"", "crow-skills bot release 9f2a1c",
+             "crow-skills bot stop 9f2a1c"]),
     "broadcast": ("Sessões vivas dos CLIs, arquivos em edição, conflitos, reservas e mensagens entre sessões.",
                   ["crow-skills broadcast", "crow-skills broadcast claim src/api --ttl 30m", "crow-skills broadcast release --all",
                    "crow-skills broadcast say \"terminei o merge, a branch é tua\" --to codex", "crow-skills broadcast inbox",
@@ -204,6 +209,17 @@ 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 = command_parser(sub, "bot", [common])
+    child.add_argument("action", nargs="?", default="list",
+                       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)")
+    child.add_argument("--brief", help="spawn: o briefing da primeira unidade")
+    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"))
@@ -567,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)
@@ -676,6 +718,87 @@ def orphans_command(args, home, interactive):
     return data
 
 
+def bot_command(args, home):
+    """Independent specialists. `list` comes first on purpose: the rule is to
+    look for an idle bot before creating another one."""
+    action = args.action
+    if action == "list":
+        rows = bots.lendable(home) if getattr(args, "lendable_only", False) else bots.listing(home)
+        return {"bots": rows, "text": bots.render(rows)}
+    if action == "spawn":
+        owner = broadcast.session_key(os.environ.get("CROW_HOST"), os.environ.get("CROW_SESSION"),
+                                      os.getcwd()) if os.environ.get("CROW_SESSION") else None
+        free = bots.lendable(home)
+        try:
+            record = bots.spawn(home, getattr(args, "role", None), getattr(args, "brief", None),
+                                cli=getattr(args, "cli", "auto"), model=getattr(args, "model", None),
+                                owner=owner, cwd=os.getcwd())
+        except (ValueError, RuntimeError) as exc:
+            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
+            # command exists to avoid.
+            out["idle_available"] = [{"id": b["id"], "role": b.get("role")} for b in free]
+            out["text"] += "\nAviso: havia bot ocioso para reaproveitar — " + \
+                ", ".join(b["id"] + " (" + str(b.get("role")) + ")" for b in free)
+        return out
+    if action == "assign":
+        brief = " ".join(getattr(args, "text", []) or []).strip()
+        if not getattr(args, "target", None) or not brief:
+            raise CrowError("usage", "assign precisa do id do bot e do novo briefing.")
+        try:
+            record = bots.assign(home, args.target, brief)
+        except (ValueError, RuntimeError) as exc:
+            raise CrowError("usage", str(exc))
+        return {"bot": record, "text": "bot " + record["id"] + " retomou a sessão e já está trabalhando"}
+    if action in ("release", "stop"):
+        if not getattr(args, "target", None):
+            raise CrowError("usage", action + " precisa do id do bot.")
+        try:
+            record = bots.release(home, args.target) if action == "release" else bots.stop(home, args.target)
+        except ValueError as exc:
+            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))
+
+
 def broadcast_command(args, home):
     action = args.action
     cwd = os.path.abspath(getattr(args, "cwd", None) or os.getcwd())
@@ -754,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)
@@ -768,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))
@@ -1231,6 +1364,8 @@ def run(args):
         return mcp_command(args, home)
     if args.command == "events":
         return events_command(args, home, store)
+    if args.command == "bot":
+        return bot_command(args, home)
     if args.command == "broadcast":
         return broadcast_command(args, home)
     if args.command == "resources":

package/crow_skills/hook.py

@@ -391,6 +391,15 @@ def update_session(home, event, extra=None, fallback_cwd=None, presence=None):
         for field in ("cwd", "model", "permissionMode"):
             if event.get(field):
                 snap[field] = event[field]
+        # A bot is spawned with these in its environment, so the session it
+        # registers carries its parent and its speciality. Without them a
+        # detached helper is just another anonymous session and the roster can
+        # show no tree, which is why lending one was never possible.
+        for field, var in (("botId", "CROW_BOT_ID"), ("botOwner", "CROW_BOT_OWNER"),
+                           ("botRole", "CROW_BOT_ROLE")):
+            value = os.environ.get(var)
+            if value:
+                snap[field] = value
         if not snap.get("cwd") and fallback_cwd:
             snap["cwd"] = fallback_cwd  # hosts that send no cwd: the hook runs in the session's directory
         kind = event["event"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/crow-skills",
-  "version": "0.37.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": "e81ffb7e0427f976533c16e6649feba6cd9cb78085e564a57a1841b6ab4f08cf"
+      "sha256": "5c2d124b8f54ae50df371268045f54ba0e08e8cdb27f2141773bfb80fba661b1"
     },
     "crow_skills/__main__.py": {
       "executable": false,
@@ -43,7 +43,12 @@
     "crow_skills/autoupdate.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "10d8267ec1fd861d56af8423a2a1a71769ccc9d59a89fdf2f41858a6476666cd"
+      "sha256": "bab32c72d6ce57e0c5b1d4194e14a0be2880d50c85f5ebea2a5bfb6edb6c2693"
+    },
+    "crow_skills/bots.py": {
+      "executable": false,
+      "kind": "file",
+      "sha256": "b6119c6974d06152b3462c67368b0fd81d4be389419838eebf3c5007e421a10d"
     },
     "crow_skills/broadcast.py": {
       "executable": false,
@@ -53,7 +58,7 @@
     "crow_skills/cli.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "b245ff68ff48d48fecc076fc0cec7a24065a07ec205805285dbfe3a8faee652d"
+      "sha256": "7fdd9af628596e8b7abc111b9277cc6498f5a68e6bdab9421e9aec35c0374ab3"
     },
     "crow_skills/events.py": {
       "executable": false,
@@ -73,7 +78,7 @@
     "crow_skills/hook.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "225f706590ae59cd28f99d237403bfa6090a9a6c29b07fe668482f33ad627152"
+      "sha256": "ba8da0cdf6e8aa8d1002966c4b05718c74740c132b6d703f22071135d54a4342"
     },
     "crow_skills/integrations.py": {
       "executable": false,
@@ -143,7 +148,7 @@
     "package.json": {
       "executable": false,
       "kind": "file",
-      "sha256": "1c30d4fd90f7cfc3536419fe86dc9229e3ea5efbededcf85b227954650de0e10"
+      "sha256": "64e8d706972b11b51c6decc284fa11abb151d87e977e43723eb3849d1f409d87"
     },
     "skills/crow-accessibility/SKILL.md": {
       "executable": false,
@@ -208,7 +213,7 @@
     "skills/crow-behaviour/SKILL.md": {
       "executable": false,
       "kind": "file",
-      "sha256": "f8e0f38537875772027868c2112071f38a8c7a699295bec057bf64e6c2930999"
+      "sha256": "e7f2cdb1acf214e78be8f8b7c27c013e591478df7ac99addd3e0891cbc0d13b9"
     },
     "skills/crow-behaviour/agents/openai.yaml": {
       "executable": false,
@@ -966,7 +971,7 @@
       "sha256": "160c814085dfdbe93e0166f2a773345dd1436f07a63dbf58d447f3f7674dc759"
     }
   },
-  "revision": "df47e9b5e6507bb9c543ccc5d20e38e8d69d3239",
+  "revision": "b86c3ef157a305468fa37ce18f84cca40dc1b11d",
   "schema_version": 1,
-  "version": "0.37.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