taskswarm-cli 0.1.0__py3-none-any.whl

taskswarm/server/http_server.py

@@ -0,0 +1,255 @@
+"""The TaskSwarm HTTP+SSE server: POST /events ingests a status transition,
+GET /events lists current session state, GET /live streams new events over
+Server-Sent Events, and GET / serves the live status page. Ported from
+src/server/http-server.ts.
+
+Uses only the standard library (`http.server.ThreadingHTTPServer`) -- one
+thread per connection, which is what makes a long-lived GET /live SSE
+connection sit in its own thread without blocking any other request. This
+mirrors Node's single-process-many-connections model closely enough for a
+tool meant to run on a developer's own machine, not at scale.
+"""
+from __future__ import annotations
+
+import json
+import os
+import queue
+import threading
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any, Dict, Optional
+from urllib.parse import parse_qs, urlparse
+
+from ..notifications.dispatch import NotifyOptions, notify
+from ..schema.events import EventValidationError, parse_agent_event_input, to_agent_event
+from .auth import extract_bearer_token, tokens_match
+from .event_store import EventStore
+
+# 64KiB is generous for a single event envelope.
+MAX_BODY_BYTES = 64 * 1024
+
+_UI_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "ui")
+
+# SSE clients that get a heartbeat comment (never real data) if nothing
+# arrives for this long, so a dead TCP connection is noticed and cleaned up
+# instead of the serving thread blocking on it forever.
+_SSE_HEARTBEAT_SECONDS = 15.0
+
+# Caps concurrent /live SSE connections (each holds its own OS thread here,
+# since ThreadingHTTPServer is one-thread-per-connection) so a client
+# (malicious or just leaked-token) can't exhaust server threads/FDs by
+# opening unbounded long-lived connections.
+_MAX_SSE_CLIENTS = 64
+
+
+class TaskSwarmHTTPServer(ThreadingHTTPServer):
+    daemon_threads = True
+    allow_reuse_address = True
+
+    store: EventStore
+    token: str
+    notify_options: NotifyOptions
+    sse_clients: "set[queue.Queue]"
+    sse_lock: threading.Lock
+
+
+def _send_json(handler: BaseHTTPRequestHandler, status: int, body: Any) -> None:
+    payload = json.dumps(body).encode("utf-8")
+    handler.send_response(status)
+    handler.send_header("Content-Type", "application/json; charset=utf-8")
+    handler.send_header("Content-Length", str(len(payload)))
+    handler.end_headers()
+    try:
+        handler.wfile.write(payload)
+    except (BrokenPipeError, ConnectionResetError):
+        pass
+
+
+def _is_authorized(
+    handler: BaseHTTPRequestHandler, token: str, query: Dict[str, list], allow_query_token: bool
+) -> bool:
+    header_token = extract_bearer_token(handler.headers.get("Authorization"))
+    if header_token and tokens_match(header_token, token):
+        return True
+    # SSE clients (EventSource) cannot set custom headers, so /live -- and
+    # only /live -- also accepts the token as a query parameter. Every other
+    # route requires the Authorization header, since a query-string token
+    # lands in local access logs / shell history / browser history and there
+    # is no EventSource-style constraint forcing it there for POST/GET /events.
+    if allow_query_token:
+        query_token = (query.get("token") or [None])[0]
+        if query_token and tokens_match(query_token, token):
+            return True
+    return False
+
+
+class TaskSwarmRequestHandler(BaseHTTPRequestHandler):
+    server: TaskSwarmHTTPServer
+    protocol_version = "HTTP/1.1"
+
+    def log_message(self, format: str, *args: Any) -> None:  # noqa: A002 - stdlib signature
+        # Silence the default access log to stderr; this is a local
+        # developer tool, not a production service that needs request logs.
+        pass
+
+    def do_GET(self) -> None:  # noqa: N802 - stdlib method name
+        parsed = urlparse(self.path)
+        query = parse_qs(parsed.query)
+
+        if parsed.path in ("/", "/index.html"):
+            self._serve_index()
+            return
+
+        if parsed.path == "/events":
+            if not _is_authorized(self, self.server.token, query, allow_query_token=False):
+                _send_json(self, 401, {"error": "unauthorized"})
+                return
+            self._handle_get_events()
+            return
+
+        if parsed.path == "/live":
+            if not _is_authorized(self, self.server.token, query, allow_query_token=True):
+                _send_json(self, 401, {"error": "unauthorized"})
+                return
+            self._handle_live()
+            return
+
+        _send_json(self, 404, {"error": "not found"})
+
+    def do_POST(self) -> None:  # noqa: N802 - stdlib method name
+        parsed = urlparse(self.path)
+        query = parse_qs(parsed.query)
+
+        if parsed.path == "/events":
+            if not _is_authorized(self, self.server.token, query, allow_query_token=False):
+                _send_json(self, 401, {"error": "unauthorized"})
+                return
+            self._handle_post_event()
+            return
+
+        _send_json(self, 404, {"error": "not found"})
+
+    def _serve_index(self) -> None:
+        try:
+            with open(os.path.join(_UI_DIR, "index.html"), "r", encoding="utf-8") as handle:
+                html = handle.read()
+        except OSError:
+            _send_json(self, 500, {"error": "ui assets not found"})
+            return
+        payload = html.encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html; charset=utf-8")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def _read_body(self) -> Optional[bytes]:
+        content_length = self.headers.get("Content-Length")
+        if content_length is None:
+            return b""
+        try:
+            length = int(content_length)
+        except ValueError:
+            return b""
+        if length > MAX_BODY_BYTES:
+            return None
+        return self.rfile.read(length)
+
+    def _handle_post_event(self) -> None:
+        raw = self._read_body()
+        if raw is None:
+            _send_json(self, 413, {"error": "request body too large"})
+            return
+
+        try:
+            parsed_json = json.loads(raw) if len(raw) > 0 else {}
+        except json.JSONDecodeError:
+            _send_json(self, 400, {"error": "invalid JSON body"})
+            return
+
+        try:
+            validated = parse_agent_event_input(parsed_json)
+        except EventValidationError as error:
+            _send_json(self, 400, {"error": "invalid event", "details": error.details})
+            return
+
+        event = to_agent_event(validated)
+        previous_status, previous_blocked_reason = self.server.store.append(event)
+        notify(event, previous_status, previous_blocked_reason, self.server.notify_options)
+
+        _send_json(self, 201, event.to_dict())
+
+    def _handle_get_events(self) -> None:
+        sessions = self.server.store.list_sessions()
+        _send_json(
+            self,
+            200,
+            {
+                "sessions": [
+                    {
+                        "session_id": s.session_id,
+                        "latest": s.latest.to_dict(),
+                        "history": [e.to_dict() for e in s.history],
+                    }
+                    for s in sessions
+                ]
+            },
+        )
+
+    def _handle_live(self) -> None:
+        with self.server.sse_lock:
+            at_capacity = len(self.server.sse_clients) >= _MAX_SSE_CLIENTS
+        if at_capacity:
+            _send_json(self, 503, {"error": "too many concurrent /live connections"})
+            return
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream; charset=utf-8")
+        self.send_header("Cache-Control", "no-cache")
+        self.send_header("Connection", "keep-alive")
+        self.end_headers()
+        try:
+            self.wfile.write(b": connected\n\n")
+            self.wfile.flush()
+        except (BrokenPipeError, ConnectionResetError):
+            return
+
+        client_queue: "queue.Queue[str]" = queue.Queue()
+        with self.server.sse_lock:
+            self.server.sse_clients.add(client_queue)
+        try:
+            while True:
+                try:
+                    frame = client_queue.get(timeout=_SSE_HEARTBEAT_SECONDS)
+                except queue.Empty:
+                    self.wfile.write(b": keep-alive\n\n")
+                    self.wfile.flush()
+                    continue
+                self.wfile.write(frame.encode("utf-8"))
+                self.wfile.flush()
+        except (BrokenPipeError, ConnectionResetError, OSError):
+            pass
+        finally:
+            with self.server.sse_lock:
+                self.server.sse_clients.discard(client_queue)
+
+
+def create_http_server(store: EventStore, token: str, notify_options: Optional[NotifyOptions] = None) -> TaskSwarmHTTPServer:
+    """Creates (but does not start listening on) the TaskSwarm HTTP+SSE
+    server, bound to a placeholder address. Call `server.server_bind()` and
+    `server.server_activate()` (or use `server/index.py`'s `start_server`)
+    to actually listen."""
+    server = TaskSwarmHTTPServer(("127.0.0.1", 0), TaskSwarmRequestHandler, bind_and_activate=False)
+    server.store = store
+    server.token = token
+    server.notify_options = notify_options or NotifyOptions()
+    server.sse_clients = set()
+    server.sse_lock = threading.Lock()
+
+    def _on_event(event: Any) -> None:
+        frame = f"data: {json.dumps(event.to_dict())}\n\n"
+        with server.sse_lock:
+            clients = list(server.sse_clients)
+        for client_queue in clients:
+            client_queue.put(frame)
+
+    store.add_listener(_on_event)
+    return server

