Skip to content

rrrrrredy/research-toolkit / plugins/research-toolkit

research-toolkit

Flagged

Use for source-backed long-form research and writing in English or Chinese across fields, including revisions and continuation. Understand requirements, develop analysis through substantive research collaboration, and deliver a complete report after independent review, audit and acceptance.

FileKindSize
.codex-plugin/plugin.jsonconfig1.0 KB
.generated-files.jsonconfig6.3 KB
.mcp.jsonconfig158 B
LICENSEother1.0 KB
README.mdmarkdown3.4 KB
README.zh-CN.mdmarkdown3.0 KB
SKILL.mdskill md7.8 KB
SKILL.zh-CN.mdmarkdown6.5 KB
VERSIONother6 B
docs/compatibility.mdmarkdown3.8 KB
docs/compatibility.zh-CN.mdmarkdown3.2 KB
docs/delivery-verification.mdmarkdown19.2 KB
docs/delivery-verification.zh-CN.mdmarkdown16.3 KB
docs/review-completion.mdmarkdown18.0 KB
docs/review-completion.zh-CN.mdmarkdown14.7 KB
docs/usage-data.mdmarkdown15.4 KB
docs/usage-data.zh-CN.mdmarkdown13.9 KB
docs/usage-modes.mdmarkdown55.6 KB
docs/usage-modes.zh-CN.mdmarkdown48.6 KB
hooks/hooks.jsonconfig3.2 KB
mcp.jsonconfig253 B
plugin.jsonconfig1.1 KB
references/gotchas.mdmarkdown6.2 KB
references/gotchas.zh-CN.mdmarkdown3.6 KB
references/horizontal-vertical-analysis.mdmarkdown4.3 KB
references/horizontal-vertical-analysis.zh-CN.mdmarkdown3.2 KB
references/optional-analysis-lenses.mdmarkdown8.1 KB
references/optional-analysis-lenses.zh-CN.mdmarkdown6.1 KB
references/postmortem-lessons.mdmarkdown4.3 KB
references/postmortem-lessons.zh-CN.mdmarkdown3.5 KB
references/quality-gates.mdmarkdown5.7 KB
references/quality-gates.zh-CN.mdmarkdown4.5 KB
references/research-standard.mdmarkdown18.2 KB
references/research-standard.zh-CN.mdmarkdown13.7 KB
references/research-workflow.mdmarkdown25.5 KB
references/research-workflow.zh-CN.mdmarkdown19.9 KB
references/subagents-and-review-loop.mdmarkdown17.0 KB
references/subagents-and-review-loop.zh-CN.mdmarkdown13.4 KB
references/task-continuity.mdmarkdown6.9 KB
references/task-continuity.zh-CN.mdmarkdown5.3 KB
references/writing-style.mdmarkdown18.1 KB
references/writing-style.zh-CN.mdmarkdown14.9 KB
requirements-mcp.txtmarkdown11 B
scripts/agent_session.pyscript6.2 KB
scripts/check_delivery.pyscript44.6 KB
scripts/check_review_completion.pyscript28.5 KB
scripts/cli_agent_session.pyscript9.6 KB
scripts/codex_session.pyscript7.5 KB
scripts/extract_source_text.pyscript10.7 KB
scripts/host_review.pyscript78.4 KB
scripts/install_usage.pyscript9.7 KB
scripts/record_changes.pyscript13.7 KB
scripts/release_updates.pyscript9.8 KB
scripts/research_guidance.pyscript5.8 KB
scripts/research_host.pyscript52.4 KB
scripts/research_mcp.pyscript18.9 KB
scripts/research_records.pyscript28.5 KB
scripts/research_workflow.pyscript40.9 KB
scripts/review_process.pyscript5.2 KB
scripts/review_runner.pyscript20.2 KB
scripts/run_observation.pyscript7.7 KB
scripts/task_context.pyscript21.1 KB
scripts/task_lock.pyscript1.7 KB
scripts/task_reading.pyscript4.0 KB
scripts/task_storage.pyscript3.1 KB
scripts/usage_events.pyscript38.9 KB
scripts/usage_host.pyscript7.8 KB
scripts/usage_opencode.mjsscript3.1 KB

