@capagents/forgeqe 2.2.2 → 2.2.3

package/forgeqe.example.yaml

@@ -86,9 +86,11 @@ browser:
   max_steps: 40 # a checkpoint: a run still making progress carries on, up to 3x
   timeout_seconds: 600 # whole run
   vision_detail: low # low | high
-  viewport:
+  viewport: # headless page size; a visible window too with window: viewport
     width: 1280
     height: 800
+  window: maximized # visible browser: maximized | viewport
+  video: true # video.mp4 of each run, shown in its report
   allowed_hosts: []
   judge: false # true: a second model call checks each finished run against the goal and can fail it
   overlay: true # visible browser: ForgeQE start page, edge glow, a bar with the current step, your mouse and keyboard locked while the agent works

package/llms.example.json

@@ -50,10 +50,8 @@
     },
     "copilot": {
       "provider": "github_copilot",
-      "model": "claude-sonnet-4.6",
-      "engine_model": "openai/gpt-4.1",
-      "github_org": "",
-      "description": "GitHub Copilot seat for ForgeQE's agent and Scribe (forgeqe auth login copilot); the browser engine uses GitHub Models with your GitHub sign-in"
+      "model": "gpt-4.1",
+      "description": "GitHub Copilot seat for the browser engine, through GitHub's Copilot SDK (forgeqe auth login copilot: a fine-grained token with Copilot Requests, or the GitHub CLI's sign-in)"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capagents/forgeqe",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "description": "ForgeQE: a browser agent CLI that runs goals and test cases in local Chrome or Chromium, or BrowserStack and TestMu AI/LambdaTest when configured, and turns passing runs into tests in your repo",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -40,11 +40,13 @@
     "forgeqe": "bun src/index.ts",
     "start": "bun src/index.ts start",
     "test": "bun test",
+    "test:release": "bun scripts/release-tests.ts",
     "typecheck": "tsc --noEmit",
     "build:report": "cd report-ui && npm install --no-audit --no-fund && npm run build && cp dist/index.html ../src/report/template.html",
     "build": "bun scripts/build.ts",
     "notices": "bun scripts/gen-notices.ts",
-    "prepack": "bun scripts/build.ts && bun scripts/gen-notices.ts"
+    "prepack": "bun scripts/build.ts && bun scripts/gen-notices.ts",
+    "prepublishOnly": "bun run typecheck && bun scripts/release-tests.ts"
   },
   "keywords": [
     "forgeqe",

package/py/forgeqe_engine/browser.py

@@ -192,7 +192,20 @@ def _testmu_caps(remote: Dict[str, Any]) -> Dict[str, Any]:
     }
 
 
+# browser.provider docker: ForgeQE starts the browser container and passes its gateway's endpoint (with its token) here.
+DOCKER_CDP_ENV = "FORGEQE_BROWSER_CDP_URL"
+
+
+def docker_browser_launch_kwargs() -> Dict[str, Any]:
+    url = (os.getenv(DOCKER_CDP_ENV) or "").strip()
+    if not url.startswith("ws://127.0.0.1:"):
+        raise RuntimeError(f"docker: {DOCKER_CDP_ENV} is not set to the browser container's local endpoint; ForgeQE starts that container itself.")
+    return {"cdp_url": url}
+
+
 def remote_browser_launch_kwargs(provider: str, remote: Dict[str, Any]) -> Dict[str, Any]:
+    if provider == "docker":
+        return docker_browser_launch_kwargs()
     endpoint = str(remote.get("endpoint") or "").strip().rstrip("/")
     if not endpoint:
         raise RuntimeError(f"{provider}: a remote endpoint is required.")
