@capagents/forgeqe 2.2.10 → 2.3.1

package/py/forgeqe_engine/copilot_gateway.py

@@ -1,10 +1,14 @@
 """
 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.
+Copilot has no model API for other tools: the SDK runs Copilot "sessions" on the user's seat. The browser engine, the
+desktop agent and the agent runtime (ForgeQE's agent and Scribe) speak OpenAI chat completions, so this gateway turns
+each request into one SDK session with none of Copilot's own tools (the system prompt replaced, screenshots attached, a
+JSON schema passed on) and answers in the OpenAI shape, streamed when the caller asks.
+
+The caller's tools become the session's only tools, each one terminal: when the model calls one, the SDK hands the call
+to the gateway, which records it, ends the turn and returns it as OpenAI tool_calls. The caller runs the tool and sends
+its result in the next request's history, as with any OpenAI endpoint. The gateway runs nothing itself.
 
   python -m forgeqe_engine copilot-gateway
     env    COPILOT_GITHUB_TOKEN          a fine-grained token with Copilot Requests; without it, the signed-in user
@@ -21,6 +25,7 @@ import asyncio
 import hmac
 import json
 import os
+import re
 import sys
 import tempfile
 import time
@@ -35,6 +40,9 @@ 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
+# A tool name as OpenAI and the Copilot SDK take it.
+TOOL_NAME = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
+MAX_TOOLS = 256
 LOCAL_ORIGINS = ("http://127.0.0.1", "http://localhost", "https://127.0.0.1", "https://localhost")
 
 
@@ -68,23 +76,52 @@ def _data_url(url: str) -> Optional[Tuple[str, str]]:
     return mime, data
 
 
+def _text(content: Any) -> str:
+    return "\n".join(str(p.get("text") or "") for p in _parts(content) if p.get("type") == "text")
+
+
+def _tools(body: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """The caller's function tools as {name, description, parameters}; [] when it sent none or tool_choice is none."""
+    raw = body.get("tools")
+    if body.get("functions"):
+        raise GatewayError(400, "The legacy functions field is not supported: send tools.")
+    if raw is None or body.get("tool_choice") == "none":
+        return []
+    if not isinstance(raw, list) or len(raw) > MAX_TOOLS:
+        raise GatewayError(400, f"tools must be a list of at most {MAX_TOOLS} functions.")
+    out: List[Dict[str, Any]] = []
+    for t in raw:
+        fn = t.get("function") if isinstance(t, dict) and t.get("type") == "function" else None
+        if not isinstance(fn, dict):
+            raise GatewayError(400, "Only function tools are supported.")
+        name = str(fn.get("name") or "")
+        if not TOOL_NAME.match(name):
+            raise GatewayError(400, f"Tool name {name[:80]!r} is not a valid function name.")
+        params = fn.get("parameters")
+        if params is not None and not isinstance(params, dict):
+            raise GatewayError(400, f"Tool {name}'s parameters must be a JSON schema object.")
+        out.append({"name": name, "description": str(fn.get("description") or ""), "parameters": params or {"type": "object", "properties": {}}})
+    if len({t["name"] for t in out}) != len(out):
+        raise GatewayError(400, "Tool names must be unique.")
+    return out
+
+
 def translate(body: Dict[str, Any]) -> Dict[str, Any]:
-    """The session a chat completions request becomes: {model, system, prompt, attachments, schema, json_only}."""
+    """The session a chat completions request becomes: {model, system, prompt, attachments, schema, json_only, tools, stream}."""
     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.")
+    tools = _tools(body)
     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]]]] = []
+    # Tool results name their call by id; the call itself, in an earlier assistant message, names the tool.
+    called: Dict[str, str] = {}
     for m in messages:
         if not isinstance(m, dict):
             continue
@@ -92,9 +129,21 @@ def translate(body: Dict[str, Any]) -> Dict[str, Any]:
         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")