taskswarm/server/server.py

@@ -0,0 +1,72 @@
+"""Boots the event store + HTTP/SSE server and starts listening. Ported
+from src/server/index.ts."""
+from __future__ import annotations
+
+import sys
+import threading
+from dataclasses import dataclass
+from typing import Any, Callable, Optional
+from urllib.parse import quote
+
+from ..notifications.dispatch import NotifyOptions
+from .config import TaskSwarmConfig, get_event_log_path, load_or_create_config
+from .event_store import EventStore
+from .http_server import TaskSwarmHTTPServer, create_http_server
+
+# Sentinel distinguishing "no log_path argument given" (use the default
+# path) from "log_path=None passed explicitly" (disable persistence).
+_UNSET = object()
+
+
+@dataclass
+class RunningServer:
+    server: TaskSwarmHTTPServer
+    store: EventStore
+    config: TaskSwarmConfig
+    url: str
+    close: Callable[[], None]
+
+
+def start_server(
+    config: Optional[TaskSwarmConfig] = None,
+    log_path: Any = _UNSET,
+    notify_options: Optional[NotifyOptions] = None,
+) -> RunningServer:
+    resolved_config = config or load_or_create_config()
+    resolved_log_path = None if log_path is None else (get_event_log_path() if log_path is _UNSET else log_path)
+
+    resolved_notify_options = notify_options
+    if resolved_notify_options is None:
+        ntfy = resolved_config.ntfy or {}
+        resolved_notify_options = NotifyOptions(ntfy=ntfy if ntfy.get("enabled") else None)
+
+    store = EventStore(resolved_log_path)
+    server = create_http_server(store, resolved_config.token, resolved_notify_options)
+    server.server_address = (resolved_config.host, resolved_config.port)
+    server.server_bind()
+    server.server_activate()
+    # The actual bound port (relevant when port=0 was requested, e.g. in tests).
+    resolved_config.port = server.server_address[1]
+
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+
+    if resolved_config.host not in ("127.0.0.1", "localhost", "::1"):
+        # Two things get worse off loopback: the bearer token travels in
+        # plaintext http:// (no TLS path exists), and it's accepted as a
+        # ?token= query parameter for /live, which lands in local access logs.
+        print(
+            f'[taskswarm] warning: binding to "{resolved_config.host}" instead of loopback -- '
+            "the API token is sent over plaintext http:// with no TLS, and is accepted as a URL "
+            "query parameter for /live (visible in local access logs). Only do this on a "
+            "network you trust.",
+            file=sys.stderr,
+        )
+
+    url = f"http://{resolved_config.host}:{resolved_config.port}/?token={quote(resolved_config.token)}"
+
+    def close() -> None:
+        server.shutdown()
+        server.server_close()
+
+    return RunningServer(server=server, store=store, config=resolved_config, url=url, close=close)

