@kestrel-agents/ruhroh 0.5.0-beta.0

package/dist/scenarios.d.ts

@@ -0,0 +1,61 @@
+import { type RuhrohContinuityLevel, type RuhrohRunAgentAdapterCapabilities } from "./adapters.js";
+export type RuhrohScenarioTier = "smoke" | "nightly" | "release";
+export type RuhrohScenarioKind = "real_user" | "contract_stress";
+export type RuhrohLoopStopPolicy = "goal_satisfied_or_max";
+export type RuhrohDriverMode = "build" | "plan" | "chat";
+export type RuhrohEvaluationMode = "agentic_goal_review";
+export type RuhrohScenarioVersion = "ruhroh_scenario_v1" | "ruhroh_scenario_v2";
+export interface RuhrohScenario {
+    version: RuhrohScenarioVersion;
+    id: string;
+    title: string;
+    tier: RuhrohScenarioTier;
+    kind: RuhrohScenarioKind;
+    userPrompt: string;
+    assets?: string[] | undefined;
+    driver?: {
+        adapter: string;
+        profileId?: string | undefined;
+        mode?: RuhrohDriverMode | undefined;
+        timeoutSeconds: number;
+        env?: Record<string, string> | undefined;
+        command?: string | undefined;
+        completionProtocol?: string | undefined;
+    };
+    run: {
+        mode?: RuhrohDriverMode | undefined;
+        timeoutSeconds: number;
+    };
+    requires: {
+        continuity: RuhrohContinuityLevel;
+        tools: string[];
+        network: boolean;
+    };
+    loop: {
+        defaultMaxIterations: number;
+        stopPolicy: RuhrohLoopStopPolicy;
+    };
+    evaluation: {
+        mode: RuhrohEvaluationMode;
+        scenarioContext: string[];
+        goalRubric: string[];
+        evidenceGuidance: string[];
+    };
+}
+export interface ValidateRuhrohScenarioOptions {
+    adapters?: Record<string, RuhrohRunAgentAdapterCapabilities> | undefined;
+}
+export interface RuhrohScenarioSource {
+    scenarioDir: string;
+    scenarioPath: string;
+    instructionPath?: string | undefined;
+    assetsDir?: string | undefined;
+}
+export declare function validateRuhrohScenario(scenario: RuhrohScenario, options?: ValidateRuhrohScenarioOptions): string[];
+export declare function getRuhrohScenarioById<TScenario extends {
+    id: string;
+}>(scenarios: TScenario[], id: string): TScenario | undefined;
+export declare function getRuhrohScenariosByTier<TScenario extends {
+    tier: RuhrohScenarioTier;
+}>(scenarios: TScenario[], tier: RuhrohScenarioTier): TScenario[];
+//# sourceMappingURL=scenarios.d.ts.map

package/dist/scenarios.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenarios.d.ts","sourceRoot":"","sources":["../src/scenarios.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,iCAAiC,EACvC,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AACjE,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,iBAAiB,CAAC;AACjE,MAAM,MAAM,oBAAoB,GAAG,uBAAuB,CAAC;AAC3D,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AACzD,MAAM,MAAM,oBAAoB,GAAG,qBAAqB,CAAC;AACzD,MAAM,MAAM,qBAAqB,GAAG,oBAAoB,GAAG,oBAAoB,CAAC;AAEhF,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,qBAAqB,CAAC;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,kBAAkB,CAAC;IACzB,IAAI,EAAE,kBAAkB,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC9B,MAAM,CAAC,EAAE;QACP,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC/B,IAAI,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;QACpC,cAAc,EAAE,MAAM,CAAC;QACvB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;QACzC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC7B,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;KACzC,CAAC;IACF,GAAG,EAAE;QACH,IAAI,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;QACpC,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,QAAQ,EAAE;QACR,UAAU,EAAE,qBAAqB,CAAC;QAClC,KAAK,EAAE,MAAM,EAAE,CAAC;QAChB,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC;IACF,IAAI,EAAE;QACJ,oBAAoB,EAAE,MAAM,CAAC;QAC7B,UAAU,EAAE,oBAAoB,CAAC;KAClC,CAAC;IACF,UAAU,EAAE;QACV,IAAI,EAAE,oBAAoB,CAAC;QAC3B,eAAe,EAAE,MAAM,EAAE,CAAC;QAC1B,UAAU,EAAE,MAAM,EAAE,CAAC;QACrB,gBAAgB,EAAE,MAAM,EAAE,CAAC;KAC5B,CAAC;CACH;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iCAAiC,CAAC,GAAG,SAAS,CAAC;CAC1E;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,cAAc,EACxB,OAAO,GAAE,6BAAkC,GAC1C,MAAM,EAAE,CA4DV;AAED,wBAAgB,qBAAqB,CAAC,SAAS,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EACpE,SAAS,EAAE,SAAS,EAAE,EACtB,EAAE,EAAE,MAAM,GACT,SAAS,GAAG,SAAS,CAEvB;AAED,wBAAgB,wBAAwB,CAAC,SAAS,SAAS;IAAE,IAAI,EAAE,kBAAkB,CAAA;CAAE,EACrF,SAAS,EAAE,SAAS,EAAE,EACtB,IAAI,EAAE,kBAAkB,GACvB,SAAS,EAAE,CAEb"}