scripts/cli_agent_session.py

View on GitHub
"""Claude Code and OpenCode native CLI sessions behind the Agent event boundary."""
from __future__ import annotations

from datetime import datetime, timezone
import json
import os
from pathlib import Path
import queue
import subprocess
import sys
import threading
import uuid

from agent_session import PROCESS_EXIT_TIMEOUT, native_id, stop_native_process
from review_process import ProcessCleanupError, WindowsJob, WINDOWS_GATE


STARTUP_TIMEOUT = 60


class CLIAgentSession:
    supports_steer = False

    def __init__(self, cwd, directory, host, executable):
        self.cwd, self.directory = Path(cwd).resolve(), Path(directory)
        self.directory.mkdir(parents=True, exist_ok=True)
        self.name, self.executable = host, executable
        self.events, self.runs = queue.Queue(), []
        self.lock = threading.Lock()
        self.closed = False
        self.trace = (self.directory / "protocol.jsonl").open("a", encoding="utf-8")

    def record(self, turn, direction, message):
        with self.lock:
            self.trace.write(json.dumps({"at": datetime.now(timezone.utc).isoformat(),
                "host": self.name, "turn": turn, "direction": direction, "message": message}, ensure_ascii=False) + "\n")
            self.trace.flush()

    @property
    def available(self):
        return not self.closed

    def start(self, prompt, previous=None, read_paths=None, *, workdir=None):
        if self.closed:
            raise RuntimeError(f"{self.name}: session is closed.")
        previous = native_id(self.name, previous)
        turn = uuid.uuid4().hex
        command = list(self.executable)
        paths = [str(Path(p).resolve()) for p in (read_paths or [])]
        if not paths:
            raise ValueError("Prepared research execution needs the retained reading pages for this invocation.")
        cwd = Path(workdir).resolve() if workdir else self.cwd
        if self.name == "claude":
            command += ["-p", "--output-format", "stream-json", "--verbose"]
            command += ["--resume", previous] if previous else ["--session-id", str(uuid.uuid4())]
        else:
            command += ["run", "--format", "json", "--dir", str(cwd)]
            if previous:
                command += ["--session", previous]
        run = {"turn": turn, "previous": previous, "read_paths": paths, "cwd": cwd,
               "ready": queue.Queue(), "launch_lock": threading.Lock(),
               "process": None, "job": None, "stopped": False}
        self.runs.append(run)
        self.record(turn, "send", {"argv": command, "prompt": prompt})
        run["worker"] = threading.Thread(target=self._run, args=(run, command, prompt), daemon=True)
        run["worker"].start()
        # Wait for the native session identity, not for generated content. A
        # launch/error/EOF before identification wakes this queue with the error.
        try:
            identity = run["ready"].get(timeout=STARTUP_TIMEOUT)
        except queue.Empty as exc:
            self._stop(run)
            message = f"{self.name}: no native session identity within {STARTUP_TIMEOUT:g} seconds. See {self.trace.name}."
            self.record(turn, "error", message)
            raise RuntimeError(message) from exc
        except KeyboardInterrupt:
            self._stop(run)
            self.record(turn, "error", "Canceled while waiting for the native session identity.")
            raise
        if isinstance(identity, Exception):
            raise identity
        return identity, turn

    def _run(self, run, command, prompt):
        session, failure, result = None, None, None
        text_parts, final_reason = {}, None
        stderr_path = self.directory / (run["turn"] + ".stderr.txt")
        try:
            env = os.environ.copy()
            # This is a separate native session, not a nested turn of the parent.
            # Keep account/model settings, but do not inherit parent identity.
            for key in ("CLAUDECODE", "CLAUDE_CODE_ENTRYPOINT", "CODEX_THREAD_ID"):
                env.pop(key, None)
            # Keep the installed tool's tools, permissions and provider settings.
            # Research may require searches, downloads and executable calculations.
            with run["launch_lock"], stderr_path.open("w", encoding="utf-8") as stderr:
                if run["stopped"]:
                    return
                run["job"] = WindowsJob() if os.name == "nt" else None
                argv = [sys.executable, "-c", WINDOWS_GATE, json.dumps(command)] if run["job"] else command
                process = run["process"] = subprocess.Popen(argv, cwd=run["cwd"], env=env,
                    stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=stderr,
                    text=True, encoding="utf-8", bufsize=1,
                    creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0,
                    start_new_session=os.name != "nt")
                if run["job"]:
                    run["job"].attach(process.pid)
                    process.stdin.write("1")
                    process.stdin.flush()
            process.stdin.write(prompt)
            process.stdin.close()
            for line in process.stdout:
                try:
                    raw = json.loads(line)
                except ValueError:
                    self.record(run["turn"], "receive", {"unparsed": line})
                    failure = "Native CLI emitted non-JSON output; inspect the original protocol."
                    continue
                self.record(run["turn"], "receive", raw)
                if not isinstance(raw, dict):
                    raise ValueError("Native CLI protocol event must be a JSON object.")
                identity = raw.get("session_id") if self.name == "claude" else raw.get("sessionID")
                if isinstance(identity, str) and identity and not session:
                    if run["previous"] and identity != run["previous"]:
                        raise ValueError("Native CLI resumed a different session than the recorded owner.")
                    session = self.name + ":" + identity
                    run["ready"].put(session)
                if self.name == "claude":
                    if raw.get("type") == "result":
                        result = raw
                else:
                    if raw.get("type") == "error":
                        failure = raw.get("error") or "Native CLI reported an error."
                    part = raw.get("part", {})
                    if raw.get("type") == "text":
                        text_parts[part["id"]] = part
                    if raw.get("type") == "step_finish":
                        final_reason = part.get("reason")
            try:
                code = process.wait(timeout=PROCESS_EXIT_TIMEOUT)
            except subprocess.TimeoutExpired as exc:
                raise RuntimeError(f"{self.name}: process did not exit after closing its output; see {stderr_path}.") from exc
            self._stop(run)
            if self.name == "claude":
                content = result.get("result", "") if result else ""
                completed = result and not result.get("is_error") and result.get("subtype") == "success"
            else:
                parts = list(text_parts.values())
                last_message = parts[-1].get("messageID") if parts else None
                content = "\n\n".join(p["text"] for p in parts if p.get("messageID") == last_message)
                completed = final_reason == "stop"
            if not session:
                raise RuntimeError(f"{self.name}: no native session returned (exit {code}); see {stderr_path}.")
            if not failure and (code != 0 or not completed):
                failure = f"{self.name}: process exited without a successful terminal result (exit {code}); see {stderr_path}."
            if content:
                self.events.put({"kind": "message", "session": session, "turn": run["turn"],
                    "id": run["turn"], "phase": "final_answer", "text": content})
            self.events.put({"kind": "completed", "session": session, "turn": run["turn"],
                "status": "completed" if code == 0 and completed and not failure else "failed",
                "raw": {"exit_code": code, "error": failure, "result": result, "finish_reason": final_reason}})
        except Exception as exc:
            try:
                self._stop(run)
            except ProcessCleanupError as cleanup_error:
                exc = cleanup_error
            if session:
                self.events.put({"kind": "completed", "session": session, "turn": run["turn"],
                    "status": "failed", "raw": {"error": str(exc)}})
            else:
                run["ready"].put(exc)
            self.record(run["turn"], "error", str(exc))
        finally:
            if process := run["process"]:
                try:
                    process.stdin.close()
                except BrokenPipeError:
                    # The process has stopped and cannot receive the remaining prompt bytes.
                    pass
                finally:
                    process.stdout.close()

    def _stop(self, run):
        with run["launch_lock"]:
            if not run["stopped"]:
                run["stopped"] = True
                stop_native_process(run["process"], run["job"])

    def next_event(self, timeout=1):
        return self.events.get(timeout=timeout)

    def close(self):
        if self.closed:
            return
        self.closed = True
        for run in self.runs:
            self._stop(run)
        for run in self.runs:
            run["worker"].join(timeout=PROCESS_EXIT_TIMEOUT)
            if run["worker"].is_alive():
                raise ProcessCleanupError(f"Native protocol reader did not close; see {self.trace.name}.")
        self.trace.close()
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall