@andespindola/crow-skills 0.38.2 → 0.39.1

package/crow_skills/__init__.py

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

package/crow_skills/cli.py

@@ -8,6 +8,7 @@ import sys
 from . import __version__
 from . import autoupdate
 from . import bots
+from . import demands as demands_mod
 from . import broadcast
 from . import events
 from . import groups as groups_mod
@@ -75,6 +76,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"]),
+    "demand": ("Demandas do dono que ficam registradas até alguém assumir — sem validade, porque demanda sem resposta não é velha, é pendente.",
+               ["crow-skills demand list", "crow-skills demand list --pending",
+                "crow-skills demand add \"arrumar o scroll do painel\"",
+                "crow-skills demand take 9f2a1c", "crow-skills demand done 9f2a1c \"publicado em 0.2.26\""]),
     "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",
@@ -209,6 +214,13 @@ 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, "demand", [common])
+    child.add_argument("action", nargs="?", default="list",
+                       choices=("list", "add", "take", "done", "fail", "release"))
+    child.add_argument("target", nargs="?", help="take/done/fail/release: id da demanda")
+    child.add_argument("text", nargs="*", help="add: o pedido; done/fail: a nota de desfecho")
+    child.add_argument("--pending", action="store_true", help="list: só o que ninguém assumiu")
+    child.add_argument("--thread", help="add: id da conversa do broadcast que originou o pedido")
     child = command_parser(sub, "bot", [common])
     child.add_argument("action", nargs="?", default="list",
                        choices=("list", "spawn", "assign", "release", "stop", "prune", "learned", "knowledge"))
@@ -718,6 +730,45 @@ def orphans_command(args, home, interactive):
     return data
 
 