package/dist/scenarios.js

@@ -0,0 +1,69 @@
+import { adapterSatisfiesRequirements, } from "./adapters.js";
+export function validateRuhrohScenario(scenario, options = {}) {
+    const errors = [];
+    if (scenario.version !== "ruhroh_scenario_v1" && scenario.version !== "ruhroh_scenario_v2") {
+        errors.push("version must be ruhroh_scenario_v1 or ruhroh_scenario_v2");
+    }
+    if (scenario.id.trim().length === 0) {
+        errors.push("id is required");
+    }
+    if (!/^[a-zA-Z0-9._-]+$/u.test(scenario.id)) {
+        errors.push(`id contains unsafe characters: ${scenario.id}`);
+    }
+    if (scenario.title.trim().length === 0) {
+        errors.push("title is required");
+    }
+    if (scenario.userPrompt.trim().length === 0) {
+        errors.push("userPrompt is required");
+    }
+    if (scenario.version === "ruhroh_scenario_v2" && scenario.driver !== undefined) {
+        errors.push("driver is not allowed in ruhroh_scenario_v2; choose adapters at runtime");
+    }
+    if (scenario.version !== "ruhroh_scenario_v2") {
+        if (scenario.driver === undefined || scenario.driver.adapter.trim().length === 0) {
+            errors.push("driver.adapter is required for legacy scenarios");
+        }
+        if ((scenario.driver?.timeoutSeconds ?? 0) <= 0) {
+            errors.push("driver.timeoutSeconds must be positive for legacy scenarios");
+        }
+    }
+    if (scenario.run.timeoutSeconds <= 0) {
+        errors.push("run.timeoutSeconds must be positive");
+    }
+    if (!["native_session", "workspace_plus_transcript", "workspace_only"].includes(scenario.requires.continuity)) {
+        errors.push("requires.continuity must be native_session, workspace_plus_transcript, or workspace_only");
+    }
+    if (scenario.requires.tools.some((tool) => tool.trim().length === 0)) {
+        errors.push("requires.tools entries must be non-empty");
+    }
+    const capabilities = scenario.driver?.adapter === undefined ? undefined : options.adapters?.[scenario.driver.adapter];
+    if (capabilities !== undefined) {
+        errors.push(...adapterSatisfiesRequirements(capabilities, scenario.requires));
+    }
+    if (scenario.loop.defaultMaxIterations <= 0) {
+        errors.push("loop.defaultMaxIterations must be positive");
+    }
+    if (scenario.loop.stopPolicy !== "goal_satisfied_or_max") {
+        errors.push("loop.stopPolicy must be goal_satisfied_or_max");
+    }
+    if (scenario.evaluation.mode !== "agentic_goal_review") {
+        errors.push("evaluation.mode must be agentic_goal_review");
+    }
+    if (scenario.evaluation.goalRubric.length === 0) {
+        errors.push("evaluation.goalRubric must include at least one criterion");
+    }
+    if (scenario.evaluation.scenarioContext.some((item) => item.trim().length === 0)) {
+        errors.push("evaluation.scenarioContext entries must be non-empty");
+    }
+    if (scenario.evaluation.evidenceGuidance.some((item) => item.trim().length === 0)) {
+        errors.push("evaluation.evidenceGuidance entries must be non-empty");
+    }
+    return errors;
+}
+export function getRuhrohScenarioById(scenarios, id) {
+    return scenarios.find((scenario) => scenario.id === id);
+}
+export function getRuhrohScenariosByTier(scenarios, tier) {
+    return scenarios.filter((scenario) => scenario.tier === tier);
+}
+//# sourceMappingURL=scenarios.js.map

