crowsnest 0.0.2__py3-none-any.whl

crowsnest/__init__.py

@@ -0,0 +1,52 @@
+"""One session that watches the others.
+
+A machine running many Claude Code sessions has a question nobody answers: *what are they
+all doing, and which of them needs me?* Each session knows only itself, the terminal tabs
+are silent until you click them, and the answer lives in forty scrollbacks.
+
+``crowsnest`` reads what Claude Code already writes -- the registry it keeps for every
+running session, and the transcript each session appends to -- and answers in three
+tiers, cheapest first:
+
+1. **The roster** (:func:`crowsnest.tools.roster`): who is alive, busy, idle or waiting,
+   where, since when. Instant; no transcript is read.
+2. **The activity** (:func:`crowsnest.tools.show`, :func:`crowsnest.tools.turns`): what a
+   session was last asked, what it last said, the tool it is running now, the question
+   it is waiting on -- read from the tail of its transcript, which costs the watched
+   session nothing and never interrupts it. ``turns`` pages further back when the tail is
+   not enough.
+3. **The ask**: a running session can be *messaged* and will answer from its own
+   context. That is a Claude Code feature, not a Python one, so it lives in the shipped
+   skill (``crowsnest/data/skills/crowsnest/SKILL.md``) rather than here -- with the rule
+   that says when it is worth a turn of someone else's context and when it is not.
+
+And one stream: :func:`crowsnest.watch.events` yields a line every time a session starts,
+exits, finishes a turn, or starts waiting on its human, so a monitor is told rather than
+made to poll.
+
+Everything here is read-only. Nothing sends, spawns, kills, or writes into another
+session; the one write in the package is the skill installer, and it writes symlinks.
+
+>>> from crowsnest import live_sessions, roster
+>>> live_sessions(home='/nonexistent-dir-for-doctest')
+[]
+"""
+
+from crowsnest.activity import Activity, Turn, read_activity, read_turns
+from crowsnest.registry import LiveSession, live_sessions
+from crowsnest.tools import resolve, roster, show, turns
+from crowsnest.watch import events
+
+__all__ = [
+    "Activity",
+    "LiveSession",
+    "Turn",
+    "events",
+    "live_sessions",
+    "read_activity",
+    "read_turns",
+    "resolve",
+    "roster",
+    "show",
+    "turns",
+]

crowsnest/__main__.py