+def demand_command(args, home):
+    """The owner's queue. `list` is the default action because the first thing
+    an agent should do is look at what is already waiting."""
+    action = args.action
+    cwd = os.path.abspath(getattr(args, "cwd", None) or os.getcwd())
+    if action == "list":
+        live = {s.get("key") for s in broadcast.live_sessions(home)}
+        rows = demands_mod.listing(home, pending_only=getattr(args, "pending", False), live_keys=live)
+        return {"demands": rows, "text": demands_mod.render(rows)}
+    if action == "add":
+        # `target` is positional, so it swallows the first word of the demand;
+        # for add there is no id, and the whole tail is the request.
+        parts = ([getattr(args, "target", None)] if getattr(args, "target", None) else []) + list(getattr(args, "text", []) or [])
+        text = " ".join(p for p in parts if p).strip()
+        if not text:
+            raise CrowError("usage", "add precisa do pedido: crow-skills demand add \"o que fazer\".")
+        try:
+            record = demands_mod.add(home, text, thread=getattr(args, "thread", None))
+        except ValueError as exc:
+            raise CrowError("usage", str(exc))
+        return {"demand": record,
+                "text": "demanda " + record["id"] + " registrada e pendente; ela não expira."}
+    if not getattr(args, "target", None):
+        raise CrowError("usage", action + " precisa do id da demanda.")
+    note = " ".join(getattr(args, "text", []) or []).strip()
+    try:
+        if action == "take":
+            owner = broadcast_owner(args, home, cwd)
+            record = demands_mod.take(home, args.target, by=(owner or {}).get("key"))
+            return {"demand": record, "text": "demanda " + record["id"] + " é sua; devolva com release se não puder terminar."}
+        if action in ("done", "fail"):
+            record = demands_mod.close(home, args.target, "done" if action == "done" else "failed", note)
+            return {"demand": record, "text": "demanda " + record["id"] + " encerrada como " + record["state"] + "."}
+        record = demands_mod.release(home, args.target)
+        return {"demand": record, "text": "demanda " + record["id"] + " devolvida à fila."}
+    except (ValueError, RuntimeError) as exc:
+        raise CrowError("usage", str(exc))
+
+
 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."""
@@ -1364,6 +1415,8 @@ def run(args):
         return mcp_command(args, home)
     if args.command == "events":
         return events_command(args, home, store)
+    if args.command == "demand":
+        return demand_command(args, home)
     if args.command == "bot":
         return bot_command(args, home)
     if args.command == "broadcast":

package/crow_skills/demands.py

@@ -0,0 +1,195 @@
+"""The owner's demands, kept until somebody takes them.
+
+A demand typed in the Crow Cockpit used to exist only as a broadcast message,
+and broadcast messages expire (`stale_minutes`, 30 by default). So a demand
+sent while no agent session was alive to receive it simply evaporated: nothing
+to resume, because nothing had been written down. Closing the app looked like
+the cause; the real cause was that the request was never recorded anywhere.
+
+This is deliberately NOT a second memory. The vault remains the record: an
+agent that takes a demand writes it there. This store exists for one narrow
+reason — the cockpit is not an agent, carries no contract and has no
+authenticated path to the vault, so it needs somewhere durable to leave a
+request for the window in which nobody is listening. It holds the handoff, not
+the history, and it should disappear the day the cockpit can record directly.
+
+No TTL, on purpose: an unanswered demand is not stale, it is unanswered.
+"""
+
+import json
+import os
+import uuid
+
+from . import broadcast
+from .storage import atomic_json, ensure_dir
+
+SCHEMA = "crow-demands/1"
+
+#: pending  — written, nobody took it
+#: taken    — an agent is on it (with who and when)
+#: done     — finished, with a short note of the outcome
+#: failed   — attempted and abandoned, with the reason
+STATES = ("pending", "taken", "done", "failed")
+
+#: Keep finished demands around this long so the owner can still see what was
+#: answered; they are history, not queue, and are pruned on write.
+KEEP_DONE_HOURS = 72
+
+
+def path(home):
+    return broadcast.state_dir(home) / "demands.json"
+
+
+def _load(home):
+    data = broadcast.read_json(path(home)) or {}
+    if data.get("schema") != SCHEMA:
+        return {"schema": SCHEMA, "demands": []}
+    data.setdefault("demands", [])
+    return data
+
+
+def _save(home, data):
+    target = path(home)
+    ensure_dir(target.parent)
+    atomic_json(target, data)
+
+
+def _age_hours(stamp):
+    import time
+    try:
+        return (time.time() - time.mktime(time.strptime((stamp or "")[:19], "%Y-%m-%dT%H:%M:%S"))) / 3600
+    except (ValueError, TypeError):
+        return None
+
+
+def add(home, text, thread=None, source=None):
+    """Record a demand. Called by whoever received it, before acting."""
+    text = (text or "").strip()
+    if not text:
+        raise ValueError("uma demanda vazia não é uma demanda")
+    record = {
+        "id": uuid.uuid4().hex[:10],
+        "text": text,
+        "state": "pending",
+        "createdAt": broadcast.now_iso(),
+        "thread": thread or None,
+        "source": source or "cockpit",
+        "takenBy": None,
+        "takenAt": None,
+        "closedAt": None,
+        "note": None,
+        "attempts": 0,
+    }
+    data = _load(home)
+    data["demands"].append(record)
+    _prune(data)
+    _save(home, data)
+    return record
+
+
+def _find(data, demand_id):
+    return next((d for d in data["demands"] if d.get("id") == demand_id), None)
+
+
+def take(home, demand_id, by=None):
+    """Claim a demand. Refuses one already in hand, so two agents do not both
+    start the same work — the duplication this queue exists to prevent."""
+    data = _load(home)
+    record = _find(data, demand_id)
+    if not record:
+        raise ValueError("demanda desconhecida: " + str(demand_id))
+    if record["state"] == "taken" and record.get("takenBy") not in (None, by):
+        raise RuntimeError("a demanda " + demand_id + " já está com " + str(record.get("takenBy")))
+    if record["state"] in ("done", "failed"):
+        raise RuntimeError("a demanda " + demand_id + " já foi encerrada como " + record["state"])
+    record.update(state="taken", takenBy=by, takenAt=broadcast.now_iso(),
+                  attempts=int(record.get("attempts") or 0) + 1)
+    _save(home, data)
+    return record
+
+
+def close(home, demand_id, state, note=None):
+    """Finish a demand. `note` is what the owner needs to read, not a status."""
+    if state not in ("done", "failed"):
+        raise ValueError("estado final inválido: " + str(state))
+    if state == "failed" and not (note or "").strip():
+        raise ValueError("uma demanda que falhou precisa dizer por quê")
+    data = _load(home)
+    record = _find(data, demand_id)
+    if not record:
+        raise ValueError("demanda desconhecida: " + str(demand_id))
+    record.update(state=state, closedAt=broadcast.now_iso(), note=(note or "").strip() or None)
+    _prune(data)
+    _save(home, data)
+    return record
+
+
+def release(home, demand_id):
+    """Put a taken demand back. An agent that cannot finish must hand it back
+    rather than leave it held by a session that is about to die."""
+    data = _load(home)
+    record = _find(data, demand_id)
+    if not record:
+        raise ValueError("demanda desconhecida: " + str(demand_id))
+    if record["state"] != "taken":
+        raise RuntimeError("a demanda " + demand_id + " não está tomada")
+    record.update(state="pending", takenBy=None, takenAt=None)
+    _save(home, data)
+    return record
+
+
+def _prune(data):
+    kept = []
+    for record in data["demands"]:
+        if record.get("state") in ("done", "failed"):
+            age = _age_hours(record.get("closedAt"))
+            if age is not None and age > KEEP_DONE_HOURS:
+                continue
+        kept.append(record)
+    data["demands"] = kept
+
+
+def listing(home, pending_only=False, live_keys=None):
+    """The queue, with abandonment made visible.
+
+    A demand held by a session that no longer exists is reported as `orphaned`
+    rather than `taken`: it is the one state that looks like progress and is
+    not, and it is exactly what happens when the owner's agent dies mid-task.
+    """
+    data = _load(home)
+    rows = []
+    changed = False
+    for record in data["demands"]:
+        row = dict(record)
+        if record.get("state") == "taken" and live_keys is not None:
+            if record.get("takenBy") and record["takenBy"] not in live_keys:
+                row["orphaned"] = True
+                # Hand it back so somebody can pick it up again.
+                record.update(state="pending", takenBy=None, takenAt=None)
+                row["state"] = "pending"
+                changed = True
+        if pending_only and row.get("state") != "pending":
+            continue
+        rows.append(row)
+    if changed:
+        _save(home, data)
+    return rows
+
+
+def render(rows):
+    if not rows:
+        return "(nenhuma demanda registrada)"
+    mark = {"pending": "○", "taken": "●", "done": "✓", "failed": "✗"}
+    lines = []
+    for d in rows:
+        text = broadcast.clean(d.get("text"), 90) if hasattr(broadcast, "clean") else str(d.get("text"))[:90]
+        extra = []
+        if d.get("orphaned"):
+            extra.append("estava com uma sessão que morreu, devolvida à fila")
+        if d.get("takenBy"):
+            extra.append("com " + str(d["takenBy"])[:10])
+        if d.get("note"):
+            extra.append(str(d["note"])[:60])
+        lines.append("  " + mark.get(d.get("state"), "·") + " [" + str(d.get("id")) + "] " + text +
+                     ("  · " + "; ".join(extra) if extra else ""))
+    return "\n".join(lines)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andespindola/crow-skills",
-  "version": "0.38.2",
+  "version": "0.39.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": "7765d89d0c3b7dd8b7d765a61e6a507429a1b2f7710fae47b1d014183fb87e40"
+      "sha256": "cc31d6c68bd4608a765d04e1159af015aa8cba0aa61d2da53c027fc033be366f"
     },
     "crow_skills/__main__.py": {
       "executable": false,
@@ -58,7 +58,12 @@
     "crow_skills/cli.py": {
       "executable": false,
       "kind": "file",
-      "sha256": "7fdd9af628596e8b7abc111b9277cc6498f5a68e6bdab9421e9aec35c0374ab3"
+      "sha256": "506a45896915a0effa409a6763c95ddabf46953aa68e16f958af1d2088e7ad18"
+    },
+    "crow_skills/demands.py": {
+      "executable": false,
+      "kind": "file",
+      "sha256": "ce2436f20878b92eb175143d6b36f03ed62d490315bbb01958aa1646ae9d8225"
     },
     "crow_skills/events.py": {
       "executable": false,
@@ -148,7 +153,7 @@
     "package.json": {
       "executable": false,
       "kind": "file",
-      "sha256": "9c066a2aa80bb4a853faf9ec8c9d5e0887884e4541539f5e61c62dd369c715b3"
+      "sha256": "5b9beb57525b19906aa91a49dce1505bb0b230a4b402e5c9bd35686f489965f7"
     },
     "skills/crow-accessibility/SKILL.md": {
       "executable": false,
@@ -213,7 +218,7 @@
     "skills/crow-behaviour/SKILL.md": {
       "executable": false,
       "kind": "file",
-      "sha256": "e7f2cdb1acf214e78be8f8b7c27c013e591478df7ac99addd3e0891cbc0d13b9"
+      "sha256": "7c8ac7b0f41d07a5815b3beb600848894e661c6318526e62ca564026f3e10c31"
     },
     "skills/crow-behaviour/agents/openai.yaml": {
       "executable": false,
@@ -971,7 +976,7 @@
       "sha256": "7dd3660097c3afeadb58357939b51da518a4da7cf2d7e684c2618b22f6c4a87b"
     }
   },
-  "revision": "11982e7c39ba1b449a442f8deb6468d5a27d26f4",
+  "revision": "0f9a4474c68714d028c27163a483cc3381d84e64",
   "schema_version": 1,
-  "version": "0.38.2"
+  "version": "0.39.1"
 }

package/skills/crow-behaviour/SKILL.md

@@ -62,6 +62,11 @@ 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.
+- **Pendência que você encontra é registro, e quando outro pode resolvê-la, é oferta.** Anotar o que deu certo e esconder o que ficou pela metade produz um vault que parece completo e não é: sem um registro próprio, a pendência vira prosa dentro do desfecho e ninguém consegue perguntar "o que está pendente". Então registre-a **assim que a identificar**, não no fim, com o que a torna acionável: o que falta, o que ela destrava e como se sabe que fechou. Em seguida decida se é **sua** ou **de qualquer um**: pendência que depende de decisão do dono, de credencial ou de acesso que só você tem fica registrada e **não** é anunciada — pedir ajuda que ninguém pode dar é ruído no canal que o dono observa. Pendência que outro agente conseguiria resolver vira **handoff compartilhado** na memória do dono (`scope: "shared"`, com `summary`, `nextSteps` e `sources` apontando caminho e revisão exata), e só então o broadcast anuncia que existe — a mensagem é a campainha, nunca o registro, porque mensagem expira e pendência não. Quem assume reivindica o handoff (`claim`, que carrega lease e cerca de versão, de modo que dois não pegam o mesmo e quem morrer segurando solta sozinho) e fecha com `complete` e o desfecho. **Não crie fila própria para isso:** o mecanismo existe, é testado, e duplicá-lo produz dois registros divergindo.
+- **Ocioso não é desocupado: é quem pode ajudar.** Ao ficar sem trabalho, leia os handoffs compartilhados em aberto antes de encerrar ou de inventar tarefa. Se couber no seu escopo autorizado, **assuma e resolva**. Se não couber — porque o conserto é do dono daquele código, ou exige acesso que você não tem — ainda assim ajude de outra forma: **levante a informação que falta** para quem vai atuar (reprodução mínima, revisão exata, trecho relevante, o que já foi descartado) e devolva isso no handoff. Informação boa entregue a quem pode agir vale mais que um conserto apressado feito por quem não deveria tocar ali, e evita dois agentes brigando pelo mesmo arquivo.
+
+- **Antes de pegar trabalho novo, veja o que o dono já pediu e ninguém assumiu.** Demanda digitada no cockpit fica registrada numa fila local sem validade (`crow-skills demand list --pending`), porque mensagem de broadcast expira e pedido sem resposta não é velho, é pendente. Ao iniciar, e sempre que ficar ocioso, leia a fila: se houver demanda compatível com o seu escopo autorizado, **assuma** (`demand take <id>`), execute, e encerre dizendo o desfecho (`demand done <id> "<o que saiu>"` ou `demand fail <id> "<por quê>"`). Se não puder terminar, **devolva** (`demand release <id>`) em vez de morrer segurando — a fila marca como órfã a demanda presa a uma sessão que sumiu, mas devolver na hora é honesto e evita a espera. A fila é entrega, não memória: ao assumir, registre o pedido na memória do dono, que é onde ele passa a existir de verdade.
+
 - **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.