@capagents/forgeqe 1.3.1 → 2.0.0

package/py/forgeqe_desktop/workflow.py

@@ -0,0 +1,338 @@
+"""
+Desktop workflows as YAML (format ``forgeqe-desktop-v1``): load, validate, save, and fill in variables.
+
+A workflow may have been written by the model or edited by hand, so everything in it is checked before a step runs:
+known ops and keys only, locators by UIA properties, key chords from a small grammar without the Windows key, image
+names that stay inside the workflow's baselines folder.
+
+Timing: ``timeout`` (seconds to wait for a control) and ``retries`` (tries again after a failure) apply to the whole
+workflow and can be set per step; ``wait_for`` waits for a control to appear, show a text or go away (a splash
+screen, a progress bar); ``dismiss`` lists controls (a dialog's OK button) to click whenever they are in the way.
+"""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Mapping, Optional
+
+import yaml
+
+FORMAT = "forgeqe-desktop-v1"
+# Mobile apps (Android and iOS, through Appium or Maestro): the same steps where they make sense, plus touch gestures.
+MOBILE_FORMAT = "forgeqe-mobile-v1"
+FORMATS = (FORMAT, MOBILE_FORMAT)
+
+OPS = ("launch", "click", "double_click", "type", "select", "keys", "expect", "expect_image", "wait", "wait_for", "close")
+TARGET_OPS = ("click", "double_click", "type", "select", "expect", "wait_for")
+MAX_WAIT_SECONDS = 60
+MAX_TIMEOUT_SECONDS = 300
+MAX_RETRIES = 5
+MAX_DISMISS = 10
+# Steps whose action is tried again after a failure, when retries allow.
+RETRY_OPS = ("click", "double_click", "type", "select", "keys", "expect", "expect_image")
+TIMEOUT_OPS = ("launch", *TARGET_OPS, "expect_image", "long_press", "double_tap", "tap", "scroll_to")
+
+MOBILE_OPS = ("launch", "tap", "double_tap", "long_press", "type", "expect", "expect_image", "swipe", "scroll_to", "back", "hide_keyboard", "keys", "wait", "wait_for", "close")
+MOBILE_TARGET_OPS = ("tap", "double_tap", "long_press", "type", "expect", "wait_for", "scroll_to")
+MOBILE_RETRY_OPS = ("tap", "double_tap", "long_press", "type", "expect", "expect_image", "swipe", "scroll_to", "keys")
+MOBILE_KEYS = ("enter", "back", "tab", "delete", "search")
+SWIPE_DIRECTIONS = ("up", "down", "left", "right")
+_MOBILE_STEP_KEYS = {
+    "launch": set(),
+    "tap": {"target"},
+    "double_tap": {"target"},
+    "long_press": {"target"},
+    "type": {"target", "text"},
+    "expect": {"target", "text"},
+    "expect_image": {"target", "image", "tolerance", "ignore"},
+    "swipe": {"direction", "target"},
+    "scroll_to": {"target", "direction"},
+    "back": set(),
+    "hide_keyboard": set(),
+    "keys": {"keys"},
+    "wait": {"seconds"},
+    "wait_for": {"target", "text", "gone"},
+    "close": set(),
+}
+_MOBILE_REQUIRED = {"type": {"target", "text"}, "keys": {"keys"}, "wait": {"seconds"}, "expect_image": {"image"}, "swipe": {"direction"}}
+IMAGE_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_-]{0,99}\.png$")
+MAX_IGNORE = 20
+
+LOCATOR_KEYS = ("automation_id", "name", "control_type", "class_name", "index", "path")
+_STEP_KEYS = {
+    "launch": set(),
+    "click": {"target"},
+    "double_click": {"target"},
+    "type": {"target", "text"},
+    "select": {"target", "value"},
+    "keys": {"keys"},
+    "expect": {"target", "text"},
+    "expect_image": {"target", "image", "tolerance", "ignore"},
+    "wait": {"seconds"},
+    "wait_for": {"target", "text", "gone"},
+    "close": set(),
+}
+_REQUIRED = {"type": {"target", "text"}, "select": {"target", "value"}, "keys": {"keys"}, "wait": {"seconds"}, "expect_image": {"image"}}
+
+APP_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$")
+_VAR_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]{0,63}$")
+# {{name}} or {{secret:NAME}}; anything else between braces is an error, not text to keep.
+_PLACEHOLDER = re.compile(r"\{\{\s*([^{}]*?)\s*\}\}")
+
+MODIFIERS = ("ctrl", "shift", "alt")
+NAMED_KEYS = (
+    "enter", "tab", "esc", "space", "backspace", "delete", "insert", "home", "end", "pageup", "pagedown",
+    "up", "down", "left", "right", *[f"f{n}" for n in range(1, 13)],
+)
+# Win+R and the context-menu key reach other programs; typing after them can run any command.
+REFUSED_KEYS = ("win", "lwin", "rwin", "windows", "super", "meta", "cmd", "apps", "menu")
+
+
+class WorkflowError(ValueError):
+    """A workflow that cannot run as written; the message says which step and why."""
+
+
+def parse_chord(chord: str) -> List[str]:
+    """``"ctrl+shift+s"`` as ``["ctrl", "shift", "s"]``: modifiers first, then one named key or one character."""
+    if not isinstance(chord, str) or not chord.strip():
+        raise WorkflowError("keys must be a chord such as ctrl+s or enter")
+    parts = [p.strip().lower() for p in chord.split("+")]
+    if chord.strip().endswith("++"):
+        parts = parts[:-2] + ["+"]
+    if any(not p for p in parts):
+        raise WorkflowError(f"keys {chord!r} has an empty part")
+    for p in parts:
+        if p in REFUSED_KEYS:
+            raise WorkflowError(f"keys {chord!r}: the {p} key is not allowed, it reaches programs outside the app")
+    *mods, key = parts
+    for m in mods:
+        if m not in MODIFIERS:
+            raise WorkflowError(f"keys {chord!r}: {m!r} is not ctrl, shift or alt")
+    if len(set(mods)) != len(mods):
+        raise WorkflowError(f"keys {chord!r} repeats a modifier")
+    if key not in NAMED_KEYS and not (len(key) == 1 and key.isprintable() and not key.isspace()):
+        raise WorkflowError(f"keys {chord!r}: {key!r} is not a key (use one character or {', '.join(NAMED_KEYS[:6])}, …)")
+    return [*mods, key]
+
+
+def _check_target(where: str, target: Any) -> Dict[str, Any]:
+    if not isinstance(target, dict):
+        raise WorkflowError(f"{where}: target must be a mapping of UIA properties")
+    unknown = set(target) - set(LOCATOR_KEYS)
+    if unknown:
+        raise WorkflowError(f"{where}: unknown target keys {sorted(unknown)}; use {', '.join(LOCATOR_KEYS)}")
+    if not str(target.get("automation_id") or "").strip() and not str(target.get("name") or "").strip():
+        raise WorkflowError(f"{where}: target needs an automation_id or a name")
+    for k in ("automation_id", "name", "control_type", "class_name"):
+        if k in target and not isinstance(target[k], str):
+            raise WorkflowError(f"{where}: target.{k} must be text")
+    if "index" in target and (not isinstance(target["index"], int) or isinstance(target["index"], bool) or target["index"] < 0):
+        raise WorkflowError(f"{where}: target.index must be a whole number, 0 or more")
+    if "path" in target:
+        path = target["path"]
+        if not isinstance(path, list) or not all(isinstance(p, dict) and set(p) <= {"control_type", "name"} for p in path):
+            raise WorkflowError(f"{where}: target.path must be a list of {{control_type, name}}")
+    return dict(target)
+
+
+def _seconds(where: str, value: Any, most: float) -> float:
+    if not isinstance(value, (int, float)) or isinstance(value, bool) or not 0 <= value <= most:
+        raise WorkflowError(f"{where} must be a number of seconds between 0 and {most:g}")
+    return value
+
+
+def _retries(where: str, value: Any) -> int:
+    if not isinstance(value, int) or isinstance(value, bool) or not 0 <= value <= MAX_RETRIES:
+        raise WorkflowError(f"{where} must be a whole number from 0 to {MAX_RETRIES}")
+    return value
+
+
+def check_image_name(where: str, name: Any) -> str:
+    """A baseline image's file name: letters, digits, _ and -, ending .png; never a path."""
+    if not isinstance(name, str) or not IMAGE_NAME.match(name):
+        raise WorkflowError(f"{where}: image must be a file name such as invoice-total.png (letters, digits, _ and -), not a path")
+    return name
+
+
+def _ignore(where: str, regions: Any) -> List[List[int]]:
+    if not isinstance(regions, list) or len(regions) > MAX_IGNORE:
+        raise WorkflowError(f"{where}: ignore must be a list of at most {MAX_IGNORE} regions [x, y, width, height]")
+    out: List[List[int]] = []
+    for r in regions:
+        if not (isinstance(r, list) and len(r) == 4 and all(isinstance(n, int) and not isinstance(n, bool) and n >= 0 for n in r)):
+            raise WorkflowError(f"{where}: each ignore region is [x, y, width, height] in whole pixels")
+        out.append(list(r))
+    return out
+
+
+def validate(doc: Any) -> Dict[str, Any]:
+    """The workflow, checked and normalised; raises WorkflowError naming the first problem."""
+    if not isinstance(doc, dict):
+        raise WorkflowError("a workflow is a YAML mapping")
+    fmt = doc.get("format")
+    if fmt not in FORMATS:
+        raise WorkflowError(f"format must be {FORMAT} (Windows desktop) or {MOBILE_FORMAT} (Android, iOS)")
+    mobile = fmt == MOBILE_FORMAT
+    ops, step_keys, required = (MOBILE_OPS, _MOBILE_STEP_KEYS, _MOBILE_REQUIRED) if mobile else (OPS, _STEP_KEYS, _REQUIRED)
+    target_ops, retry_ops = (MOBILE_TARGET_OPS, MOBILE_RETRY_OPS) if mobile else (TARGET_OPS, RETRY_OPS)
+    app = doc.get("app")
+    if not isinstance(app, str) or not APP_NAME.match(app):
+        raise WorkflowError(f"app must name an entry in forgeqe.yaml {'mobile' if mobile else 'desktop'}.apps (letters, digits, _ . -), not a path")
+    variables = doc.get("variables") or {}
+    if not isinstance(variables, dict):
+        raise WorkflowError("variables must be a mapping")
+    for k, v in variables.items():
+        if not isinstance(k, str) or not _VAR_NAME.match(k):
+            raise WorkflowError(f"variable name {k!r} must be letters, digits and _")
+        if not isinstance(v, (str, int, float)) or isinstance(v, bool):
+            raise WorkflowError(f"variable {k} must be text or a number")
+    steps = doc.get("steps")
+    if not isinstance(steps, list) or not steps:
+        raise WorkflowError("steps must be a non-empty list")
+    out: List[Dict[str, Any]] = []
+    for i, step in enumerate(steps, 1):
+        where = f"step {i}"
+        if not isinstance(step, dict):
+            raise WorkflowError(f"{where} must be a mapping")
+        op = step.get("op")
+        if op not in ops:
+            raise WorkflowError(f"{where}: op {op!r} is not one of {', '.join(ops)}")
+        allowed = step_keys[op] | {"op", "note"} | ({"timeout"} if op in TIMEOUT_OPS else set()) | ({"retries"} if op in retry_ops else set())
+        unknown = set(step) - allowed
+        if unknown:
+            raise WorkflowError(f"{where} ({op}): unknown keys {sorted(unknown)}")
+        missing = (required.get(op, set()) | ({"target"} if op in target_ops else set())) - set(step)
+        if missing:
+            raise WorkflowError(f"{where} ({op}) needs {', '.join(sorted(missing))}")
+        clean: Dict[str, Any] = {"op": op}
+        if "target" in step:
+            clean["target"] = _check_target(where, step["target"])
+        for k in ("text", "value"):
+            if k in step:
+                if not isinstance(step[k], (str, int, float)) or isinstance(step[k], bool):
+                    raise WorkflowError(f"{where}: {k} must be text")
+                clean[k] = str(step[k])
+        if op == "keys" and mobile:
+            key = str(step["keys"]).strip().lower()
+            if key not in MOBILE_KEYS:
+                raise WorkflowError(f"{where}: keys on a phone is one of {', '.join(MOBILE_KEYS)}")
+            clean["keys"] = key
+        elif op == "keys":
+            parse_chord(step["keys"])
+            clean["keys"] = str(step["keys"]).strip().lower()
+        if op in ("swipe", "scroll_to") and "direction" in step:
+            if step["direction"] not in SWIPE_DIRECTIONS:
+                raise WorkflowError(f"{where}: direction is one of {', '.join(SWIPE_DIRECTIONS)}")
+            clean["direction"] = step["direction"]
+        if op == "wait":
+            s = step["seconds"]
+            if not isinstance(s, (int, float)) or isinstance(s, bool) or not 0 <= s <= MAX_WAIT_SECONDS:
+                raise WorkflowError(f"{where}: seconds must be between 0 and {MAX_WAIT_SECONDS}")
+            clean["seconds"] = s
+        if op == "wait_for":
+            if "gone" in step and not isinstance(step["gone"], bool):
+                raise WorkflowError(f"{where}: gone must be true or false")
+            if step.get("gone") and "text" in step:
+                raise WorkflowError(f"{where}: wait_for waits for a control to go away (gone) or to show a text, not both")
+            if step.get("gone"):
+                clean["gone"] = True
+        if op == "expect_image":
+            clean["image"] = check_image_name(where, step["image"])
+            if "tolerance" in step:
+                t = step["tolerance"]
+                if not isinstance(t, (int, float)) or isinstance(t, bool) or not 0 <= t <= 1:
+                    raise WorkflowError(f"{where}: tolerance is the share of pixels that may differ, from 0 to 1 (0.01 is 1%)")
+                clean["tolerance"] = t
+            if "ignore" in step:
+                clean["ignore"] = _ignore(where, step["ignore"])
+        if "timeout" in step:
+            clean["timeout"] = _seconds(f"{where}: timeout", step["timeout"], MAX_TIMEOUT_SECONDS)
+        if "retries" in step:
+            clean["retries"] = _retries(f"{where}: retries", step["retries"])
+        if isinstance(step.get("note"), str):
+            clean["note"] = step["note"]
+        out.append(clean)
+    result: Dict[str, Any] = {"format": fmt, "name": str(doc.get("name") or ""), "app": app, "variables": dict(variables), "steps": out}
+    if "timeout" in doc:
+        result["timeout"] = _seconds("timeout", doc["timeout"], MAX_TIMEOUT_SECONDS)
+    if "retries" in doc:
+        result["retries"] = _retries("retries", doc["retries"])
+    if "dismiss" in doc:
+        dismiss = doc["dismiss"]
+        if not isinstance(dismiss, list) or len(dismiss) > MAX_DISMISS:
+            raise WorkflowError(f"dismiss must be a list of at most {MAX_DISMISS} targets (the buttons that close a dialog in the way)")
+        result["dismiss"] = [_check_target(f"dismiss {i}", t) for i, t in enumerate(dismiss, 1)]
+    return result
+
+
+def load(path: str | os.PathLike) -> Dict[str, Any]:
+    with open(path, "r", encoding="utf-8") as f:
+        return validate(yaml.safe_load(f))
+
+
+def dump(workflow: Dict[str, Any]) -> str:
+    return yaml.safe_dump(validate(workflow), sort_keys=False, allow_unicode=True)
+
+
+def save(workflow: Dict[str, Any], path: str | os.PathLike) -> None:
+    Path(path).write_text(dump(workflow), encoding="utf-8")
+
+
+def env_secret(name: str) -> Optional[str]:
+    return os.environ.get(name)
+
+
+def fill(text: str, variables: Mapping[str, Any], secret: Callable[[str], Optional[str]] = env_secret) -> str:
+    """
+    ``text`` with ``{{name}}`` and ``{{secret:NAME}}`` replaced, in one pass: a value that itself contains ``{{…}}`` is
+    typed as it is, never expanded again. An unknown variable or secret is an error, not an empty string.
+    """
+
+    def one(m: "re.Match[str]") -> str:
+        ref = m.group(1)
+        if ref.startswith("secret:"):
+            name = ref[len("secret:"):].strip()
+            if not _VAR_NAME.match(name):
+                raise WorkflowError(f"secret name {name!r} must be letters, digits and _")
+            value = secret(name)
+            if value is None:
+                raise WorkflowError(f"secret {name} is not set")
+            return value
+        if not _VAR_NAME.match(ref):
+            raise WorkflowError(f"{{{{{ref}}}}} is not a variable name")
+        if ref not in variables:
+            raise WorkflowError(f"variable {ref} has no value")
+        return str(variables[ref])
+
+    return _PLACEHOLDER.sub(one, text)
+
+
+def fill_targets(workflow: Mapping[str, Any], variables: Mapping[str, Any]) -> Dict[str, Any]:
+    """
+    The workflow with ``{{name}}`` filled in its targets (steps and ``dismiss``), so a data row can name the control to
+    use ("tap the result {{term}}"). A secret is refused there: a locator is shown in reports and to the healing model.
+    """
+
+    def no_secret(name: str) -> Optional[str]:
+        raise WorkflowError(f"a target may not use {{{{secret:{name}}}}}; secrets are typed with text, never part of a locator")
+
+    def one(target: Mapping[str, Any]) -> Dict[str, Any]:
+        out = dict(target)
+        for k in ("automation_id", "name", "control_type", "class_name"):
+            if isinstance(out.get(k), str):
+                out[k] = fill(out[k], variables, no_secret)
+        if isinstance(out.get("path"), list):
+            out["path"] = [{**p, **({"name": fill(p["name"], variables, no_secret)} if isinstance(p.get("name"), str) else {})} for p in out["path"]]
+        return out
+
+    wf = dict(workflow)
+    wf["steps"] = [{**s, "target": one(s["target"])} if isinstance(s.get("target"), Mapping) else dict(s) for s in wf.get("steps") or []]
+    if wf.get("dismiss"):
+        wf["dismiss"] = [one(t) for t in wf["dismiss"]]
+    return wf
+
+
+def secret_names(text: str) -> List[str]:
+    """The ``{{secret:NAME}}`` names in ``text``, so a report can mask what they were filled with."""
+    return [m.group(1)[len("secret:"):].strip() for m in _PLACEHOLDER.finditer(text) if m.group(1).startswith("secret:")]