package/dist/scenarios.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenarios.js","sourceRoot":"","sources":["../src/scenarios.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@kestrel-agents/ruhroh",
+  "version": "0.5.0-beta.0",
+  "description": "Real-User Harness for Repair-Oriented Harbor",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LumiCorp/ruhroh.git"
+  },
+  "homepage": "https://github.com/LumiCorp/ruhroh",
+  "bugs": {
+    "url": "https://github.com/LumiCorp/ruhroh/issues"
+  },
+  "keywords": [
+    "ruhroh",
+    "harbor",
+    "benchmark",
+    "agents",
+    "repair",
+    "typescript"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.js"
+    }
+  },
+  "bin": {
+    "ruhroh": "./dist/cli.js"
+  },
+  "files": [
+    "assets/**/*",
+    "dist",
+    "python/**/*.py",
+    "python/**/*.sh",
+    "scenarios/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "clean": "node --input-type=module -e \"import { rmSync } from 'node:fs'; rmSync('dist', { recursive: true, force: true });\"",
+    "build": "pnpm run clean && tsc -p tsconfig.json",
+    "prepare": "pnpm run build",
+    "test": "node --import tsx --test tests/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  },
+  "packageManager": "pnpm@9.12.3"
+}

package/python/ruhroh/__init__.py

@@ -0,0 +1,5 @@
+"""Package-owned Ruhroh Harbor runtime."""
+
+from .harbor_agent import RuhrohHarborAgent
+
+__all__ = ["RuhrohHarborAgent"]

package/python/ruhroh/harbor_agent.py

