Convert Claude Code or Codex into the most intelligent Deep Research Agent. Collect, search, and synthesize web research into a persistent, searchable wiki that builds on itself. Hosted API + MCP: hyperresearch.ai
Python agentsagentskillscitationsclaude-codecodexcodex-plugincodex-skilldeep-researchdeep-research-agentdeepresearchmcp-serverresearchresearch-agentresearch-tools
fix: validate the run tag so it can only name a child of research/runs/ (#125)
Jordan Gibbs75b1ecfb2891
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 9c904de..57d03af 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,7 @@## [Unreleased]+- **A run tag is a slug (#116).** `Vault.run_dir()` joined the tag onto `research/runs/` unchecked, and pathlib replaces the base on an absolute segment, so `hpr run init ../../x` or `hpr run init C:/anything` scaffolded a run workspace outside the vault and every later `run` subcommand followed it there. Tags are now validated at that one seam: letters, digits, `-`, `_` and `.`, starting with a letter or digit, which is what `hpr vault-tag` mints. `run`, `levers` and `citecheck` report a bad tag as a clean error instead of a traceback. Same bug class as the `claims ingest --tag` traversal fixed in 0.11.1; exposure is low because the tag comes from the operator or the orchestrating agent, not from fetched content.- **The builtin provider fetches PDFs (#82, reported by @earldodd).** The PDF lane (`_is_pdf_url` / `_fetch_pdf`) lived inside the crawl4ai provider only, so a vault still on `provider = "builtin"` (the default until `hpr install` switches it) had no PDF handling at all: a direct `.pdf` link was decoded as HTML text and rejected by the junk gate as "Binary PDF garbage in content", identically for every mirror of the same document, and an arXiv `/abs/` link saved the 900-word abstract page instead of the paper. The lane now lives in `web/pdf.py` and both providers use it; the crawl4ai module keeps the old names. The builtin provider also detects a PDF from its bytes when the URL does not look like one. When the PDF lane declines a URL and the HTML fallback turns out to be junk, `hpr fetch -j` now says why the lane declined it (`PDF lane: HTTP 403`, `no extractable text layer`, ...) instead of the generic junk verdict, and the pymupdf document handle is closed on the exception path instead of leaking one per encrypted PDF.- **`serply` web provider.** Google organic results with page fetch through the same `SERPLY_API_KEY`; opt-in via `[web] provider = "serply"`, no new dependency.diff --git a/src/hyperresearch/cli/citecheck_cmd.py b/src/hyperresearch/cli/citecheck_cmd.pyindex 1955b70..a2bb0ee 100644--- a/src/hyperresearch/cli/citecheck_cmd.py+++ b/src/hyperresearch/cli/citecheck_cmd.py@@ -26,7 +26,7 @@ def citecheck_extract(runs/<tag>/cite-check-pairs.json for the cite-checker agent."""from hyperresearch.core.citecheck import write_pairs_file- from hyperresearch.core.vault import Vault, VaultError+ from hyperresearch.core.vault import InvalidRunTagError, Vault, VaultError, validate_run_tagtry:vault = Vault.discover()@@ -37,6 +37,15 @@ def citecheck_extract(console.print(f"[red]Error:[/] {e}")raise typer.Exit(1)+ try:+ validate_run_tag(vault_tag)+ except InvalidRunTagError as e:+ if json_output:+ output(error(str(e), "INVALID_TAG"), json_mode=True)+ else:+ console.print(f"[red]Error:[/] {e}")+ raise typer.Exit(1)+vault.auto_sync()report_path = Path(report) if report else (vault.root / "research" / "notes" / f"final_report_{vault_tag}.md"diff --git a/src/hyperresearch/cli/levers_cmd.py b/src/hyperresearch/cli/levers_cmd.pyindex d9936b9..d774b75 100644--- a/src/hyperresearch/cli/levers_cmd.py+++ b/src/hyperresearch/cli/levers_cmd.py@@ -5,13 +5,14 @@ from __future__ import annotationsimport typerfrom hyperresearch.cli._output import console, output+from hyperresearch.core.vault import VaultErrorfrom hyperresearch.models.output import error, successapp = typer.Typer()def _discover(json_output: bool):- from hyperresearch.core.vault import Vault, VaultError+ from hyperresearch.core.vault import Vaulttry:return Vault.discover()@@ -49,7 +50,7 @@ def levers_render(vault.auto_sync()try:result = render_shims(vault, vault_tag)- except LeverError as e:+ except (LeverError, VaultError) as e:_fail(str(e), "LEVER_ERROR", json_output)returnlevers = result["levers"]@@ -91,7 +92,7 @@ def levers_set(result = {"levers": levers, "rerendered": rerender}if rerender:result = {**render_shims(vault, vault_tag), "rerendered": True}- except LeverError as e:+ except (LeverError, VaultError) as e:_fail(str(e), "LEVER_ERROR", json_output)returnif json_output:diff --git a/src/hyperresearch/cli/run_cmd.py b/src/hyperresearch/cli/run_cmd.pyindex d5c02be..07e8d5a 100644--- a/src/hyperresearch/cli/run_cmd.py+++ b/src/hyperresearch/cli/run_cmd.py@@ -7,13 +7,14 @@ import jsonimport typerfrom hyperresearch.cli._output import console, output+from hyperresearch.core.vault import VaultErrorfrom hyperresearch.models.output import error, successapp = typer.Typer()def _vault_or_exit(json_output: bool):- from hyperresearch.core.vault import Vault, VaultError+ from hyperresearch.core.vault import Vaulttry:return Vault.discover()@@ -59,7 +60,7 @@ def run_init(query = Path(query_file).read_text(encoding="utf-8-sig")try:manifest = init_run(vault, vault_tag, profile=profile, budget_usd=budget, query=query)- except RunError as e:+ except (RunError, VaultError) as e:if json_output:output(error(str(e), "RUN_ERROR"), json_mode=True)else:@@ -86,7 +87,7 @@ def run_status(tag = _resolve_tag(vault, vault_tag, json_output)try:summary = status_summary(vault, tag)- except RunError as e:+ except (RunError, VaultError) as e:if json_output:output(error(str(e), "RUN_ERROR"), json_mode=True)else:@@ -168,7 +169,7 @@ def run_resume(tag = _resolve_tag(vault, vault_tag, json_output)try:manifest = load_manifest(vault, tag)- except RunError as e:+ except (RunError, VaultError) as e:if json_output:output(error(str(e), "RUN_ERROR"), json_mode=True)else:@@ -210,7 +211,7 @@ def run_abort(vault = _vault_or_exit(json_output)try:manifest = set_status(vault, vault_tag, "aborted")- except RunError as e:+ except (RunError, VaultError) as e:if json_output:output(error(str(e), "RUN_ERROR"), json_mode=True)else:@@ -236,7 +237,7 @@ def run_step(vault = _vault_or_exit(json_output)try:manifest = set_step(vault, vault_tag, step, status, chapter=chapter)- except RunError as e:+ except (RunError, VaultError) as e:if json_output:output(error(str(e), "RUN_ERROR"), json_mode=True)else:@@ -267,7 +268,7 @@ def run_spend(estimated_usd=usd, sources_fetched=sources,notes_written=notes, agents_spawned=agents,)- except RunError as e:+ except (RunError, VaultError) as e:if json_output:output(error(str(e), "RUN_ERROR"), json_mode=True)else:@@ -303,7 +304,7 @@ def run_event(raise typer.Exit(1)try:record_event(vault, vault_tag, payload)- except RunError as e:+ except (RunError, VaultError) as e:if json_output:output(error(str(e), "RUN_ERROR"), json_mode=True)else:@@ -327,7 +328,7 @@ def run_block(vault = _vault_or_exit(json_output)try:manifest = set_status(vault, vault_tag, "blocked", blocked_on=on)- except RunError as e:+ except (RunError, VaultError) as e:if json_output:output(error(str(e), "RUN_ERROR"), json_mode=True)else:@@ -362,7 +363,7 @@ def run_report(continuetry:reports.append(run_report_data(vault, tag))- except RunError:+ except (RunError, VaultError):continueagg = {"runs": len(reports),@@ -385,7 +386,7 @@ def run_report(try:load_manifest(vault, tag)report = run_report_data(vault, tag)- except RunError as e:+ except (RunError, VaultError) as e:if json_output:output(error(str(e), "RUN_ERROR"), json_mode=True)else:@@ -424,7 +425,7 @@ def run_verify(tag = _resolve_tag(vault, vault_tag, json_output)try:result = verify_run(vault, tag)- except RunError as e:+ except (RunError, VaultError) as e:if json_output:output(error(str(e), "RUN_ERROR"), json_mode=True)else:@@ -460,7 +461,7 @@ def run_finish(tag = _resolve_tag(vault, vault_tag, json_output)try:result = finish_run(vault, tag)- except RunError as e:+ except (RunError, VaultError) as e:if json_output:output(error(str(e), "RUN_ERROR"), json_mode=True)else:diff --git a/src/hyperresearch/core/vault.py b/src/hyperresearch/core/vault.pyindex 982b78e..15d45f5 100644--- a/src/hyperresearch/core/vault.py+++ b/src/hyperresearch/core/vault.py@@ -2,6 +2,7 @@from __future__ import annotations+import reimport sqlite3from pathlib import Path@@ -17,6 +18,33 @@ class VaultError(Exception):pass+class InvalidRunTagError(VaultError):+ """A run tag that is not a plain slug (path separators, `..`, absolute paths)."""+++# A run tag is a slug: what `hpr vault-tag` mints, plus underscore and dot so+# hand-written tags survive. No separators, so it can only ever name a child+# of research/runs/; the leading character rule rejects `.` and `..`.+RUN_TAG_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$")+++def validate_run_tag(vault_tag: str) -> str:+ """Return the tag unchanged, or raise InvalidRunTagError.++ Every run command joins the tag onto research/runs/, and pathlib replaces+ the base on an absolute segment, so without this `run init ../../x` or+ `run init C:/anything` scaffolds a workspace outside the vault and every+ later subcommand follows it there (#116).+ """+ if not isinstance(vault_tag, str) or not RUN_TAG_RE.fullmatch(vault_tag):+ raise InvalidRunTagError(+ f"invalid run tag {vault_tag!r}: a tag is a slug of letters, digits, "+ "'-', '_' and '.', starting with a letter or digit (mint one with "+ "`hyperresearch vault-tag <slug>`)"+ )+ return vault_tag++class Vault:"""Represents a hyperresearch research base vault."""@@ -85,7 +113,7 @@ class Vault:return self.research_dir / "runs"def run_dir(self, vault_tag: str) -> Path:- return self.runs_dir / vault_tag+ return self.runs_dir / validate_run_tag(vault_tag)@propertydef templates_dir(self) -> Path:diff --git a/tests/test_core/test_run_tag_validation.py b/tests/test_core/test_run_tag_validation.pynew file mode 100644index 0000000..10f28b9--- /dev/null+++ b/tests/test_core/test_run_tag_validation.py@@ -0,0 +1,115 @@+"""A run tag is a slug; it can only ever name a child of research/runs/ (#116).++`Vault.run_dir()` joins the tag onto research/runs/ and pathlib replaces the+base on an absolute segment, so before this `run init ../../x` (or an+absolute path) scaffolded a run workspace outside the vault and every later+`run` subcommand followed it there. Same bug class as the `claims ingest+--tag` traversal fixed in #114; this one is closed at the single seam every+run command goes through.+"""++from __future__ import annotations++import json++import pytest+from typer.testing import CliRunner++from hyperresearch.cli import app+from hyperresearch.core.vault import InvalidRunTagError, validate_run_tag++runner = CliRunner()+++ "tag",+ [+ "efield-dft-sac-3f9a1c",+ "non-ai-web-design-trends-2026-b0dbbe",+ "Run_2026.09.12",+ "a",+ "x" * 100,+ ],+)+def test_slugs_pass(tag):+ assert validate_run_tag(tag) == tag+++ "tag",+ [+ "../../x",+ "..",+ ".",+ ".hidden",+ "-leading-dash",+ "a/b",+ "a\b",+ "C:/anything",+ "/etc/passwd",+ "has space",+ "",+ "x" * 101,+ "tag\n",+ ],+)+def test_paths_and_junk_are_refused(tag):+ with pytest.raises(InvalidRunTagError):+ validate_run_tag(tag)+++def test_run_dir_refuses_before_touching_the_filesystem(tmp_vault):+ with pytest.raises(InvalidRunTagError):+ tmp_vault.run_dir("../../escape")+ assert not (tmp_vault.root.parent / "escape").exists()+++def test_run_init_with_a_traversal_tag_is_a_clean_error(tmp_vault, monkeypatch):+ monkeypatch.chdir(tmp_vault.root)+ outside = tmp_vault.root.parent / "outside"++ result = runner.invoke(app, ["run", "init", "../../outside", "-j"])++ payload = json.loads(result.stdout)+ assert result.exit_code == 1+ assert payload["ok"] is False+ assert "invalid run tag" in payload["error"]+ assert not outside.exists()+ assert not (tmp_vault.root / "research" / "runs").exists() or not any(+ (tmp_vault.root / "research" / "runs").iterdir()+ )+++def test_run_init_with_an_absolute_tag_is_a_clean_error(tmp_vault, tmp_path, monkeypatch):+ monkeypatch.chdir(tmp_vault.root)+ target = tmp_path / "elsewhere"++ result = runner.invoke(app, ["run", "init", str(target), "-j"])++ assert result.exit_code == 1+ assert json.loads(result.stdout)["ok"] is False+ assert not target.exists()+++def test_other_run_commands_report_the_bad_tag_too(tmp_vault, monkeypatch):+ monkeypatch.chdir(tmp_vault.root)+ for argv in (+ ["run", "status", "../../x", "-j"],+ ["run", "step", "../../x", "1", "--status", "done", "-j"],+ ["run", "verify", "../../x", "-j"],+ ["citecheck", "extract", "../../x", "-j"],+ ["levers", "render", "../../x", "-j"],+ ):+ result = runner.invoke(app, argv)+ assert result.exit_code == 1, argv+ assert json.loads(result.stdout)["ok"] is False, argv+ assert "invalid run tag" in json.loads(result.stdout)["error"], argv+++def test_a_good_tag_still_scaffolds_inside_the_vault(tmp_vault, monkeypatch):+ monkeypatch.chdir(tmp_vault.root)++ result = runner.invoke(app, ["run", "init", "good-tag-0a1b2c", "-j"])++ assert result.exit_code == 0, result.stdout+ assert (tmp_vault.root / "research" / "runs" / "good-tag-0a1b2c" / "run.json").exists()