@topy-ai/maggie 0.7.49 → 0.7.51

package/bundled-tools/clis/maggie_skill_catalog.py

@@ -0,0 +1,262 @@
+#!/usr/bin/env python3
+"""Skill catalog tooling for any Agent Skills collection (``maggie skills``).
+
+Maggie validates its own skills with ``scripts/validate_skills.py``; a product
+that ships its own catalog (tens or hundreds of skills) needs the same checks
+plus packaging for Claude Code plugin marketplaces:
+
+- ``scaffold``: a new ``<root>/<name>/SKILL.md`` with valid front matter;
+- ``validate``: front matter (``name`` = folder, lower-case, at most 64
+  characters; ``description`` at most 1024), duplicate names, unfinished
+  placeholders, relative links, optional pinned references (``references``
+  entries with a 40-character commit) and an optional catalog index;
+- ``package``: category plugins plus one all-in-one plugin, each with
+  ``.claude-plugin/plugin.json``, and a ``.claude-plugin/marketplace.json``;
+- ``smoke``: re-validates a packaged marketplace (names, versions, sources,
+  every packaged skill) and runs ``claude plugin validate`` when available.
+
+Skill bodies are copied as-is; nothing is published.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+NAME_RE = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+LINK_RE = re.compile(r"\]\(([^)#\s]+)(?:#[^)]*)?\)")
+PLACEHOLDER_RE = re.compile(r"\bTODO\b|replace-me|lorem ipsum", re.I)
+COMMIT_RE = re.compile(r"^[0-9a-f]{40}$")
+IGNORED = {".git", "node_modules", "dist", "build"}
+
+
+def parse_front_matter(text: str) -> tuple[dict, str]:
+    """Parse a small YAML front matter subset: scalars, inline lists, one nesting level."""
+    if not text.startswith("---\n"):
+        raise ValueError("missing YAML front matter")
+    end = text.find("\n---", 4)
+    if end < 0:
+        raise ValueError("front matter is not closed")
+    data: dict = {}
+    current: str | None = None
+    for raw in text[4:end].splitlines():
+        if not raw.strip() or raw.lstrip().startswith("#"):
+            continue
+        if raw.startswith((" ", "\t")) and current:
+            stripped = raw.strip()
+            if stripped.startswith("- "):
+                data.setdefault(current, [])
+                if isinstance(data[current], list):
+                    data[current].append(_scalar(stripped[2:]))
+            elif ":" in stripped:
+                key, _, value = stripped.partition(":")
+                if not isinstance(data.get(current), dict):
+                    data[current] = {}
+                data[current][key.strip()] = _scalar(value)
+            continue
+        key, sep, value = raw.partition(":")
+        if not sep:
+            raise ValueError(f"invalid front matter line: {raw[:60]}")
+        current = key.strip()
+        data[current] = _scalar(value) if value.strip() else None
+    return data, text[end + 4:]
+
+
+def _scalar(value: str) -> object:
+    value = value.strip()
+    if value.startswith("[") and value.endswith("]"):
+        return [_scalar(item) for item in value[1:-1].split(",") if item.strip()]
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+        return value[1:-1]
+    if value in {"true", "false"}:
+        return value == "true"
+    return value
+
+
+def find_skills(root: Path) -> list[Path]:
+    return sorted(path for path in root.rglob("SKILL.md") if not any(part in IGNORED for part in path.relative_to(root).parts))
+
+
+def validate(root: Path, require_pinned: bool, catalog: Path | None) -> dict:
+    root = root.resolve()
+    errors: list[str] = []
+    warnings: list[str] = []
+    seen: dict[str, str] = {}
+    skills = find_skills(root)
+    if not skills:
+        errors.append("no SKILL.md files found")
+    records = []
+    for path in skills:
+        rel = str(path.relative_to(root))
+        text = path.read_text(encoding="utf-8")
+        try:
+            meta, body = parse_front_matter(text)
+        except ValueError as error:
+            errors.append(f"{rel}: {error}"); continue
+        name = str(meta.get("name") or "")
+        description = str(meta.get("description") or "")
+        if not NAME_RE.match(name) or len(name) > 64:
+            errors.append(f"{rel}: name must be lower-case letters, digits and hyphens, at most 64 characters")
+        if name != path.parent.name:
+            errors.append(f"{rel}: name {name!r} must equal its folder {path.parent.name!r}")
+        if name in seen:
+            errors.append(f"{rel}: duplicate name {name!r} (also {seen[name]})")
+        seen[name] = rel
+        if not description.strip():
+            errors.append(f"{rel}: description is required")
+        elif len(description) > 1024:
+            errors.append(f"{rel}: description is {len(description)} characters; the limit is 1024")
+        elif len(description) < 40:
+            warnings.append(f"{rel}: description is very short; say what it does and when to use it")
+        if re.search(r"<[^>]+>", description):
+            errors.append(f"{rel}: description must not contain XML/HTML tags")
+        if PLACEHOLDER_RE.search(text):
+            errors.append(f"{rel}: unfinished placeholder")
+        for target in LINK_RE.findall(body):
+            if target.startswith(("http://", "https://", "mailto:")):
+                continue
+            if not (path.parent / target).resolve().exists():
+                errors.append(f"{rel}: broken link {target}")
+        references = meta.get("references")
+        if require_pinned:
+            for item in references if isinstance(references, list) else []:
+                commit = item.get("commit") if isinstance(item, dict) else None
+                if not commit or not COMMIT_RE.match(str(commit)):
+                    errors.append(f"{rel}: reference is not pinned to a 40-character commit")
+        if len(body.splitlines()) > 500:
+            warnings.append(f"{rel}: body is over 500 lines; move detail into references/ files")
+        records.append({"name": name, "path": rel, "category": (meta.get("metadata") or {}).get("category") if isinstance(meta.get("metadata"), dict) else meta.get("category"), "version": (meta.get("metadata") or {}).get("version") if isinstance(meta.get("metadata"), dict) else meta.get("version")})
+    if catalog:
+        index = json.loads(catalog.read_text(encoding="utf-8"))
+        entries = index.get("skills", index if isinstance(index, list) else [])
+        listed = {str(item.get("id") or item.get("name")) for item in entries if isinstance(item, dict)}
+        for name in sorted(set(seen) - listed):
+            errors.append(f"catalog: {name} has a SKILL.md but no catalog entry")
+        for name in sorted(listed - set(seen)):
+            errors.append(f"catalog: {name} is listed but has no SKILL.md")
+    return {"schemaVersion": "maggie-skill-catalog-validation.v1", "passed": not errors, "skills": len(records), "records": records, "errors": errors, "warnings": warnings}
+
+
+def scaffold(root: Path, name: str, description: str, category: str | None) -> Path:
+    if not NAME_RE.match(name) or len(name) > 64:
+        raise ValueError("name must be lower-case letters, digits and hyphens, at most 64 characters")
+    if not description.strip() or len(description) > 1024:
+        raise ValueError("description is required and at most 1024 characters")
+    target = root / (category or "") / name / "SKILL.md"
+    if target.exists():
+        raise ValueError(f"{target} already exists")
+    target.parent.mkdir(parents=True)
+    meta = f"---\nname: {name}\ndescription: {json.dumps(description, ensure_ascii=False)}\n"
+    if category:
+        meta += f"metadata:\n  category: {category}\n  version: 0.1.0\n"
+    title = name.replace("-", " ").title()
+    target.write_text(meta + f"---\n\n# {title}\n\n## When to use\n\n## Inputs\n\n## Steps\n\n## Output\n\n## Safety and limits\n", encoding="utf-8")
+    return target
+
+
+def package(root: Path, out: Path, prefix: str, owner: str, version: str, all_name: str | None, force: bool) -> dict:
+    report = validate(root, False, None)
+    if not report["passed"]:
+        raise ValueError("fix validation errors before packaging: " + "; ".join(report["errors"][:5]))
+    if not NAME_RE.match(prefix):
+        raise ValueError("--prefix must be lower-case kebab-case")
+    if out.exists():
+        if not force:
+            raise ValueError(f"{out} exists; pass --force to replace it")
+        shutil.rmtree(out)
+    root = root.resolve()
+    groups: dict[str, list[dict]] = {}
+    for record in report["records"]:
+        category = record["category"] or (Path(record["path"]).parts[0] if len(Path(record["path"]).parts) > 2 else "core")
+        groups.setdefault(re.sub(r"[^a-z0-9-]+", "-", str(category).lower()).strip("-") or "core", []).append(record)
+    plugins = []
+
+    def write_plugin(plugin_name: str, records: list[dict], description: str) -> None:
+        folder = out / "plugins" / plugin_name
+        (folder / ".claude-plugin").mkdir(parents=True)
+        for record in records:
+            shutil.copytree((root / record["path"]).parent, folder / "skills" / record["name"])
+        (folder / ".claude-plugin" / "plugin.json").write_text(json.dumps({"name": plugin_name, "description": description, "version": version, "author": {"name": owner}}, indent=2) + "\n", encoding="utf-8")
+        plugins.append({"name": plugin_name, "source": f"./plugins/{plugin_name}", "description": description, "version": version, "skills": len(records)})
+
+    for category, records in sorted(groups.items()):
+        write_plugin(f"{prefix}-{category}", records, f"{len(records)} {category} skills from {owner}")
+    if all_name is not False:
+        write_plugin(all_name or f"{prefix}-all", report["records"], f"All {len(report['records'])} skills from {owner} in one plugin")
+    marketplace = {"name": prefix, "owner": {"name": owner}, "description": f"{report['skills']} skills from {owner}, by category or all in one", "plugins": [{key: value for key, value in plugin.items() if key != "skills"} for plugin in plugins]}
+    (out / ".claude-plugin").mkdir(parents=True, exist_ok=True)
+    (out / ".claude-plugin" / "marketplace.json").write_text(json.dumps(marketplace, indent=2) + "\n", encoding="utf-8")
+    return {"schemaVersion": "maggie-skill-catalog-package.v1", "passed": True, "output": str(out), "plugins": plugins, "skills": report["skills"], "published": False}
+
+
+def smoke(out: Path, use_claude: bool) -> dict:
+    errors: list[str] = []
+    checks: list[dict] = []
+    marketplace_path = out / ".claude-plugin" / "marketplace.json"
+    if not marketplace_path.is_file():
+        raise ValueError("no .claude-plugin/marketplace.json in the output folder")
+    marketplace = json.loads(marketplace_path.read_text(encoding="utf-8"))
+    if not marketplace.get("name") or not isinstance(marketplace.get("owner"), dict):
+        errors.append("marketplace.json needs name and owner")
+    names = [plugin.get("name") for plugin in marketplace.get("plugins", [])]
+    if len(names) != len(set(names)):
+        errors.append("marketplace.json lists a plugin twice")
+    for entry in marketplace.get("plugins", []):
+        folder = (out / str(entry.get("source", ""))).resolve()
+        manifest = folder / ".claude-plugin" / "plugin.json"
+        if not manifest.is_file():
+            errors.append(f"{entry.get('name')}: source {entry.get('source')} has no .claude-plugin/plugin.json"); continue
+        plugin = json.loads(manifest.read_text(encoding="utf-8"))
+        if plugin.get("name") != entry.get("name"):
+            errors.append(f"{entry.get('name')}: plugin.json name is {plugin.get('name')!r}")
+        if entry.get("version") and plugin.get("version") != entry.get("version"):
+            errors.append(f"{entry.get('name')}: plugin.json version {plugin.get('version')} differs from marketplace {entry.get('version')}")
+        packaged = validate(folder / "skills", False, None) if (folder / "skills").is_dir() else {"passed": False, "errors": ["no skills folder"], "skills": 0}
+        if not packaged["passed"]:
+            errors.extend(f"{entry.get('name')}: {error}" for error in packaged["errors"][:5])
+        checks.append({"plugin": entry.get("name"), "skills": packaged["skills"]})
+    claude = shutil.which("claude") if use_claude else None
+    claude_result = None
+    if use_claude and not claude:
+        errors.append("--claude was requested but the claude CLI is not on PATH")
+    elif claude:
+        run = subprocess.run([claude, "plugin", "validate", str(out)], capture_output=True, text=True, check=False, timeout=120)
+        claude_result = {"exitCode": run.returncode, "output": (run.stdout + run.stderr)[-600:]}
+        if run.returncode:
+            errors.append("claude plugin validate failed")
+    return {"schemaVersion": "maggie-skill-catalog-smoke.v1", "passed": not errors, "plugins": checks, "claudeValidate": claude_result, "errors": errors}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie skills", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command", required=True)
+    new = sub.add_parser("scaffold"); new.add_argument("--root", type=Path, required=True); new.add_argument("--name", required=True); new.add_argument("--description", required=True); new.add_argument("--category")
+    check = sub.add_parser("validate"); check.add_argument("--root", type=Path, required=True); check.add_argument("--require-pinned", action="store_true", help="references must pin a 40-character commit"); check.add_argument("--catalog", type=Path, help="catalog index JSON with skills[].id or .name")
+    pack = sub.add_parser("package"); pack.add_argument("--root", type=Path, required=True); pack.add_argument("--out", type=Path, required=True); pack.add_argument("--prefix", required=True, help="plugin name prefix and marketplace name"); pack.add_argument("--owner", required=True); pack.add_argument("--version", default="0.1.0"); pack.add_argument("--all-name", help="name of the all-in-one plugin (default <prefix>-all)"); pack.add_argument("--no-all", action="store_true"); pack.add_argument("--force", action="store_true")
+    test = sub.add_parser("smoke"); test.add_argument("--out", type=Path, required=True); test.add_argument("--claude", action="store_true", help="also run `claude plugin validate`")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "scaffold":
+            path = scaffold(args.root, args.name, args.description, args.category)
+            report = {"schemaVersion": "maggie-skill-scaffold.v1", "passed": True, "created": str(path)}
+        elif args.command == "validate":
+            report = validate(args.root, args.require_pinned, args.catalog)
+            report.pop("records", None)
+        elif args.command == "package":
+            report = package(args.root, args.out, args.prefix, args.owner, args.version, False if args.no_all else args.all_name, args.force)
+        else:
+            report = smoke(args.out, args.claude)
+    except (OSError, ValueError, json.JSONDecodeError, subprocess.SubprocessError) as error:
+        print(f"BLOCKED: maggie skills {args.command}: {error}", file=sys.stderr)
+        return 2
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/runtime/assistant_approval.py

@@ -0,0 +1,111 @@
+"""Reference implementation of signed one-time approval tokens for assistant writes.
+
+An assistant (in-app agent, MCP server, ChatGPT/Claude app) may only run a
+write after the person approves the exact call. The token binds:
+
+- ``id``: a random approval ID (also the audit ``actionId`` and the root of
+  each write's idempotency key);
+- ``calls``: the exact tool names and canonical arguments that were shown;
+- ``principal``: a hash of the caller identity (never the raw key);
+- ``scope``: ``account`` or the workspace/site the call acts on;
+- ``expires``: a short TTL (10 minutes by default).
+
+Format: ``base64url(canonical JSON) + "." + base64url(HMAC-SHA256)``.
+
+Single use is enforced by the server, not the client: the in-app agent stores
+the token with the model turn that proposed the write, the client answers
+only yes/no, and the server consumes the stored token on the first approval.
+A client that echoes ``{approved: true}`` without a token must still work —
+returning the token to the client and expecting it back is the bug that made
+every approval look "expired".
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import secrets
+import time
+
+DEFAULT_TTL_SECONDS = 600
+
+
+class ApprovalError(ValueError):
+    """Raised when a token is malformed, tampered, expired, reused or mismatched."""
+
+
+def canonical(value: object) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def _b64(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _unb64(text: str) -> bytes:
+    return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
+
+
+def principal_hash(identity: str) -> str:
+    return hashlib.sha256(("maggie-principal:" + identity).encode("utf-8")).hexdigest()
+
+
+def issue(secret: bytes, identity: str, scope: str, calls: list[dict], ttl: int = DEFAULT_TTL_SECONDS, now: float | None = None) -> tuple[str, dict]:
+    if not calls or not all(isinstance(call, dict) and call.get("name") for call in calls):
+        raise ApprovalError("an approval needs at least one named call")
+    approval = {
+        "id": secrets.token_hex(16),
+        "calls": [{"name": call["name"], "args": call.get("args", {})} for call in calls],
+        "principal": principal_hash(identity),
+        "scope": scope,
+        "expires": int((now if now is not None else time.time()) + ttl),
+    }
+    body = canonical(approval).encode("utf-8")
+    signature = hmac.new(secret, body, hashlib.sha256).digest()
+    return _b64(body) + "." + _b64(signature), approval
+
+
+def verify(secret: bytes, token: str, identity: str, scope: str, calls: list[dict], now: float | None = None) -> dict:
+    """Check signature, expiry, principal, scope and the exact calls; does not consume."""
+    try:
+        body_text, signature_text = token.split(".", 1)
+        body, signature = _unb64(body_text), _unb64(signature_text)
+    except (ValueError, TypeError) as error:
+        raise ApprovalError("approval token is malformed") from error
+    if not hmac.compare_digest(hmac.new(secret, body, hashlib.sha256).digest(), signature):
+        raise ApprovalError("approval token signature does not match")
+    approval = json.loads(body)
+    if approval.get("expires", 0) < (now if now is not None else time.time()):
+        raise ApprovalError("approval expired; ask again")
+    if not hmac.compare_digest(approval.get("principal", ""), principal_hash(identity)):
+        raise ApprovalError("approval belongs to another caller")
+    if approval.get("scope") != scope:
+        raise ApprovalError("approval was issued for another scope")
+    expected = [{"name": call["name"], "args": call.get("args", {})} for call in calls]
+    if canonical(approval.get("calls")) != canonical(expected):
+        raise ApprovalError("approved calls differ from the calls being run")
+    return approval
+
+
+def idempotency_key(approval_id: str, call: dict) -> str:
+    return hashlib.sha256(f"{approval_id}:{canonical(call)}".encode("utf-8")).hexdigest()[:48]
+
+
+class TurnStore:
+    """In-memory model of the server-side store: the token lives with the model turn."""
+
+    def __init__(self) -> None:
+        self.turns: dict[str, str] = {}
+
+    def propose(self, turn_id: str, token: str) -> None:
+        self.turns[turn_id] = token
+
+    def consume(self, turn_id: str, client_token: str | None = None) -> str:
+        """Return the token to verify (client-supplied or stored) and delete it: single use."""
+        stored = self.turns.pop(turn_id, None)
+        token = client_token or stored
+        if not token:
+            raise ApprovalError("no pending approval for this turn (already used or never proposed)")
+        return token

package/bundled-tools/runtime/cdp_client.py

@@ -0,0 +1,246 @@
+"""Minimal Chrome DevTools Protocol client using only the standard library.
+
+Maggie collectors need a real browser session (signed-in app routes, real
+viewport screenshots) without adding Playwright or a websocket dependency.
+This module implements just enough of RFC 6455 (client text frames, masked;
+server frames with fragmentation, ping/pong and close) and the flattened CDP
+session protocol to drive one tab.
+
+Two ways to obtain a browser:
+
+- ``attach(cdp_url)``: connect to an already running Chrome started with
+  ``--remote-debugging-port`` (the host's signed-in session);
+- ``launch(chrome, profile_dir)``: start headless Chrome with a dedicated
+  profile directory, so a rotated refresh token is persisted between renders.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import socket
+import struct
+import subprocess
+import time
+from pathlib import Path
+from typing import Callable
+from urllib.parse import urlsplit
+from urllib.request import urlopen
+
+
+class CdpError(RuntimeError):
+    """Raised for protocol, transport, or browser start failures."""
+
+
+class WebSocket:
+    """A blocking RFC 6455 client connection carrying text frames."""
+
+    def __init__(self, url: str, timeout: float = 30.0) -> None:
+        parts = urlsplit(url)
+        if parts.scheme != "ws":
+            raise CdpError("only ws:// DevTools endpoints on this machine are supported")
+        host, port = parts.hostname or "127.0.0.1", parts.port or 80
+        self.sock = socket.create_connection((host, port), timeout=timeout)
+        key = base64.b64encode(os.urandom(16)).decode()
+        path = parts.path + (f"?{parts.query}" if parts.query else "")
+        request = (
+            f"GET {path} HTTP/1.1\r\nHost: {host}:{port}\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n"
+            f"Sec-WebSocket-Key: {key}\r\nSec-WebSocket-Version: 13\r\n\r\n"
+        )
+        self.sock.sendall(request.encode())
+        response = b""
+        while b"\r\n\r\n" not in response:
+            chunk = self.sock.recv(4096)
+            if not chunk:
+                raise CdpError("DevTools endpoint closed the connection during the handshake")
+            response += chunk
+        head, _, self.buffer = response.partition(b"\r\n\r\n")
+        if b" 101 " not in head.split(b"\r\n", 1)[0]:
+            raise CdpError("DevTools endpoint refused the websocket upgrade")
+
+    def _read(self, count: int) -> bytes:
+        while len(self.buffer) < count:
+            chunk = self.sock.recv(max(65536, count - len(self.buffer)))
+            if not chunk:
+                raise CdpError("DevTools connection closed")
+            self.buffer += chunk
+        data, self.buffer = self.buffer[:count], self.buffer[count:]
+        return data
+
+    def send_frame(self, payload: bytes, opcode: int = 1) -> None:
+        header = bytes([0x80 | opcode])
+        length = len(payload)
+        if length < 126:
+            header += bytes([0x80 | length])
+        elif length < 1 << 16:
+            header += bytes([0x80 | 126]) + struct.pack(">H", length)
+        else:
+            header += bytes([0x80 | 127]) + struct.pack(">Q", length)
+        mask = os.urandom(4)
+        self.sock.sendall(header + mask + bytes(byte ^ mask[index % 4] for index, byte in enumerate(payload)))
+
+    def send(self, text: str) -> None:
+        self.send_frame(text.encode("utf-8"))
+
+    def recv(self) -> str:
+        message = b""
+        while True:
+            first, second = self._read(2)
+            opcode, final = first & 0x0F, bool(first & 0x80)
+            length = second & 0x7F
+            if length == 126:
+                length = struct.unpack(">H", self._read(2))[0]
+            elif length == 127:
+                length = struct.unpack(">Q", self._read(8))[0]
+            mask = self._read(4) if second & 0x80 else b""
+            payload = self._read(length)
+            if mask:
+                payload = bytes(byte ^ mask[index % 4] for index, byte in enumerate(payload))
+            if opcode == 0x9:
+                self.send_frame(payload, 0xA)
+                continue
+            if opcode == 0xA:
+                continue
+            if opcode == 0x8:
+                raise CdpError("DevTools connection closed by the browser")
+            message += payload
+            if final:
+                return message.decode("utf-8")
+
+    def close(self) -> None:
+        try:
+            self.send_frame(b"", 0x8)
+        except OSError:
+            pass
+        self.sock.close()
+
+
+class Browser:
+    """A browser-level CDP connection that drives one flattened page session."""
+
+    def __init__(self, ws_url: str, process: subprocess.Popen | None = None, timeout: float = 60.0) -> None:
+        self.ws = WebSocket(ws_url)
+        self.process = process
+        self.timeout = timeout
+        self.next_id = 0
+        self.session: str | None = None
+        self.target: str | None = None
+        self.events: list[dict] = []
+        self.responses: dict[int, dict] = {}
+        self.handlers: dict[str, Callable[[dict], None]] = {}
+
+    def _dispatch(self, message: dict) -> None:
+        handler = self.handlers.get(message.get("method", ""))
+        if handler:
+            handler(message.get("params", {}))
+        else:
+            self.events.append(message)
+
+    def call(self, method: str, params: dict | None = None, session: bool = True) -> dict:
+        self.next_id += 1
+        payload = {"id": self.next_id, "method": method, "params": params or {}}
+        if session and self.session:
+            payload["sessionId"] = self.session
+        self.ws.send(json.dumps(payload))
+        call_id = self.next_id
+        deadline = time.monotonic() + self.timeout
+        while time.monotonic() < deadline:
+            # A handler may issue its own call while we wait, so responses can arrive out of order.
+            message = self.responses.pop(call_id, None) or json.loads(self.ws.recv())
+            if message.get("id") == call_id:
+                if "error" in message:
+                    raise CdpError(f"{method} failed: {message['error'].get('message', 'unknown error')}")
+                return message.get("result", {})
+            if "id" in message:
+                self.responses[message["id"]] = message
+                continue
+            self._dispatch(message)
+        raise CdpError(f"{method} timed out")
+
+    def wait_for(self, method: str, timeout: float) -> dict | None:
+        for index, event in enumerate(self.events):
+            if event.get("method") == method:
+                return self.events.pop(index)
+        deadline = time.monotonic() + timeout
+        self.ws.sock.settimeout(max(0.1, timeout))
+        try:
+            while time.monotonic() < deadline:
+                try:
+                    message = json.loads(self.ws.recv())
+                except (socket.timeout, TimeoutError):
+                    return None
+                if message.get("method") == method:
+                    return message
+                if "id" in message:
+                    self.responses[message["id"]] = message
+                    continue
+                self._dispatch(message)
+        finally:
+            self.ws.sock.settimeout(self.timeout)
+        return None
+
+    def pump(self, seconds: float) -> None:
+        """Process events (and handlers) for a fixed time, e.g. while the page settles."""
+        deadline = time.monotonic() + seconds
+        while time.monotonic() < deadline:
+            self.wait_for("__never__", max(0.05, deadline - time.monotonic()))
+
+    def open_tab(self, url: str = "about:blank") -> None:
+        self.target = self.call("Target.createTarget", {"url": url}, session=False)["targetId"]
+        self.session = self.call("Target.attachToTarget", {"targetId": self.target, "flatten": True}, session=False)["sessionId"]
+
+    def evaluate(self, expression: str) -> object:
+        result = self.call("Runtime.evaluate", {"expression": expression, "returnByValue": True, "awaitPromise": True})
+        if "exceptionDetails" in result:
+            raise CdpError("page script failed: " + str(result["exceptionDetails"].get("text", "exception"))[:200])
+        return result.get("result", {}).get("value")
+
+    def close(self) -> None:
+        try:
+            if self.target:
+                self.call("Target.closeTarget", {"targetId": self.target}, session=False)
+        except (CdpError, OSError):
+            pass
+        self.ws.close()
+        if self.process:
+            self.process.terminate()
+            try:
+                self.process.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                self.process.kill()
+
+
+def attach(cdp_url: str) -> Browser:
+    """Attach to a running Chrome exposing ``--remote-debugging-port`` on this machine."""
+    parts = urlsplit(cdp_url)
+    if parts.hostname not in {"127.0.0.1", "localhost", "::1"}:
+        raise CdpError("--cdp-url must point at a DevTools port on this machine (127.0.0.1 or localhost)")
+    with urlopen(cdp_url.rstrip("/") + "/json/version", timeout=10) as response:
+        version = json.loads(response.read().decode("utf-8"))
+    url = version.get("webSocketDebuggerUrl")
+    if not url:
+        raise CdpError("DevTools endpoint did not report a browser websocket URL")
+    return Browser(url)
+
+
+def launch(chrome: str, profile_dir: Path, headless: bool = True) -> Browser:
+    """Start Chrome with a dedicated profile and connect to its browser target."""
+    profile_dir.mkdir(parents=True, exist_ok=True)
+    port_file = profile_dir / "DevToolsActivePort"
+    port_file.unlink(missing_ok=True)
+    args = [chrome, "--remote-debugging-port=0", f"--user-data-dir={profile_dir}", "--no-first-run", "--no-default-browser-check", "--disable-gpu", "--hide-scrollbars"]
+    if headless:
+        args += ["--headless=new", "--no-sandbox"]
+    process = subprocess.Popen(args + ["about:blank"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    deadline = time.monotonic() + 30
+    while time.monotonic() < deadline:
+        if port_file.is_file():
+            lines = port_file.read_text(encoding="utf-8").splitlines()
+            if len(lines) >= 2:
+                return Browser(f"ws://127.0.0.1:{lines[0].strip()}{lines[1].strip()}", process)
+        if process.poll() is not None:
+            break
+        time.sleep(0.1)
+    process.kill()
+    raise CdpError("Chrome did not expose a DevTools port; is another Chrome using this profile directory?")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.7.49",
+  "version": "0.7.51",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",