+        elif role == "assistant" and isinstance(m.get("tool_calls"), list):
+            for c in m["tool_calls"]:
+                fn = c.get("function") if isinstance(c, dict) else None
+                if isinstance(fn, dict):
+                    cid = str(c.get("id") or "")[:64]
+                    name = str(fn.get("name") or "")
+                    called[cid] = name if TOOL_NAME.match(name) else "unknown"
+                    parts = parts + [{"type": "text", "text": f"[called tool {called[cid]} (call {cid}) with {fn.get('arguments') or '{}'}]"}]
+            turns.append((role, parts))
+        elif role == "tool":
+            cid = str(m.get("tool_call_id") or "")[:64]
+            turns.append((f"tool_result name={called.get(cid, 'unknown')} call={cid}", [{"type": "text", "text": _text(m.get("content"))}]))
         else:
             turns.append((role, parts))
-    if not turns:
+    if not any(role == "user" for role, _ in 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.
@@ -115,10 +164,18 @@ def translate(body: Dict[str, Any]) -> Dict[str, Any]:
                 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}>")
+        tag = role.split(" ", 1)[0]
+        lines.append(text if len(turns) == 1 else f"<{role}>\n{text}\n</{tag}>")
     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
+    if tools:
+        prompt += "\n\nTo use a tool, call it through the tool interface; never write a tool call as text."
+        choice = body.get("tool_choice")
+        if choice == "required":
+            prompt += " Call at least one tool now."
+        elif isinstance(choice, dict) and isinstance(choice.get("function"), dict):
+            prompt += f" Call the tool {choice['function'].get('name')} now."
 
     schema = None
     json_only = False
@@ -131,19 +188,31 @@ def translate(body: Dict[str, Any]) -> Dict[str, Any]:
         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}
+    return {
+        "model": model,
+        "system": "\n\n".join(s for s in system if s),
+        "prompt": prompt,
+        "attachments": attachments,
+        "schema": schema,
+        "json_only": json_only,
+        "tools": tools,
+        "stream": bool(body.get("stream")),
+    }
 
 
-def completion(model: str, content: str, usage: Dict[str, int]) -> Dict[str, Any]:
-    """An OpenAI chat.completion object."""
+def completion(model: str, content: str, usage: Dict[str, int], tool_calls: Optional[List[Dict[str, Any]]] = None) -> Dict[str, Any]:
+    """An OpenAI chat.completion object; with tool_calls, the calls the model made and finish_reason tool_calls."""
     prompt_tokens = int(usage.get("input", 0))
     completion_tokens = int(usage.get("output", 0))
+    message: Dict[str, Any] = {"role": "assistant", "content": content}
+    if tool_calls:
+        message["tool_calls"] = [{"id": c["id"], "type": "function", "function": {"name": c["name"], "arguments": c["arguments"]}} for c in tool_calls]
     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"}],
+        "choices": [{"index": 0, "message": message, "finish_reason": "tool_calls" if tool_calls else "stop"}],
         "usage": {"prompt_tokens": prompt_tokens, "completion_tokens": completion_tokens, "total_tokens": prompt_tokens + completion_tokens},
     }
     if usage.get("cached"):
@@ -151,6 +220,21 @@ def completion(model: str, content: str, usage: Dict[str, int]) -> Dict[str, Any
     return out
 
 
+def chunks(done: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """A finished chat.completion as the chat.completion.chunk events a streaming caller expects, usage last."""
+    choice = done["choices"][0]
+    message = choice["message"]
+    base = {"id": done["id"], "object": "chat.completion.chunk", "created": done["created"], "model": done["model"]}
+    delta: Dict[str, Any] = {"role": "assistant", "content": message.get("content") or ""}
+    if message.get("tool_calls"):
+        delta["tool_calls"] = [{"index": i, **c} for i, c in enumerate(message["tool_calls"])]
+    return [
+        {**base, "choices": [{"index": 0, "delta": delta, "finish_reason": None}]},
+        {**base, "choices": [{"index": 0, "delta": {}, "finish_reason": choice["finish_reason"]}]},
+        {**base, "choices": [], "usage": done["usage"]},
+    ]
+
+
 def strip_fences(text: str) -> str:
     """```json … ``` → the JSON inside, for models that wrap structured replies in a code fence."""
     t = text.strip()
@@ -206,6 +290,9 @@ class Copilot:
         self.workdir = tempfile.mkdtemp(prefix="forgeqe-copilot-")
         self.signed_in_user = not token
         self.client = CopilotClient(**client_options(token, home, self.workdir))
+        # Caller tools named like one of Copilot's own: they must say they replace it. Learned from Copilot's answers
+        # (BUILTIN_TOOLS to start with), kept for the gateway's life, so only a first request pays a retry.
+        self.replaces: set = set(BUILTIN_TOOLS)
 
     async def start(self) -> None:
         await self.client.start()
@@ -225,8 +312,21 @@ class Copilot:
     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))})
