hexharness 1.0.0__py3-none-any.whl

hexharness/__init__.py

@@ -0,0 +1,7 @@
+"""HexHarness — agentic pentesting harness.
+
+The value is not the agent loop (that is standard) but the domain CONTROL PLANE:
+scope, ROE, evidence, approvals, budget. See hexharness.control.
+"""
+
+__version__ = "0.1.0"

hexharness/__main__.py

@@ -0,0 +1,214 @@
+"""Thin CLI.
+
+    # run a task against an existing engagement
+    python -m hexharness run "Look up CWE-79" --engagement engagements/example.engagement.yaml
+
+    # describe scope in natural language; the agent drafts the engagement, you confirm,
+    # then it runs the first task under it — all in one flow
+    python -m hexharness init "External test of acme.example and 203.0.113.0/24, \
+        exclude vpn.acme.example, enumeration only, business hours" --task "Resolve www.acme.example"
+
+`run` is the default when no subcommand is given (back-compat). The in-process entry
+point; the client/daemon WS split is a separate path.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import re
+import sys
+from pathlib import Path
+
+from hexharness.control.hitl import CLIApprover
+from hexharness.control.policy import Autonomy, Mode, Phase
+from hexharness.control.secrets import GetpassSecretRequester
+from hexharness.engine import Engine
+
+_DRAFT_SYSTEM = (
+    "You are setting up a new pentest engagement. Read the operator's natural-language "
+    "brief and call the engagement_draft tool EXACTLY ONCE with a structured spec: "
+    "scope.domains, scope.cidrs, scope.exclusions, roe.max_risk/max_autonomy/max_phase, "
+    "optional time windows and budget. Infer a short engagement name. Do not invent scope "
+    "the operator did not give. After drafting, briefly summarize what you proposed."
+)
+
+_PATH_RE = re.compile(r"Draft written to (\S+) \(")
+
+
+def _build_mode(args) -> Mode:
+    return Mode(autonomy=Autonomy[args.autonomy.upper()], phase=Phase[args.phase.upper()])
+
+
+async def _run(args) -> str:
+    from hexharness.providers.anthropic import AnthropicProvider
+
+    provider = AnthropicProvider()
+    engine = Engine.from_engagement(
+        args.engagement, provider=provider, requested_mode=_build_mode(args),
+        approver=CLIApprover(), secret_requester=GetpassSecretRequester(), kill_trigger_file=args.kill_file,
+    )
+    engine.kill_switch.install_signal_handler()
+    engine.kill_switch.start_file_watch()
+    try:
+        return await engine.loop(provider=provider, model=args.model).run(args.prompt)
+    finally:
+        engine.close_sandbox()  # remove the session container; /workspace persists
+
+
+async def _init(args) -> str:
+    from hexharness.providers.anthropic import AnthropicProvider
+
+    provider = AnthropicProvider()
+    # Locked bootstrap engine: empty scope, report-only, can ONLY draft an engagement.
+    boot = Engine.bootstrap(out_dir=args.out, approver=CLIApprover())
+    out = await boot.loop(provider=provider, model=args.model).run(args.brief)
+    print(out)
+
+    m = _PATH_RE.search(out)
+    if not m:
+        return "No draft was produced. Rephrase the brief and try again."
+    path = Path(m.group(1))
+
+    # HUMAN gate: the operator approves the ROE before anything runs under it (invariant #4).
+    print("\n" + "=" * 60)
+    print(path.read_text())
+    print("=" * 60)
+    try:
+        answer = input(f"Activate {path.name} and run under it? [y/N] ").strip().lower()
+    except EOFError:
+        answer = ""
+    if answer not in ("y", "yes"):
+        return f"Not activated. Draft left inert at {path}."
+
+    if not args.task:
+        return f"Activated: {path}. Run a task with:\n  python -m hexharness run \"<task>\" --engagement {path}"
+
+    engine = Engine.from_engagement(
+        path, provider=provider, requested_mode=_build_mode(args),
+        approver=CLIApprover(), secret_requester=GetpassSecretRequester(), kill_trigger_file=args.kill_file,
+    )
+    engine.kill_switch.install_signal_handler()
+    engine.kill_switch.start_file_watch()
+    return await engine.loop(provider=provider, model=args.model).run(args.task)
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="hexharness")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    def _common(sp):
+        sp.add_argument("--autonomy", default="interactive", choices=[a.name.lower() for a in Autonomy])
+        sp.add_argument("--phase", default="recon", choices=[ph.name.lower() for ph in Phase])
+        sp.add_argument("--model", default=None)
+        sp.add_argument("--kill-file", default=None,
+                        help="touch this path from anywhere to trigger the out-of-band kill switch")
+
+    r = sub.add_parser("run", help="run a task against an existing engagement")
+    r.add_argument("prompt")
+    r.add_argument("--engagement", default="engagements/example.engagement.yaml")
+    _common(r)
+
+    i = sub.add_parser("init", help="draft a new engagement from a natural-language brief, then run it")
+    i.add_argument("brief", help="natural-language scope/ROE description")
+    i.add_argument("--task", default=None, help="first task to run once the engagement is activated")
+    i.add_argument("--out", default="engagements", help="directory to write the engagement file into")
+    _common(i)
+
+    t = sub.add_parser("tui", help="launch the terminal UI")
+    # No default: launched without --engagement, the TUI starts blank (no scope, no resumed
+    # history) and the operator configures a new engagement by describing the target.
+    t.add_argument("--engagement", default=None)
+
+    sub.add_parser("build-image", help="build the HexHarness sandbox image (Kali + tools)")
+
+    v = sub.add_parser("verify", help="verify a session's audit log (SHA-256 hash chain) for tampering")
+    v.add_argument("--engagement", default="engagements/example.engagement.yaml")
+
+    rp = sub.add_parser("report", help="render a client report from an engagement's confirmed findings")
+    rp.add_argument("--engagement", default="engagements/example.engagement.yaml")
+    rp.add_argument("--out", default=None, help="output path; extension picks the format (.html/.pdf/.docx/.md)")
+    rp.add_argument("--template", default=None, help="template path (defaults to the bundled HTML template)")
+    rp.add_argument("--no-generative", action="store_true", help="skip the LLM exec-summary/risk-narrative")
+    rp.add_argument("--model", default=None)
+    return p
+
+
+def _verify(args) -> str:
+    from hexharness import session as sess
+    from hexharness.engagement import Engagement
+    from hexharness.events.store import EventStore, HashChainError
+
+    name = Engagement.load(args.engagement).name
+    db = sess.db_path(name)
+    if not db.exists():
+        return f"no session log for '{name}' at {db} — nothing to verify."
+    store = EventStore(str(db))
+    n = len(store.all())
+    try:
+        store.verify()
+    except HashChainError as exc:
+        return f"TAMPERED: audit log for '{name}' failed verification at — {exc} ({n} events)"
+    return f"OK: audit log for '{name}' is intact — {n} events, hash chain verified."
+
+
+async def _report(args) -> str:
+    from hexharness import session as sess
+    from hexharness.engagement import Engagement
+    from hexharness.evidence.store import EvidenceStore
+    from hexharness.events.store import EventStore
+    from hexharness.reporting.build import build_report
+
+    eng = Engagement.load(args.engagement)
+    db = sess.db_path(eng.name)
+    if not db.exists():
+        return f"no session for '{eng.name}' at {db} — run a task first so there are findings."
+    events = EventStore(str(db))
+    evidence = EvidenceStore(str(db), events=events)
+    provider = None
+    if not args.no_generative:
+        from hexharness.providers.anthropic import AnthropicProvider
+
+        provider = AnthropicProvider()
+    out = args.out or str(sess.session_dir(eng.name) / f"report-{eng.name}.html")
+    path = await build_report(eng, evidence, out, provider=provider,
+                              template=args.template, model_name=args.model)
+    return f"report written to {path} ({len(evidence.confirmed())} confirmed findings)."
+
+
+def main() -> int:
+    argv = sys.argv[1:]
+    _subcommands = ("run", "init", "tui", "build-image", "verify", "report", "-h", "--help")
+    if argv and argv[0] not in _subcommands:
+        argv = ["run", *argv]  # back-compat: bare prompt => run
+    args = _parser().parse_args(argv)
+
+    if args.cmd == "verify":
+        print(_verify(args))
+        return 0
+
+    if args.cmd == "build-image":
+        from hexharness.sandbox.image import DEFAULT_SANDBOX_IMAGE, build_image
+
+        ok, out = asyncio.run(build_image(DEFAULT_SANDBOX_IMAGE, on_output=print))
+        print(f"\n{'built' if ok else 'failed'}: {DEFAULT_SANDBOX_IMAGE}")
+        return 0 if ok else 1
+
+    if args.cmd == "tui":
+        from hexharness.tui.app import HexTUI  # textual only imported here
+
+        HexTUI(engagement=args.engagement).run()
+        return 0
+
+    coro = {"init": _init, "report": _report}.get(args.cmd, _run)(args)
+    try:
+        print(asyncio.run(coro))
+        return 0
+    except KeyboardInterrupt:
+        return 130
+    except Exception as exc:  # noqa: BLE001
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

hexharness/agent/__init__.py

@@ -0,0 +1,4 @@
+from hexharness.agent.context import ExecContext
+from hexharness.agent.loop import AgentLoop
+
+__all__ = ["ExecContext", "AgentLoop"]

hexharness/agent/context.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+from hexharness.control.policy import Mode
+
+
+@dataclass(frozen=True)
+class ExecContext:
+    """Per-subagent execution context. The mode lives HERE, not as a global — each
+    subagent (Recon, WebApp, ...) can run at a different autonomy/phase under the same
+    ROE ceiling."""
+
+    engagement_id: str
+    subagent_id: str
+    mode: Mode
+    # Pinned clock for deterministic ROE time-window checks in tests; None = real now.
+    now: datetime | None = None

hexharness/agent/loop.py

@@ -0,0 +1,203 @@
+"""Single-agent loop. The orchestrator-worker split (phase 8) composes many of these;
+each still routes every tool call through the same chokepoint.
+
+INVARIANT #1 lives here: the only place a tool is executed is `_execute`, and it is
+reached only after `control.authorize(...)` returned ALLOW. There is no other path.
+"""
+from __future__ import annotations
+
+from hexharness.agent.context import ExecContext
+from hexharness.control.plane import ControlPlane
+from hexharness.control.pricing import usd_cost
+from hexharness.events.store import EventStore
+from hexharness.events.types import EventType
+from hexharness.providers.base import LLMProvider
+from hexharness.providers.types import (
+    Message,
+    Role,
+    StopReason,
+    TextBlock,
+    ToolResultBlock,
+)
+from hexharness.tools.registry import ToolRegistry
+
+DEFAULT_SYSTEM = (
+    "You are a pentesting assistant operating inside HexHarness. Every tool call is "
+    "mediated by a control plane that enforces scope, rules of engagement, and human "
+    "approval. If a tool is denied, respect it and adapt — do not retry a denied action.\n\n"
+    "exec_command runs each invocation in a SEPARATE, EPHEMERAL Docker container (docker "
+    "run --rm): nothing you install or change in one call survives to the next. Only files "
+    "under /workspace persist (it is mounted from the host and shared with file_read/"
+    "file_write). So do NOT try to `pip install`/`apt-get install` a tool in one call and "
+    "use it in another — the second container starts clean. If you need a tool that is not "
+    "already in the image, install it and use it within the SAME exec_command call (chain "
+    "with 'sh -c'), or write outputs to /workspace. For driving a web browser (navigation, "
+    "clicks, screenshots) use the dedicated `browser` tool — it runs Playwright on the host, "
+    "not in the sandbox, so never install Playwright via exec_command."
+)
+
+
+class AgentLoop:
+    def __init__(
+        self,
+        *,
+        provider: LLMProvider,
+        control: ControlPlane,
+        registry: ToolRegistry,
+        events: EventStore,
+        ctx: ExecContext,
+        system: str = DEFAULT_SYSTEM,
+        model: str | None = None,
+        max_iterations: int = 12,
+        kill_switch=None,
+        on_text=None,
+        on_thinking=None,
+        compact_threshold: float = 0.8,
+    ):
+        self.provider = provider
+        self.control = control
+        self.registry = registry
+        self.events = events
+        self.ctx = ctx
+        self.system = system
+        self.model = model
+        self.max_iterations = max_iterations
+        self.kill_switch = kill_switch
+        self.on_text = on_text
+        self.on_thinking = on_thinking
+        self.compact_threshold = compact_threshold
+        # Persistent conversation across run() calls, so the model remembers prior turns
+        # and compaction has something to compact.
+        self.conversation: list[Message] = []
+        self.last_input_tokens = 0
+
+    def _model_id(self) -> str:
+        return self.model or getattr(self.provider, "default_model", "") or ""
+
+    def context_ratio(self) -> float:
+        """Fraction of the model's context window used by the last call (for the UI)."""
+        from hexharness.providers.context_window import usage_ratio
+
+        return usage_ratio(self._model_id(), self.last_input_tokens)
+
+    async def compact(self, *, reason: str = "manual") -> int:
+        """Summarize the conversation into durable notes and replace the history with a
+        single summary message. Returns how many messages were collapsed."""
+        if len(self.conversation) < 2:
+            return 0
+        before = len(self.conversation)
+        summary_req = [
+            *self.conversation,
+            Message.user_text(
+                "Compact this pentest session into terse durable notes: objectives, scope, "
+                "confirmed/candidate findings, decisions, and open threads. Preserve facts "
+                "needed to continue; drop chatter."
+            ),
+        ]
+        resp = await self.provider.complete(
+            summary_req, system="You compact a pentest session transcript into durable notes.",
+            model=self.model,
+        )
+        self.conversation = [Message.user_text(f"[compacted session summary]\n{resp.text()}")]
+        self.last_input_tokens = resp.usage.input_tokens
+        await self.events.append(
+            EventType.CONTEXT_COMPACTED,
+            {"reason": reason, "messages_before": before, "messages_after": len(self.conversation)},
+        )
+        return before - len(self.conversation)
+
+    def _system_with_scope(self) -> str:
+        """System prompt + the live engagement boundary (scope, ROE, mode) so the model
+        knows where it may act and does not waste turns on auto-denied targets."""
+        scope = self.control.scope_guard.scope
+        roe = self.control.roe
+        lines = [self.system, "", "## Engagement boundary (ENFORCED — out-of-scope or over-ROE actions are auto-denied)"]
+        if scope.domains:
+            lines.append("In-scope domains: " + ", ".join(scope.domains))
+        if scope.cidrs:
+            lines.append("In-scope CIDRs: " + ", ".join(scope.cidrs))
+        if scope.exclusions:
+            lines.append("EXCLUDED (never touch): " + ", ".join(scope.exclusions))
+        if not scope.domains and not scope.cidrs:
+            lines.append("In-scope targets: (none set — scope-sensitive tools will be denied)")
+        lines.append(
+            f"ROE ceiling: max_risk={roe.max_risk.name.lower()}, "
+            f"max_autonomy={roe.max_autonomy.name.lower()}, max_phase={roe.max_phase.name.lower()}"
+        )
+        lines.append(
+            f"Current mode: {self.ctx.mode.autonomy.name.lower()}/{self.ctx.mode.phase.name.lower()}. "
+            "Act only within this scope and ROE; do not attempt targets or risk levels beyond them."
+        )
+        return "\n".join(lines)
+
+    async def run(self, user_prompt: str) -> str:
+        from hexharness.providers.context_window import should_compact
+
+        await self.events.append(EventType.USER_PROMPT, {"text": user_prompt, "subagent": self.ctx.subagent_id})
+        # Auto-compact BEFORE adding the new turn if the last call was near the window.
+        if should_compact(self._model_id(), self.last_input_tokens, self.compact_threshold):
+            await self.compact(reason="auto")
+        self.conversation.append(Message.user_text(user_prompt))
+        messages = self.conversation
+        system = self._system_with_scope()  # rebuilt each turn so scope/ROE changes show up
+
+        for _ in range(self.max_iterations):
+            if self.kill_switch and self.kill_switch.triggered:
+                return f"[killed: {self.kill_switch.reason}]"
+
+            resp = await self.provider.complete(
+                messages, tools=self.registry.specs(), system=system, model=self.model,
+                on_text=self.on_text, on_thinking=self.on_thinking,
+            )
+            self.last_input_tokens = resp.usage.input_tokens
+            self.control.budget.add_tokens(resp.usage.total_tokens)
+            self.control.budget.add_usd(usd_cost(resp.model or self.model or "", resp.usage))
+            await self.events.append(
+                EventType.MODEL_RESPONSE,
+                {"stop_reason": resp.stop_reason.value, "tokens": resp.usage.total_tokens},
+            )
+            await self.events.append(
+                EventType.BUDGET_UPDATED,
+                {"tokens_used": self.control.budget.tokens_used, "usd_used": round(self.control.budget.usd_used, 4)},
+            )
+            messages.append(Message(role=Role.ASSISTANT, content=resp.content))
+
+            tool_uses = resp.tool_uses()
+            if resp.stop_reason is not StopReason.TOOL_USE or not tool_uses:
+                return resp.text()
+
+            results: list[ToolResultBlock] = []
+            for tu in tool_uses:
+                results.append(await self._handle_tool_use(tu))
+            messages.append(Message(role=Role.USER, content=results))  # type: ignore[arg-type]
+
+        return "[max iterations reached]"
+
+    async def _handle_tool_use(self, tu) -> ToolResultBlock:
+        tool = self.registry.get(tu.name)
+        if tool is None:
+            # Fail-closed: unknown tool is never executed.
+            return ToolResultBlock(tool_use_id=tu.id, content=f"unknown tool: {tu.name}", is_error=True)
+
+        # THE chokepoint. No branch executes the tool without passing here first.
+        decision = await self.control.authorize(self.ctx, tool, tu.input)
+        if not decision.allowed:
+            return ToolResultBlock(
+                tool_use_id=tu.id,
+                content=f"DENIED by {decision.gate}: {decision.reason}",
+                is_error=True,
+            )
+        return await self._execute(tool, tu)
+
+    async def _execute(self, tool, tu) -> ToolResultBlock:
+        await self.events.append(EventType.TOOL_STARTED, {"tool": tool.name, "input": tu.input})
+        try:
+            output = await tool.run(tu.input)
+            # ponytail: truncate the copy stored in the event/shown in the TUI; the model
+            # still gets the full output via the ToolResultBlock below.
+            await self.events.append(EventType.TOOL_FINISHED,
+                                     {"tool": tool.name, "ok": True, "output": output[:2000]})
+            return ToolResultBlock(tool_use_id=tu.id, content=output)
+        except Exception as exc:  # noqa: BLE001
+            await self.events.append(EventType.TOOL_FINISHED, {"tool": tool.name, "ok": False, "error": str(exc)})
+            return ToolResultBlock(tool_use_id=tu.id, content=f"tool error: {exc}", is_error=True)

