HydraR: Stateful Agentic Orchestration for Scientific Reproducibility in R

[IgnatiusPang]

Submitting Author Name: Ignatius Pang
Submitting Author Github Handle: @IgnatiusPang
Other Package Authors Github handles: @aidantay
Repository: https://github.com/APAF-bioinformatics/HydraR
Version submitted: v0.2.3
Submission type: Standard
Editor: TBD
Reviewers: TBD

Archive: TBD
Version accepted: TBD
Language: en

---

• Paste the full DESCRIPTION file inside a code block below:

Package: HydraR
Type: Package
Title: Stateful Agentic Orchestration for Scientific Reproducibility
Version: v0.2.3
Authors@R: 
    c(person(given = c("Chi", "Nam", "Ignatius"),
             family = "Pang",
             role = c("aut", "cre"),
             email = "ignatius.pang@mq.edu.au",
             comment = c(ORCID = "0000-0001-9703-5741")),
      person(given = "Aidan",
             family = "Tay",
             role = c("aut", "cre"),
             comment = c(ORCID = "0000-0003-1315-4896")))
Description: A high-performance framework for orchestrating complex 
    agentic workflows in R, specifically designed for scientific 
    reproducibility and auditability. HydraR provides a robust, 
    state-managed engine for Directed Acyclic Graphs (DAGs) and 
    iterative state machines, prioritizing CLI-native LLM 
    interactions (e.g., Gemini, Claude, Copilot) and hardened 
    state persistence (DuckDB/SQLite). It features isolated 
    execution via Git Worktrees for parallel file-modifying 
    tasks, autonomous quality control through integrated 
    auditors, and human-readable visualization using Mermaid.js. 
    Ideal for creating auditable, resumable research assistants 
    and complex bioinformatics pipelines.
URL: https://github.com/APAF-bioinformatics/HydraR
BugReports: https://github.com/APAF-bioinformatics/HydraR/issues
License: LGPL (>= 3)
Encoding: UTF-8
RoxygenNote: 7.3.3
Depends: 
    R (>= 4.1.0)
Imports: 
    DBI,
    digest,
    furrr,
    igraph,
    jsonlite,
    purrr,
    R6,
    yaml
Suggests: 
    testthat (>= 3.0.0),
    duckdb,
    knitr,
    rmarkdown,
    httr2,
    future,
    devtools,
    withr,
    reticulate,
    DiagrammeR
VignetteBuilder: knitr
Config/testthat/edition: 3

Scope

• Please indicate which category or categories from our package fit policies this package falls under: (Please check an appropriate box below. If you are unsure, we suggest you make a pre-submission inquiry.):

  • data retrieval
  • data extraction
  • data munging
  • data deposition
  • data validation and testing
  • workflow automation
  • version control
  • citation management and bibliometrics
  • scientific software wrappers
  • field and lab reproducibility tools
  • database software bindings
  • geospatial data
  • translation
  • rOpenSci internal tools

• Explain how and why the package falls under these categories (briefly, 1-2 sentences):

  HydraR provides a stateful, auditable engine for orchestrating complex agentic workflows, specifically targeting scientific reproducibility via Git worktree isolation and persistent DuckDB/SQLite checkpointing. It acts as a robust wrapper for large language model (LLM) command line interfaces (CLIs) tailored for bioinformatics research.

• Who is the target audience and what are scientific applications of this package?

  The target audience includes bioinformaticians, research software engineers, and data scientists building multi-agent systems for automated data analysis, code refactoring, and large-scale literature synthesis.

• Are there other R packages that accomplish the same thing? If so, how does yours differ or meet our criteria for best-in-category?

While 'ellmer' focuses on high-level API convenience, 'mall' excels at structured data operations, and 'gptstudio' on IDE integration, HydraR is uniquely centered on persistent session lifecycles and native command-line integration. It enables complex research pipelines with restorable execution states and complete audit trails, permitting safe parallel file modifications via Git worktrees, which are features essential for reproducible scientific computing. Furthermore, unlike solutions that rely on 'reticulate' to bridge R with Python-based AI frameworks (such as LangChain), HydraR is built entirely on R's native architectural frameworks, avoiding the data-translation barriers and compatibility issues often encountered when passing complex statistical structures between languages.

