Package {corteza}

Title:	AI Agent Runtime
Version:	0.6.9
Description:	An agent runtime that gives Large Language Models (LLMs) from 'Anthropic' https://www.anthropic.com/, 'OpenAI' https://openai.com/, 'Moonshot' https://www.moonshot.ai/, and 'Ollama' https://ollama.com/ direct access to a live R session with managed workspace state. Tools execute as R function calls with provenance tracking, and a deterministic retrieval system keeps relevant objects in context across turns. Three entry points: a shell command-line interface (CLI), a console read-eval-print-loop via chat(), and a Model Context Protocol (MCP) server via serve() for external clients.
License:	Apache License (≥ 2)
URL:	https://github.com/cornball-ai/corteza
BugReports:	https://github.com/cornball-ai/corteza/issues
Depends:	R (≥ 4.4.0)
Imports:	callr, codetools, curl, jsonlite, llm.api (≥ 0.1.4), printify, processx, saber
Suggests:	clipr, fortunes, mx.api, rstudioapi, simplermarkdown, tinytest
VignetteBuilder:	simplermarkdown
SystemRequirements:	On Windows, Rtools45 (R 4.5.x) or Rtools44 (R 4.4.x) is recommended so the 'bash' shell tool is available; minimal installs fall back to a 'cmd' tool. 'git' is required for the git_status, git_diff, and git_log tools (install Git for Windows, or 'pacman -Sy git' from an Rtools shell).
Encoding:	UTF-8
NeedsCompilation:	no
Packaged:	2026-05-28 14:46:15 UTC; troy
Author:	Troy Hernandez [aut, cre], Grant McDermott [ctb], Jorge Krzyzaniak [ctb], cornball.ai [cph]
Maintainer:	Troy Hernandez <troy@cornball.ai>
Repository:	CRAN
Date/Publication:	2026-05-28 23:50:08 UTC

AI Agent Runtime

Description

An agent runtime that gives Large Language Models (LLMs) from 'Anthropic' <https://www.anthropic.com/>, 'OpenAI' <https://openai.com/>, 'Moonshot' <https://www.moonshot.ai/>, and 'Ollama' <https://ollama.com/> direct access to a live R session with managed workspace state. Tools execute as R function calls with provenance tracking, and a deterministic retrieval system keeps relevant objects in context across turns. Three entry points: a shell command-line interface (CLI), a console read-eval-print-loop via chat(), and a Model Context Protocol (MCP) server via serve() for external clients.

Package Content

Index of help topics:

add_observer            Add a tool-call observer to a session
chat                    Start Interactive Chat
default_local_model     Detect the preferred local Ollama model
install_cli             Install corteza CLI
matrix_archive_all      Flush all in-memory matrix sessions to the
                        pensar vault
matrix_configure        Configure the Matrix channel for this host
matrix_poll             One iteration of sync-and-reply
matrix_request_flush    Ask the running matrix bot to archive sessions
                        to pensar
matrix_run              Run the Matrix adapter as a long-poll loop
matrix_send             Send a message to a Matrix room
mcp_tool_executor       Build a tool executor that routes through an
                        MCP connection
new_session             Create a new turn session
observer_progress       Built-in progress observer that prints to
                        stdout
policy                  Evaluate policy for a tool call
serve                   Start MCP Server
session_setup           Configure and construct a session for any
                        channel
skill_install           Install a skill from a path or URL
skill_list_installed    List installed skills
skill_remove            Remove an installed skill
skill_test              Run skill tests
subagent_collect        Collect the result of a previously-fired async
                        subagent query.
subagent_kill           Kill a subagent.
subagent_list           List active subagents.
subagent_query          Query a subagent.
subagent_spawn          Spawn a subagent.
turn                    Run one agent turn
uninstall_cli           Uninstall corteza CLI

Maintainer

Troy Hernandez <troy@cornball.ai>

Author(s)

