kanbot 0.1.0__py3-none-any.whl

kanbot/__init__.py

@@ -0,0 +1,3 @@
+"""Deckhand — a Kanban board where every card is a task run by your local CLI coding agents."""
+
+__version__ = "0.1.0"

kanbot/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

kanbot/agents.py

@@ -0,0 +1,134 @@
+"""Built-in CLI agent catalog, shared by the server (display) and runner (execution).
+
+Each agent is defined declaratively so adding "whatever else is available in the
+CLI" is a one-liner here, or a config override on the runner side. The runner
+detects which `bin` are on PATH and only advertises those it finds.
+
+Command templates use Python str.format with:
+    {prompt}  -> the task prompt (already shell-safe; passed as a single argv item)
+The command is a list of argv tokens; the runner substitutes {prompt} per-token
+so no shell quoting is needed.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass
+class AgentSpec:
+    name: str            # stable id, e.g. "claude"
+    label: str           # display name
+    bin: str             # executable to look for on PATH
+    argv: List[str]      # argv template; tokens may contain {prompt}
+    description: str = ""
+    env: Dict[str, str] = field(default_factory=dict)
+    color: str = "#8b5cf6"
+    # argv template to resume/continue an existing agent session. Tokens may
+    # contain {prompt} and {session_id}. Empty => resume not supported.
+    resume_argv: List[str] = field(default_factory=list)
+
+
+# Non-interactive / headless invocations for each known coding CLI.
+BUILTIN_AGENTS: List[AgentSpec] = [
+    AgentSpec(
+        name="claude",
+        label="Claude Code",
+        bin="claude",
+        argv=["claude", "-p", "{prompt}", "--dangerously-skip-permissions"],
+        resume_argv=["claude", "--resume", "{session_id}", "-p", "{prompt}",
+                     "--dangerously-skip-permissions"],
+        description="Anthropic Claude Code in headless print mode.",
+        color="#d97757",
+    ),
+    AgentSpec(
+        name="codex",
+        label="Codex",
+        bin="codex",
+        argv=["codex", "exec", "--sandbox", "workspace-write",
+              "--skip-git-repo-check", "{prompt}"],
+        resume_argv=["codex", "exec", "resume", "--skip-git-repo-check",
+                     "{session_id}", "{prompt}"],
+        description="OpenAI Codex CLI, non-interactive exec (workspace-write sandbox).",
+        color="#10a37f",
+    ),
+    AgentSpec(
+        name="gemini",
+        label="Gemini CLI",
+        bin="gemini",
+        argv=["gemini", "-y", "-p", "{prompt}"],
+        description="Google Gemini CLI in YOLO/auto mode.",
+        color="#4285f4",
+    ),
+    AgentSpec(
+        name="glm",
+        label="GLM / Z.ai",
+        bin="claude",
+        argv=["claude", "-p", "{prompt}", "--dangerously-skip-permissions"],
+        resume_argv=["claude", "--resume", "{session_id}", "-p", "{prompt}",
+                     "--dangerously-skip-permissions"],
+        description="Z.ai GLM coding plan via Claude Code (set ANTHROPIC_BASE_URL).",
+        env={"ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic"},
+        color="#2563eb",
+    ),
+    AgentSpec(
+        name="opencode",
+        label="OpenCode",
+        bin="opencode",
+        argv=["opencode", "run", "{prompt}"],
+        description="OpenCode terminal agent, non-interactive run.",
+        color="#f59e0b",
+    ),
+    AgentSpec(
+        name="hermes",
+        label="Hermes",
+        bin="hermes",
+        argv=["hermes", "-p", "{prompt}"],
+        description="Hermes coding agent (best-effort; override argv in config if it differs).",
+        color="#e879f9",
+    ),
+    AgentSpec(
+        name="aider",
+        label="Aider",
+        bin="aider",
+        argv=["aider", "--yes", "--no-auto-commits", "--message", "{prompt}"],
+        description="Aider pair-programmer, single message mode.",
+        color="#22c55e",
+    ),
+    AgentSpec(
+        name="cursor-agent",
+        label="Cursor Agent",
+        bin="cursor-agent",
+        argv=["cursor-agent", "-p", "{prompt}"],
+        description="Cursor CLI agent in print mode.",
+        color="#000000",
+    ),
+    AgentSpec(
+        name="shell",
+        label="Shell command",
+        bin="bash",
+        argv=["bash", "-lc", "{prompt}"],
+        description="Run the prompt as a raw shell command. Always available.",
+        color="#64748b",
+    ),
+]
+
+BUILTIN_BY_NAME: Dict[str, AgentSpec] = {a.name: a for a in BUILTIN_AGENTS}
+
+
+def builtin_names() -> List[str]:
+    return [a.name for a in BUILTIN_AGENTS]
+
+
+def spec_to_dict(a: AgentSpec) -> dict:
+    return {
+        "name": a.name,
+        "label": a.label,
+        "bin": a.bin,
+        "description": a.description,
+        "color": a.color,
+    }
+
+
+def catalog() -> List[dict]:
+    return [spec_to_dict(a) for a in BUILTIN_AGENTS]

kanbot/cli.py

@@ -0,0 +1,260 @@
+"""KanBot command-line interface.
+
+  kanbot up            # start server + a local runner together (best first run)
+  kanbot server        # just the web server / API / board
+  kanbot runner        # just the background runner (connects to a server)
+  kanbot agents        # show which CLI coding agents are detected here
+  kanbot config        # view / set server URL, token, runner name
+  kanbot open          # open the board in your browser
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+import threading
+import time
+import webbrowser
+
+from . import __version__
+from .config import Config, config_path, db_path
+
+
+def _rich():
+    try:
+        from rich.console import Console
+        return Console()
+    except Exception:
+        return None
+
+
+def cmd_server(args) -> int:
+    import uvicorn
+    from .server.app import create_app
+
+    app = create_app(db_path=args.db)
+    url = f"http://{args.host}:{args.port}"
+    print(f"KanBot server v{__version__}  →  {url}")
+    print(f"  db:    {args.db or db_path()}")
+    print(f"  open:  {url}  (then run `kanbot runner` on any machine)")
+    uvicorn.run(app, host=args.host, port=args.port, log_level=args.log_level)
+    return 0
+
+
+def cmd_runner(args) -> int:
+    from .runner.worker import Runner
+
+    cfg = Config.load()
+    if args.server:
+        cfg.server_url = args.server
+    if args.token:
+        cfg.token = args.token
+    if args.name:
+        cfg.runner_name = args.name
+    if args.concurrency:
+        cfg.max_concurrency = args.concurrency
+    cfg.save()
+
+    runner = Runner(cfg)
+    try:
+        asyncio.run(runner.run_forever())
+    except KeyboardInterrupt:
+        print("\nrunner stopped.")
+    return 0
+
+
+def cmd_up(args) -> int:
+    """Start the server in-process and attach a local runner. One command demo."""
+    import uvicorn
+    from .runner.worker import Runner
+    from .server.app import create_app
+
+    app = create_app(db_path=args.db)
+    config = uvicorn.Config(app, host=args.host, port=args.port, log_level="warning")
+    server = uvicorn.Server(config)
+
+    def serve():
+        asyncio.run(server.serve())
+
+    t = threading.Thread(target=serve, daemon=True)
+    t.start()
+
+    # wait for the server to come up
+    import httpx
+    base = f"http://{args.host}:{args.port}"
+    for _ in range(50):
+        try:
+            httpx.get(base + "/api/health", timeout=0.5)
+            break
+        except Exception:
+            time.sleep(0.1)
+
+    print(f"KanBot is up  →  {base}")
+    if not args.no_open:
+        try:
+            webbrowser.open(base)
+        except Exception:
+            pass
+
+    cfg = Config.load()
+    cfg.server_url = base
+    if args.name:
+        cfg.runner_name = args.name
+    if args.concurrency:
+        cfg.max_concurrency = args.concurrency
+    cfg.save()
+    runner = Runner(cfg)
+    print(f"Local runner '{cfg.runner_name}' attaching with agents: "
+          f"{', '.join(runner.agents) or '(none — install claude/codex/etc.)'}")
+    print("Press Ctrl-C to stop.\n")
+    try:
+        asyncio.run(runner.run_forever())
+    except KeyboardInterrupt:
+        print("\nshutting down.")
+        server.should_exit = True
+    return 0
+
+
+def cmd_agents(args) -> int:
+    from .runner.agents import detect_agents
+    from .agents import BUILTIN_AGENTS
+
+    cfg = Config.load()
+    found = detect_agents(cfg)
+    console = _rich()
+    if console:
+        from rich.table import Table
+        table = Table(title="CLI agents on this machine")
+        table.add_column("agent")
+        table.add_column("status")
+        table.add_column("description")
+        for spec in BUILTIN_AGENTS:
+            ok = spec.name in found
+            disabled = spec.name in cfg.disabled_agents
+            status = "[green]available[/green]" if ok else (
+                "[yellow]disabled[/yellow]" if disabled else "[dim]not found[/dim]")
+            table.add_row(spec.name, status, spec.description)
+        console.print(table)
+    else:
+        for spec in BUILTIN_AGENTS:
+            mark = "✓" if spec.name in found else "·"
+            print(f" {mark} {spec.name:14} {spec.description}")
+    print(f"\nadvertised capabilities: {', '.join(found) or '(none)'}")
+
+    # Session trackers: which TUIs KanBot can see / revive.
+    from .runner.discovery import active_providers, builtin_providers
+    trackers = active_providers(cfg.discovery_sources)
+    active_names = {t["name"] for t in trackers}
+    print("\nsession trackers (TUIs KanBot watches):")
+    for p in builtin_providers():
+        mark = "✓" if p.name in active_names else "·"
+        state = "tracking" if p.name in active_names else "no sessions found"
+        print(f"  {mark} {p.label:14} {p.root}  [{state}]")
+    for t in trackers:
+        if t["name"] not in ("claude", "codex"):
+            print(f"  ✓ {t['label']:14} {t['root']}  [custom]")
+    print("\nTrack another agent: add to discovery_sources in "
+          f"{config_path()}, e.g.\n"
+          '  {"name": "hermes", "label": "Hermes", "root": "~/.hermes/sessions",\n'
+          '   "pattern": "*.jsonl", "recursive": true, "fmt": "claude"}')
+    return 0
+
+
+def cmd_config(args) -> int:
+    cfg = Config.load()
+    changed = False
+    if args.server:
+        cfg.server_url = args.server; changed = True
+    if args.token is not None:
+        cfg.token = args.token; changed = True
+    if args.name:
+        cfg.runner_name = args.name; changed = True
+    if args.concurrency:
+        cfg.max_concurrency = args.concurrency; changed = True
+    if args.disable:
+        for a in args.disable:
+            if a not in cfg.disabled_agents:
+                cfg.disabled_agents.append(a)
+        changed = True
+    if args.enable:
+        cfg.disabled_agents = [a for a in cfg.disabled_agents if a not in args.enable]
+        changed = True
+    if changed:
+        cfg.save()
+        print(f"saved {config_path()}")
+    print(f"server_url      : {cfg.server_url}")
+    print(f"token           : {'(set)' if cfg.token else '(none)'}")
+    print(f"runner_name     : {cfg.runner_name}")
+    print(f"runner_id       : {cfg.runner_id}")
+    print(f"max_concurrency : {cfg.max_concurrency}")
+    print(f"disabled_agents : {', '.join(cfg.disabled_agents) or '(none)'}")
+    return 0
+
+
+def cmd_open(args) -> int:
+    cfg = Config.load()
+    url = args.server or cfg.server_url
+    print(f"opening {url}")
+    webbrowser.open(url)
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="kanbot", description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--version", action="version", version=f"kanbot {__version__}")
+    sub = p.add_subparsers(dest="cmd")
+
+    sp = sub.add_parser("up", help="start server + local runner (recommended first run)")
+    sp.add_argument("--host", default="127.0.0.1")
+    sp.add_argument("--port", type=int, default=8787)
+    sp.add_argument("--db", default=None)
+    sp.add_argument("--name", default=None, help="runner name")
+    sp.add_argument("--concurrency", type=int, default=None)
+    sp.add_argument("--no-open", action="store_true", help="don't open the browser")
+    sp.set_defaults(func=cmd_up)
+
+    sp = sub.add_parser("server", help="run the web server / API only")
+    sp.add_argument("--host", default="127.0.0.1")
+    sp.add_argument("--port", type=int, default=8787)
+    sp.add_argument("--db", default=None)
+    sp.add_argument("--log-level", default="info")
+    sp.set_defaults(func=cmd_server)
+
+    sp = sub.add_parser("runner", help="run the background runner only")
+    sp.add_argument("--server", default=None, help="server URL (e.g. http://host:8787)")
+    sp.add_argument("--token", default=None)
+    sp.add_argument("--name", default=None)
+    sp.add_argument("--concurrency", type=int, default=None)
+    sp.set_defaults(func=cmd_runner)
+
+    sp = sub.add_parser("agents", help="show detected CLI agents")
+    sp.set_defaults(func=cmd_agents)
+
+    sp = sub.add_parser("config", help="view or set configuration")
+    sp.add_argument("--server", default=None)
+    sp.add_argument("--token", default=None)
+    sp.add_argument("--name", default=None)
+    sp.add_argument("--concurrency", type=int, default=None)
+    sp.add_argument("--disable", nargs="*", help="agent names to disable")
+    sp.add_argument("--enable", nargs="*", help="agent names to re-enable")
+    sp.set_defaults(func=cmd_config)
+
+    sp = sub.add_parser("open", help="open the board in a browser")
+    sp.add_argument("--server", default=None)
+    sp.set_defaults(func=cmd_open)
+
+    return p
+
+
+def main(argv=None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if not getattr(args, "cmd", None):
+        parser.print_help()
+        return 0
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

kanbot/config.py

@@ -0,0 +1,77 @@
+"""User/runner configuration stored in ~/.kanbot/config.json."""
+from __future__ import annotations
+
+import json
+import os
+import socket
+import uuid
+from dataclasses import dataclass, asdict, field
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+def config_dir() -> Path:
+    base = os.environ.get("KANBOT_HOME") or os.environ.get("DECKHAND_HOME")
+    if base:
+        path = Path(base).expanduser()
+    else:
+        path = Path.home() / ".kanbot"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def config_path() -> Path:
+    return config_dir() / "config.json"
+
+
+def db_path() -> Path:
+    env = os.environ.get("KANBOT_DB") or os.environ.get("DECKHAND_DB")
+    if env:
+        return Path(env).expanduser()
+    return config_dir() / "kanbot.db"
+
+
+@dataclass
+class Config:
+    """Local config used by both the runner and convenience commands."""
+
+    server_url: str = "http://127.0.0.1:8787"
+    token: str = ""
+    runner_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    runner_name: str = field(default_factory=lambda: socket.gethostname())
+    # Map of agent-name -> override command template. Empty = use built-in defaults.
+    agent_overrides: Dict[str, str] = field(default_factory=dict)
+    # Agents the user has explicitly disabled.
+    disabled_agents: list = field(default_factory=list)
+    max_concurrency: int = 2
+    # Extra session stores to track, e.g. Hermes or any agent that logs JSONL:
+    #   [{"name": "hermes", "label": "Hermes", "root": "~/.hermes/sessions",
+    #     "pattern": "*.jsonl", "recursive": true, "fmt": "claude"}]
+    discovery_sources: list = field(default_factory=list)
+
+    @classmethod
+    def load(cls) -> "Config":
+        p = config_path()
+        if p.exists():
+            try:
+                data = json.loads(p.read_text())
+            except (json.JSONDecodeError, OSError):
+                data = {}
+        else:
+            data = {}
+        known = {f for f in cls.__dataclass_fields__}  # type: ignore[attr-defined]
+        clean = {k: v for k, v in data.items() if k in known}
+        cfg = cls(**clean)
+        return cfg
+
+    def save(self) -> None:
+        config_path().write_text(json.dumps(asdict(self), indent=2))
+
+    @property
+    def ws_url(self) -> str:
+        url = self.server_url.rstrip("/")
+        if url.startswith("https://"):
+            return "wss://" + url[len("https://"):]
+        if url.startswith("http://"):
+            return "ws://" + url[len("http://"):]
+        return url

kanbot/runner/__init__.py

@@ -0,0 +1 @@
+"""Deckhand runner package."""

kanbot/runner/agents.py

@@ -0,0 +1,141 @@
+"""Agent detection and execution for the runner.
+
+Detection: walk the built-in catalog, keep any whose `bin` is on PATH, apply
+user overrides/disables from config. The resulting list of names is what the
+runner advertises to the server as its capabilities.
+
+Execution: spawn the agent's argv (with {prompt} substituted per token) in the
+target cwd, stream stdout/stderr lines back through an async callback, and honor
+cancellation.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import shlex
+import shutil
+from dataclasses import dataclass
+from typing import Awaitable, Callable, Dict, List, Optional
+
+from ..agents import BUILTIN_AGENTS, AgentSpec
+from ..config import Config
+
+
+@dataclass
+class ResolvedAgent:
+    name: str
+    label: str
+    argv: List[str]
+    env: Dict[str, str]
+    resume_argv: List[str] = None  # type: ignore[assignment]
+
+    @property
+    def can_resume(self) -> bool:
+        return bool(self.resume_argv)
+
+
+def _override_argv(template: str) -> List[str]:
+    """A config override is a shell-ish string; keep {prompt} as its own token."""
+    return shlex.split(template)
+
+
+def detect_agents(cfg: Config) -> Dict[str, ResolvedAgent]:
+    found: Dict[str, ResolvedAgent] = {}
+    for spec in BUILTIN_AGENTS:
+        if spec.name in cfg.disabled_agents:
+            continue
+        argv = spec.argv
+        binary = spec.bin
+        if spec.name in cfg.agent_overrides:
+            argv = _override_argv(cfg.agent_overrides[spec.name])
+            binary = argv[0] if argv else spec.bin
+        if not shutil.which(binary):
+            continue
+        found[spec.name] = ResolvedAgent(
+            name=spec.name, label=spec.label, argv=list(argv), env=dict(spec.env),
+            resume_argv=list(spec.resume_argv),
+        )
+    return found
+
+
+def build_argv(agent: ResolvedAgent, prompt: str, resume_of: str = "") -> List[str]:
+    template = agent.resume_argv if (resume_of and agent.can_resume) else agent.argv
+    out: List[str] = []
+    for tok in template:
+        tok = tok.replace("{prompt}", prompt)
+        tok = tok.replace("{session_id}", resume_of)
+        out.append(tok)
+    return out
+
+
+LogCb = Callable[[str, str], Awaitable[None]]  # (stream, text) -> awaitable
+
+
+class Execution:
+    """A running agent subprocess for one session."""
+
+    def __init__(self, session_id: str, proc: asyncio.subprocess.Process):
+        self.session_id = session_id
+        self.proc = proc
+
+    async def cancel(self) -> None:
+        if self.proc.returncode is None:
+            try:
+                self.proc.terminate()
+            except ProcessLookupError:
+                return
+            try:
+                await asyncio.wait_for(self.proc.wait(), timeout=5)
+            except asyncio.TimeoutError:
+                try:
+                    self.proc.kill()
+                except ProcessLookupError:
+                    pass
+
+
+async def run_agent(agent: ResolvedAgent, prompt: str, cwd: str, on_log: LogCb,
+                    register: Callable[[Execution], None], resume_of: str = "") -> int:
+    """Run the agent, streaming output. Returns the process exit code."""
+    if resume_of and not agent.can_resume:
+        await on_log("system", f"agent '{agent.name}' can't resume sessions; starting fresh.")
+        resume_of = ""
+    argv = build_argv(agent, prompt, resume_of)
+    if resume_of:
+        await on_log("system", f"resuming {agent.name} session {resume_of}")
+    workdir = cwd if cwd and os.path.isdir(cwd) else os.getcwd()
+    env = os.environ.copy()
+    env.update(agent.env)
+
+    await on_log("system", f"$ {' '.join(shlex.quote(a) for a in argv)}")
+    await on_log("system", f"(cwd: {workdir})")
+
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *argv, cwd=workdir, env=env,
+            stdin=asyncio.subprocess.DEVNULL,  # headless: never block on interactive stdin
+            stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE,
+        )
+    except FileNotFoundError:
+        await on_log("stderr", f"agent binary not found: {argv[0]}")
+        return 127
+    except OSError as e:
+        await on_log("stderr", f"failed to start agent: {e}")
+        return 1
+
+    execution = Execution("", proc)
+    register(execution)
+
+    async def pump(stream, name: str):
+        assert stream is not None
+        while True:
+            line = await stream.readline()
+            if not line:
+                break
+            await on_log(name, line.decode("utf-8", "replace").rstrip("\n"))
+
+    await asyncio.gather(
+        pump(proc.stdout, "stdout"),
+        pump(proc.stderr, "stderr"),
+    )
+    rc = await proc.wait()
+    return rc