• (If applicable) Does your package comply with our guidance around Ethics, Data Privacy and Human Subjects Research?

  N/A

• If you made a pre-submission inquiry, please paste the link to the corresponding issue, forum post, or other discussion, or @tag the editor you contacted.

  N/A

• Explain reasons for any pkgcheck items which your package is unable to pass.

  The package currently passes R CMD check with 0 Errors and 0 Warnings. Minor NOTEs regarding hidden developer files (.github, .lintr) are intentional for repository management.

Technical checks

Confirm each of the following by checking the box.

• I have read the rOpenSci packaging guide.
• I have read the author guide and I expect to maintain this package for at least 2 years or to find a replacement.

This package:

• does not violate the Terms of Service of any service it interacts with.
• has a CRAN and OSI accepted license.
• contains a README with instructions for installing the development version.
• includes documentation with examples for all functions, created with roxygen2.
• contains a vignette with examples of its essential functions and uses.
• has a test suite.
• has continuous integration, including reporting of test coverage.

Use of Generative AI

• Generative AI tools were used to produce some of the material in this submission.

If so, please describe usage, and include links to any relevant aspects of your repository.

The core R6 architecture, state-management patterns, and Git worktree isolation strategies were designed and authored by the human authors (Ignatius Pang and Aidan Tay) and then rigorously tested manually. AI (Antigravity and Gemini CLI) was strategically employed for implementing logic blocks, unit tests, and documentation, following a rigorous "Human-in-the-loop" pattern where every line was manually reviewed and verified. Detailed disclosure is available in agents.md and DESIGN.md. To ensure software reliability, the framework is continuously evaluated against an automated testing suite consisting of 556 unit tests, currently maintaining a 100% pass rate (zero failures).

Publication options

• Do you intend for this package to go on CRAN?

• Do you intend for this package to go on Bioconductor?

• Do you wish to submit an Applications Article about your package to Methods in Ecology and Evolution? If so:

MEE Options