taskswarm/ui/index.html

@@ -0,0 +1,241 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>TaskSwarm</title>
+    <style>
+      :root {
+        color-scheme: light dark;
+        --bg: #0b0d12;
+        --fg: #e6e8ee;
+        --muted: #8b93a7;
+        --border: #232733;
+        --row: #12151d;
+        --accent: #5b8cff;
+      }
+      @media (prefers-color-scheme: light) {
+        :root {
+          --bg: #f7f8fa;
+          --fg: #14171f;
+          --muted: #5b6272;
+          --border: #e1e4ea;
+          --row: #ffffff;
+          --accent: #2f5fe0;
+        }
+      }
+      * {
+        box-sizing: border-box;
+      }
+      body {
+        margin: 0;
+        font-family:
+          -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+        background: var(--bg);
+        color: var(--fg);
+        padding: 2rem 1.5rem 4rem;
+      }
+      header {
+        display: flex;
+        align-items: baseline;
+        justify-content: space-between;
+        max-width: 1100px;
+        margin: 0 auto 1.5rem;
+      }
+      h1 {
+        font-size: 1.25rem;
+        margin: 0;
+        letter-spacing: -0.01em;
+      }
+      #conn-status {
+        font-size: 0.8rem;
+        color: var(--muted);
+      }
+      #conn-status.live {
+        color: #35c26a;
+      }
+      #conn-status.down {
+        color: #e0553f;
+      }
+      table {
+        width: 100%;
+        max-width: 1100px;
+        margin: 0 auto;
+        border-collapse: collapse;
+        border: 1px solid var(--border);
+        border-radius: 8px;
+        overflow: hidden;
+      }
+      thead th {
+        text-align: left;
+        font-size: 0.75rem;
+        text-transform: uppercase;
+        letter-spacing: 0.04em;
+        color: var(--muted);
+        padding: 0.6rem 0.9rem;
+        border-bottom: 1px solid var(--border);
+      }
+      tbody td {
+        padding: 0.7rem 0.9rem;
+        border-bottom: 1px solid var(--border);
+        font-size: 0.9rem;
+        background: var(--row);
+      }
+      tbody tr:last-child td {
+        border-bottom: none;
+      }
+      .status-pill {
+        display: inline-block;
+        padding: 0.15rem 0.55rem;
+        border-radius: 999px;
+        font-size: 0.75rem;
+        font-weight: 600;
+      }
+      .status-queued {
+        background: #3a3f4d;
+        color: #c7cbd6;
+      }
+      .status-running {
+        background: #1f3a63;
+        color: #8fb8ff;
+      }
+      .status-blocked {
+        background: #5a3a17;
+        color: #ffbd6b;
+      }
+      .status-needs-review {
+        background: #5a3a17;
+        color: #ffd76b;
+      }
+      .status-done {
+        background: #17402a;
+        color: #6ee6a2;
+      }
+      .status-failed {
+        background: #4a1c1c;
+        color: #ff8f8f;
+      }
+      #empty {
+        max-width: 1100px;
+        margin: 3rem auto;
+        text-align: center;
+        color: var(--muted);
+      }
+      code {
+        font-size: 0.85em;
+        color: var(--muted);
+      }
+    </style>
+  </head>
+  <body>
+    <header>
+      <h1>TaskSwarm</h1>
+      <span id="conn-status">connecting&hellip;</span>
+    </header>
+    <table id="sessions-table">
+      <thead>
+        <tr>
+          <th>Session</th>
+          <th>Repo</th>
+          <th>Agent</th>
+          <th>Status</th>
+          <th>Last event</th>
+        </tr>
+      </thead>
+      <tbody id="sessions-body"></tbody>
+    </table>
+    <p id="empty" hidden>
+      No sessions tracked yet. Report one with <code>taskswarm agent report-status</code>.
+    </p>
+
+    <script>
+      (function () {
+        var params = new URLSearchParams(window.location.search);
+        var token = params.get('token') || '';
+        var tbody = document.getElementById('sessions-body');
+        var empty = document.getElementById('empty');
+        var connStatus = document.getElementById('conn-status');
+        var sessions = new Map();
+
+        function statusClass(status) {
+          return 'status-pill status-' + status;
+        }
+
+        function render() {
+          var rows = Array.from(sessions.values()).sort(function (a, b) {
+            return Date.parse(b.timestamp) - Date.parse(a.timestamp);
+          });
+          empty.hidden = rows.length > 0;
+          tbody.innerHTML = '';
+          rows.forEach(function (row) {
+            var tr = document.createElement('tr');
+            var cells = [
+              row.session_id,
+              row.repo,
+              row.agent_type,
+              '<span class="' + statusClass(row.status) + '">' + row.status + '</span>',
+              new Date(row.timestamp).toLocaleString(),
+            ];
+            cells.forEach(function (cell, i) {
+              var td = document.createElement('td');
+              if (i === 3) {
+                td.innerHTML = cell;
+              } else {
+                td.textContent = cell;
+              }
+              tr.appendChild(td);
+            });
+            tbody.appendChild(tr);
+          });
+        }
+
+        function applyEvent(event) {
+          sessions.set(event.session_id, event);
+          render();
+        }
+
+        function loadInitial() {
+          fetch('/events', { headers: { Authorization: 'Bearer ' + token } })
+            .then(function (res) {
+              if (!res.ok) throw new Error('failed to load /events: ' + res.status);
+              return res.json();
+            })
+            .then(function (data) {
+              (data.sessions || []).forEach(function (s) {
+                sessions.set(s.session_id, s.latest);
+              });
+              render();
+            })
+            .catch(function () {
+              connStatus.textContent = 'failed to load sessions';
+              connStatus.className = 'down';
+            });
+        }
+
+        function connectLive() {
+          var url = '/live?token=' + encodeURIComponent(token);
+          var source = new EventSource(url);
+          source.addEventListener('open', function () {
+            connStatus.textContent = 'live';
+            connStatus.className = 'live';
+          });
+          source.addEventListener('message', function (evt) {
+            try {
+              var event = JSON.parse(evt.data);
+              applyEvent(event);
+            } catch (e) {
+              /* ignore malformed frame */
+            }
+          });
+          source.addEventListener('error', function () {
+            connStatus.textContent = 'reconnecting…';
+            connStatus.className = 'down';
+          });
+        }
+
+        loadInitial();
+        connectLive();
+      })();
+    </script>
+  </body>
+</html>

taskswarm/util/sync_sleep.py

@@ -0,0 +1,15 @@
+"""Ported from src/util/sync-sleep.ts. The TS version needs a genuinely
+blocking sleep (a plain `await sleep()` would yield to Node's event loop and
+let other async work interleave with the retry loops in config.py /
+tasks_registry.py that must run atomically with respect to a single
+process). Python's `time.sleep` already blocks the calling thread without
+yielding to anything else, so this wrapper exists only to keep the module
+layout parallel to the TypeScript source and give the retry loops a single,
+clearly-named call site."""
+from __future__ import annotations
+
+import time
+
+
+def sleep_sync_ms(milliseconds: float) -> None:
+    time.sleep(milliseconds / 1000.0)