@@ -212,6 +225,8 @@ def browser_launch_kwargs(*, provider: str, headless: bool, remote: Optional[Dic
 def browser_connection_label(provider: str, launch: Dict[str, Any], remote: Optional[Dict[str, Any]] = None) -> str:
     if provider == "local":
         return str(launch.get("channel") or "chrome")
+    if provider == "docker":
+        return "Chromium in a container"
     browser = str((remote or {}).get("browser") or "")
     target = str((remote or {}).get("platform") or "").strip() or " ".join(
         x for x in [str((remote or {}).get("os") or "").strip(), str((remote or {}).get("os_version") or (remote or {}).get("osVersion") or "").strip()] if x
@@ -296,6 +311,93 @@ async def reopen_in_fresh_tab(browser: Any, url: str) -> None:
             await close.event_result(raise_if_any=False, raise_if_none=False)
 
 
+VIDEO_FILE = "video.mp4"
+
+
+def _size(value: Any) -> Optional[Dict[str, int]]:
+    """browser.viewport as [width, height], or None when it is not two sizes a screen can have."""
+    if not isinstance(value, (list, tuple)) or len(value) != 2:
+        return None
+    try:
+        w, h = int(value[0]), int(value[1])
+    except (TypeError, ValueError):
+        return None
+    return {"width": w, "height": h} if 200 <= w <= 10000 and 200 <= h <= 10000 else None
+
+
+def window_launch_kwargs(browser_cfg: Dict[str, Any], *, headless: bool) -> Dict[str, Any]:
+    """
+    The size of a local browser. Headless: the page is browser.viewport. Visible: the window is that size with
+    browser.window: viewport, else the library's screen-sized window, which `maximize_window` then maximises.
+    """
+    if str(browser_cfg.get("provider") or "local") != "local":
+        return {}
+    size = _size(browser_cfg.get("viewport"))
+    if not size:
+        return {}
+    if headless:
+        return {"viewport": size}
+    return {"window_size": size} if browser_cfg.get("window") == "viewport" else {}
+
+
+def wants_maximized(browser_cfg: Dict[str, Any], *, headless: bool) -> bool:
+    return not headless and str(browser_cfg.get("provider") or "local") == "local" and browser_cfg.get("window") != "viewport"
+
+
+async def maximize_window(browser: Any) -> bool:
+    """Maximise the visible browser's window (the library only sizes it to the screen, under the menu bar and Dock)."""
+    try:
+        session = await browser.get_or_create_cdp_session()
+        send = browser.cdp_client.send.Browser
+        found = await send.getWindowForTarget(params={"targetId": session.target_id})
+        window_id = found["windowId"]
+        await send.setWindowBounds(params={"windowId": window_id, "bounds": {"windowState": "maximized"}})
+        # The page takes the new size a moment later; the video is sized from it.
+        for _ in range(10):
+            bounds = (await send.getWindowBounds(params={"windowId": window_id})).get("bounds") or {}
+            if bounds.get("windowState") == "maximized":
+                break
+            await asyncio.sleep(0.1)
+        await asyncio.sleep(0.3)
+        return True
+    except Exception as ex:
+        logger.debug("maximise window failed: %s", ex)
+        return False
+
+
+def video_available() -> bool:
+    try:
+        from browser_use.browser.video_recorder import IMAGEIO_AVAILABLE
+    except Exception:
+        return False
+    return bool(IMAGEIO_AVAILABLE)
+
+
+async def start_video(browser: Any, out_dir: Path) -> Optional[Path]:
+    """Record the agent's tab to <out_dir>/video.mp4 until `stop_video`; None when it could not start."""
+    watchdog = getattr(browser, "_recording_watchdog", None)
+    if watchdog is None or not video_available():
+        return None
+    try:
+        return Path(await watchdog.start_recording(out_dir / VIDEO_FILE))
+    except Exception as ex:
+        logger.debug("video recording did not start: %s", ex)
+        return None
+
+
+async def stop_video(browser: Any) -> Optional[Path]:
+    """Finish the video file; None when nothing was recorded."""
+    watchdog = getattr(browser, "_recording_watchdog", None)
+    if watchdog is None or not getattr(watchdog, "is_recording", False):
+        return None
+    try:
+        path = await asyncio.wait_for(watchdog.stop_recording(), timeout=120.0)
+    except Exception as ex:
+        logger.debug("video recording did not finish: %s", ex)
+        return None
+    return Path(path) if path and Path(path).is_file() and Path(path).stat().st_size else None
+
+
 async def _shutdown_browser_instance(browser: Any) -> None:
     """Stop the library gracefully, falling back to kill()."""
     if browser is None:
@@ -348,7 +450,10 @@ async def browser_profile(browser: Any, launch: Dict[str, Any], *, provider: str
         "extra_http_headers": {},
         "provider": provider,
     }
-    if provider != "local":
+    if provider == "docker":
+        # Not a browser on another machine: the coding agent's replay and live browser use the same kind of container.
+        profile["container"] = True
+    elif provider != "local":
         host = urlparse(str(launch.get("cdp_url") or "")).netloc
         profile["remote_browser"] = f"{'BrowserStack' if provider == 'browserstack' else 'TestMu AI'} via {host}"
         if remote:

package/py/forgeqe_engine/cli.py

@@ -13,6 +13,7 @@ Engine process protocol, used by the Bun CLI:
   python -m forgeqe_engine doctor
   python -m forgeqe_engine token   (stdin: an llms.json profile with auth: entra; prints {token, expires_on})
   python -m forgeqe_engine probe   (stdin: an llms.json profile; prints {ok, ms, structured, vision, error?})
+  python -m forgeqe_engine copilot-gateway   (GitHub Copilot as an OpenAI-style endpoint on 127.0.0.1; see copilot_gateway.py)
 """
 from __future__ import annotations
 
@@ -73,6 +74,14 @@ def _doctor(out: TextIO) -> int:
         info["azure_identity"] = version("azure-identity")
     except Exception:
         pass
+    try:
+        info["copilot_sdk"] = version("github-copilot-sdk")
+    except Exception:
+        pass
+    try:
+        info["video"] = version("imageio")
+    except Exception:
+        pass
     try:
         from .service import local_browser_launch_kwargs
 
@@ -252,5 +261,9 @@ def main(argv: list[str] | None = None) -> int:
         return _token(out)
     if cmd == "probe":
         return _probe(out)
+    if cmd == "copilot-gateway":
+        from .copilot_gateway import main as copilot_gateway
+
+        return copilot_gateway(out)
     out.write(json.dumps({"type": "done", "result": {"success": False, "error": f"Unknown command {cmd}"}}) + "\n")
     return 2

package/py/forgeqe_engine/copilot_gateway.py

@@ -0,0 +1,369 @@
+"""
+GitHub Copilot as an OpenAI-style chat endpoint on this machine, through GitHub's Copilot SDK.
+
+Copilot has no model API for other tools: the SDK runs Copilot "sessions" on the user's seat. The browser engine and
+the desktop agent speak OpenAI chat completions, so this gateway turns each request into one SDK session with no
+tools of its own (the system prompt replaced, screenshots attached, a JSON schema passed on) and answers in the
+OpenAI shape.
+
+  python -m forgeqe_engine copilot-gateway
+    env    COPILOT_GITHUB_TOKEN          the GitHub token (fine-grained with Copilot Requests, or the GitHub CLI's)
+           FORGEQE_COPILOT_GATEWAY_KEY   the one-time key every request must carry as "Bearer <key>"
+    stdout one line: {"port": N, "login": "<account>"} once it listens, or {"error": "..."}
+    stdin  end of input stops it, so it never outlives ForgeQE
+
+It listens on 127.0.0.1 only, compares the key in constant time and refuses requests a web page sends.
+"""
+from __future__ import annotations
+
+import asyncio
+import hmac
+import json
+import os
+import sys
+import tempfile
+import time
+import uuid
+from typing import Any, Dict, List, Optional, TextIO, Tuple
+
+TOKEN_ENV = "COPILOT_GITHUB_TOKEN"
+KEY_ENV = "FORGEQE_COPILOT_GATEWAY_KEY"
+
+MAX_BODY = 32 * 1024 * 1024
+# A screenshot step can take minutes on a slow model; past this the request fails rather than hangs.
+REQUEST_TIMEOUT_S = 300.0
+LOCAL_ORIGINS = ("http://127.0.0.1", "http://localhost", "https://127.0.0.1", "https://localhost")
+
+
+class GatewayError(Exception):
+    def __init__(self, status: int, message: str):
+        super().__init__(message)
+        self.status = status
+        self.message = message
+
+
+# ---------------------------------------------------------------------------------------------------------------------
+# OpenAI chat completions → one Copilot session
+
+
+def _parts(content: Any) -> List[Dict[str, Any]]:
+    if isinstance(content, str):
+        return [{"type": "text", "text": content}]
+    if isinstance(content, list):
+        return [p for p in content if isinstance(p, dict)]
+    return []
+
+
+def _data_url(url: str) -> Optional[Tuple[str, str]]:
+    """data:image/png;base64,AAAA → ("image/png", "AAAA"); None for anything else (remote images are not fetched)."""
+    if not url.startswith("data:") or ";base64," not in url:
+        return None
+    head, data = url[5:].split(";base64,", 1)
+    mime = head.split(";", 1)[0].strip().lower()
+    if not mime.startswith("image/") or not data:
+        return None
+    return mime, data
+
+
+def translate(body: Dict[str, Any]) -> Dict[str, Any]:
+    """The session a chat completions request becomes: {model, system, prompt, attachments, schema, json_only}."""
+    if not isinstance(body, dict):
+        raise GatewayError(400, "The request body must be a JSON object.")
+    model = str(body.get("model") or "").strip()
+    if not model:
+        raise GatewayError(400, "The request names no model.")
+    if body.get("stream"):
+        raise GatewayError(400, "Streaming is not supported by ForgeQE's Copilot gateway.")
+    if body.get("tools") or body.get("functions"):
+        raise GatewayError(400, "Tool calls are not supported by ForgeQE's Copilot gateway yet.")
+    messages = body.get("messages")
+    if not isinstance(messages, list) or not messages:
+        raise GatewayError(400, "The request has no messages.")
+
+    system: List[str] = []
+    turns: List[Tuple[str, List[Dict[str, Any]]]] = []
+    for m in messages:
+        if not isinstance(m, dict):
+            continue
+        role = str(m.get("role") or "user")
+        parts = _parts(m.get("content"))
+        if role in ("system", "developer"):
+            system.extend(str(p.get("text") or "") for p in parts if p.get("type") == "text")
+        else:
+            turns.append((role, parts))
+    if not turns:
+        raise GatewayError(400, "The request has no user message.")
+
+    # Only the latest message's images go to the model; the browser agent sends the current screenshot there.
+    last_with_images = max((i for i, (_, parts) in enumerate(turns) if any(p.get("type") == "image_url" for p in parts)), default=-1)
+    attachments: List[Dict[str, Any]] = []
+    lines: List[str] = []
+    for i, (role, parts) in enumerate(turns):
+        texts: List[str] = []
+        for p in parts:
+            if p.get("type") == "text":
+                texts.append(str(p.get("text") or ""))
+            elif p.get("type") == "image_url":
+                url = p.get("image_url", {}).get("url") if isinstance(p.get("image_url"), dict) else p.get("image_url")
+                img = _data_url(str(url or ""))
+                if img and i == last_with_images:
+                    attachments.append({"type": "blob", "mimeType": img[0], "data": img[1], "displayName": f"screenshot-{len(attachments) + 1}"})
+                    texts.append(f"[image attached: screenshot-{len(attachments)}]")
+                else:
+                    texts.append("[earlier image omitted]")
+        text = "\n".join(t for t in texts if t)
+        lines.append(text if len(turns) == 1 else f"<{role}>\n{text}\n</{role}>")
+    prompt = "\n\n".join(lines)
+    if len(turns) > 1:
+        prompt = "The conversation so far, oldest first. Reply as the assistant to the last message.\n\n" + prompt
+
+    schema = None
+    json_only = False
+    fmt = body.get("response_format")
+    if isinstance(fmt, dict):
+        if fmt.get("type") == "json_schema" and isinstance(fmt.get("json_schema"), dict):
+            schema = fmt["json_schema"].get("schema")
+            if not isinstance(schema, dict):
+                raise GatewayError(400, "response_format.json_schema has no schema.")
+        elif fmt.get("type") == "json_object":
+            json_only = True
+            prompt += "\n\nReply with a single JSON object and nothing else."
+    return {"model": model, "system": "\n\n".join(s for s in system if s), "prompt": prompt, "attachments": attachments, "schema": schema, "json_only": json_only}
+
+
+def completion(model: str, content: str, usage: Dict[str, int]) -> Dict[str, Any]:
+    """An OpenAI chat.completion object."""
+    prompt_tokens = int(usage.get("input", 0))
+    completion_tokens = int(usage.get("output", 0))
+    out: Dict[str, Any] = {
+        "id": f"chatcmpl-{uuid.uuid4().hex}",
+        "object": "chat.completion",
+        "created": int(time.time()),
+        "model": model,
+        "choices": [{"index": 0, "message": {"role": "assistant", "content": content}, "finish_reason": "stop"}],
+        "usage": {"prompt_tokens": prompt_tokens, "completion_tokens": completion_tokens, "total_tokens": prompt_tokens + completion_tokens},
+    }
+    if usage.get("cached"):
+        out["usage"]["prompt_tokens_details"] = {"cached_tokens": int(usage["cached"])}
+    return out
+
+
+def strip_fences(text: str) -> str:
+    """```json … ``` → the JSON inside, for models that wrap structured replies in a code fence."""
+    t = text.strip()
+    if t.startswith("```") and t.endswith("```"):
+        t = t[3:-3]
+        first, _, rest = t.partition("\n")
+        return (rest if first.strip().isalpha() or not first.strip() else t).strip()
+    return text
+
+
+# ---------------------------------------------------------------------------------------------------------------------
+# Requests from this machine only
+
+
+def authorized(headers: Dict[str, str], key: str) -> bool:
+    expected = f"Bearer {key}".encode()
+    got = headers.get("authorization", "").encode()
+    return bool(key) and hmac.compare_digest(got, expected)
+
+
+def local_origin(headers: Dict[str, str]) -> bool:
+    """True when no browser page sent the request: no Origin, or one on this machine."""
+    origin = headers.get("origin")
+    if origin is None:
+        return True
+    o = origin.strip().lower()
+    return any(o == base or o.startswith(base + ":") for base in LOCAL_ORIGINS)
+
+
+# ---------------------------------------------------------------------------------------------------------------------
+# The Copilot SDK
+
+
+class Copilot:
+    def __init__(self, token: str):
+        from copilot import CopilotClient
+
+        # The SDK keeps its state under this folder, apart from the user's own Copilot CLI.
+        home = os.path.join(os.environ.get("FORGEQE_HOME") or os.path.join(os.path.expanduser("~"), ".forgeqe"), "copilot")
+        os.makedirs(home, exist_ok=True)
+        # An empty working folder: the session reads no project files and no custom instructions.
+        self.workdir = tempfile.mkdtemp(prefix="forgeqe-copilot-")
+        self.client = CopilotClient(github_token=token, use_logged_in_user=False, base_directory=home, working_directory=self.workdir, log_level="error")
+
+    async def start(self) -> None:
+        await self.client.start()
+        status = await self.client.get_auth_status()
+        self.login = status.login or ""
+        if not status.isAuthenticated:
+            raise GatewayError(401, "GitHub Copilot did not accept the token: use a fine-grained token with the Copilot Requests permission, or the GitHub CLI's sign-in, for an account with a Copilot seat.")
+
+    async def stop(self) -> None:
+        try:
+            await self.client.stop()
+        except Exception:
+            pass
+
+    async def models(self) -> List[Dict[str, Any]]:
+        out = []
+        for m in await self.client.list_models():
+            supports = getattr(getattr(m, "capabilities", None), "supports", None)
+            out.append({"id": m.id, "object": "model", "owned_by": "github-copilot", "vision": bool(getattr(supports, "vision", False))})
+        return out
+
+    async def complete(self, req: Dict[str, Any]) -> Dict[str, Any]:
+        from copilot.generated.rpc import PermissionDecisionReject
+        from copilot.session_events import AssistantMessageData, AssistantUsageData, SessionErrorData
+
+        usage = {"input": 0, "output": 0, "cached": 0}
+        errors: List[str] = []
+
+        def on_event(event: Any) -> None:
+            data = getattr(event, "data", None)
+            if isinstance(data, AssistantUsageData):
+                usage["input"] += data.input_tokens or 0
+                usage["output"] += data.output_tokens or 0
+                usage["cached"] += data.cache_read_tokens or 0
+            elif isinstance(data, SessionErrorData):
+                errors.append(data.message or data.error_type or "error")
+
+        session = await self.client.create_session(
+            model=req["model"],
+            # The caller's prompt is the whole prompt; without one the session still gets no tools.
+            system_message={"mode": "replace", "content": req["system"] or "You are a helpful assistant."},
+            available_tools=[],
+            on_permission_request=lambda *_: PermissionDecisionReject(),
+            working_directory=self.workdir,
+            skip_custom_instructions=True,
+            enable_config_discovery=False,
+            enable_skills=False,
+            enable_session_store=False,
+            on_event=on_event,
+        )
+        try:
+            reply = await session.send_and_wait(req["prompt"], attachments=req["attachments"] or None, response_schema=req["schema"], timeout=REQUEST_TIMEOUT_S)
+        except TimeoutError:
+            raise GatewayError(504, f"GitHub Copilot did not answer within {int(REQUEST_TIMEOUT_S)} seconds.")
+        finally:
+            try:
+                await session.disconnect()
+            except Exception:
+                pass
+        if errors:
+            msg = errors[-1]
+            raise GatewayError(401 if "auth" in msg.lower() or "401" in msg else 502, f"GitHub Copilot: {msg}")
+        data = getattr(reply, "data", None)
+        if not isinstance(data, AssistantMessageData):
+            raise GatewayError(502, "GitHub Copilot sent no reply.")
+        content = data.content or ""
+        if req["schema"] is not None or req["json_only"]:
+            content = strip_fences(content)
+        return completion(req["model"], content, usage)
+
+
+# ---------------------------------------------------------------------------------------------------------------------
+# A small HTTP/1.1 server: one request per connection
+
+
+def _response(status: int, payload: Dict[str, Any]) -> bytes:
+    body = json.dumps(payload).encode()
+    reason = {200: "OK", 400: "Bad Request", 401: "Unauthorized", 403: "Forbidden", 404: "Not Found", 413: "Payload Too Large", 502: "Bad Gateway", 504: "Gateway Timeout"}.get(status, "Error")
+    head = f"HTTP/1.1 {status} {reason}\r\nContent-Type: application/json\r\nContent-Length: {len(body)}\r\nConnection: close\r\n\r\n"
+    return head.encode() + body
+
+
+def _error(status: int, message: str) -> bytes:
+    return _response(status, {"error": {"message": message, "type": "forgeqe_copilot_gateway"}})
+
+
+async def handle(reader: asyncio.StreamReader, writer: asyncio.StreamWriter, copilot: Any, key: str) -> None:
+    try:
+        try:
+            head = await reader.readuntil(b"\r\n\r\n")
+        except (asyncio.IncompleteReadError, asyncio.LimitOverrunError):
+            return
+        lines = head.decode("latin-1").split("\r\n")
+        method, path = (lines[0].split(" ") + ["", ""])[:2]
+        headers = {}
+        for line in lines[1:]:
+            if ":" in line:
+                k, v = line.split(":", 1)
+                headers[k.strip().lower()] = v.strip()
+        if not local_origin(headers):
+            writer.write(_error(403, "Requests from web pages are refused."))
+            return
+        if not authorized(headers, key):
+            writer.write(_error(401, "Unauthorized"))
+            return
+        path = path.split("?", 1)[0].rstrip("/")
+        if path.startswith("/v1/"):
+            path = path[3:]
+        if method == "GET" and path == "/models":
+            writer.write(_response(200, {"object": "list", "data": await copilot.models()}))
+            return
+        if method != "POST" or path != "/chat/completions":
+            writer.write(_error(404, f"{method} {path} is not served here."))
+            return
+        try:
+            length = int(headers.get("content-length", "0"))
+        except ValueError:
+            length = -1
+        if length < 0 or length > MAX_BODY:
+            writer.write(_error(413, "The request body is too large."))
+            return
+        raw = await reader.readexactly(length)
+        try:
+            body = json.loads(raw.decode("utf-8"))
+        except ValueError:
+            writer.write(_error(400, "The request body is not JSON."))
+            return
+        writer.write(_response(200, await copilot.complete(translate(body))))
+    except GatewayError as e:
+        writer.write(_error(e.status, e.message))
+    except Exception as e:  # The SDK's own errors: report them rather than drop the connection.
+        writer.write(_error(502, f"GitHub Copilot: {type(e).__name__}: {e}"[:2000]))
+    finally:
+        try:
+            await writer.drain()
+            writer.close()
+        except Exception:
+            pass
+
+
+async def serve(out: TextIO, copilot: Any = None) -> int:
+    key = os.environ.get(KEY_ENV, "")
+    token = os.environ.get(TOKEN_ENV, "").strip()
+    if len(key) < 32:
+        out.write(json.dumps({"error": f"{KEY_ENV} must hold the gateway's one-time key."}) + "\n")
+        return 2
+    if copilot is None:
+        if not token:
+            out.write(json.dumps({"error": "No GitHub token for Copilot: run forgeqe auth login copilot."}) + "\n")
+            return 1
+        if token.startswith("ghp_"):
+            out.write(json.dumps({"error": "GitHub Copilot does not take classic tokens (ghp_): use a fine-grained token with the Copilot Requests permission."}) + "\n")
+            return 1
+        try:
+            copilot = Copilot(token)
+            await copilot.start()
+        except GatewayError as e:
+            out.write(json.dumps({"error": e.message}) + "\n")
+            return 1
+        except Exception as e:
+            out.write(json.dumps({"error": f"GitHub Copilot could not start: {type(e).__name__}: {e}"[:1500]}) + "\n")
+            return 1
+    server = await asyncio.start_server(lambda r, w: handle(r, w, copilot, key), host="127.0.0.1", port=0, limit=64 * 1024)
+    port = server.sockets[0].getsockname()[1]
+    out.write(json.dumps({"port": port, "login": getattr(copilot, "login", "")}) + "\n")
+    out.flush()
+    loop = asyncio.get_running_loop()
+    # Stop when ForgeQE closes stdin (or exits).
+    await loop.run_in_executor(None, sys.stdin.read)
+    server.close()
+    await copilot.stop()
+    return 0
+
+
+def main(out: TextIO) -> int:
+    return asyncio.run(serve(out))

package/py/forgeqe_engine/service.py

@@ -46,11 +46,18 @@ from .llm import (
     _agent_usage,
 )
 from .browser import (
+    VIDEO_FILE,
     FreshTabAfterPassword,
     browser_connection_label,
     browser_launch_kwargs,
     local_browser_launch_kwargs,
+    maximize_window,
     settle_page,
+    start_video,
+    stop_video,
+    video_available,
+    wants_maximized,
+    window_launch_kwargs,
     _shutdown_browser_instance,
     _stop_agent_instance,
     browser_profile,
@@ -1004,6 +1011,7 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
     browser_provider = str(browser_cfg.get("provider") or "local")
     browser_remote = browser_cfg.get("remote") if isinstance(browser_cfg.get("remote"), dict) else {}
     browser_kw = browser_launch_kwargs(provider=browser_provider, remote=browser_remote, headless=headless)
+    browser_kw.update(window_launch_kwargs(browser_cfg, headless=headless))
     if allowed_domains is not None:
         browser_kw["allowed_domains"] = allowed_domains
     logins = parse_logins(req.logins)
@@ -1142,6 +1150,21 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
                 shared = mem.store.shared_start(goal, normalized_initial)
                 if shared:
                     flow, kind = shared, "shared"
+        maximize = wants_maximized(browser_cfg, headless=headless)
+        video = browser_cfg.get("video") is True
+        if video and not video_available():
+            emit({"type": "log", "level": "warn", "text": "No video for this run: the engine's video packages are missing. Run: forgeqe setup"})
+            video = False
+        if maximize or video:
+            # Started before the agent so the window is maximised, and the video sized, before the first page opens.
+            try:
+                await browser.start()
+                if maximize and not await maximize_window(browser):
+                    emit({"type": "log", "level": "debug", "text": "The browser window could not be maximised"})
+                if video and await start_video(browser, out_dir) is None:
+                    emit({"type": "log", "level": "warn", "text": "No video for this run: recording did not start"})
+            except Exception as ex:
+                logger.debug("early browser start failed: %s", ex)
         if flow and kind and flow.get("steps"):
             if kind == "interrupted":
                 replay_text = (
@@ -1668,6 +1691,8 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
             await _save_logins()
         if overlay is not None:
             overlay.close()
+        if await stop_video(browser):
+            emit({"type": "log", "level": "info", "text": "Video saved: video.mp4"})
         await _shutdown_browser_instance(browser)
 
 
@@ -1694,5 +1719,9 @@ async def run_with_events(req: RunRequest, emit: Emit, cancel_event: asyncio.Eve
         except Exception as ex:
             logger.warning("artifact write failed: %s", ex)
             out["files"] = []
+    # The video is finished when the browser closes, after the other files were written.
+    video = Path(req.out_dir) / VIDEO_FILE
+    if video.is_file() and str(video) not in out["files"]:
+        out["files"].append(str(video))
     emit({"type": "done", "result": {k: v for k, v in out.items() if k != "step_events"}})
     return out