@@ -0,0 +1,345 @@
+from __future__ import annotations
+
+import base64
+import json
+import os
+import re
+import shlex
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+try:
+    from harbor.agents.installed.base import BaseInstalledAgent
+except ImportError:
+    class BaseInstalledAgent:  # type: ignore[no-redef]
+        async def exec_as_root(self, environment: Any, command: str, **kwargs: Any) -> Any:
+            raise RuntimeError("harbor is not installed")
+
+        async def exec_as_agent(self, environment: Any, command: str, **kwargs: Any) -> Any:
+            raise RuntimeError("harbor is not installed")
+
+
+RUHROH_ADAPTER = "ruhroh-harbor"
+RUHROH_DATASET = "ruhroh@local"
+RUHROH_AGENT_NAME = "ruhroh-harbor"
+RUHROH_RESULT_RE = re.compile(r"RUHROH_RESULT_JSON_BASE64:(?P<payload>[A-Za-z0-9+/=]+)")
+
+
+class RuhrohHarborAgent(BaseInstalledAgent):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super_init = getattr(super(), "__init__", None)
+        if callable(super_init):
+            try:
+                super_init(*args, **kwargs)
+            except TypeError:
+                super_init()
+        self.logs_dir = kwargs.get("logs_dir")
+        self.model_name = kwargs.get("model_name")
+        self.max_iterations = kwargs.get("max_iterations")
+
+    @staticmethod
+    def name() -> str:
+        return RUHROH_AGENT_NAME
+
+    async def install(self, environment: Any) -> None:
+        runtime_root = Path(__file__).parent
+        await self._exec_as_root(environment, "mkdir -p /installed-agent && chmod 755 /installed-agent")
+        for source, destination in {
+            runtime_root / "loop_controller.py": "/installed-agent/ruhroh_loop_controller.py",
+            runtime_root / "setup.sh": "/installed-agent/install-agent.sh",
+        }.items():
+            await upload_file_to_environment(environment, source, destination)
+        await write_text_to_environment(self, environment, "/installed-agent/setup-env.sh", harbor_env_setup_script())
+        await self._exec_as_root(
+            environment,
+            "chmod a+r /installed-agent/ruhroh_loop_controller.py "
+            "&& chmod +x /installed-agent/install-agent.sh "
+            "&& . /installed-agent/setup-env.sh "
+            "&& /installed-agent/install-agent.sh",
+            timeout_sec=harbor_install_timeout_sec(),
+        )
+
+    async def run(self, instruction: str, environment: Any, context: Any) -> None:
+        started_at = time.monotonic()
+        scenario_id = harbor_task_id(context, getattr(self, "logs_dir", None))
+        encoded = base64.b64encode(instruction.encode("utf-8")).decode("ascii")
+        max_iterations = resolve_max_iterations(getattr(self, "max_iterations", None))
+        env_file = create_run_env_file(max_iterations)
+        command = (
+            "RUHROH_ENV_FILE=/installed-agent/ruhroh-loop-env.json "
+            "python3 /installed-agent/ruhroh_loop_controller.py "
+            f"--instruction-base64 {shlex.quote(encoded)} "
+            f"--scenario-id {shlex.quote(scenario_id)} "
+            f"--max-iterations {shlex.quote(str(max_iterations))}"
+        )
+        wrapped = (
+            f"{command}; "
+            "__ruhroh_status=$?; "
+            "printf '\\nRUHROH_AGENT_EXIT_CODE:%s\\n' \"$__ruhroh_status\"; "
+            "exit 0"
+        )
+        try:
+            await upload_file_to_environment(environment, env_file, "/installed-agent/ruhroh-loop-env.json")
+            await self._exec_as_root(environment, "chmod 600 /installed-agent/ruhroh-loop-env.json")
+            result = await self._exec_as_root(environment, wrapped, timeout_sec=resolve_agent_timeout_sec(scenario_id))
+        finally:
+            env_file.unlink(missing_ok=True)
+            await persist_ruhroh_debug_artifacts(environment, getattr(self, "logs_dir", None))
+        write_command_result_artifact(context, result, getattr(self, "logs_dir", None))
+        parsed = parse_ruhroh_result(command_output_text(result)) or await read_ruhroh_result(self, environment)
+        if parsed is None:
+            parsed = {
+                "version": "ruhroh_loop_result_v1",
+                "adapter": RUHROH_ADAPTER,
+                "dataset": RUHROH_DATASET,
+                "scenarioId": scenario_id,
+                "task_id": scenario_id,
+                "status": "failed",
+                "failure_kind": "cli_command_failed",
+                "failureBucket": "cli_command_failed",
+                "duration_ms": round((time.monotonic() - started_at) * 1000),
+                "stoppedReason": "missing_result_marker",
+            }
+            write_ruhroh_result_artifact(context, parsed, getattr(self, "logs_dir", None))
+            raise RuntimeError("Ruhroh run did not emit a structured result marker.")
+        parsed.setdefault("adapter", RUHROH_ADAPTER)
+        parsed.setdefault("dataset", RUHROH_DATASET)
+        parsed.setdefault("task_id", scenario_id)
+        parsed.setdefault("duration_ms", round((time.monotonic() - started_at) * 1000))
+        write_ruhroh_result_artifact(context, parsed, getattr(self, "logs_dir", None))
+
+    async def _exec_as_root(self, environment: Any, command: str, **kwargs: Any) -> Any:
+        return await maybe_await(self.exec_as_root(environment, command=command, **without_none_values(kwargs)))
+
+
+def harbor_env_setup_script() -> str:
+    return "\n".join(
+        [
+            f"export RUHROH_RESULT_ADAPTER={shlex.quote(RUHROH_ADAPTER)}",
+            f"export RUHROH_RESULT_DATASET={shlex.quote(RUHROH_DATASET)}",
+        ]
+    ) + "\n"
+
+
+def build_run_env_values(max_iterations: int) -> dict[str, str]:
+    env = {
+        "RUHROH_RESULT_ADAPTER": RUHROH_ADAPTER,
+        "RUHROH_RESULT_DATASET": RUHROH_DATASET,
+        "RUHROH_MAX_ITERATIONS": str(max_iterations),
+    }
+    for key in (
+        "RUHROH_EVAL_RESULT_FIXTURE",
+        "RUHROH_EVAL_RESULT_FIXTURE_PATH",
+        "RUHROH_ITERATION_TIMEOUT_SEC",
+        "RUHROH_AGENT_TIMEOUT_SEC",
+        "RUHROH_INSTALL_TIMEOUT_SEC",
+        "RUHROH_RUN_AGENT_ADAPTER",
+        "RUHROH_RUN_AGENT_ADAPTER",
+        "RUHROH_RUN_AGENT_COMMAND",
+        "RUHROH_RUN_AGENT_COMPLETION_PROTOCOL",
+        "RUHROH_EVAL_COMMAND",
+    ):
+        value = os.environ.get(key)
+        if value is not None:
+            env[key] = value
+    return env
+
+
+def create_run_env_file(max_iterations: int) -> Path:
+    fd, raw_path = tempfile.mkstemp(prefix="ruhroh-env-", suffix=".json")
+    path = Path(raw_path)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            json.dump(build_run_env_values(max_iterations), handle, sort_keys=True)
+            handle.write("\n")
+    except Exception:
+        path.unlink(missing_ok=True)
+        raise
+    return path
+
+
+async def upload_file_to_environment(environment: Any, source: Path, destination: str) -> None:
+    for method_name in ("copy_to", "copy_to_container", "upload_file", "upload"):
+        method = getattr(environment, method_name, None)
+        if method is None:
+            continue
+        for args in (
+            (source, destination),
+            (str(source), destination),
+            (source, Path(destination)),
+            (str(source), Path(destination)),
+        ):
+            try:
+                await maybe_await(method(*args))
+                return
+            except TypeError:
+                continue
+    raise RuntimeError(f"Harbor environment cannot upload {source} to {destination}.")
+
+
+async def write_text_to_environment(agent: RuhrohHarborAgent, environment: Any, path: str, content: str) -> None:
+    parent = str(Path(path).parent)
+    await agent._exec_as_root(
+        environment,
+        f"mkdir -p {shlex.quote(parent)} && printf %s {shlex.quote(content)} > {shlex.quote(path)}",
+    )
+
+
+async def read_ruhroh_result(agent: RuhrohHarborAgent, environment: Any) -> dict[str, Any] | None:
+    result = await agent._exec_as_root(environment, "cat /installed-agent/ruhroh-loop-result.json 2>/dev/null || true")
+    text = command_output_text(result)
+    if not text.strip():
+        return None
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError:
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+async def persist_ruhroh_debug_artifacts(environment: Any, logs_dir: Any) -> list[Path]:
+    if not isinstance(logs_dir, (str, Path)):
+        return []
+    target_dir = Path(logs_dir)
+    target_dir.mkdir(parents=True, exist_ok=True)
+    copied: list[Path] = []
+    for source, name in (
+        ("/installed-agent/ruhroh-loop-result.json", "ruhroh-loop-result.json"),
+        ("/installed-agent/ruhroh-loop-iterations.jsonl", "ruhroh-loop-iterations.jsonl"),
+        ("/installed-agent/ruhroh-loop-journey.json", "ruhroh-loop-journey.json"),
+        ("/installed-agent/ruhroh-loop-eval.json", "ruhroh-loop-eval.json"),
+        ("/installed-agent/ruhroh-loop-bridge.jsonl", "ruhroh-loop-bridge.jsonl"),
+        ("/installed-agent/ruhroh-workspace.tar.gz", "ruhroh-workspace.tar.gz"),
+        ("/installed-agent/ruhroh-loop-events.tar.gz", "ruhroh-loop-events.tar.gz"),
+        ("/installed-agent/ruhroh-loop-transcripts.tar.gz", "ruhroh-loop-transcripts.tar.gz"),
+    ):
+        destination = target_dir / name
+        try:
+            await maybe_await(environment.download_file(source, destination))
+        except Exception:
+            continue
+        copied.append(destination)
+    return copied
+
+
+def write_ruhroh_result_artifact(context: Any, result: dict[str, Any], logs_dir: Any) -> Path | None:
+    target_dir = context_logs_dir(context, logs_dir)
+    if target_dir is None:
+        return None
+    target_dir.mkdir(parents=True, exist_ok=True)
+    task_id = str(result.get("task_id") or result.get("scenarioId") or "unknown")
+    path = target_dir / f"ruhroh-{safe_artifact_name(task_id)}.json"
+    path.write_text(json.dumps(result, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return path
+
+
+def write_command_result_artifact(context: Any, result: Any, logs_dir: Any) -> Path | None:
+    target_dir = context_logs_dir(context, logs_dir)
+    if target_dir is None:
+        return None
+    target_dir.mkdir(parents=True, exist_ok=True)
+    path = target_dir / "ruhroh-agent-command-output.log"
+    path.write_text(command_output_text(result), encoding="utf-8")
+    return path
+
+
+def context_logs_dir(context: Any, logs_dir: Any) -> Path | None:
+    for candidate in (
+        getattr(context, "agent_logs_dir", None),
+        getattr(context, "logs_dir", None),
+        logs_dir,
+    ):
+        if isinstance(candidate, (str, Path)):
+            return Path(candidate)
+    return None
+
+
+def parse_ruhroh_result(text: str) -> dict[str, Any] | None:
+    match = RUHROH_RESULT_RE.search(text)
+    if match is None:
+        return None
+    try:
+        parsed = json.loads(base64.b64decode(match.group("payload")).decode("utf-8"))
+    except Exception:
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def command_output_text(result: Any) -> str:
+    parts: list[str] = []
+    for attr in ("stdout", "stderr", "output"):
+        value = getattr(result, attr, None)
+        if isinstance(value, bytes):
+            parts.append(value.decode("utf-8", errors="replace"))
+        elif isinstance(value, str):
+            parts.append(value)
+    return "\n".join(part for part in parts if part)
+
+
+def harbor_task_id(context: Any, logs_dir: Any) -> str:
+    for attr in ("task_id", "task_name", "name"):
+        value = getattr(context, attr, None)
+        if isinstance(value, str) and value.strip():
+            return safe_task_id(value)
+    if isinstance(logs_dir, (str, Path)):
+        parent = Path(logs_dir).parent.name
+        if "__" in parent:
+            return safe_task_id(parent.split("__", 1)[0])
+    return "unknown"
+
+
+def resolve_max_iterations(value: Any) -> int:
+    if value is not None:
+        try:
+            return max(1, int(value))
+        except (TypeError, ValueError):
+            pass
+    raw = os.environ.get("RUHROH_MAX_ITERATIONS")
+    if raw is not None:
+        try:
+            return max(1, int(raw))
+        except ValueError:
+            pass
+    return 3
+
+
+def resolve_agent_timeout_sec(scenario_id: str) -> int:
+    del scenario_id
+    raw = os.environ.get("RUHROH_AGENT_TIMEOUT_SEC")
+    if raw is not None:
+        try:
+            return max(1, int(raw))
+        except ValueError:
+            pass
+    return 3600
+
+
+def harbor_install_timeout_sec() -> int:
+    raw = os.environ.get("RUHROH_INSTALL_TIMEOUT_SEC")
+    if raw is not None:
+        try:
+            return max(1, int(raw))
+        except ValueError:
+            pass
+    return 900
+
+
+def safe_task_id(value: str) -> str:
+    stripped = value.strip().split("/")[-1]
+    return safe_artifact_name(stripped) or "unknown"
+
+
+def safe_artifact_name(value: str) -> str:
+    return "".join(char if char.isalnum() or char in "-_." else "-" for char in value).strip("-_.")
+
+
+def without_none_values(value: dict[str, Any]) -> dict[str, Any]:
+    return {key: item for key, item in value.items() if item is not None}
+
+
+async def maybe_await(value: Any) -> Any:
+    if hasattr(value, "__await__"):
+        return await value
+    return value