• The package is novel and will be of interest to the broad readership of the journal.
• The manuscript describing the package is no longer than 3000 words.
• You intend to archive the code for the package in a long-term repository which meets the requirements of the journal (see MEE's Policy on Publishing Code)

Note: We also intend to submit to JOSS as the primary scholarly venue for the software.

Code of conduct

• I agree to abide by rOpenSci's Code of Conduct during the review process and in maintaining my package should it be accepted.

[ropensci-review-bot]

Thanks for submitting to rOpenSci, our editors and @ropensci-review-bot will reply soon. Type @ropensci-review-bot help for help.

[emilyriederer]

@ropensci-review-bot check package

[ropensci-review-bot]

Thanks, about to send the query.

[ropensci-review-bot]

🚀

Editor check started

👋

[ropensci-review-bot]

Checks for HydraR (v0.2.1)

git hash: 076b3d44

• ✔️ Package name is available
• ✔️ has a 'contributing' file.
• ✖️ The following functions have no documented return values: [AgentBashNode, AgentPythonNode, AgentTool, AnthropicAPIDriver, AnthropicCLIDriver, Checkpointer, CopilotCLIDriver, DuckDBMessageLog, GeminiCLIDriver, JSONLMessageLog, MemoryMessageLog, MemorySaver, MessageLog, OllamaDriver, OpenAIAPIDriver, RDSSaver, RestrictedState, set_default_driver]
• ✔️ uses 'roxygen2'.
• ✔️ 'DESCRIPTION' has a URL field.
• ✔️ 'DESCRIPTION' has a BugReports field.
• ✔️ Package has at least one HTML vignette
• ✖️ These functions do not have examples: [add_llm_node, add_logic_node, AgentBashNode, AgentMapNode, AgentObserverNode, AgentPythonNode, AgentRouterNode, AgentTool, AnthropicAPIDriver, AnthropicCLIDriver, Checkpointer, cleanup_jules_branches, ConflictResolver, CopilotCLIDriver, dag_add_llm_node, dag_add_logic_node, dag_create, DriverRegistry, DuckDBMessageLog, extract_r_code_advanced, format_toolset, GeminiAPIDriver, GeminiCLIDriver, GeminiImageDriver, get_agent_roles, get_default_driver, get_driver_registry, get_logic, get_role_prompt, get_role, init_bot_history, is_named_list, JSONLMessageLog, list_logic, load_workflow, MemoryMessageLog, MemorySaver, mermaid_to_dag, MessageLog, OllamaDriver, OpenAIAPIDriver, OpenAICodexCLIDriver, RDSSaver, reducer_append, reducer_merge_list, register_logic, register_role, render_workflow_file, resolve_default_driver, RestrictedState, set_default_driver, spawn_dag, standard_node_factory, validate_workflow_file, validate_workflow_full].
• ✔️ Package has continuous integration checks.
• ✔️ Package coverage is 78.7%.
• ✔️ R CMD check found no errors.
• ✔️ R CMD check found no warnings.
• 👀 Some goodpractice linters failed.
• 👀 Examples should not use \dontrun{} unless really necessary.

Important: All failing checks above must be addressed prior to proceeding

(Checks marked with 👀 may be optionally addressed.)

Package License: LGPL (>= 3)

---

1. Package Dependencies

Details of Package Dependency Usage (click to open)

The table below tallies all function calls to all packages ('ncalls'), both internal (r-base + recommended, along with the package itself), and external (imported and suggested packages). 'NA' values indicate packages to which no identified calls to R functions could be found. Note that these results are generated by an automated code-tagging system which may not be entirely accurate.

type	package	ncalls
internal	base	1187
internal	HydraR	93
internal	utils	49
internal	methods	38
internal	stats	37
internal	graphics	31
internal	Matrix	17
internal	curl	5
internal	tools	2
imports	purrr	81
imports	R6	33
imports	igraph	19
imports	httr2	17
imports	jsonlite	16
imports	DBI	6
imports	furrr	5
imports	uuid	1
imports	digest	1
imports	base64enc	1
imports	yaml	NA
suggests	withr	8
suggests	lintr	2
suggests	duckdb	1
suggests	DiagrammeR	1
suggests	DiagrammeRsvg	1
suggests	testthat	NA
suggests	knitr	NA
suggests	rmarkdown	NA
suggests	future	NA
suggests	devtools	NA
suggests	reticulate	NA
suggests	ggplot2	NA
suggests	rsvg	NA
suggests	mockery	NA
suggests	RSQLite	NA
suggests	htmltools	NA
linking_to	NA	NA

Click below for tallies of functions used in each package. Locations of each call within this package may be generated locally by running 's <- pkgstats::pkgstats(<path/to/repo>)', and examining the 'external_calls' table.

base

list (341), if (57), character (54), return (52), system2 (47), data.frame (42), length (41), stdout (37), c (36), is.null (30), sprintf (26), tryCatch (26), names (25), args (22), paste (19), mode (17), warnings (17), as.character (15), call (10), gsub (10), shQuote (10), stdin (10), Sys.time (10), tempfile (10), trimws (10), basename (9), get (9), conflicts (8), readLines (8), stderr (8), attr (7), file.path (7), grepl (7), paste0 (7), setdiff (7), strsplit (6), raw (5), Sys.getenv (5), file (4), format (4), inherits (4), log (4), substr (4), url (4), as.integer (3), as.list (3), as.numeric (3), difftime (3), do.call (3), file.exists (3), getwd (3), identical (3), is.function (3), is.list (3), options (3), pretty (3), tolower (3), units (3), dir (2), dirname (2), emptyenv (2), for (2), force (2), getOption (2), gregexpr (2), is.na (2), lapply (2), ls (2), new.env (2), nzchar (2), regmatches (2), remove (2), sort (2), vapply (2), any (1), append (1), as.POSIXct (1), Filter (1), formals (1), grep (1), is.character (1), match (1), min (1), nchar (1), open (1), plot (1), rbind (1), readRDS (1), regexpr (1), serialize (1), switch (1), t (1), try (1), unique (1), unserialize (1), use (1)

HydraR

logic_fn (12), get_logic (8), get_driver_registry (5), test_fn (5), auto_node_factory (3), load_workflow (3), spawn_dag (3), add_llm_node (2), add_logic_node (2), build_edges_df (2), build_nodes_df (2), check_edge_synchronization (2), check_resource_linking (2), clean_mermaid_lines (2), extract_edge_and_node_strings (2), extract_params (2), format_toolset (2), lint_workflow_logic (2), mermaid_to_dag (2), parse_mermaid (2), parse_node_string (2), resolve_default_driver (2), resolve_logic_pattern (2), resolve_test_pattern (2), cleanup_jules_branches (1), create_merge_harmonizer (1), dag_add_llm_node (1), dag_add_logic_node (1), dag_create (1), extract_r_code_advanced (1), get_agent_roles (1), get_default_driver (1), get_role (1), get_role_prompt (1), has_static_edge (1), init_bot_history (1), is_named_list (1), list_logic (1), reducer_append (1), reducer_merge_list (1), register_logic (1), register_role (1), render_workflow_file (1), set_default_driver (1)

purrr

walk (21), iwalk (12), map (11), map_chr (10), imap (6), compact (5), imap_chr (4), map_lgl (3), detect (2), detect_index (2), list_flatten (2), discard (1), keep (1), pwalk (1)

utils

prompt (34), data (6), modifyList (3), timestamp (3), example (2), capture.output (1)

methods

initialize (30), new (3), Logic (2), as (1), el (1), is (1)

stats

step (9), df (8), line (7), end (5), start (5), update (2), ar (1)

R6

R6Class (33)

graphics

text (22), lines (9)

igraph

adjacent_vertices (4), V (4), bfs (3), degree (3), graph_from_data_frame (3), make_empty_graph (1), topo_sort (1)

httr2

req_body_json (4), req_retry (3), request (3), resp_body_json (3), resp_body_string (3), req_url_query (1)

Matrix

collapse (17)

jsonlite

toJSON (7), fromJSON (4), write_json (4), read_json (1)

withr

with_dir (8)

DBI

dbGetQuery (2), dbConnect (1), dbDisconnect (1), dbReadTable (1), dbWriteTable (1)

curl

curl_fetch_disk (3), handle_setheaders (1), new_handle (1)

furrr

furrr_options (3), future_map (2)

lintr

lint (2)

tools

file_ext (2)

base64enc

base64decode (1)

DiagrammeR

grViz (1)

DiagrammeRsvg

export_svg (1)

digest

digest (1)

duckdb

duckdb (1)

uuid

UUIDgenerate (1)

NOTE: Some imported packages appear to have no associated function calls; please ensure with author that these 'Imports' are listed appropriately.

---

2. Statistical Properties

This package features some noteworthy statistical properties which may need to be clarified by a handling editor prior to progressing.

Details of statistical properties (click to open)

The package has:

• code in R (100% in 27 files) and
• 2 authors
• 5 vignettes
• no internal data file
• 11 imported packages
• 72 exported functions (median 25 lines of code)
• 11 non-exported functions in R (median 10 lines of code)

---

Statistical properties of package structure as distributional percentiles in relation to all current CRAN packages
The following terminology is used:

• loc = "Lines of Code"
• fn = "function"
• exp/not_exp = exported / not exported

All parameters are explained as tooltips in the locally-rendered HTML version of this report generated by the checks_to_markdown() function

The final measure (fn_call_network_size) is the total number of calls between functions (in R), or more abstract relationships between code objects in other languages. Values are flagged as "noteworthy" when they lie in the upper or lower 5th percentile.

measure	value	percentile	noteworthy
files_R	27	90.4
files_vignettes	23	100.0
files_tests	52	99.4
loc_R	3352	93.1
loc_vignettes	759	84.9
loc_tests	3520	96.6	TRUE
num_vignettes	5	96.9	TRUE
n_fns_r	83	89.3
n_fns_r_exported	72	92.7
n_fns_r_not_exported	11	74.5
n_fns_per_file_r	3	71.0
num_params_per_fn	2	30.4
loc_per_fn_r	23	72.9
loc_per_fn_r_exp	25	65.2
loc_per_fn_r_not_exp	10	71.7
doclines_per_fn_exp	20	36.4
doclines_per_fn_not_exp	4	87.5
fn_call_network_size	52	75.4

---

2a. Network visualisation

Click to see the interactive network visualisation of calls between objects in package

---

3. goodpractice and other checks

Details of goodpractice checks (click to open)

3a. Continuous Integration Badges

![R-CMD-check.yaml](https://github.com/apaf-bioinformatics/HydraR/actions/workflows/R-CMD-check.yaml"><img src="https://github.com/apaf-bioinformatics/HydraR/actions/workflows/test-coverage.yaml/badge.svg)

GitHub Workflow Results

id	name	conclusion	sha	run_number	date
24119838720	lint.yaml	success	076b3d	224	2026-04-08
24119838727	pkgdown.yaml	success	076b3d	125	2026-04-08
24119838713	R-CMD-check.yaml	success	076b3d	237	2026-04-08
24119838704	styler.yaml	success	076b3d	224	2026-04-08
24119838702	test-coverage.yaml	success	076b3d	230	2026-04-08

---

3b. goodpractice results

Test coverage with covr

Package coverage: 78.69

Cyclocomplexity with cyclocomp

The following functions have cyclocomplexity >= 15:

function	cyclocomplexity
cleanup_jules_branches	25
auto_node_factory	22
lint_workflow_logic	19
resolve_logic_pattern	15

Static code analyses with lintr

lintr found the following 588 potential issues:

message	number of times
Avoid using sapply, consider vapply instead, that's type safe	1
Lines should not be more than 80 characters.	587

---

Package Versions

package	version
pkgstats	0.2.2.20
pkgcheck	0.1.2.279

---

Editor-in-Chief Instructions:

Processing may not proceed until the items marked with ✖️ have been resolved.

This package has some noteworthy properties, see 'Package Statistics' details above.

[IgnatiusPang]

Thank you editor for the checks. I will work on the list of errors e.g. the list of functions without documented return values and the list of functions without examples.

I will then progress to v0.2.2 and post an update here.

Would you please let me know what I have to do once I have fixed these problems and updated to v0.2.2 to continue the peer review?

[IgnatiusPang]

Hi @emilyriederer,

I have implemented the fixes from the Editor Check phase and updated the package to v0.2.2.

Summary of Updates:

• Documentation: Added missing @return values and descriptive @examples for all core R6 methods and functions.
• NEWS: Detailed changes are available in the v0.2.2 release notes.

The package is now ready for a re-audit and the next stage of review.

[mpadge]

Thanks @IgnatiusPang. It might help you to install our pkgcheck-action in your own repo to confirm, as recommended in our Dev Guide. When you're ready, you can trigger the checks yourself exactly as @emilyriederer did above. Thanks 😄

[IgnatiusPang]

@ropensci-review-bot check package

[ropensci-review-bot]

I'm sorry @IgnatiusPang, I'm afraid I can't do that. That's something only editors, author1, author-others and reviewers-list are allowed to do.

[IgnatiusPang]

@ropensci-review-bot check package

[ropensci-review-bot]

Thanks, about to send the query.

[ropensci-review-bot]

🚀

Editor check started

👋

[ropensci-review-bot]

Checks for HydraR (v0.2.2)

git hash: c12ce89b

• ✔️ Package name is available
• ✔️ has a 'contributing' file.
• ✔️ uses 'roxygen2'.
• ✔️ 'DESCRIPTION' has a URL field.
• ✔️ 'DESCRIPTION' has a BugReports field.
• ✔️ Package has at least one HTML vignette
• ✔️ All functions have examples.
• ✔️ Package has continuous integration checks.
• ✔️ Package coverage is 78.3%.
• ✔️ R CMD check found no errors.
• ✔️ R CMD check found no warnings.
• 👀 Some goodpractice linters failed.
• 👀 Examples should not use \dontrun{} unless really necessary.

(Checks marked with 👀 may be optionally addressed.)

Package License: LGPL (>= 3)

---

1. Package Dependencies

Details of Package Dependency Usage (click to open)

The table below tallies all function calls to all packages ('ncalls'), both internal (r-base + recommended, along with the package itself), and external (imported and suggested packages). 'NA' values indicate packages to which no identified calls to R functions could be found. Note that these results are generated by an automated code-tagging system which may not be entirely accurate.

type	package	ncalls
imports	uuid	NA
imports	DBI	NA
imports	digest	NA
imports	furrr	NA
imports	igraph	NA
imports	jsonlite	NA
imports	purrr	NA
imports	R6	NA
imports	yaml	NA
imports	httr2	NA
imports	base64enc	NA
suggests	testthat	NA
suggests	duckdb	NA
suggests	knitr	NA
suggests	rmarkdown	NA
suggests	future	NA
suggests	devtools	NA
suggests	withr	NA
suggests	reticulate	NA
suggests	DiagrammeR	NA
suggests	ggplot2	NA
suggests	DiagrammeRsvg	NA
suggests	lintr	NA
suggests	rsvg	NA
suggests	mockery	NA
suggests	RSQLite	NA
suggests	htmltools	NA
linking_to	NA	NA

Click below for tallies of functions used in each package. Locations of each call within this package may be generated locally by running 's <- pkgstats::pkgstats(<path/to/repo>)', and examining the 'external_calls' table.

NOTE: No imported packages appear to have associated function calls; please ensure with author that these 'Imports' are listed appropriately.

---

2. Statistical Properties

This package features some noteworthy statistical properties which may need to be clarified by a handling editor prior to progressing.

Details of statistical properties (click to open)

The package has:

• code in R (100% in 27 files) and
• 2 authors
• 6 vignettes
• no internal data file
• 11 imported packages
• 81 exported functions (median 19 lines of code)
• 11 non-exported functions in R (median 10 lines of code)

---

Statistical properties of package structure as distributional percentiles in relation to all current CRAN packages
The following terminology is used:

• loc = "Lines of Code"
• fn = "function"
• exp/not_exp = exported / not exported

All parameters are explained as tooltips in the locally-rendered HTML version of this report generated by the checks_to_markdown() function

The final measure (fn_call_network_size) is the total number of calls between functions (in R), or more abstract relationships between code objects in other languages. Values are flagged as "noteworthy" when they lie in the upper or lower 5th percentile.

measure	value	percentile	noteworthy
files_R	27	90.4
files_vignettes	24	100.0
files_tests	52	99.4
loc_R	3359	93.1
loc_vignettes	769	85.6
loc_tests	3516	96.6	TRUE
num_vignettes	6	97.8	TRUE
n_fns_r	92	90.3
n_fns_r_exported	81	93.6
n_fns_r_not_exported	11	74.5
n_fns_per_file_r	3	71.9
num_params_per_fn	2	30.4
loc_per_fn_r	18	65.4
loc_per_fn_r_exp	19	57.2
loc_per_fn_r_not_exp	10	71.7
doclines_per_fn_exp	32	50.6
doclines_per_fn_not_exp	4	87.5
fn_call_network_size	0	0.0	TRUE

---

2a. Network visualisation

Click to see the interactive network visualisation of calls between objects in package

---

3. goodpractice and other checks

Details of goodpractice checks (click to open)

3a. Continuous Integration Badges

![R-CMD-check.yaml](https://github.com/apaf-bioinformatics/HydraR/actions/workflows/R-CMD-check.yaml"><img src="https://github.com/apaf-bioinformatics/HydraR/actions/workflows/test-coverage.yaml/badge.svg)

GitHub Workflow Results

id	name	conclusion	sha	run_number	date
24185348963	lint.yaml	success	314384	232	2026-04-09
24185348914	pkgdown.yaml	success	314384	133	2026-04-09
24185348954	R-CMD-check.yaml	success	314384	245	2026-04-09
24185348959	styler.yaml	success	314384	232	2026-04-09
24185348962	test-coverage.yaml	success	314384	238	2026-04-09

---

3b. goodpractice results

Test coverage with covr

Package coverage: 78.33

Cyclocomplexity with cyclocomp

The following function have cyclocomplexity >= 15:

function	cyclocomplexity
cleanup_jules_branches	15

Static code analyses with lintr

lintr found the following 641 potential issues:

message	number of times
Lines should not be more than 80 characters.	641

---

Package Versions

package	version
pkgstats	0.2.2.20
pkgcheck	0.1.2.279

---

Editor-in-Chief Instructions:

This package is in top shape and may be passed on to a handling editor.

This package has some noteworthy properties, see 'Package Statistics' details above.

[IgnatiusPang]

Since there was something wrong with the Package Dependencies report and Network Visualisation report, I tried to fix whatever formatting error that could be causing that problem and move to new version v0.2.3. Resubmitting this version and triggering the package check:

@ropensci-review-bot check package