package/py/forgeqe_engine/cli.py

@@ -171,8 +171,18 @@ def _token(out: TextIO) -> int:
         return 1
 
 
+def _utf8_stdio() -> None:
+    """The CLI speaks UTF-8 on every pipe; on Windows a pipe defaults to the ANSI code page, which turns a curly quote into a lone surrogate."""
+    for stream in (sys.stdin, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, ValueError):
+            pass
+
+
 def main(argv: list[str] | None = None) -> int:
     args = list(sys.argv[1:] if argv is None else argv)
+    _utf8_stdio()
     out = _event_stream()
     _configure_env()
     cmd = args[0] if args else "run"

package/py/forgeqe_engine/llm.py

@@ -125,13 +125,13 @@ def _build_llm(llm_config: Optional[Dict[str, Any]]):
         dep = str(deployment)
         common: Dict[str, Any] = {"model": dep, "azure_deployment": dep, "azure_endpoint": endpoint, "api_version": str(api_version)}
         if entra:
-            return ChatAzureOpenAI(**common, azure_ad_token_provider=entra_token_provider(cfg))
+            return _adaptive(cfg, ChatAzureOpenAI(**common, azure_ad_token_provider=entra_token_provider(cfg)))
         if not api_key:
             raise ValueError(
                 "Azure OpenAI needs an API key: set the profile's api_key_env variable (see llms.json), "
                 "or set auth: entra to sign in with Microsoft Entra ID instead."
             )
