robotframework-harness 1.0.0__py3-none-any.whl

rf_harness/_assets/variants/copilot/hooks.json

@@ -0,0 +1,53 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "type": "command",
+        "bash": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" sessionStart --agent auto",
+        "powershell": "& \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch.cmd\" sessionStart --agent auto",
+        "timeoutSec": 30
+      }
+    ],
+    "userPromptSubmitted": [
+      {
+        "type": "command",
+        "bash": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" userPromptSubmitted --agent auto",
+        "powershell": "& \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch.cmd\" userPromptSubmitted --agent auto",
+        "timeoutSec": 10
+      }
+    ],
+    "preToolUse": [
+      {
+        "type": "command",
+        "bash": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" preToolUse --agent auto",
+        "powershell": "& \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch.cmd\" preToolUse --agent auto",
+        "timeoutSec": 20
+      }
+    ],
+    "postToolUse": [
+      {
+        "type": "command",
+        "bash": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" postToolUse --agent auto",
+        "powershell": "& \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch.cmd\" postToolUse --agent auto",
+        "timeoutSec": 180
+      }
+    ],
+    "postToolUseFailure": [
+      {
+        "type": "command",
+        "bash": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" postToolUseFailure --agent auto",
+        "powershell": "& \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch.cmd\" postToolUseFailure --agent auto",
+        "timeoutSec": 180
+      }
+    ],
+    "agentStop": [
+      {
+        "type": "command",
+        "bash": "python3 -S \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch\" agentStop --agent auto",
+        "powershell": "& \"${CLAUDE_PLUGIN_ROOT}/bin/rfh-launch.cmd\" agentStop --agent auto",
+        "timeoutSec": 90
+      }
+    ]
+  }
+}

rf_harness/_assets/variants/opencode/plugins/rf-harness.js