Troy Hernandez [aut, cre] (ORCID: <https://orcid.org/0009-0005-4248-604X>), Grant McDermott [ctb] (ORCID: <https://orcid.org/0000-0001-7883-8573>), Jorge Krzyzaniak [ctb], cornball.ai [cph]

Model context limits in tokens.

Description

Table of context window sizes for known models. Used by [context_limit_for_model()]. Add new entries here as providers ship them.

Usage

MODEL_CONTEXT_LIMITS

Format

An object of class list of length 18.

Add a tool-call observer to a session

Description

Observers run after every tool call (run, denied, or declined). They receive a single event list with fields:

Usage

add_observer(session, observer)

Arguments

Details

• call — the call list passed to policy().

• decision — the policy decision for the call.

• outcome — one of "ran", "deny", "declined".

• result — the string returned to the LLM.

• success — logical; TRUE only for "ran" with no tool error.

• elapsed_ms — wall time including policy overhead.

• turn_number — the session's tool-call counter.

Errors raised inside an observer are swallowed.

Value

The session, invisibly.

Examples

s <- new_session(provider = "anthropic")
add_observer(s, function(event) {
    # An observer is just a function of one argument; record the
    # outcome for inspection.
    message(event$outcome)
})
length(s$on_tool)

Start Interactive Chat

Description

Run a conversational agent inside your R session. Tools execute as direct function calls, no MCP server needed.

Usage

chat(provider = NULL, model = NULL, tools = NULL, session = NULL,
     max_turns = NULL)

Arguments

Value

The session object (invisibly).

Examples

if (interactive()) {
    # Start chatting with defaults from config
    chat()

    # Use a specific provider/model
    chat(provider = "ollama", model = "llama3.2")

    # Minimal tools for focused work
    chat(tools = "core")
}

Find the largest cut point in ‘history' that doesn’t split a tool_use / tool_result pair.

Description

Returns the number of entries that can safely be summarized (entries '1..cut'). Entries 'cut+1..end' are preserved verbatim. Returns 0 when no safe cut is available.

Usage

compact_find_cut(history, keep_recent_turns = 1L)

Arguments

Details

Strategy: start from the maximum cut that leaves 'keep_recent_turns' user-prompt boundaries intact, then walk back as needed so the cut doesn't land between a tool_use and the tool_result that satisfies it.

Replace the compacted prefix of a session's history with a single assistant summary message.

Description

Pure function: returns the new history list, doesn't mutate anything. The summary is prefixed with a '[compacted history]' tag (followed by a blank line) so it's visually distinct in the transcript.

Usage

compact_rewrite_history(history, cut, summary)

Summarize the prefix of a history slice via the LLM.

Description

Returns the summary text on success or NULL on any error (including timeout). Caller leaves history intact on NULL.

Usage

compact_summarize_slice(slice, provider = "anthropic", model = NULL,
                        timeout_seconds = 60L)

Arguments

Look up the context window for a given model.

Description

Tries exact match, then prefix match either direction (so '"claude-3-5-sonnet"' resolves to the dated entry, and a longer model id with a known prefix also resolves).

Usage

context_limit_for_model(model)

Arguments

Value

Context limit in tokens (integer). Returns 128000L when no entry matches.

Percent of a model's context window used by a session.

Description

Convenience wrapper around [estimate_live_context_tokens()] and [context_limit_for_model()]. Returns 0 when the limit is 0 or negative (defensive — shouldn't happen with a real model).

Usage

context_usage_pct(session, model, system_prompt = NULL, tools = NULL)

Arguments

Value

Numeric percentage in '[0, +Inf)'.

Execute current line or selection in 'corteza::chat()'

Description

RStudio addin. Reads the line or selection under the cursor in the active source editor, prepends '/r' for '.R' files (or '! ' for '.sh' / '.bash' files) when 'corteza::chat()' is the active console REPL, and sends the result to the console via 'rstudioapi::sendToConsole()'. After sending, the editor cursor advances to the next line (mirroring RStudio's pre-assigned Ctrl+Enter / Cmd+Return behavior).

Usage

corteza_execute_in_chat()

Details

When 'chat()' is not running, no prefix is added – the addin is a superset of RStudio's default "execute line" behavior, so you can bind it to Ctrl+Enter without losing normal R script execution.

**Setup:** bind Ctrl+Enter to "Execute in corteza::chat()" under RStudio's Tools -> Modify Keyboard Shortcuts. Choose "Addins" in the dropdown to find the binding.

Value

Invisible NULL. Side effect: sends a line to the console.

Execute current line or selection in 'corteza::chat()' (retain cursor)

Description

Same routing logic as [corteza_execute_in_chat()] but the editor cursor stays in place after sending, mirroring RStudio's pre-assigned Alt+Enter / Option+Return behavior.

Usage

corteza_execute_in_chat_retain()

Details

**Setup:** bind Alt+Enter to "Execute in corteza::chat() (retain cursor)" under RStudio's Tools -> Modify Keyboard Shortcuts.

Value

Invisible NULL.

Detect the preferred local Ollama model

Description

Walks getOption("corteza.local_models") (default c("gpt-oss:120b", "gpt-oss:20b")) and returns the first one that is currently installed in the local Ollama server. Returns NULL if Ollama is unreachable or none of the candidates are installed. Cached per R process.

Usage

default_local_model()

Value

Character scalar model name, or NULL.

Examples

# NULL when Ollama isn't running locally; a model name otherwise.
model <- default_local_model()
is.null(model) || is.character(model)

Provider-specific default model name.

Description

Resolves the actual model a subagent (or chat session) will run with when no explicit model is set, so /agents, compaction, and the CLI all show the same model identity. Delegates to llm.api::provider_default_model() – the canonical table – rather than keeping a parallel one that drifts. Returns NULL for an unknown or empty provider (llm.api errors there; we map it to NULL).

Usage

default_provider_model(provider)

Arguments

Value

Model name (character) or NULL.

Ensure skills are registered.

Description

Registers built-in skills if not already registered. Exported with ‘@keywords internal' so a subagent’s 'callr::r_session' child can register skills in its own namespace (via 'worker_init()') before dispatching tools.

Usage

ensure_skills()

Value

Invisible character vector of skill names.

Token estimate for a list of messages (history).

Description

Sums text tokens for each message and adds a small framing overhead (6 tokens / message) that the chars/4 estimate misses.

Usage

estimate_history_tokens(messages)

Arguments

Value

Integer.

Token estimate for an entire live model-context.

Description

Sum of system prompt + tool schema + message history, plus framing overheads. Used to drive auto-compaction triggers.

Usage

estimate_live_context_tokens(session, system_prompt = NULL, tools = NULL)

Arguments

Value

Integer.

Rough token estimate from raw text.

Description

Returns 'ceil(nchar(text) / 4)'. Good enough for budget decisions but not a substitute for the provider's real usage count.

Usage

estimate_text_tokens(text)

Arguments

Value

Integer.

Token estimate for the tool schema payload.

Description

Serializes the tool list as JSON and counts tokens, plus a 12- token overhead per tool for the schema framing.

Usage

estimate_tool_tokens(tools)

Arguments

Value

Integer.

Format an age in seconds as a compact string (e.g. "12s", "3m", "2h").

Description

Format an age in seconds as a compact string (e.g. "12s", "3m", "2h").

Usage

format_age(seconds)

Format a live-context display like "4.2K/200K" or "?".

Description

Used by /agents to summarize live tokens versus model limit. Returns "?" when either value is NA.

Usage

format_live_ctx(tokens, limit)

Format a token count for display (K / M suffixes).

Description

Format a token count for display (K / M suffixes).

Usage

format_tokens(n)

Arguments

Value

Character.

Install corteza CLI

Description

Install the corteza command-line tool to a directory in your PATH. On Unix (Linux, macOS) installs the Rscript shebang binary. On Windows installs a .cmd wrapper alongside the script so corteza works from cmd.exe / PowerShell.

Usage

install_cli(path = NULL, force = FALSE)

Arguments

Details

Requires:

• r (littler) for fast R script execution (Unix only — Windows uses Rscript).

• The llm.api package for LLM connectivity

• The corteza package itself

After installation, run corteza from any terminal (you may need to add the install directory to PATH; the function prints the PATH hint if it isn't already there).

Value

The installed script path, invisibly.

Examples

## Not run: 
install_cli()
install_cli("/usr/local/bin")

## End(Not run)

Flush all in-memory matrix sessions to the pensar vault

Description

Walks the per-room session registry and archives any turns that haven't been ingested yet via the pensar archive ingest. Each session tracks an ingested_through watermark so repeated calls only write new turns. Silent no-op when pensar is not installed.

Usage

matrix_archive_all(sessions, mx_sess = NULL)

Arguments

Value

Integer count of rooms ingested, invisibly.

Examples

## Not run: 
# Requires a running Matrix session registry and the optional
# pensar package for the actual archive step.
reg <- new.env(parent = emptyenv())
matrix_archive_all(reg)

## End(Not run)

Configure the Matrix channel for this host

Description

Logs in to a Matrix homeserver as the bot account, joins (or records) the target room, and writes credentials to tools::R_user_dir("corteza", "config")/matrix.json with file mode 0600. Call once per host. Model, provider, tools_filter, and auto_approve_asks are defaults the poll loop uses unless overridden at call time.

Usage

matrix_configure(server, user, password, room, model = NULL,
                 provider = c("anthropic", "openai", "moonshot", "ollama"),
                 tools_filter = NULL, auto_approve_asks = FALSE)

Arguments

Details

Pre-CRAN releases stored the file at ~/.corteza/matrix.json; that path is still read for backward compatibility, but the next matrix_configure() call writes to the new location.

Value

The saved configuration, invisibly.

Examples

## Not run: 
# Requires a real Matrix server and bot credentials. Configuration
# is written under tools::R_user_dir("corteza", "config").
matrix_configure(
    server = "https://matrix.example.org",
    user = "bot",
    password = "secret",
    room = "!roomid:example.org"
)

## End(Not run)

One iteration of sync-and-reply

Description

Fetches new messages across all joined rooms and runs turn against each. Auto-joins any pending invites the bot has received. Replies are sent back to the originating room. On first run there is no saved sync token, so this call establishes a baseline and returns without processing history.

Usage

matrix_poll(system = NULL, model = NULL, provider = NULL, tools_filter = NULL,
            timeout = 0L, sessions = NULL)

Arguments

Details

Pass sessions = NULL (the default) for a stateless one-shot — each incoming message builds a fresh session. Pass a registry created by matrix_new_session_registry() so a long-running matrix_run keeps a separate history per room (conversations in different rooms don't cross-contaminate).

Value

An integer count of messages replied to, invisibly.

Examples

## Not run: 
# Single poll cycle against the configured Matrix homeserver.
matrix_poll(timeout = 5000L)

## End(Not run)

Ask the running matrix bot to archive sessions to pensar

Description

Drops an archive.signal file in the corteza state directory. The next iteration of the long-poll loop in matrix_run picks it up, runs matrix_archive_all, and removes the file. Safe to call from any process or scheduler — systemd, Task Scheduler, launchd, cron, or a separate R session — without needing to know the bot's PID or share its memory.

Usage

matrix_request_flush()

Value

The signal file path, invisibly.

Examples

# Writes a sentinel file under CORTEZA_STATE_DIR (or the package's
# R_user_dir data path). Redirect to a tempdir for the example so
# we don't touch persistent state.
old <- Sys.getenv("CORTEZA_STATE_DIR")
Sys.setenv(CORTEZA_STATE_DIR = file.path(tempdir(), "state"))
sig <- matrix_request_flush()
file.exists(sig)
unlink(Sys.getenv("CORTEZA_STATE_DIR"), recursive = TRUE)
Sys.setenv(CORTEZA_STATE_DIR = old)

Run the Matrix adapter as a long-poll loop

Description

Creates one session up front and reuses it across polls so conversation history accumulates within the process lifetime. Intended as the entry point for a systemd user unit.

Usage

matrix_run(timeout = 30000L, system = NULL, model = NULL, provider = NULL,
           tools_filter = NULL)

Arguments

Value

Never returns under normal operation. Crashes on fatal error so systemd can restart.

Examples

## Not run: 
# Run the Matrix bot loop -- typically launched by a systemd unit
# rather than from an interactive R session.
matrix_run()

## End(Not run)

Send a message to a Matrix room

Description

Send a message to a Matrix room

Usage

matrix_send(text, room_id = NULL, msgtype = "m.text")

Arguments

Value

The event ID of the sent message.

Examples

## Not run: 
# Requires matrix_configure() to have run.
matrix_send("hello from corteza")

## End(Not run)

Maybe compact a turn_session's in-memory history.

Description

Decision points: - Compaction mode off → return invisibly without checking. - History shorter than 'min_messages' → skip (nothing to gain). - Live token usage below threshold → skip. - No safe cut available (e.g. open tool_use) → skip. - Summarizer fails → log and leave history intact.

Usage

maybe_compact_turn_session(session, config, kind = NULL)

Arguments

Details

On success, mutates 'session$history' in place. Returns invisibly TRUE if compaction ran successfully, FALSE otherwise.

Build a tool executor that routes through an MCP connection

Description

Returns a closure suitable for the tool_executor argument of turn. Each tool call is forwarded to the connected MCP server via llm.api::mcp_call.

Usage

mcp_tool_executor(conn)

Arguments

Value

A function with signature function(name, args) that returns an MCP-format result list.

Examples

## Not run: 
# Needs an open MCP connection to a running corteza::serve().
conn <- llm.api::mcp_connect("tcp://localhost:7850")
executor <- mcp_tool_executor(conn)
s <- new_session(provider = "anthropic")
turn("Hello", s, tool_executor = executor)

## End(Not run)

Best-effort flatten of a message's 'content' field into one string.

Description

Messages may have content as a plain string or a list of typed blocks (text / tool_use / tool_result). For budget math we just want the textual surface area.

Usage

message_text(message)

Arguments

Value

Character.

Create a new turn session

Description

Returns an environment with sensible defaults. Adapters set channel- specific fields (e.g. approval_cb, tools_filter) before calling turn.

Usage

new_session(channel = c("cli", "console", "matrix"), history = NULL,
            model_map = NULL, provider = "anthropic", tools_filter = NULL,
            system = NULL, approval_cb = NULL, max_turns = 10L,
            verbose = FALSE, plan_mode = FALSE)

Arguments

Value

An environment holding the session state.

Examples

# Build a stateless session for the CLI channel without making any
# network calls. The returned environment carries history, the
# active provider/model, and the approval callback.
s <- new_session(channel = "cli", provider = "anthropic")
is.environment(s)
identical(s$provider, "anthropic")

Built-in progress observer that prints to stdout

Description

Prints one line per tool call suitable for an interactive REPL: " [tool] hint (N lines)\n". The hint is a short summary of the call (file path, code snippet, search pattern) computed by tool_hint().

Usage

observer_progress()

Value

A function to pass to add_observer.

Examples

obs <- observer_progress()
s <- new_session(provider = "anthropic")
add_observer(s, obs)

Evaluate policy for a tool call

Description

Returns a decision list(model, approval, reason). model is "cloud" or "local"; approval is "allow", "ask", or "deny".

Usage

policy(call, config = NULL)

Arguments

Details

When config is supplied, the project's approval_mode / dangerous_tools / per-tool permissions are overlaid on top of the default tensor: a tool the user has configured as "ask" or "deny" will have its decision promoted accordingly. Safety verdicts (credential paths, plan mode) still win because those represent invariants the user can't waive from config.

Both corteza::chat() and the CLI tool dispatch loop pass their session's config through here so the /permissions contract advertised by both surfaces is enforced consistently.

Value

A decision list with fields model, approval, reason.

Examples

# A bare-environment read_file call resolves under the default
# built-in policy without needing any session config.
decision <- policy(list(name = "read_file",
                        arguments = list(path = "DESCRIPTION")))
decision$approval

Register a skill whose schema is derived from its function.

Description

Register a skill whose schema is derived from its function.

Usage

register_skill_from_fn(tool_name, fn, available = NULL)

Arguments

Value

Invisible tool name.

Derive an LLM tool schema from an R function's signature and docs.

Description

Derive an LLM tool schema from an R function's signature and docs.

Usage

schema_from_fn(fn_name, pkg = "corteza", max_desc_chars = 200L)

Arguments

Value

A tool-definition list with 'name', 'description', and 'input_schema' ready for the Anthropic chat-API 'tools' parameter.

Build the LLM API 'tools' payload from the tool registry.

Description

Returns a list of tool definitions in the shape Anthropic's chat completion API expects (name, description, input_schema). Built in-process from the shared registry.

Usage

schema_from_registry(filter = NULL)

Arguments

Details

Exported with '@keywords internal': the CLI calls this directly, but it is not part of the public user-facing API.

Value

List of tool definitions.

Start MCP Server

Description

Start the corteza MCP server. This exposes R tools to MCP clients like Claude Desktop, VS Code, or the corteza CLI.

Usage

serve(port = NULL, cwd = NULL, tools = NULL, expose_subagents = NULL)

Arguments

Details

The server supports two transport modes:

- **stdio** (default): For Claude Desktop and other MCP clients. Communication happens via stdin/stdout.

- **socket**: For the corteza CLI and R clients. Listens on a TCP port.

## Tools Provided

- 'read_file', 'write_file', 'replace_in_file', 'list_files', 'grep_files' - File operations - 'run_r' - Execute R code in the server session - 'bash' - Run shell commands - 'r_help' - Query package docs via saber (exports, function help) - 'installed_packages' - List installed packages - 'web_search' - Search the web via Tavily (requires TAVILY_API_KEY) - 'fetch_url' - Fetch web content - 'git_status', 'git_diff', 'git_log' - Git operations - 'chat', 'chat_models' - LLM chat (requires llm.api)

Value

NULL (runs until interrupted or client disconnects)

Examples

## Not run: 
# For Claude Desktop (stdio)
serve()

# For corteza CLI (socket) with all tools
serve(port = 7850)

# Minimal tools for small context models
serve(port = 7850, tools = "core")

# Specific categories
serve(port = 7850, tools = c("file", "git"))

## End(Not run)

Configure and construct a session for any channel

Description

Performs pre-turn setup common to all channels:

Usage

session_setup(channel = c("cli", "console", "matrix"), cwd = getwd(),
              provider = NULL, model = NULL, tools = NULL, system = NULL,
              approval_cb = NULL, history = NULL, load_project_context = TRUE,
              validate_api_key = TRUE, verbose = FALSE, max_turns = 50L)

Arguments

Details

1. Loads project + global corteza config from cwd.

2. Resolves provider, model, and verifies the required API environment variable is set.

3. Registers built-in skills and loads user/project skills and skill docs from tools::R_user_dir("corteza", "data")/skills and <cwd>/.corteza/skills.

4. Loads skill packages declared in the config.

5. Optionally builds the system prompt via load_context(cwd).

6. Returns a new_session() built from the above.

Value

A session environment from new_session, with an extra cwd field set.

Examples

## Not run: 
# Requires the relevant provider API key in the environment.
s <- session_setup("cli", provider = "anthropic",
                   load_project_context = FALSE)
s$model

## End(Not run)

Install a skill from a path or URL

Description

Install a skill from a path or URL

Usage

skill_install(source, target_dir = NULL, force = FALSE)

Arguments

Value

Installed skill name

Examples

# Install into a throwaway directory rather than the user's
# R_user_dir, so this example doesn't mutate state.
src <- file.path(tempdir(), "demo_skill")
dir.create(src, showWarnings = FALSE)
writeLines(c(
               "---",
               "name: demo",
               "description: A demo skill",
               "---",
               "Demo body."
            ),
           file.path(src, "SKILL.md"))

dest <- file.path(tempdir(), "skills_lib")
skill_install(src, target_dir = dest)

unlink(src, recursive = TRUE)
unlink(dest, recursive = TRUE)

List installed skills

Description

List installed skills

Usage

skill_list_installed(skill_dir = NULL)

Arguments

Value

Data frame with skill info

Examples

# List skills from an empty tempdir; returns a zero-row data frame
# with the documented columns.
empty <- file.path(tempdir(), "empty_skills")
dir.create(empty, showWarnings = FALSE)
skill_list_installed(skill_dir = empty)
unlink(empty, recursive = TRUE)

Remove an installed skill

Description

Remove an installed skill

Usage

skill_remove(name, skill_dir = NULL)

Arguments

Value

Invisible TRUE on success

Examples

# Install a demo skill into a tempdir, then remove it. The
# installed name is the source directory's basename.
src <- file.path(tempdir(), "demo_skill")
dir.create(src, showWarnings = FALSE)
writeLines(c("---", "name: demo_skill",
             "description: A demo skill", "---"),
           file.path(src, "SKILL.md"))
dest <- file.path(tempdir(), "skills_lib")
name <- skill_install(src, target_dir = dest)
skill_remove(name, skill_dir = dest)

unlink(src, recursive = TRUE)
unlink(dest, recursive = TRUE)

Run skill tests

Description

Executes test_*.R files in a skill directory.

Usage

skill_test(path, verbose = TRUE)

Arguments

Value

List with passed, failed, errors

Examples

# A skill directory with no test_*.R files returns a zero-result
# summary rather than erroring.
p <- file.path(tempdir(), "skill_no_tests")
dir.create(p, showWarnings = FALSE)
skill_test(p, verbose = FALSE)
unlink(p, recursive = TRUE)

Collect the result of a previously-fired async subagent query.

Description

Pairs with 'subagent_query(..., wait = FALSE)'. Returns the reply text once the child finishes its turn, or NULL while the query is still running. Result is read exactly once: after a successful collect the pending slot is cleared, so the next async query can fire.

Usage

subagent_collect(id, wait = TRUE, timeout = 60L)

Arguments

Value

Reply text (character) when ready; NULL when still running.

Examples

## Not run: 
id <- subagent_spawn("background research")
subagent_query(id, "what's in DESCRIPTION?", wait = FALSE)
# ... do other work ...
subagent_collect(id, wait = TRUE, timeout = 30)
subagent_kill(id)

## End(Not run)

Resolve the effective compaction threshold for a subagent.

Description

Returns a numeric percent. NULL means "compaction off for this child" — caller skips entirely.

Usage

subagent_compact_threshold(config)

Arguments

Value

Numeric percent in (0, 100], or NULL.

Kill a subagent.

Description

Kill a subagent.

Usage

subagent_kill(id)

Arguments

Value

Invisible TRUE if killed, FALSE if not found.

Examples

# Unknown id is a silent no-op (returns FALSE), so this is safe to
# run during R CMD check without a live subagent.
subagent_kill("no-such-id")

List active subagents.

Description

Returns a list of info objects per agent: id/seq/task/started_at/ time_remaining/pending plus model/age/cumulative usage and a best-effort live token count for idle agents ('NA' for busy).

Usage

subagent_list()

Value

List of subagent info objects.

Examples

# Empty when no subagent has been spawned yet -- safe to call any time.
subagent_list()

Query a subagent.

Description

Sends a prompt to a running subagent. Inside the child it runs through [turn()] with the child's persistent turn session: the LLM replies, any tool calls it makes resolve against the child's in-process skill registry, and history accumulates across queries.

Usage

subagent_query(id, prompt, wait = TRUE, timeout = 60L, return_name = NULL)

Arguments

Details

With 'wait = FALSE' the call returns immediately after firing the prompt; the parent collects the reply later with [subagent_collect()]. A subagent can only carry one in-flight async query at a time: firing a second one while the first is pending raises an error.

Value

Reply text (character) when 'wait = TRUE', with a handle block appended when 'return_name' resolved. Canonical id (character, invisibly) when 'wait = FALSE'.

Examples

## Not run: 
# Requires LLM credentials in the child's environment.
id <- subagent_spawn("read R/skill.R and summarize", preset = "minimal")
subagent_query(id, "what does this file do?", wait = TRUE)
subagent_kill(id)

## End(Not run)

Seed the child's turn-session history with an externally-built slice.

Description

Used by the archival runtime: the parent spawns a holder subagent, then ships the just-finished turn's history into the holder via this function so the holder owns the full transcript while the parent keeps only '{summary, subagent_id}'.

Usage

subagent_seed_history(history)

Arguments

Value

Invisible TRUE.

Spawn a subagent.

Description

Starts a fresh 'callr::r_session' with corteza loaded and its tool registry set up. Stores the handle in the package-level registry keyed by subagent id.

Usage

subagent_spawn(task, model = NULL, tools = NULL, preset = NULL,
               parent_session = NULL, config = NULL)

Arguments

Details

Permissions: subagents have no interactive approval channel back to the parent or user. The child's 'approval_cb' denies by default and there is no mid-run escalation path. Whatever capability the child needs must be granted at spawn time through 'preset' or 'tools'. If a task may need shell, write, or network capability, pick a preset that includes it (or pass an explicit 'tools' list); otherwise the child should report that it is blocked rather than retry.

Value

Subagent ID (character).

Examples

if (interactive()) {
    # Spawns a callr::r_session child loaded with corteza; the
    # registry is in-memory and dies with the parent R session, so
    # we wrap in interactive() to keep R CMD check from leaving
    # children behind.
    id <- subagent_spawn("look up the package version",
                         preset = "minimal")
    subagent_kill(id)
}

Initialize the child-side turn session.

Description

Called once per child just after [worker_init()]. Creates a ‘new_session()' configured with the subagent’s provider/model/tools and stores it where [subagent_turn_prompt()] can find it. The child's 'approval_cb' denies by default: subagents have no interactive approval channel back to the parent or user, and tool permissions are fixed at spawn time via 'tools_filter' (derived from the parent's 'preset' or explicit 'tools' argument to [subagent_spawn()]). There is no way to grant additional capability mid-run.

Usage

subagent_turn_init(provider = "anthropic", model = NULL, tools_filter = NULL,
                   system = NULL, max_turns = 10L, depth = 0L, plan_mode = FALSE)

Arguments

Value

Invisible TRUE.

Forward a prompt to the child-side turn session.

Description

Captures the pre-turn history length so that, if archival is enabled and this query qualifies, the child can recursively archive its own turn into a sub-subagent (capped by depth_cap).

Usage

subagent_turn_prompt(prompt, return_name = NULL)

Arguments

Value

A list with '$reply' (character, the LLM reply text), '$usage' (list with 'input_tokens', 'output_tokens', 'total_tokens', and optionally 'cost' – provider-dependent), and, when 'return_name' is set, '$final' (the resolved value) or '$final_note' (why nothing was returned). Callers extract the reply and accumulate usage into the parent-side registry.

Set this child's subagent id post-spawn.

Description

Called from [subagent_spawn()] right after [subagent_turn_init()] so the child knows its own id when archival inside the child needs to pass 'parent_session_id'.

Usage

subagent_turn_set_id(id)

Arguments

Value

Invisible TRUE.

Run a bash shell command.

Description

Use background=true for long-running servers or processes.

Usage

tool_bash(command, timeout = 30L, background = FALSE)

Arguments

Value

An MCP tool-result list.

Kill a background process by id.

Description

Kill a background process by id.

Usage

tool_bg_kill(id)

Arguments

Value

An MCP tool-result list.

Check status and output of background processes.

Description

Check status and output of background processes.

Usage

tool_bg_status()

Value

An MCP tool-result list.

Run a Windows cmd.exe command.

Description

Use background=true for long-running processes.

Usage

tool_cmd(command, timeout = 30L, background = FALSE)

Arguments

Value

An MCP tool-result list.

Collect the result of a previously-fired async subagent query.

Description

Collect the result of a previously-fired async subagent query.

Usage

tool_collect_subagent(id, wait = TRUE, timeout = 60)

Arguments

Value

An MCP tool-result list. On timeout returns a note that the query is still running.

Submit a plan and exit plan mode.

Description

Called by the LLM after it has finished research in plan mode. The plan text is shown to the user; on approval the session leaves plan mode and the LLM proceeds with the work. On decline the session stays in plan mode and the LLM iterates.

Usage

tool_exit_plan_mode(plan)

Arguments

Details

This tool is only exposed when the session is in plan mode. Outside plan mode it is hidden from the LLM's tool list.

Value

An MCP tool-result list.

Fetch the contents of a URL and return the response body.

Description

Fetch the contents of a URL and return the response body.

Usage

tool_fetch_url(url, max_chars = 8000L)

Arguments

Value

An MCP tool-result list.

Show git diff for the current repository.

Description

Show git diff for the current repository.

Usage

tool_git_diff(ref = "HEAD", path = ".", file_path = "", staged = FALSE,
              context_lines = 3L)

Arguments

Value

An MCP tool-result list.

Show recent git commits.

Description

Show recent git commits.

Usage

tool_git_log(n = 10L, ref = "HEAD", path = ".")

Arguments

Value

An MCP tool-result list.

Show git working tree status.

Description

Show git working tree status.

Usage

tool_git_status(path = ".")

Arguments

Value

An MCP tool-result list.

Search file contents with regex pattern.

Description

Search file contents with regex pattern.

Usage

tool_grep_files(pattern, path = ".", file_pattern = "*.R")

Arguments

Value

An MCP tool-result list.

List installed R packages, optionally filtered by name.

Description

List installed R packages, optionally filtered by name.

Usage

tool_installed_packages(pattern = NULL, limit = 100L)

Arguments

Value

An MCP tool-result list.

Terminate a running subagent.

Description

Terminate a running subagent.

Usage

tool_kill_subagent(id)

Arguments

Value

An MCP tool-result list.

List files in a directory.

Description

List files in a directory.

Usage

tool_list_files(path = ".", pattern = NULL, recursive = FALSE,
                all_files = FALSE, limit = 200L)

Arguments

Value

An MCP tool-result list.

List all active subagents.

Description

List all active subagents.

Usage

tool_list_subagents()

Value

An MCP tool-result list.

Send a prompt to a running subagent and get the response.

Description

Send a prompt to a running subagent and get the response.

Usage

tool_query_subagent(id, prompt, wait = TRUE, return_name = NULL)

Arguments

Value

An MCP tool-result list.

Get R package documentation via saber (exports, function help).

Description

Get R package documentation via saber (exports, function help).

Usage

tool_r_help(topic, package = NULL)

Arguments

Value

An MCP tool-result list.

Read file contents, optionally with line numbers.

Description

Read file contents, optionally with line numbers.

Usage

tool_read_file(path, from = 1L, lines = NULL, line_numbers = TRUE)

Arguments

Value

An MCP tool-result list.

Read / inspect a stashed handle.

Description

The LLM's only window onto large stashed objects. Supports a few common ops: 'str' (structure), 'head' (first six rows / elements), ‘summary' (R’s summary()), 'print' (full print of the object).

Usage

tool_read_handle(handle, op = "str")

Arguments

Value

An MCP tool-result list.

Replace exact text in a file without rewriting the whole file manually.

Description

Replace exact text in a file without rewriting the whole file manually.

Usage

tool_replace_in_file(path, old_text, new_text, all = FALSE,
                     expected_count = NULL)

Arguments

Value

An MCP tool-result list.

Execute R code in the session's global environment.

Description

New bindings are auto-captured into the workspace cache. Large result values (data frames, matrices, long vectors, objects over ~10 KB) are stashed via 'with_handle()' and returned as a 'str()' summary plus a short '.h_NNN' handle the LLM can reference in a later 'run_r' call or inspect with 'read_handle'.

Usage

tool_run_r(code)

Arguments

Value

An MCP tool-result list.

Execute R code in a clean subprocess via littler.

Description

Use for scripts that modify packages, run tests, or need isolation from the server.

Usage

tool_run_r_script(code, timeout = 30L)

Arguments

Value

An MCP tool-result list.

Spawn a specialized subagent for a task.

Description

Use for parallel work or tasks requiring focused attention. Parent session is read from 'ctx$session', which the skill handler injects from the invoking context; not from LLM-provided args.

Usage

tool_spawn_subagent(task, model = NULL, tools = NULL, preset = NULL,
                    ctx = list())

Arguments

Value

An MCP tool-result list.

Create a list of tasks to track for the current request.

Description

Call this at the start of any multi-step user request (3+ steps) to commit to a visible plan. The list persists across turns and replaces any prior list. After creating, update each task's status with 'task_update' as you work: mark a task 'in_progress' when you start it, 'completed' when done, 'cancelled' if the user redirects.

Usage

tool_task_create(tasks)

Arguments

Value

Confirmation string.

Update one task's status in the current session task list.

Description

Update one task's status in the current session task list.

Usage

tool_task_update(index, status)

Arguments

Value

Confirmation string.

Search the web using Tavily API.

Description

Search the web using Tavily API.

Usage

tool_web_search(query, max_results = 5L)

Arguments

Value

An MCP tool-result list.

Write text to a file.

Description

Creates parent directories by default.

Usage

tool_write_file(path, content, append = FALSE, create_dirs = TRUE)

Arguments

Value

An MCP tool-result list.

Run one agent turn

Description

Sends prompt to the configured LLM with tool use enabled. Every tool call the LLM makes is routed through policy before being dispatched.

Usage

turn(prompt, session, tool_executor = NULL, tools = NULL)

Arguments

Details

Tool dispatch is pluggable via tool_executor, but the CLI and chat() both leave it NULL: tools run in-process through the default call_skill dispatcher against the local skill registry. serve() is a separate MCP server for external clients only; it is not part of the CLI's tool path. Pass an explicit function(name, args) -> list executor only when dispatching tools somewhere other than the in-process registry.

Value

A list with reply (character) and session (the updated session environment; also mutated in place).

Examples

## Not run: 
# Requires ANTHROPIC_API_KEY (or the configured provider's key) and
# a network connection to the LLM.
s <- new_session(provider = "anthropic")
out <- turn("Say hello", s)
out$reply

## End(Not run)

Uninstall corteza CLI

Description

Remove the corteza command-line tool.

Usage

uninstall_cli(path = NULL)

Arguments

Value

TRUE if removed, FALSE if not found, invisibly.

Examples

## Not run: 
uninstall_cli()

## End(Not run)

Build a condition object representing "user denied this tool call".

Description

Raised by [chat_approval_cb()] (and the CLI's 'cli_approval_cb') when the user picks "3. Deny". The class deliberately excludes '"error"' so the defensive 'tryCatch(error = function(e) FALSE)' wrapper around approval_cb in [.make_tool_handler()] does not swallow it. The '"interrupt"' class lets the existing chat()/CLI interrupt-marker machinery fall through cleanly if a surface forgets to register a 'corteza_user_deny' handler.

Usage

user_deny_condition(tool = "?")

Arguments

Value

A condition object with class 'c("corteza_user_deny", "interrupt", "condition")'.

History marker written when a turn is aborted by a user deny.

Description

Format chosen so the LLM, reading the marker on the next turn, knows to stop and ask the user how to proceed instead of retrying the same tool or planning a workaround.

Usage

user_deny_marker(tool = "?")

Arguments

Value

Character scalar.

History marker written when a turn is interrupted (Ctrl+C / Esc).

Description

Carries the same "stop and ask the user" directive as [user_deny_marker()] so an interrupt and a deny leave the LLM with the same next-turn instruction – matching the (Esc)/(Ctrl+C) hint on the approval prompt, which converges on this interrupt path.

Usage

user_interrupt_marker()

Value

Character scalar.

Subagent session initialization.

Description

Runs inside a subagent's private 'callr::r_session' subprocess (invoked via 'corteza::worker_init()' across the callr boundary). Sets the subprocess cwd, ensures built-in skills are registered, and loads user/project skills so the subagent can execute tools.

Usage

worker_init(cwd = getwd())

Arguments

Details

Exported (with '@keywords internal') because it is called as 'corteza::worker_init()' from inside the 'callr::r_session' child, where ‘corteza:::' would trip the R CMD check "calls to the package’s namespace" NOTE.

Value

Invisible TRUE on success.