+            caps = getattr(m, "capabilities", None)
+            supports = getattr(caps, "supports", None)
+            limits = getattr(caps, "limits", None)
+            policy = getattr(getattr(m, "policy", None), "state", None)
+            multiplier = getattr(getattr(m, "billing", None), "multiplier", None)
+            out.append({
+                "id": m.id,
+                "object": "model",
+                "owned_by": "github-copilot",
+                "vision": bool(getattr(supports, "vision", False)),
+                # enabled, disabled (the seat's policy turns it off) or unconfigured (enable it in GitHub's Copilot settings).
+                "policy": str(policy) if policy else "enabled",
+                **({"multiplier": float(multiplier)} if isinstance(multiplier, (int, float)) else {}),
+                **({"context": int(limits.max_prompt_tokens)} if getattr(limits, "max_prompt_tokens", None) else {}),
+            })
         return out
 
     async def complete(self, req: Dict[str, Any]) -> Dict[str, Any]:
@@ -235,6 +335,7 @@ class Copilot:
 
         usage = {"input": 0, "output": 0, "cached": 0}
         errors: List[str] = []
+        calls: List[Dict[str, Any]] = []
 
         def on_event(event: Any) -> None:
             data = getattr(event, "data", None)
@@ -245,40 +346,118 @@ class Copilot:
             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:
+        tried: set = set()
+        reply: Any = None
+        for _ in range(MAX_TOOL_RETRIES + 1):
+            errors.clear()
+            calls.clear()
+            names = {t["name"] for t in req["tools"]}
+            tools = relay_tools(req["tools"], calls, replaces=self.replaces & names)
+            options: Dict[str, Any] = dict(
+                model=req["model"],
+                # The caller's prompt is the whole prompt; Copilot's own tools are never offered, only the caller's.
+                system_message={"mode": "replace", "content": req["system"] or "You are a helpful assistant."},
+                tools=tools or None,
+                available_tools=[t.name for t in 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,
+            )
+            failure: Optional[str] = None
+            session = None
             try:
-                await session.disconnect()
-            except Exception:
-                pass
-        if errors:
+                session = await self.client.create_session(**options)
+                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.")
+            except Exception as e:  # Copilot names a tool it will not take; anything else is reported below.
+                failure = str(e)
+            finally:
+                if session is not None:
+                    try:
+                        await session.disconnect()
+                    except Exception:
+                        pass
+            # Copilot reports a clash with its own tools when the session starts or when the turn starts.
+            fix = tool_conflict(failure or (errors[-1] if errors and not calls else ""), names)
+            if fix and fix not in tried:
+                tried.add(fix)
+                name, replace = fix
+                (self.replaces.add if replace else self.replaces.discard)(name)
+                continue
+            if failure:
+                raise GatewayError(502, f"GitHub Copilot: {failure}"[:2000])
+            break
+        else:
+            raise GatewayError(502, "GitHub Copilot kept refusing the names of the caller's tools.")
+        if errors and not calls:
             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)
+        content = (data.content or "") if isinstance(data, AssistantMessageData) else ""
+        if calls:
+            return completion(req["model"], content, usage, calls)
         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)
 
 