@@ -0,0 +1,130 @@
+// rf-harness hooks for OpenCode (ported from the measured v3.2 prototype plugin, hookpkg32 install.py OPENCODE_PLUGIN).
+// Every event goes to the same launcher as the other agents: python3 -S <..>/rf-harness/bin/rfh-launch <Event>
+// --agent opencode, which finds the project's Python and runs rf_harness.runtime.hook there.
+//   plugin init -> SessionStart (its setup hint / context is added to the first prompt)
+//   chat.message -> UserPromptSubmit (first prompt only: project context appended to the prompt text)
+//   tool.execute.before -> PreToolUse (deny = throw; rewrite = mutate output.args; the Python side turns a repeated
+//     denial into allow + warning after 2)
+//   tool.execute.after -> PostToolUse (context PREPENDED to the tool output so a weak model reads it first)
+//   assistant message finished -> Stop gate (OpenCode has no blocking stop: a noReply prompt keeps `opencode run` going)
+//   dispose -> SessionEnd
+// OpenCode has no hook timeout: every call is bounded here. The launcher path is resolved relative to this file
+// (<root>/plugins/rf-harness.js -> <root>/rf-harness/bin/rfh-launch); RF_HARNESS_LAUNCHER overrides it and
+// RF_HARNESS_LAUNCHER_PYTHON the interpreter that runs it (default: python3, on Windows `py -3`).
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const LAUNCH = process.env.RF_HARNESS_LAUNCHER || fileURLToPath(new URL("../rf-harness/bin/rfh-launch", import.meta.url));
+const WIN = process.platform === "win32";
+const PY = process.env.RF_HARNESS_LAUNCHER_PYTHON || (WIN ? "py" : "python3");
+const PY_ARGS = process.env.RF_HARNESS_LAUNCHER_PYTHON || !WIN ? ["-S"] : ["-3", "-S"];
+const LAUNCH_ARGS = [/*rf-harness:launch-args*/];
+const EDIT = new Set(["write", "edit", "multiedit", "patch", "apply_patch"]);
+const READ = new Set(["read", "view"]);
+const RF = /\.(robot|resource)\b/;
+const SHELL_PRE = /(^|[\s;&|(\/'"])(robot|robotcode|pip3?|uv|playwright|rfbrowser|npm|npx|PYTHONPATH=|cat|less)\b|PYTHONPATH|\.rf\/docs\/kw\//;
+const ROBOT = /(^|[\s;&|(\/])(robot|robotcode)\s/;
+
+// The model id goes into every payload (output profile lean|rich): `opencode run -m <provider/model>` from argv,
+// OPENCODE_MODEL, then the model of the first chat message.
+function argvModel() {
+  const a = (typeof process !== "undefined" && process.argv) || [];
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] === "-m" || a[i] === "--model") return String(a[i + 1] || "");
+    if (String(a[i]).startsWith("--model=")) return String(a[i]).slice(8);
+  }
+  return (typeof process !== "undefined" && process.env && process.env.OPENCODE_MODEL) || "";
+}
+let MODEL = argvModel();
+function modelOf(m) {
+  if (!m) return "";
+  if (typeof m === "string") return m;
+  const id = m.modelID || m.modelId || m.id || "";
+  const prov = m.providerID || m.providerId || "";
+  return id ? (prov && !String(id).startsWith(prov + "/") ? prov + "/" + id : String(id)) : "";
+}
+
+// async spawn (round-5 finding: spawnSync blocked OpenCode's event loop for the whole hook, ~5 s per edit)
+function call(event, payload, ms) {
+  if (MODEL && payload && !payload.model) payload.model = MODEL;
+  if (payload) payload.ts = Date.now();
+  return new Promise((resolve) => {
+    let out = "", done = false;
+    const finish = (v) => { if (!done) { done = true; clearTimeout(timer); resolve(v); } };
+    let p;
+    try {
+      p = spawn(PY, [...PY_ARGS, LAUNCH, event, "--agent", "opencode", ...LAUNCH_ARGS],
+        { cwd: payload.cwd, stdio: ["pipe", "pipe", "ignore"], windowsHide: true });
+    } catch (e) { return finish({}); }
+    const timer = setTimeout(() => { try { p.kill("SIGKILL"); } catch (e) {} finish({}); }, ms);
+    p.stdout.on("data", (d) => { out += d; });
+    p.on("error", () => finish({}));
+    p.on("close", () => { try { finish(out.trim() ? JSON.parse(out.trim().split("\n").pop()) : {}); } catch (e) { finish({}); } });
+    try { p.stdin.end(JSON.stringify(payload)); } catch (e) {}
+  });
+}
+
+export const RfHarness = async ({ directory, client }) => {
+  const start = await call("SessionStart", { hook_event_name: "SessionStart", cwd: directory }, 30000);
+  let sessionNote = (start && start.text) || "";
+  const notes = new Map();
+  let lastStopAt = 0;
+  let prompted = false;
+  return {
+    "chat.message": async (input, output) => {
+      const m = modelOf((input && input.model) || (output && output.message && output.message.model));
+      if (m) MODEL = m;
+      if (prompted) return;
+      prompted = true;
+      const res = await call("UserPromptSubmit", { hook_event_name: "UserPromptSubmit", cwd: directory,
+        session_id: input && input.sessionID }, 10000);
+      const tp = output && output.parts && output.parts.find((p) => p.type === "text");
+      const text = [sessionNote, res.text].filter(Boolean).join("\n\n");
+      sessionNote = "";
+      if (text && tp) tp.text += "\n\n" + text;
+    },
+    "tool.execute.before": async (input, output) => {
+      const tool = String(input.tool || "").toLowerCase();
+      const args = output.args || {};
+      const s = JSON.stringify(args);
+      const want = (EDIT.has(tool) && RF.test(s)) || (tool === "bash" && SHELL_PRE.test(" " + (args.command || "")))
+        || (READ.has(tool) && (/\.(xml|html?|json|log|txt|yaml|jpe?g|png)\b/.test(s) || /\.rf\/docs\/kw\//.test(s)));
+      if (!want) return;
+      const res = await call("PreToolUse", { hook_event_name: "PreToolUse", tool_name: input.tool, tool_input: args,
+        cwd: directory, session_id: input.sessionID, call_id: input.callID }, 20000);
+      if (res.action === "deny") throw new Error(res.text || "refused by the Robot Framework hook");
+      if (res.action === "rewrite" && res.args) Object.assign(output.args, res.args);
+      if (res.text) notes.set(input.callID, res.text);
+    },
+    "tool.execute.after": async (input, output) => {
+      const tool = String(input.tool || "").toLowerCase();
+      const args = input.args || {};
+      const s = JSON.stringify(args);
+      let text = notes.get(input.callID) || "";
+      notes.delete(input.callID);
+      if ((EDIT.has(tool) && RF.test(s)) || (tool === "bash" && ROBOT.test(" " + (args.command || "")))) {
+        const res = await call("PostToolUse", { hook_event_name: "PostToolUse", tool_name: input.tool, tool_input: args,
+          tool_response: output && output.output, cwd: directory, session_id: input.sessionID, call_id: input.callID },
+          180000);
+        text = [res.text, text].filter(Boolean).join("\n\n");
+      }
+      if (text && output && typeof output.output === "string")
+        output.output = "[Robot Framework hook]\n" + text + "\n[/hook]\n\n" + output.output;
+    },
+    event: async ({ event }) => {
+      const info = event.properties && event.properties.info;
+      if (event.type === "message.updated" && info && info.role === "assistant" && info.finish
+          && info.finish !== "tool-calls" && Date.now() - lastStopAt > 5000) {
+        lastStopAt = Date.now();
+        const res = await call("Stop", { hook_event_name: "Stop", cwd: directory, session_id: info.sessionID }, 90000);
+        if (res.action === "block" && res.text) {
+          try {
+            await client.session.prompt({ path: { id: info.sessionID }, body: { noReply: true,
+              parts: [{ type: "text", text: res.text }] } });
+          } catch (e) {}
+        }
+      }
+    },
+    dispose: async () => { await call("SessionEnd", { hook_event_name: "SessionEnd", cwd: directory }, 5000); },
+  };
+};

rf_harness/config.py

@@ -0,0 +1,255 @@
+"""Registry of every RFH_* environment variable: the single source for runtime defaults and the docs reference.
+
+Each runtime module reads its settings through `get()` / `get_float()` / `get_int()` / `get_bool()` / `get_list()`, so a
+variable that is not registered here raises at import time in tests, and `docs/reference/environment.md` is generated
+from `VARIABLES`. Defaults are the measured v3.2 prototype values (hookpkg32); change them only through the release
+gate.
+
+Precedence: the process environment, then the `env` object of the project's `.rf/harness.json` (written by the
+installer, e.g. `{"python": ..., "version": ..., "env": {"RFH_STATIC": "runtime-only"}}`), then the registered default.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+CATEGORIES = ("live", "feedback", "profiles", "guards", "docs", "lint", "logging", "desktop", "general")
+AGENTS = ("claude", "codex", "copilot", "opencode", "vscode")
+HARNESS_JSON = Path(".rf") / "harness.json"
+
+
+@dataclass(frozen=True)
+class Var:
+    name: str
+    default: str
+    doc: str
+    category: str = "general"
+
+
+VARIABLES: dict[str, Var] = {}
+_PROJECT_ENV: dict[str, str] | None = None
+
+
+def register(name: str, default: str, doc: str, category: str = "general") -> Var:
+    if not name.startswith("RFH_"):
+        raise ValueError(f"harness variables start with RFH_: {name}")
+    if category not in CATEGORIES:
+        raise ValueError(f"unknown category {category!r} for {name}; one of {', '.join(CATEGORIES)}")
+    var = Var(name, default, doc, category)
+    VARIABLES[name] = var
+    return var
+
+
+def get(name: str) -> str:
+    var = VARIABLES.get(name)
+    if var is None:
+        raise KeyError(f"unregistered harness variable {name}; add it to rf_harness.config")
+    value = os.environ.get(name)
+    if value is not None:
+        return value
+    return project_env().get(name, var.default)
+
+
+def find_harness_json(start: str | os.PathLike[str] | None = None) -> Path | None:
+    """`.rf/harness.json` of the project: in RFH_ROOT / CLAUDE_PROJECT_DIR when set, else in `start` (default: the
+    cwd) or one of its six nearest parents."""
+    # os.environ directly, not get(): get() consults project_env(), which calls this function
+    env_root = os.environ.get("RFH_ROOT") or os.environ.get("CLAUDE_PROJECT_DIR")
+    if start is None and env_root and Path(env_root).is_dir():
+        candidates = [Path(env_root)]
+    else:
+        base = Path(start or os.getcwd()).absolute()
+        candidates = [base, *list(base.parents)[:6]]
+    for d in candidates:
+        f = d / HARNESS_JSON
+        if f.is_file():
+            return f
+    return None
+
+
+def load_project_env(path: Path | None) -> dict[str, str]:
+    """RFH_* entries of the `env` object in a harness.json (anything unreadable or malformed is ignored)."""
+    if path is None:
+        return {}
+    try:
+        env = (json.loads(path.read_text(encoding="utf-8")) or {}).get("env") or {}
+    except (OSError, ValueError, AttributeError):
+        return {}
+    if not isinstance(env, dict):
+        return {}
+    return {str(k): str(v) for k, v in env.items()
+            if str(k).startswith("RFH_") and isinstance(v, (str, int, float, bool))}
+
+
+def project_env() -> dict[str, str]:
+    """Project defaults from `.rf/harness.json` (discovered once per process, see find_harness_json)."""
+    global _PROJECT_ENV
+    if _PROJECT_ENV is None:
+        _PROJECT_ENV = load_project_env(find_harness_json())
+    return _PROJECT_ENV
+
+
+def set_project_root(root: str | os.PathLike[str] | None) -> None:
+    """Use `<root>/.rf/harness.json` from now on (None: rediscover on next access; tests)."""
+    global _PROJECT_ENV
+    _PROJECT_ENV = None if root is None else load_project_env(Path(root) / HARNESS_JSON)
+
+
+def get_float(name: str) -> float:
+    try:
+        return float(get(name))
+    except ValueError:
+        return float(VARIABLES[name].default)
+
+
+def get_int(name: str) -> int:
+    return int(get_float(name))
+
+
+def get_bool(name: str) -> bool:
+    return get(name).strip().lower() not in ("0", "false", "no", "off", "")
+
+
+def get_list(name: str) -> list[str]:
+    """Comma-separated value; an empty value means the default (like the prototype's `os.environ.get(X) or default`)."""
+    return (get(name) or VARIABLES[name].default).split(",")
+
+
+def is_registered(name: str) -> bool:
+    return name in VARIABLES
+
+
+# ---------------------------------------------------------------------------------------------------- general
+register("RFH_ROOT", "", "Project root; default: CLAUDE_PROJECT_DIR, else the nearest parent of the hook's cwd that "
+         "already has .rf/hook, else the cwd.", "general")
+register("RFH_PYTHON", "", "Interpreter for the helper daemons and doc workers; default: the hook's own interpreter.",
+         "general")
+register("RFH_WATCH_PID", "", "PID of the agent process the daemons watch (they exit when it is gone); 0 disables the "
+         "watch; default: detected from the hook's ancestors.", "general")
+register("RFH_TOKEN", "", "Internal: random per-daemon token set in the daemons' environment to find and clean up "
+         "their child processes. Do not set it.", "general")
+register("RFH_FORCE_REPL", "0", "1 activates the REPL-only short-timeout listener also outside `robotcode repl|shell` "
+         "(tests only).", "general")
+
+# ---------------------------------------------------------------------------------------------------- live session
+register("RFH_BUDGET", "90", "Maximum seconds a PostToolUse hook waits for live results before reporting 'still "
+         "running' (the result is delivered with the next hook event).", "live")
+register("RFH_IDLE_EXIT", "1200", "Seconds without requests after which the helper daemons exit.", "live")
+register("RFH_SHORT_TIMEOUTS", "1", "0 disables the short live element timeouts (live and REPL listener).", "live")
+register("RFH_SHORT_TIMEOUT", "2.5", "Live element-keyword timeout in seconds (Browser).", "live")
+register("RFH_SHORT_TIMEOUT_SELENIUM", "", "Live element timeout for SeleniumLibrary; default: RFH_SHORT_TIMEOUT.",
+         "live")
+register("RFH_STABLE_S", "2", "Seconds without DOM change after which a page counts as stable (a missing element on a "
+         "stable page is MISSING at once).", "live")
+register("RFH_ADAPT_FACTOR", "1.5", "A late element raises the site's learned short timeout to this factor times its "
+         "observed latency.", "live")
+register("RFH_FRESH_DOC_S", "6", "A document younger than this many seconds is not yet considered stable.", "live")
+register("RFH_MAX_CAPTURES", "2", "Maximum page captures per edit (failure + end of run).", "live")
+register("RFH_STATE_HISTORY", "15", "Number of step-* capture directories kept in .rf/state.", "live")
+register("RFH_CAPTURE", "end", "Page capture mode: end (after the last step and on failures), step (after every "
+         "page keyword) or off.", "live")
+register("RFH_CAPTURE_SETTLE", "1.5", "Maximum seconds the end-of-run capture waits for the page to settle.", "live")
+register("RFH_CAPTURE_GATE", "1", "0 captures after every page keyword (v2 behavior) instead of only on navigation, "
+         "failures and real DOM changes.", "live")
+register("RFH_GUARD_SETTLE", "5.0", "Seconds the pre-execution guard lets a page settle between back-to-back file "
+         "lines.", "live")
+register("RFH_PAGE_TEXT", "4000", "Maximum characters of visible page text in .rf/state/latest/page.txt.", "live")
+
+# ---------------------------------------------------------------------------------------------------- feedback
+register("RFH_MAX_CONTEXT", "2048", "Maximum characters of any hook context returned to the agent.", "feedback")
+register("RFH_MAX_CONTEXT_OPENCODE", "1200", "Maximum characters of hook context for OpenCode.", "feedback")
+register("RFH_LEAN", "1", "0 switches to the v2 output format (ablation only).", "feedback")
+register("RFH_REPRODUCE", "1", "0 disables the live reproduction of the first failure of a plain robot run.",
+         "feedback")
+register("RFH_LOOP_AT", "3", "Number of identical failures after which the one-time loop hint is shown.", "feedback")
+register("RFH_READ_STREAK_AT", "8", "Consecutive reads without an edit or command after which a note is added "
+         "(again at twice the value); 0 disables it.", "feedback")
+register("RFH_COMPACT_AGENTS", "opencode", "Comma-separated agents that get the compact v2 output and image-read "
+         "guard.", "feedback")
+register("RFH_RFMCP_HINTS", "0", "1 adds hints from the vendored rf-mcp hint engine (runtime/hints.py) to live failures. "
+         "Off by default: the measured v3.2 prototype ran without it.", "feedback")
+register("RFH_GUIDANCE_FIRST", "opencode", "Comma-separated agents whose feedback starts with the guidance "
+         "(hint, NEXT:).", "feedback")
+for _agent in AGENTS:
+    register(f"RFH_MAX_CTX_{_agent.upper()}", "", f"Lean-profile budget for {_agent} as 'ok,fail' characters; default: "
+             "the per-agent caps in leanfmt.", "feedback")
+register("RFH_MAX_CTX_RICH", "", "Rich-profile budget as 'ok,fail' characters for every agent; default 1200,1200.",
+         "feedback")
+for _agent in AGENTS:
+    register(f"RFH_MAX_CTX_RICH_{_agent.upper()}", "", f"Rich-profile budget for {_agent} as 'ok,fail' characters "
+             "(RFH_MAX_CTX_RICH wins).", "feedback")
+del _agent
+
+# ---------------------------------------------------------------------------------------------------- profiles
+register("RFH_PROFILE", "", "Force the output profile: lean or rich; default: chosen from the model in use.",
+         "profiles")
+register("RFH_MODEL", "", "Model id used for the profile choice; default: from the hook payload, the agent's "
+         "environment, transcript or config.", "profiles")
+
+# ---------------------------------------------------------------------------------------------------- guards
+register("RFH_RELAXED_DENIALS", "1", "0 restores the v2 denial policy (refuse every static finding; ablation only).",
+         "guards")
+register("RFH_DENY_CODES", "TokenError,ParsingError,InvalidHeader,ModelError", "Comma-separated static-analysis codes "
+         "that refuse an edit; every other finding is a one-line warning.", "guards")
+register("RFH_REWRITE_AGENTS", "claude,opencode,codex,copilot", "Comma-separated agents whose tool input may be "
+         "rewritten (deprecated-syntax fixes, REPL format fixes).", "guards")
+register("RFH_MAX_DENIALS", "3", "Refusals of the same kind before the edit or command is let through with a note.",
+         "guards")
+register("RFH_MAX_DENIALS_OPENCODE", "2", "RFH_MAX_DENIALS for OpenCode.", "guards")
+register("RFH_MAX_STOP_BLOCKS", "2", "How often the end of a turn is blocked for a missing green plain robot run.",
+         "guards")
+
+# ---------------------------------------------------------------------------------------------------- docs
+register("RFH_DOC_WAIT", "1.2", "Seconds a hook waits for a keyword documentation file before naming its path "
+         "anyway.", "docs")
+register("RFH_KWDOC_FILES", "0", "1 writes .rf/docs/kw/<Owner>.<Keyword>.md on every failure (v2) instead of on "
+         "demand.", "docs")
+
+# ---------------------------------------------------------------------------------------------------- lint
+register("RFH_STATIC", "on", "on: the harness checks edits statically (refusals for certainly-wrong structure, one-line "
+         "warnings, deprecated-syntax fixes). runtime-only: only certainly-wrong structural edits are refused, no static "
+         "warnings or fixes, and live runs execute lines without the static pre-check (used when rf-agentskills "
+         "validates edits).", "lint")
+register("RFH_GATE_TIMEOUT", "2.5", "Seconds the PreToolUse static gate waits for the lint daemon; on timeout the "
+         "edit proceeds.", "lint")
+
+# ---------------------------------------------------------------------------------------------------- desktop
+# Read by rf_harness.runtime.desktop through its own _env.env_get (rf-mcp's exact truthiness rules); registered here
+# for the docs reference. Name/default/doc copied from desktop/_env.py ENV_VARIABLES (a test keeps them in sync).
+register("RFH_DESKTOP", "0", "Set to 1 to allow live desktop (PlatynUI) steps. Off by default until the vendored rf-mcp "
+         "desktop guards pass their parity tests; even when on, every safety, isolation and focus guard still applies.",
+         "desktop")
+register("RFH_PLATYNUI_ISOLATED_DISPLAY", "", "Isolation marker: the X DISPLAY(s) (comma/space separated) the harness "
+         "may drive, for example ':99'. Only counts when RFH_PLATYNUI_ISOLATED_XPID names the live X server for that "
+         "display.", "desktop")
+register("RFH_PLATYNUI_ISOLATED_XPID", "", "PID of the Xvfb/Xephyr/Xorg server that owns the isolated display. "
+         "Corroborates the isolation marker; without it the display is classified 'unknown' and desktop input is "
+         "refused.", "desktop")
+register("RFH_PLATYNUI_ALLOW_ACTIVE_DESKTOP", "0", "Escape hatch: 1 allows desktop input on an 'active' or 'unknown' "
+         "display (audited). Input may still target the wrong window on a shared desktop; prefer an isolated display.",
+         "desktop")
+register("RFH_PLATYNUI_SAFETY_GUARD", "enforce", "'warn' logs instead of refusing desktop input on a non-isolated "
+         "display (transition mode).", "desktop")
+register("RFH_PLATYNUI_REQUIRE_ISOLATED", "0", "Windows only: 1 refuses desktop input on the active Windows desktop "
+         "(there is no nested-display model).", "desktop")
+register("RFH_PLATYNUI_ALLOW_UNSCOPED", "0", "1 allows //-rooted desktop Query/Evaluate locators (whole-desktop walks) "
+         "with a one-time warning.", "desktop")
+register("RFH_PLATYNUI_ALLOW_PATH_DESCRIPTOR", "0", "1 allows an image path in the Take Screenshot descriptor slot "
+         "with a one-time warning.", "desktop")
+register("RFH_PLATYNUI_ALLOW_CONTROL_WINDOW", "0", "1 allows control:Window locators on Linux (AT-SPI windows are "
+         "control:Frame) with a one-time warning.", "desktop")
+register("RFH_PLATYNUI_NO_FOCUS", "0", "1 disables focus-before-act for desktop pointer/keyboard steps (the step is "
+         "marked focus-bypassed).", "desktop")
+register("RFH_PLATYNUI_HIGHLIGHT", "1", "0 disables highlighting the target element before desktop input.", "desktop")
+register("RFH_PLATYNUI_KEEP_WAYLAND", "0", "1 keeps the native Wayland backend instead of forcing "
+         "XDG_SESSION_TYPE=x11 before PlatynUI starts.", "desktop")
+register("RFH_PLATYNUI_STEERING_CONFIDENCE", "enforce", "'warn' downgrades a 'contradicted' steering-confidence verdict "
+         "from a step failure to a warning.", "desktop")
+register("RFH_SCREENSHOT_DIR", "", "Extra directory desktop screenshots may be written to (the system temp dir is "
+         "always allowed).", "desktop")
+
+# ---------------------------------------------------------------------------------------------------- logging
+register("RFH_HOOK_LOG", "", "Path of the JSONL hook event log; default: .rf/hook/hooks.jsonl.", "logging")

rf_harness/installer/__init__.py

@@ -0,0 +1 @@
+"""rf-harness installer: sets up the Robot Framework agent harness for coding agents (stdlib only)."""

rf_harness/installer/_assets.py

@@ -0,0 +1,73 @@
+"""Locate the plugin tree (skill, hooks, launcher, variants) that the installer copies.
+
+Search order:
+1. ``RF_HARNESS_ASSETS_DIR`` (tests, local experiments);
+2. a source checkout: ``<repo>/plugins/rf-harness`` next to ``src/rf_harness`` (the single source of truth);
+3. the wheel: ``rf_harness/_assets`` (built from ``plugins/rf-harness`` by hatch_build.py).
+
+Adapted from robotframework-agentskills' ``installer/src/rf_agentskills/_assets.py`` (same author, Apache-2.0).
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import os
+from collections.abc import Iterator
+from contextlib import ExitStack
+from importlib.resources import as_file, files
+from pathlib import Path
+
+ASSETS_ENV = "RF_HARNESS_ASSETS_DIR"
+_IGNORED = {"__pycache__", ".DS_Store"}
+_stack = ExitStack()
+atexit.register(_stack.close)
+
+
+class AssetsMissing(RuntimeError):
+    """The plugin tree could not be found."""
+
+
+def _valid(root: Path) -> bool:
+    return (root / ".claude-plugin" / "plugin.json").is_file()
+
+
+def source_checkout_root() -> Path | None:
+    """``plugins/rf-harness`` of the repository this package was imported from, if any."""
+    candidate = Path(__file__).resolve().parents[3] / "plugins" / "rf-harness"
+    return candidate if _valid(candidate) else None
+
+
+def plugin_root() -> Path:
+    env = os.environ.get(ASSETS_ENV)
+    if env:
+        root = Path(env).expanduser().resolve()
+        if not _valid(root):
+            raise AssetsMissing(f"{ASSETS_ENV}={env} has no .claude-plugin/plugin.json")
+        return root
+    checkout = source_checkout_root()
+    if checkout is not None:
+        return checkout
+    traversable = files("rf_harness").joinpath("_assets")
+    root = Path(_stack.enter_context(as_file(traversable)))  # type: ignore[arg-type]
+    if not _valid(root):
+        raise AssetsMissing("the bundled plugin assets (rf_harness/_assets) are missing; reinstall robotframework-harness")
+    return root
+
+
+def bundle_version(root: Path | None = None) -> str:
+    root = root or plugin_root()
+    data = json.loads((root / ".claude-plugin" / "plugin.json").read_text(encoding="utf-8"))
+    return str(data.get("version", "unknown"))
+
+
+def iter_files(base: Path) -> Iterator[Path]:
+    """Every shipped file under ``base`` (sorted, caches skipped)."""
+    if base.is_file():
+        yield base
+        return
+    if not base.is_dir():
+        return
+    for path in sorted(base.rglob("*")):
+        if path.is_file() and not (_IGNORED & set(path.parts)) and path.suffix != ".pyc":
+            yield path

rf_harness/installer/adapters/__init__.py

@@ -0,0 +1,37 @@
+"""Per-agent adapters for the v1 agents: Claude Code, Codex, GitHub Copilot CLI, VS Code (Copilot) and OpenCode.
+
+Cursor, Goose and Gemini CLI are out of v1 until they are verified live (design, Resolved Decisions).
+"""
+
+from __future__ import annotations
+
+from ._base import Adapter, ConfigOp, FileTarget, Options, Plan
+from .claude_code import ClaudeCodeAdapter
+from .codex import CodexAdapter
+from .copilot_cli import CopilotCliAdapter
+from .opencode import OpenCodeAdapter
+from .vscode import VSCodeAdapter
+
+ALL_ADAPTERS: tuple[type[Adapter], ...] = (
+    ClaudeCodeAdapter,
+    CodexAdapter,
+    CopilotCliAdapter,
+    VSCodeAdapter,
+    OpenCodeAdapter,
+)
+ALIASES = {"claude": "claude-code", "copilot": "copilot-cli", "code": "vscode", "vs-code": "vscode"}
+
+
+def all_names() -> tuple[str, ...]:
+    return tuple(cls.name for cls in ALL_ADAPTERS)
+
+
+def by_name(name: str) -> Adapter | None:
+    name = ALIASES.get(name, name)
+    for cls in ALL_ADAPTERS:
+        if cls.name == name:
+            return cls()
+    return None
+
+
+__all__ = ["ALL_ADAPTERS", "Adapter", "ConfigOp", "FileTarget", "Options", "Plan", "all_names", "by_name"]