hexharness/agent/orchestrator.py

@@ -0,0 +1,143 @@
+"""Orchestrator-worker coordination (phase 8, part 2).
+
+The orchestrator LLM plans an objective into a list of ``{role, task}`` subtasks.
+Each subtask is handed to a worker that runs its OWN AgentLoop with:
+
+  - an ISOLATED ExecContext (distinct subagent_id, the role's phase),
+  - its OWN message history (AgentLoop.run builds a fresh list — workers never
+    share messages, that is the context isolation),
+  - a registry filtered to the role's tools.
+
+Workers reuse the PARENT control plane, registry source, and event store: every
+worker tool call still routes through ControlPlane.authorize with its own ctx —
+the orchestrator never bypasses the chokepoint. Results are aggregated and
+returned; delegation start/finish is traced on the event log.
+"""
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from typing import Any
+
+from hexharness.agent.context import ExecContext
+from hexharness.agent.loop import AgentLoop
+from hexharness.agent.subagents import ROLES, Role
+from hexharness.control.plane import ControlPlane
+from hexharness.control.policy import Autonomy, Mode
+from hexharness.events.store import EventStore
+from hexharness.events.types import EventType
+from hexharness.providers.base import LLMProvider
+from hexharness.tools.registry import ToolRegistry
+
+ORCHESTRATOR_SYSTEM = (
+    "You are the lead pentest orchestrator. Decompose the objective into subtasks for "
+    "specialist workers. Reply with ONLY a JSON array of objects "
+    '{"role": <one of: ' + ", ".join(ROLES) + '>, "task": <imperative instruction>}. '
+    "No prose, no code fences."
+)
+
+
+class Orchestrator:
+    def __init__(
+        self,
+        *,
+        provider: LLMProvider,
+        control: ControlPlane,
+        registry: ToolRegistry,
+        events: EventStore,
+        engagement_id: str,
+        model: str | None = None,
+        autonomy: Autonomy = Autonomy.INTERACTIVE,
+        max_iterations: int = 12,
+        kill_switch: Any = None,
+        # Per-worker provider. Default: reuse the planning provider. A factory lets a
+        # caller (or test) give each worker an independent scripted provider.
+        make_worker_provider: Callable[[Role], LLMProvider] | None = None,
+    ):
+        self.provider = provider
+        self.control = control
+        self.registry = registry
+        self.events = events
+        self.engagement_id = engagement_id
+        self.model = model
+        self.autonomy = autonomy
+        self.max_iterations = max_iterations
+        self.kill_switch = kill_switch
+        self._make_worker_provider = make_worker_provider
+
+    async def run(self, objective: str) -> dict[str, Any]:
+        plan = await self._plan(objective)
+        workers: list[dict[str, Any]] = []
+        for i, item in enumerate(plan):
+            workers.append(await self._delegate(ROLES[item["role"]], item["task"], i))
+        return {"objective": objective, "plan": plan, "workers": workers}
+
+    async def _plan(self, objective: str) -> list[dict[str, str]]:
+        resp = await self.provider.complete(
+            [self._user(objective)], system=ORCHESTRATOR_SYSTEM, model=self.model
+        )
+        self.control.budget.add_tokens(resp.usage.total_tokens)
+        return _parse_plan(resp.text())
+
+    async def _delegate(self, role: Role, task: str, i: int) -> dict[str, Any]:
+        subagent_id = f"{role.name}-{i}"  # distinct per worker => isolated identity
+        # Invariant #4: active mode = min(requested, ROE ceiling) — clamp BOTH axes,
+        # not just autonomy, so a role's phase can never exceed the engagement ceiling.
+        mode = self.control.roe.clamp_mode(Mode(autonomy=self.autonomy, phase=role.default_phase))
+        ctx = ExecContext(engagement_id=self.engagement_id, subagent_id=subagent_id, mode=mode)
+        await self.events.append(
+            EventType.DELEGATION_STARTED,
+            {"subagent": subagent_id, "role": role.name, "phase": mode.phase.name, "task": task},
+        )
+        loop = AgentLoop(
+            provider=self._worker_provider(role),
+            control=self.control,  # SHARED chokepoint — authorize runs per worker ctx
+            registry=self._filtered_registry(role),
+            events=self.events,
+            ctx=ctx,
+            system=role.system_prompt,
+            model=self.model,
+            max_iterations=self.max_iterations,
+            kill_switch=self.kill_switch,
+        )
+        result = await loop.run(task)
+        await self.events.append(
+            EventType.DELEGATION_FINISHED,
+            {"subagent": subagent_id, "role": role.name, "result": result},
+        )
+        return {"role": role.name, "subagent_id": subagent_id,
+                "phase": mode.phase.name, "task": task, "result": result}
+
+    def _worker_provider(self, role: Role) -> LLMProvider:
+        return self._make_worker_provider(role) if self._make_worker_provider else self.provider
+
+    def _filtered_registry(self, role: Role) -> ToolRegistry:
+        reg = ToolRegistry()
+        # ponytail: ToolRegistry has no public iterator; read its dict directly.
+        for tool in self.registry._tools.values():  # noqa: SLF001
+            if role.tool_filter(tool):
+                reg.register(tool)
+        return reg
+
+    @staticmethod
+    def _user(text: str):
+        from hexharness.providers.types import Message
+
+        return Message.user_text(text)
+
+
+def _parse_plan(text: str) -> list[dict[str, str]]:
+    """Pull the JSON array out of the model's reply; keep only well-formed, known roles.
+    Fail-closed: anything unparseable yields an empty plan (no workers spawned)."""
+    start, end = text.find("["), text.rfind("]")
+    if start == -1 or end <= start:
+        return []
+    try:
+        raw = json.loads(text[start : end + 1])
+    except json.JSONDecodeError:
+        return []
+    return [
+        {"role": item["role"], "task": str(item["task"])}
+        for item in raw
+        if isinstance(item, dict) and item.get("role") in ROLES and item.get("task")
+    ]