-        return ChatAzureOpenAI(**common, api_key=api_key)
+        return _adaptive(cfg, ChatAzureOpenAI(**common, api_key=api_key))
 
     if provider in ("openai", "openai_compatible"):
         from browser_use.llm.openai.chat import ChatOpenAI
@@ -146,17 +146,67 @@ def _build_llm(llm_config: Optional[Dict[str, Any]]):
                 # The gateway takes an Entra ID bearer token; the client asks for a fresh one on every request.
                 kw["api_key"] = "entra"
                 kw["http_client"] = _bearer_client(entra_token_provider(cfg))
-                return ChatOpenAI(**kw)
+                return _adaptive(cfg, ChatOpenAI(**kw))
             kw["api_key"] = api_key or "local"
         else:
             if not api_key:
                 raise ValueError("OpenAI needs an API key: set OPENAI_API_KEY or the profile's api_key_env.")
             kw["api_key"] = api_key
-        return ChatOpenAI(**kw)
+        return _adaptive(cfg, ChatOpenAI(**kw))
 
     raise ValueError(f"Unsupported LLM provider for the engine: {provider}")
 
 
+def _adaptive(cfg: Dict[str, Any], llm: Any) -> Any:
+    """
+    A browser_use OpenAI or Azure chat model that sends the parameters its model takes (``model_params``): reasoning
+    models are told apart by the profile's model name, not only the deployment's, and a refusal of a parameter turns
+    that parameter off and sends the step again.
+    """
+    from .model_params import MAX_ADJUSTMENTS, is_reasoning, refused_parameters
+
+    said = cfg.get("reasoning")
+    if said is False:
+        llm.reasoning_models = []
+    elif is_reasoning(cfg):
+        llm.reasoning_models = [*(llm.reasoning_models or []), str(llm.model)]
+    original = llm.ainvoke
+
+    async def ainvoke(messages: Any, output_format: Any = None, **kwargs: Any) -> Any:
+        for attempt in range(MAX_ADJUSTMENTS + 1):
+            try:
+                return await original(messages, output_format, **kwargs)
+            except Exception as e:
+                changed = _turn_off(llm, refused_parameters(e))
+                if not changed or attempt == MAX_ADJUSTMENTS:
+                    raise
+                logger.info("model %s refused %s; sending the step again without it", llm.model, ", ".join(changed))
+
+    llm.ainvoke = ainvoke
+    return llm
+
+
+def _turn_off(llm: Any, refused: Any) -> List[str]:
+    """Change the browser_use model so it no longer sends the refused parameters; returns what changed."""
+    changed: List[str] = []
+
+    def unset(attr: str, value: Any = None) -> None:
+        if getattr(llm, attr, value) != value:
+            setattr(llm, attr, value)
+            changed.append(attr)
+
+    for key in sorted(refused):
+        if key in ("temperature", "frequency_penalty", "top_p", "seed", "service_tier", "max_completion_tokens"):
+            unset(key)
+        elif key == "reasoning_effort" and llm.reasoning_models:
+            llm.reasoning_models = []
+            changed.append(key)
+        elif key == "response_format":
+            unset("dont_force_structured_output", True)
+            unset("add_schema_to_system_prompt", True)
+    return changed
+
+
 def call_usage(result: Any) -> Dict[str, int]:
     """One model call's tokens from its completion (browser-use ChatInvokeUsage); prompt tokens include cached ones."""
     u = getattr(result, "usage", None)