@@ -0,0 +1,234 @@
+"""The ``crowsnest`` command: the one surface v0 builds.
+
+Every verb is a thin renderer over a function in :mod:`crowsnest.tools`, the single list
+all surfaces dispatch from. The core prints nothing and exits nothing; the formatting is
+here so that a later MCP or HTTP adapter needs no change to the core.
+
+Bare ``crowsnest`` prints the roster, because the fewest keystrokes have to produce the
+useful thing.
+"""
+
+# PYTHON_ARGCOMPLETE_OK
+
+from __future__ import annotations
+
+import json as _json
+import sys
+from datetime import datetime, timezone
+
+from crowsnest import skills as _skills
+from crowsnest import tools
+from crowsnest import watch as _watch
+
+__all__ = ["main"]
+
+DEFAULT_COMMAND = "roster"
+
+
+def _age(epoch: float | None) -> str:
+    if not epoch:
+        return "?"
+    seconds = max(0.0, datetime.now(timezone.utc).timestamp() - epoch)
+    for size, unit in ((86400, "d"), (3600, "h"), (60, "m")):
+        if seconds >= size:
+            return f"{seconds / size:.0f}{unit}"
+    return f"{seconds:.0f}s"
+
+
+def _one_line(text: str, limit: int) -> str:
+    text = " ".join((text or "").split())
+    return text if len(text) <= limit else text[: limit - 1].rstrip() + "…"
+
+
+def _local(stamp: str) -> str:
+    """An ISO timestamp as local ``HH:MM``, or the raw value when unparseable."""
+    try:
+        return (
+            datetime.fromisoformat(stamp.replace("Z", "+00:00"))
+            .astimezone()
+            .strftime("%H:%M")
+        )
+    except ValueError:
+        return stamp
+
+
+def _row_detail(row: dict, limit: int) -> str:
+    act = row.get("activity") or {}
+    status = row["status"]
+    if status == "waiting":
+        cause = act.get("pending_question") or "; ".join(act.get("in_flight") or ())
+        parts = [
+            row.get("waiting_for") or "waiting",
+            cause or act.get("last_assistant_text", ""),
+        ]
+        return _one_line(" · ".join(p for p in parts if p), limit)
+    if status == "busy":
+        running = "; ".join(act.get("in_flight") or ())
+        if running:
+            return _one_line("→ " + running, limit)
+        return _one_line("asked: " + act.get("last_user_prompt", ""), limit)
+    said = act.get("last_assistant_text", "")
+    mark = "⚠ " if act.get("errored") else ""
+    return _one_line(f'{mark}"{said}"' if said else "", limit)
+
+
+def roster(*, home: str | None = None, brief: bool = False, width: int = 110):
+    """Who is alive, most urgent first: waiting on you, then busy, then idle.
+
+    `--brief` answers from the registry alone, without reading any transcript.
+    """
+    result = tools.roster(home=home, activity=not brief)
+    lines = []
+    for row in result["sessions"]:
+        head = f"{row['status']:<8}{_age(row['status_since']):>4}  {row['label'][:26]:<27}{row['project'][:16]:<17}"
+        detail = "" if brief else _row_detail(row, max(20, width - len(head)))
+        lines.append((head + detail).rstrip())
+    counts = result["counts"]
+    summary = ", ".join(f"{n} {k}" for k, n in counts.items() if n)
+    lines.append(f"-- {len(result['sessions'])} live: {summary or 'none'}")
+    return "\n".join(lines)
+
+
+def show(session: str, *, home: str | None = None, recent: int = 8, json: bool = False):
+    """One session in full: what it was asked, what it said, what it is running now.
+
+    `session` is a registry name, a unique prefix of one, a session-id prefix, or a pid.
+    """
+    result = tools.show(session, home=home, recent=recent)
+    if json:
+        return _json.dumps(result, indent=2)
+    s, act = result["session"], result["activity"]
+    since = _age(s["status_since"])
+    out = [
+        f"# {s['label']}  ({s['status']} for {since}"
+        + (f", {s['waiting_for']}" if s["waiting_for"] else "")
+        + ")"
+    ]
+    out.append(
+        f"pid {s['pid']} · session {s['session_id'][:8]} · {s['cwd']}"
+        + (f" · branch {act['git_branch']}" if act["git_branch"] else "")
+        + (" · remote control on" if s["remote_control"] else "")
+    )
+    if act["pending_question"]:
+        out += ["", "## Waiting on you", act["pending_question"]]
+    if act["in_flight"]:
+        out += ["", "## In flight", *[f"- {t}" for t in act["in_flight"]]]
+    out += [
+        "",
+        f"## Last asked ({_local(act['last_prompt_at'])})",
+        act["last_user_prompt"] or "(none in the tail)",
+    ]
+    out += [
+        "",
+        f"## Last said ({_local(act['last_text_at'])})",
+        act["last_assistant_text"] or "(none in the tail)",
+    ]
+    if act["recent_tools"]:
+        out += ["", "## Recent tools", *[f"- {t}" for t in act["recent_tools"]]]
+    flags = [k for k in ("turn_open", "errored") if act[k]]
+    if flags or not act["tail_complete"]:
+        out += [
+            "",
+            "flags: "
+            + ", ".join(flags + ([] if act["tail_complete"] else ["tail only"])),
+        ]
+    return "\n".join(out)
+
+
+def turns(
+    session: str,
+    *,
+    last: int = 5,
+    before: int | None = None,
+    home: str | None = None,
+    json: bool = False,
+):
+    """The last few turns of a session, oldest first. `--before N` pages back from turn N."""
+    result = tools.turns(session, last=last, before=before, home=home)
+    if json:
+        return _json.dumps(result, indent=2)
+    out = [f"# {result['session']['label']} — turns"]
+    for t in result["turns"]:
+        out += [
+            "",
+            f"## turn {t['index']}  ({_local(t['prompt_at'])})",
+            f"> {t['prompt']}",
+        ]
+        if t["tools"]:
+            out.append(
+                f"tools ({len(t['tools'])}): "
+                + "; ".join(t["tools"][:8])
+                + (" …" if len(t["tools"]) > 8 else "")
+            )
+        out.append(t["reply"] or "(no final text)")
+    if not result["turns"]:
+        out.append("(no turns)")
+    return "\n".join(out)
+
+
+def watch(
+    *, interval: float = _watch.DFLT_INTERVAL, home: str | None = None, json: bool = False
+):
+    """Print one line per change, forever: started, exited, idle, busy, waiting, error.
+
+    Built for Claude Code's `Monitor` tool: each line becomes a notification in the
+    watching session. Stop with Ctrl-C.
+    """
+    try:
+        for event in _watch.events(interval=interval, home=home):
+            if json:
+                line = _json.dumps(event)
+            else:
+                when = _local(event["at"])
+                line = f"{when}  {event['kind']:<8} {event['name']} ({event['project']})"
+                if event["detail"]:
+                    line += f" — {event['detail']}"
+            print(line, flush=True)
+    except KeyboardInterrupt:
+        pass
+
+
+def install_skills(
+    *,
+    target: str | None = None,
+    only: str | None = None,
+    force: bool = False,
+    dry_run: bool = False,
+):
+    """Link the bundled skill and subagent into ~/.claude (or `--target`). Idempotent."""
+    names = [n for n in (only or "").split(",") if n.strip()] or None
+    plan = _skills.install_skills(target=target, only=names, force=force, dry_run=dry_run)
+    lines = [f"{'would install' if dry_run else 'installed'} into {plan['target']}"]
+    for row in plan["actions"]:
+        how = f" ({row['method']})" if row["method"] else ""
+        lines.append(
+            f"{row['action']:<9}{row['kind']:<7}{row['name']:<18}{row['reason']}{how}"
+        )
+    return "\n".join(lines)
+
+
+_commands = [roster, show, turns, watch, install_skills]
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Dispatch the ``crowsnest`` command. Bare ``crowsnest`` runs :func:`roster`."""
+    import cw
+
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0].startswith("-") and argv[0] not in ("-h", "--help"):
+        argv = [DEFAULT_COMMAND, *argv]
+    parser = cw.mk_parser(
+        _commands, prog="crowsnest", description=__doc__.splitlines()[0]
+    )
+    try:
+        code = cw.run(parser, argv)
+    except (ValueError, KeyError) as exc:
+        message = exc.args[0] if exc.args else str(exc)
+        print(f"crowsnest: {message}", file=sys.stderr)
+        sys.exit(2)
+    if code:
+        raise SystemExit(code)
+
+
+if __name__ == "__main__":
+    main()

crowsnest/activity.py

@@ -0,0 +1,353 @@
+"""What a session is doing right now, read from the tail of its transcript.
+
+A transcript is append-only and can run to megabytes; the part that says what a session
+is doing *now* is its last few kilobytes. So :func:`read_activity` reads from the end,
+widening the window only until it has seen one human prompt, and reports what it found:
+what the session was last asked, what it last said, the tools it ran most recently, the
+tool call that has not returned yet, and -- the case a monitor exists for -- a question it
+has put to its human that nobody has answered.
+
+What the transcript's *content* means is :mod:`openloops.transcripts`'s business -- which
+``user`` line is a person speaking and which is tooling, what the assistant's last words
+were, whether the turn ended -- and :func:`openloops.transcripts.parse_session` is called
+on the tail rather than that logic being written a second time. What this module adds is
+the tool-level view that a dated digest has no use for and a live monitor cannot do
+without.
+
+:func:`read_turns` is the deep path. It reads the whole file and pages backwards through
+turns, for when the tail did not carry enough context and the alternative is spending a
+turn of the watched session's own context asking it.
+
+>>> read_activity('/nonexistent-file-for-doctest').last_user_prompt
+''
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+from openloops.transcripts import parse_session
+
+__all__ = [
+    "QUESTION_TOOL",
+    "RECENT_TOOLS",
+    "TAIL_BYTES",
+    "Activity",
+    "Turn",
+    "describe_tool",
+    "load_records",
+    "read_activity",
+    "read_turns",
+    "tail_records",
+]
+
+#: How much of the file's end is read first. A turn of tool calls is a few kilobytes; a
+#: quarter megabyte covers the last several turns of nearly every session and costs a
+#: few milliseconds. The window doubles until it holds a human prompt.
+TAIL_BYTES = 256 * 1024
+
+#: How many recent tool calls an :class:`Activity` carries.
+RECENT_TOOLS = 6
+
+#: The tool Claude Code uses to put a structured question to its human. A call to it with
+#: no result yet is a session waiting on a person.
+QUESTION_TOOL = "AskUserQuestion"
+
+#: Which input field best says what a tool call was about, first match wins. A
+#: ``description`` is written for a human; a path or a target is the next best thing.
+_ARG_KEYS = (
+    "description",
+    "file_path",
+    "path",
+    "pattern",
+    "to",
+    "query",
+    "url",
+    "prompt",
+    "command",
+    "message",
+)
+_PATH_KEYS = ("file_path", "path")
+_ARG_LIMIT = 80
+
+
+def _parse_lines(data: bytes) -> list[dict]:
+    records = []
+    for line in data.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rec = json.loads(line)
+        except ValueError:
+            continue
+        if isinstance(rec, dict):
+            records.append(rec)
+    return records
+
+
+def load_records(path: str | Path) -> list[dict]:
+    """Every record in a transcript, tolerating blank and malformed lines."""
+    try:
+        return _parse_lines(Path(path).read_bytes())
+    except OSError:
+        return []
+
+
+def _has_prompt(records: list[dict]) -> bool:
+    return bool(parse_session(records).last_user_prompt)
+
+
+def tail_records(
+    path: str | Path,
+    *,
+    tail_bytes: int = TAIL_BYTES,
+    enough: Callable[[list[dict]], bool] = _has_prompt,
+) -> tuple[list[dict], bool]:
+    """The records in the last ``tail_bytes`` of a transcript, widening until ``enough``.
+
+    Returns the records and whether the window reached the start of the file. The first
+    line of a window that starts mid-file is a fragment and is dropped.
+
+    >>> tail_records('/nonexistent-file-for-doctest')
+    ([], True)
+    """
+    path = Path(path)
+    try:
+        size = path.stat().st_size
+    except OSError:
+        return [], True
+    window = max(1, tail_bytes)
+    while True:
+        start = max(0, size - window)
+        try:
+            with path.open("rb") as f:
+                f.seek(start)
+                data = f.read()
+        except OSError:
+            return [], True
+        if start > 0:
+            data = data.partition(b"\n")[2]
+        records = _parse_lines(data)
+        if start == 0 or enough(records):
+            return records, start == 0
+        window *= 2
+
+
+def _blocks(record: dict) -> list[dict]:
+    content = (record.get("message") or {}).get("content")
+    if isinstance(content, list):
+        return [b for b in content if isinstance(b, dict)]
+    return []
+
+
+def _stamp(record: dict) -> str:
+    return str(record.get("timestamp") or "")
+
+
+def _main_thread(records: list[dict]) -> list[dict]:
+    return sorted((r for r in records if not r.get("isSidechain")), key=_stamp)
+
+
+def describe_tool(name: str, inputs: dict | None, *, limit: int = _ARG_LIMIT) -> str:
+    """One line naming a tool call: the tool, and the argument that says what it did.
+
+    >>> describe_tool('Bash', {'command': 'ls -la', 'description': 'List files'})
+    'Bash: List files'
+    >>> describe_tool('Read', {'file_path': '/a/b/c.py'})
+    'Read: c.py'
+    >>> describe_tool('AskUserQuestion', {'questions': [{'question': 'Ship it?'}]})
+    'AskUserQuestion: Ship it?'
+    >>> describe_tool('ListAgents', {})
+    'ListAgents'
+    """
+    inputs = inputs if isinstance(inputs, dict) else {}
+    arg = ""
+    if name == QUESTION_TOOL:
+        questions = inputs.get("questions") or []
+        first = questions[0] if questions and isinstance(questions[0], dict) else {}
+        arg = str(first.get("question") or "")
+    else:
+        for key in _ARG_KEYS:
+            value = inputs.get(key)
+            if isinstance(value, str) and value.strip():
+                arg = Path(value).name if key in _PATH_KEYS else value
+                break
+    arg = " ".join(arg.split())
+    if len(arg) > limit:
+        arg = arg[: limit - 1].rstrip() + "…"
+    return f"{name}: {arg}" if arg else name
+
+
+def _tool_calls(records: list[dict]) -> tuple[list[tuple[str, str, dict]], set[str]]:
+    """Every tool call on the main thread in order, and the ids that got a result."""
+    calls: list[tuple[str, str, dict]] = []
+    answered: set[str] = set()
+    for rec in records:
+        if rec.get("type") == "assistant":
+            for b in _blocks(rec):
+                if b.get("type") == "tool_use":
+                    calls.append(
+                        (
+                            str(b.get("id") or ""),
+                            str(b.get("name") or ""),
+                            b.get("input") or {},
+                        )
+                    )
+        elif rec.get("type") == "user":
+            for b in _blocks(rec):
+                if b.get("type") == "tool_result" and b.get("tool_use_id"):
+                    answered.add(str(b["tool_use_id"]))
+    return calls, answered
+
+
+@dataclass(frozen=True)
+class Activity:
+    """What one session is doing, as its transcript tail reads. Flat and JSON-shaped.
+
+    ``in_flight`` lists tool calls with no result yet, oldest first: normally one, several
+    when calls were issued in parallel. ``pending_question`` is the first question of an
+    in-flight :data:`QUESTION_TOOL` call -- a session waiting on a person.
+    ``tail_complete`` says whether the window reached the start of the file, which is what
+    makes the difference between "no prompt in the tail" and "no prompt at all".
+    """
+
+    session_id: str = ""
+    last_event_at: str = ""
+    last_user_prompt: str = ""
+    last_prompt_at: str = ""
+    last_assistant_text: str = ""
+    last_text_at: str = ""
+    recent_tools: tuple[str, ...] = ()
+    in_flight: tuple[str, ...] = ()
+    pending_question: str = ""
+    turn_open: bool = False
+    errored: bool = False
+    git_branch: str = ""
+    tail_complete: bool = True
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+def read_activity(
+    path: str | Path,
+    *,
+    session_id: str = "",
+    tail_bytes: int = TAIL_BYTES,
+    recent: int = RECENT_TOOLS,
+) -> Activity:
+    """Read the tail of a transcript into an :class:`Activity`.
+
+    Costs the watched session nothing: the file is opened read-only and the session is
+    never signalled, messaged or otherwise made aware.
+    """
+    records, complete = tail_records(path, tail_bytes=tail_bytes)
+    main = _main_thread(records)
+    session = parse_session(main, key=session_id)
+    calls, answered = _tool_calls(main)
+    in_flight = [
+        (name, inputs) for call_id, name, inputs in calls if call_id not in answered
+    ]
+    question = next((describe_tool(n, i) for n, i in in_flight if n == QUESTION_TOOL), "")
+    stamps = [_stamp(r) for r in main if _stamp(r)]
+    return Activity(
+        session_id=session.key or session_id,
+        last_event_at=max(stamps) if stamps else "",
+        last_user_prompt=session.last_user_prompt,
+        last_prompt_at=session.last_prompt_at,
+        last_assistant_text=session.last_assistant_text,
+        last_text_at=session.last_turn_at,
+        recent_tools=tuple(describe_tool(n, i) for _, n, i in calls[-recent:])
+        if recent
+        else (),
+        in_flight=tuple(describe_tool(n, i) for n, i in in_flight),
+        pending_question=question.partition(": ")[2] if question else "",
+        turn_open=session.ended_mid_turn,
+        errored=session.ended_with_error,
+        git_branch=session.git_branch,
+        tail_complete=complete,
+    )
+
+
+@dataclass(frozen=True)
+class Turn:
+    """One exchange: a human prompt, what the assistant did, and its last words."""
+
+    index: int
+    prompt: str
+    prompt_at: str
+    reply: str
+    reply_at: str
+    tools: tuple[str, ...]
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+def _opens_a_turn(record: dict) -> bool:
+    """A ``user`` record that could be a human prompt: not a tool result, not injected."""
+    if (
+        record.get("type") != "user"
+        or record.get("isMeta")
+        or record.get("isCompactSummary")
+    ):
+        return False
+    return not any(b.get("type") == "tool_result" for b in _blocks(record))
+
+
+def _turn_chunks(records: list[dict]) -> list[list[dict]]:
+    """Split main-thread records at each human prompt.
+
+    A ``user`` record that opens a chunk but carries no human text once its tooling
+    wrappers are stripped -- a system reminder, a task notification -- was not a turn, and
+    its chunk is folded into the turn before it. That judgement is
+    :func:`openloops.transcripts.parse_session`'s, made on the chunk, not repeated here.
+    """
+    chunks: list[list[dict]] = [[]]
+    for rec in records:
+        if _opens_a_turn(rec):
+            chunks.append([rec])
+        else:
+            chunks[-1].append(rec)
+    turns: list[list[dict]] = []
+    for chunk in chunks:
+        if chunk and parse_session(chunk).last_user_prompt:
+            turns.append(chunk)
+        elif turns:
+            turns[-1].extend(chunk)
+    return turns
+
+
+def read_turns(
+    path: str | Path,
+    *,
+    last: int = 5,
+    before: int | None = None,
+) -> list[Turn]:
+    """The last ``last`` turns of a transcript, oldest first; ``before=N`` pages back.
+
+    Reads the whole file. This is the deep path, taken on request when the tail did not
+    carry enough context -- still cheaper than a turn of the watched session's own.
+    """
+    chunks = _turn_chunks(_main_thread(load_records(path)))
+    turns = []
+    for index, chunk in enumerate(chunks, start=1):
+        session = parse_session(chunk)
+        calls, _ = _tool_calls(chunk)
+        turns.append(
+            Turn(
+                index=index,
+                prompt=session.last_user_prompt,
+                prompt_at=session.last_prompt_at,
+                reply=session.last_assistant_text,
+                reply_at=session.last_turn_at,
+                tools=tuple(describe_tool(n, i) for _, n, i in calls),
+            )
+        )
+    if before is not None:
+        turns = [t for t in turns if t.index < before]
+    return turns[-last:] if last > 0 else turns