+# Copilot's own tools that the agent runtime's tools are named like (bash, glob, grep, edit, …). A caller tool with one
+# of these names says it replaces Copilot's: the caller's tool is the one offered, and it runs nothing here.
+BUILTIN_TOOLS = frozenset({"bash", "powershell", "glob", "grep", "view", "edit", "create", "task", "skill", "web_fetch", "think", "update_todo", "report_intent"})
+MAX_TOOL_RETRIES = 8
+
+_CONFLICT = re.compile(r'(?:external )?tool "([A-Za-z0-9_-]{1,64})" conflicts with a built-in tool', re.I)
+_NO_BUILTIN = re.compile(r'tool "([A-Za-z0-9_-]{1,64})"[^"\n]{0,80}(?:does not|doesn\'t|no) (?:override|built-in|builtin)', re.I)
+
+
+def tool_conflict(message: str, names: set) -> Optional[Tuple[str, bool]]:
+    """
+    From Copilot's error, the caller tool to retry with: (name, True) when it clashes with a built-in and must replace
+    it, (name, False) when Copilot has no built-in of that name to replace. None for any other error.
+    """
+    if not message:
+        return None
+    m = _CONFLICT.search(message)
+    if m and m.group(1) in names:
+        return m.group(1), True
+    m = _NO_BUILTIN.search(message)
+    if m and m.group(1) in names:
+        return m.group(1), False
+    return None
+
+
+def relay_tools(specs: List[Dict[str, Any]], calls: List[Dict[str, Any]], override: bool = False, replaces: Optional[set] = None) -> List[Any]:
+    """
+    The caller's tools as Copilot SDK tools that run nothing: each records the call in `calls` and, being terminal, ends
+    the turn, so the call goes back to the caller as OpenAI tool_calls. A tool in `replaces` (or every tool, with
+    `override`) replaces Copilot's built-in tool of the same name.
+    """
+    if not specs:
+        return []
+    from copilot.tools import Tool, ToolResult
+
+    def handler(invocation: Any) -> Any:
+        args = invocation.arguments
+        calls.append({
+            "id": invocation.tool_call_id or f"call_{uuid.uuid4().hex[:24]}",
+            "name": invocation.tool_name,
+            "arguments": args if isinstance(args, str) else json.dumps(args if args is not None else {}),
+        })
+        return ToolResult(text_result_for_llm="The caller runs this tool and sends its result in the next message.")
+
+    return [
+        Tool(name=t["name"], description=t["description"], parameters=t["parameters"], handler=handler, skip_permission=True, is_terminal=True, defer="never", overrides_built_in_tool=override or t["name"] in (replaces or set()))
+        for t in specs
+    ]
+
+
 # ---------------------------------------------------------------------------------------------------------------------
 # A small HTTP/1.1 server: one request per connection
 
@@ -290,6 +469,13 @@ def _response(status: int, payload: Dict[str, Any]) -> bytes:
     return head.encode() + body
 
 
+def _stream(done: Dict[str, Any]) -> bytes:
+    """The answer as server-sent events; the connection closes after [DONE]."""
+    events = "".join(f"data: {json.dumps(c)}\n\n" for c in chunks(done)) + "data: [DONE]\n\n"
+    head = "HTTP/1.1 200 OK\r\nContent-Type: text/event-stream\r\nCache-Control: no-cache\r\nConnection: close\r\n\r\n"
+    return head.encode() + events.encode()
+
+
 def _error(status: int, message: str) -> bytes:
     return _response(status, {"error": {"message": message, "type": "forgeqe_copilot_gateway"}})
 
@@ -335,7 +521,9 @@ async def handle(reader: asyncio.StreamReader, writer: asyncio.StreamWriter, cop
         except ValueError:
             writer.write(_error(400, "The request body is not JSON."))
             return
-        writer.write(_response(200, await copilot.complete(translate(body))))
+        req = translate(body)
+        done = await copilot.complete(req)
+        writer.write(_stream(done) if req["stream"] else _response(200, done))
     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.
@@ -364,6 +552,9 @@ async def serve(out: TextIO, copilot: Any = None) -> int:
         except GatewayError as e:
             out.write(json.dumps({"error": e.message}) + "\n")
             return 1
+        except ImportError as e:
+            out.write(json.dumps({"error": f"GitHub's Copilot SDK is not installed in the ForgeQE engine ({e}): run forgeqe setup, which installs it from pypi.org."}) + "\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