package/py/forgeqe_engine/model_params.py

@@ -0,0 +1,169 @@
+"""
+Request parameters that suit the model behind an llms.json profile, worked out without the user setting them.
+
+Chat models differ in what they accept: reasoning models (o1, o3, o4, gpt-5, ...) take ``max_completion_tokens``
+instead of ``max_tokens``, only the default temperature, and no ``frequency_penalty``; older models and many
+OpenAI-compatible servers know nothing of ``max_completion_tokens`` or ``reasoning_effort``; some servers refuse
+``response_format``. An Azure deployment's name says nothing of the model behind it.
+
+So parameters are settled in two ways:
+
+- **Up front:** a profile is a reasoning model when it says so (``"reasoning": true`` or ``false`` in llms.json), else
+  when its ``model`` or ``deployment`` name is one of the reasoning families.
+- **From the API's answer:** a 400 that names a parameter or value the model refuses changes that parameter (switch
+  ``max_tokens`` and ``max_completion_tokens``, drop the rest) and the call is sent again. What was learned is kept per
+  model for the rest of the process, so only the first call pays for it.
+
+Only parameters in ``ADJUSTABLE`` are ever changed or dropped; messages, the model and tools never are.
+"""
+from __future__ import annotations
+
+import re
+import threading
+from typing import Any, Dict, Mapping, Optional, Set
+
+# Model families that reason before answering: they refuse max_tokens and a temperature other than the default.
+_REASONING = re.compile(r"(^|[^a-z0-9])(o1|o3|o4|gpt-5|gpt5|codex|deepseek-r1|qwq)([^a-z0-9]|$)|reason", re.I)
+_LIMITS = ("max_tokens", "max_completion_tokens")
+# Parameters that only shape sampling or the reply's form; a call works without them.
+DROPPABLE = ("temperature", "top_p", "frequency_penalty", "presence_penalty", "response_format", "reasoning_effort", "service_tier", "seed", "logprobs", "top_logprobs", "parallel_tool_calls")
+ADJUSTABLE = frozenset(_LIMITS + DROPPABLE)
+# Most retries for one call: each one fixes a different parameter.
+MAX_ADJUSTMENTS = 4
+# A reasoning model can spend a small limit on reasoning alone and answer nothing; the limit it then gets.
+REASONING_ROOM = 2048
+
+_PARAM = re.compile(r"""(?:parameter|param|argument|field|value)[^'"`]{0,40}['"`]([a-z_]+)['"`]|['"`]([a-z_]+)['"`][^.]{0,60}(?:not supported|unsupported|unrecognized|unknown|not allowed|extra (?:fields|inputs) not permitted|does not support)""", re.I)
+
+_PARAM_FIELD = re.compile(r"""['"]param['"]\s*:\s*['"]([a-z_]+)['"]|(?:argument|parameter)s?\s+supplied:\s*([a-z_]+)""", re.I)
+
+
+def is_reasoning(profile: Mapping[str, Any]) -> bool:
+    """A reasoning model: ``reasoning`` in llms.json when set, else the model or deployment name."""
+    said = profile.get("reasoning")
+    if isinstance(said, bool):
+        return said
+    names = " ".join(str(profile.get(k) or "") for k in ("model", "deployment", "deploymentName"))
+    return bool(_REASONING.search(names))
+
+
+def refused_parameters(error: Any) -> Set[str]:
+    """The adjustable parameters a provider's error says the model refuses (empty when it is another error)."""
+    text = str(error)
+    if not re.search(r"\b400\b|bad ?request|invalid_request|unsupported|not supported|unrecognized|unknown (?:parameter|field)|extra (?:fields|inputs)", text, re.I):
+        return set()
+    found = {(m.group(1) or m.group(2)).lower() for m in _PARAM.finditer(text)}
+    # The error body's own "param" field, and "argument supplied: name" without quotes.
+    found |= {(m.group(1) or m.group(2)).lower() for m in _PARAM_FIELD.finditer(text)}
+    if re.search(r"temperature.{0,80}(only the default|does not support|not supported|unsupported)|(only the default|unsupported value).{0,80}temperature", text, re.I | re.S):
+        found.add("temperature")
+    if "max_completion_tokens" in text and "max_tokens" in text and re.search(r"use ['\"`]?max_completion_tokens", text, re.I):
+        found = (found - {"max_completion_tokens"}) | {"max_tokens"}
+    return found & ADJUSTABLE
+
+
+class ModelParams:
+    """What one model accepts, starting from its profile and learning from its refusals; safe across threads."""
+
+    def __init__(self, profile: Mapping[str, Any]) -> None:
+        self.reasoning = is_reasoning(profile)
+        self.limit_key = "max_completion_tokens" if self.reasoning else "max_tokens"
+        self.dropped: Set[str] = set()
+        if self.reasoning:
+            self.dropped |= {"temperature", "top_p", "frequency_penalty", "presence_penalty"}
+        self._lock = threading.Lock()
+
+    def apply(self, kw: Dict[str, Any]) -> Dict[str, Any]:
+        """``kw`` with the token limit under the key this model takes and the parameters it refuses left out."""
+        out = dict(kw)
+        for key in _LIMITS:
+            if key in out and key != self.limit_key:
+                out[self.limit_key] = out.pop(key)
+        if self.reasoning and self.limit_key in out and out[self.limit_key] is not None:
+            # The limit covers reasoning too: a small one leaves nothing for the answer.
+            out[self.limit_key] = max(int(out[self.limit_key]), REASONING_ROOM)
+        for key in self.dropped:
+            out.pop(key, None)
+        return out
+
+    def learn(self, error: Any, sent: Mapping[str, Any]) -> bool:
+        """Take in a refusal of what was ``sent``; True when something changed and the call is worth sending again."""
+        refused = refused_parameters(error) & set(sent)
+        if not refused:
+            return False
+        changed = False
+        with self._lock:
+            for key in refused:
+                if key in _LIMITS:
+                    other = _LIMITS[1] if key == _LIMITS[0] else _LIMITS[0]
+                    if self.limit_key == key:
+                        self.limit_key = other
+                        changed = True
+                        if other == "max_completion_tokens":
+                            self.reasoning = True
+                elif key not in self.dropped:
+                    self.dropped.add(key)
+                    changed = True
+        return changed
+
+    def needs_room(self, response: Any, sent: Mapping[str, Any]) -> bool:
+        """An empty answer cut off by the token limit: the model reasoned through all of it. Raises the limit for next time."""
+        choices = getattr(response, "choices", None) or []
+        if not choices:
+            return False
+        first = choices[0]
+        content = getattr(getattr(first, "message", None), "content", None)
+        if content or getattr(first, "finish_reason", None) != "length":
+            return False
+        limit = sent.get(self.limit_key)
+        if not isinstance(limit, int) or limit >= REASONING_ROOM:
+            return False
+        with self._lock:
+            self.reasoning = True
+        return True
+
+
+_SHARED: Dict[str, ModelParams] = {}
+_SHARED_LOCK = threading.Lock()
+
+
+def params_for(profile: Mapping[str, Any]) -> ModelParams:
+    """One ``ModelParams`` per model (provider, endpoint and deployment or model) for the whole process."""
+    key = "|".join(str(profile.get(k) or "") for k in ("provider", "endpoint", "deployment", "model", "reasoning"))
+    with _SHARED_LOCK:
+        p = _SHARED.get(key)
+        if p is None:
+            p = _SHARED[key] = ModelParams(profile)
+        return p
+
+
+def call_with_params(params: ModelParams, create: Any, kw: Mapping[str, Any]) -> Any:
+    """``create(**kw)`` with the parameters this model takes, sent again after each refusal that teaches something."""
+    for _ in range(MAX_ADJUSTMENTS + 1):
+        sent = params.apply(dict(kw))
+        try:
+            response = create(**sent)
+        except Exception as e:
+            if params.learn(e, sent):
+                continue
+            raise
+        if params.needs_room(response, sent):
+            continue
+        return response
+    return create(**params.apply(dict(kw)))
+
+
+async def acall_with_params(params: ModelParams, create: Any, kw: Mapping[str, Any]) -> Any:
+    """``call_with_params`` for an async ``create``."""
+    for _ in range(MAX_ADJUSTMENTS + 1):
+        sent = params.apply(dict(kw))
+        try:
+            response = await create(**sent)
+        except Exception as e:
+            if params.learn(e, sent):
+                continue
+            raise
+        if params.needs_room(response, sent):
+            continue
+        return response
+    return await create(**params.apply(dict(kw)))

package/py/forgeqe_engine/summary.py

@@ -81,6 +81,12 @@ def _error_summary_from_history(history: Any) -> str:
         n = len(errs)
         if len(distinct) == 1:
             msg = distinct[0]
+            if n > 1 and "surrogates not allowed" in msg:
+                return (
+                    f"Run stopped after {n} identical errors: {msg}. "
+                    "The request to the model held text that was decoded in the wrong encoding, so it was never sent; "
+                    "the LLM provider is not at fault. Update ForgeQE; the engine now reads its input as UTF-8."
+                )
             if n > 1:
                 return (
                     f"Run stopped after {n} identical errors: {msg}. "

package/py/forgeqe_mobile/__init__.py

@@ -0,0 +1 @@
+"""ForgeQE's mobile engine: Android and iOS apps through Appium or Maestro (docs/MOBILE.md)."""

package/py/forgeqe_mobile/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())