Package {corteza}

Title:	AI Agent Runtime
Version:	0.8.0
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, digest, jsonlite, llm.api (≥ 0.2.0), printify, processx, saber (≥ 0.8.0), utils
Suggests:	chat.api (≥ 0.2.0), clipr, fortunes, rgrpc (≥ 0.1.0), mx.client (≥ 0.3.0), pensar, RProtoBuf (≥ 0.4.24), 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-11-13 20:28:45 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-11-13 21:10: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
audit_payload_expire    Expire unpinned audit payloads explicitly
audit_payload_pin       Pin or unpin an audit payload
audit_payload_read      Read an immutable audit payload
audit_read              Read an audit event stream
bot_archive_all         Flush all in-memory matrix sessions to the
                        pensar vault
bot_configure           Configure the Matrix channel for this host
bot_poll                One iteration of sync-and-reply
bot_request_flush       Ask the running matrix bot to archive sessions
                        to pensar
bot_run                 Run the Matrix adapter as a long-poll loop
bot_run_init            Initialize the Matrix long-poll state
bot_run_step            One Matrix long-poll iteration
bot_send                Send a message to a Matrix room
chat                    Start Interactive Chat
default_local_model     Detect the preferred local Ollama model
install_cli             Install corteza CLI
matrix_archive_all      Deprecated: use bot_archive_all()
matrix_configure        Deprecated: use bot_configure()
matrix_poll             Deprecated: use bot_poll()
matrix_request_flush    Deprecated: use bot_request_flush()
matrix_run              Deprecated: use bot_run()
matrix_run_init         Deprecated: use bot_run_init()
matrix_run_step         Deprecated: use bot_run_step()
matrix_send             Deprecated: use bot_send()
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
voice_serve             Serve AgentVoice for live voice clients

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 21.

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)

Expire unpinned audit payloads explicitly

Description

Never runs automatically. Only files in the named writer's payload store are eligible; event metadata and other writers' stores are left intact. Expiry decisions append to a separate maintenance stream before deletion. Event retention is a planning value until an explicit event-retention tool is used.

Usage

audit_payload_expire(store, days = 30, now = Sys.time(), dry_run = TRUE)

Arguments

Value

Character vector of eligible (or deleted) hashes.

Examples

## Not run: 
audit_payload_expire(ref$store)

## End(Not run)

Pin or unpin an audit payload

Description

Pins keep incident/evaluation evidence through explicit expiry. Pinned bytes still count toward the store quota; capture reports quota omissions when full.

Usage

audit_payload_pin(ref, pin = TRUE)

Arguments

Value

The payload reference, invisibly.

Examples

## Not run: 
audit_payload_pin(ref)

## End(Not run)

Read an immutable audit payload

Description

Reads only a payload whose bytes still match its recorded SHA-256. Redaction affects the returned view, never the stored record. An omitted, expired, missing or damaged payload is an error, not an empty successful read.

Usage

audit_payload_read(ref, redact = TRUE, secrets = character())

Arguments

Value

The decoded JSON object or UTF-8 text, as recorded.

Examples

## Not run: 
audit_payload_read(ref)

## End(Not run)

Read an audit event stream

Description

Uses the auto-log decoder, retaining malformed-line locations and separating a torn final line from interior damage. A missing terminal turn record means unresolved completion. Redaction changes this returned view only; callers can supply additional known credential values. It cannot detect all secrets.

Usage

audit_read(path, redact = TRUE, secrets = character())

Arguments

Value

List with records, auto-run start/end compatibility fields and malformed-record diagnostics. Turn endings remain in records.

Examples

audit_read(tempfile())

History marker written when an unattended run escalates to a human.

Description

Carries the same "stop and ask" directive as its siblings, for the same reason: whatever the worker does next, it must not be another attempt at the thing that just got escalated.

Usage

auto_escalate_marker(reason = "")

Arguments

Value

Character scalar.

Flush all in-memory matrix sessions to the pensar vault

Description

Walks the per-room session registry and archives each room's unarchived Matrix events via the pensar archive ingest. Archived events are consumed from the session ledger, and their Matrix event ids are persisted per room under CORTEZA_STATE_DIR so a restart's backfill is recognized rather than archived again. Silent no-op when pensar is not installed.

Usage

bot_archive_all(sessions, chat = 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())
bot_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

bot_configure(
  server,
  user,
  password,
  room,
  model = NULL,
  provider = "anthropic",
  tools_filter = NULL,
  auto_approve_asks = FALSE,
  bots = NULL,
  models = NULL,
  model_badge = c("never", "non_default", "always"),
  display_name = NULL,
  fallback = NULL
)

Arguments

Details

Pre-CRAN releases stored the file at ~/.corteza/matrix.json; that path is still read for backward compatibility, but the next bot_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").
bot_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

bot_poll(
  system = NULL,
  model = NULL,
  provider = NULL,
  tools_filter = NULL,
  timeout = 0L,
  sessions = NULL,
  hooks = 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 bot_new_session_registry() so a long-running bot_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.
bot_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 bot_run picks it up, runs bot_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

bot_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 <- bot_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. A thin wrapper over bot_run_init plus a bot_run_step loop; call those two directly when an external scheduler needs to own the main process.

Usage

bot_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.

This is a bare bot: it runs with no hooks, so /clear archives and resets without filing the conversation anywhere, and a thread reply starts from the thread's own history. A host that wants segment rooms and rehydration drives the loop itself through bot_run_init and supplies them.

See Also

bot_run_init, bot_run_step

Examples

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

## End(Not run)

Initialize the Matrix long-poll state

Description

Performs everything bot_run does before its loop: builds the per-room session registry, catches up on invites that predate the saved sync token, and backfills recent room history into the registry. Returns an opaque state object to drive with bot_run_step.

Usage

bot_run_init(
  system = NULL,
  model = NULL,
  provider = NULL,
  tools_filter = NULL,
  hooks = NULL
)

Arguments

Details

End-to-end encryption is not set up here. When the config sets e2ee, the chat.api Matrix adapter owns the Olm account and Megolm sessions and both directions of encrypted traffic, so there is no crypto state for this package to build or carry.

Use this with bot_run_step() when an external loop owns the main process and needs to interleave the Matrix poll with other work (a scheduler, a multiplexer, an embedding host). For a standalone bot, call bot_run, which wraps both.

Value

A list holding the session registry, startup session handle, archive-flush signal path, and the saved poll options. Pass it to bot_run_step.

Hooks

corteza runs a conversation. What becomes of one once it ends, and where a thread's earlier context comes from, belong to the host that runs the bot over time (cerebro files segments and folds them into topic rooms). Two slots, both optional:

on_clear(chat, cfg, room_id, title, vault_ref)

Called from the /clear handler once the conversation is archived, when the user said something in it and the clear was not inside a thread. chat is the live chat.api client, cfg the bot config, title the segment title corteza derived from the transcript's opening line, vault_ref the archive's vault-relative path (or NULL). Returns list(id, name) for a room it filed the conversation into, which the acknowledgement names, or NULL for none. An error is reported and treated as none: archive-and-reset is the critical path.

thread_context(chat, room_id, thread_root)

Called once per thread session before its first reply. Returns list(segment, vault) naming the archived conversation the thread continues, or NULL when it continues nothing; vault is the transcript's path, vault-relative or absolute. A result seeds the session with the transcript's tail.

See Also

bot_run_step, bot_run

Examples

## Not run: 
# Drive the loop yourself instead of calling bot_run():
state <- bot_run_init()
repeat bot_run_step(state, timeout = 30000L)

## End(Not run)

One Matrix long-poll iteration

Description

Polls /sync once (blocking up to timeout ms, returning early when a message arrives), runs the agent against any new messages and posts the replies, then services a pending archive-flush signal. Mutates the session registry held in state in place, so successive calls accumulate conversation history.

Usage

bot_run_step(state, timeout = 30000L)

Arguments

Value

Invisibly, the integer count of messages replied to this poll.

See Also

bot_run_init, bot_run

Examples

## Not run: 
state <- bot_run_init()
bot_run_step(state, timeout = 5000L)

## End(Not run)

Send a message to a Matrix room

Description

Send a message to a Matrix room

Usage

bot_send(text, room_id = NULL, msgtype = "m.text", markdown = FALSE)

Arguments

Value

The event ID of the sent message.

Examples

## Not run: 
# Requires bot_configure() to have run.
bot_send("hello from corteza")

## End(Not run)

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,
  web_search = 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, keep_recent_tokens = 20000L)

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,
  summary_prompt = NULL,
  error_callback = NULL,
  session = NULL
)

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, provider = NULL)

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,
  provider = 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)

Deprecated: use bot_archive_all()

Description

Deprecated: use bot_archive_all()

Usage

matrix_archive_all(sessions, mx_sess = NULL, chat = NULL)

Arguments

Value

See bot_archive_all.

See Also

bot_archive_all

Examples

## Not run: 
matrix_archive_all(sessions)  # use bot_archive_all()

## End(Not run)

Deprecated: use bot_configure()

Description

Deprecated: use bot_configure()

Usage

matrix_configure(
  server,
  user,
  password,
  room,
  model = NULL,
  provider = "anthropic",
  tools_filter = NULL,
  auto_approve_asks = FALSE,
  bots = NULL,
  models = NULL,
  model_badge = c("never", "non_default", "always"),
  display_name = NULL,
  fallback = NULL
)

Arguments

Value

See bot_configure.

See Also

bot_configure

Examples

## Not run: 
matrix_configure(server, user, password, room)  # use bot_configure()

## End(Not run)

Deprecated: use bot_poll()

Description

Deprecated: use bot_poll()

Usage

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

Arguments

Value

See bot_poll.

See Also

bot_poll

Examples

## Not run: 
matrix_poll()  # use bot_poll()

## End(Not run)

Deprecated: use bot_request_flush()

Description

Deprecated: use bot_request_flush()

Usage

matrix_request_flush()

Value

See bot_request_flush.

See Also

bot_request_flush

Examples

## Not run: 
matrix_request_flush()  # use bot_request_flush()

## End(Not run)

Deprecated: use bot_run()

Description

Deprecated: use bot_run()

Usage

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

Arguments

Value

See bot_run.

See Also

bot_run

Examples

## Not run: 
matrix_run()  # use bot_run()

## End(Not run)

Deprecated: use bot_run_init()

Description

Deprecated: use bot_run_init()

Usage

matrix_run_init(
  system = NULL,
  model = NULL,
  provider = NULL,
  tools_filter = NULL,
  hooks = NULL
)

Arguments

Value

See bot_run_init.

See Also

bot_run_init

Examples

## Not run: 
matrix_run_init()  # use bot_run_init()

## End(Not run)

Deprecated: use bot_run_step()

Description

Deprecated: use bot_run_step()

Usage

matrix_run_step(state, timeout = 30000L)

Arguments

Value

See bot_run_step.

See Also

bot_run_step

Examples

## Not run: 
matrix_run_step(state)  # use bot_run_step()

## End(Not run)

Deprecated: use bot_send()

Description

Deprecated: use bot_send()

Usage

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

Arguments

Value

See bot_send.

See Also

bot_send

Examples

## Not run: 
matrix_send("hello")  # use bot_send()

## 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 and serialized request size below thresholds → 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,
  tools = NULL,
  system = NULL,
  threshold,
  byte_limit,
  min_messages,
  reason = "threshold"
)

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,
  web_search = NULL,
  base_url = NULL,
  max_tokens = NULL,
  reasoning_effort = NULL,
  thinking_budget_tokens = NULL,
  cache = NULL,
  compaction_prompt = NULL,
  context_edit = NULL
)

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,
  web_search = NULL
)

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 and source manifest via load_context_bundle(cwd).

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

Value

A session environment from new_session, with an extra cwd field and, for an auto-built system prompt, a context_manifest field.

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,
  report = FALSE
)

Arguments

Details

Both paths fire the prompt the same way, as a one-shot call on the child's 'callr::r_session'. With 'wait = FALSE' the call returns immediately and the parent collects the reply later with [subagent_collect()]. With 'wait = TRUE' the call collects on the parent's behalf, but only up to 'timeout' seconds: a child that has not replied by then is left running with the query pending, and the call returns NULL, so the wait is bounded by default ('Inf' opts out). A subagent can only carry one in-flight query at a time: firing a second one while the first is pending raises an error.

Value

Reply text (character) when 'wait = TRUE' and the child replied within 'timeout', with a handle block appended when 'return_name' resolved; NULL (invisibly) when the timeout elapsed and the query is still pending. 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,
  web_search = NULL,
  allowed_paths = NULL,
  channel = "console",
  reasoning_effort = NULL,
  thinking_budget_tokens = NULL,
  thinking = NULL,
  context_edit = NULL
)

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, report = FALSE)

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). '$termination' records whether the turn finished, stopped incomplete, or was cancelled, with a machine-readable reason. When 'return_name' is set, '$final' (the resolved value) or '$final_note' (why nothing was returned). When 'report = TRUE', '$report' is the validated structured handoff or '$report_error' explains why the child did not provide one. 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.

Hand a task to this session's doer.

Description

Queues a job for the session's persistent worker and returns at once. The result arrives later as its own message. The doer does not see this conversation, so the task must be self-contained.

Usage

tool_delegate(
  task,
  review = NULL,
  room = NULL,
  attach_context = NULL,
  ctx = list()
)

Arguments

Value

An MCP tool-result list.

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.

Record a one-line lesson in the continual harness store

Description

Stores one durable, verified fact learned during the session, as a single exact line. It will be shown in future sessions' context. Use it the moment a fact is verified – including negative results ("X does NOT do Y"). Approval is asked per note by default.

Usage

tool_harness_note(
  title,
  fact,
  evidence = NULL,
  scope = "project",
  ctx = list()
)

Arguments

Value

Confirmation string with the entry id.

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.

Cancel one of this session's jobs.

Description

Cancel one of this session's jobs.

Usage

tool_job_cancel(id, ctx = list())

Arguments

Value

An MCP tool-result list.

Resume an incomplete delegated job after an explicit user request.

Description

Resume an incomplete delegated job after an explicit user request.

Usage

tool_job_resume(id, ctx = list())

Arguments

Value

An MCP tool-result list.

Show this session's recent jobs.

Description

Show this session's recent jobs.

Usage

tool_job_status(id = NULL, ctx = list())

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.

Description

Fires the prompt and returns at once; collect the reply later with collect_subagent, so several subagents can run in parallel. wait = TRUE for a quick answer.

Usage

tool_query_subagent(
  id,
  prompt,
  wait = FALSE,
  return_name = NULL,
  timeout = 60,
  report = FALSE
)

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), 'grep' (the lines matching 'pattern', numbered), and 'lines' (a range of lines, 'start' to 'end'). The last two are how a tool result that was cut for length is searched and paged; each returns few enough lines not to be cut again.

Usage

tool_read_handle(handle, op = "str", pattern = NULL, start = NULL, end = NULL)

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 a persistent environment.

Description

By default, code runs in the host's global environment, preserving the original run_r contract. Pass a private persistent environment to give an agent or capability its own R scope. Scoped evaluation retains assignments and handles but does not copy bindings into the host workspace cache.

Usage

tool_run_r(code, envir = globalenv())

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.

Read a session-scoped instruction or supporting resource.

Description

Resolves an exact instruction identifier against the immutable catalog captured for the current agent session. Supporting resources are confined to the same snapshotted instruction directory and checked for drift.

Usage

tool_skill_instructions(id, resource = NULL, ctx = list())

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.

When the provider refuses the request with a limit error (HTTP 429, 503, or 529, or a body naming a rate, usage, or quota limit) and the session has a fallback chain, the turn is retried on the next "model provider" entry in that chain. The chain comes from session$fallback (the Matrix config's fallback key, see bot_configure) or the cwd config's fallback key. A provider that hit a limit is skipped process-wide for fallback_cooldown_minutes (default 30); a configured fallback_primary_retry_at can hold the primary until a weekly reset boundary. Provider-native histories are bridged when the wire changes, and a partially completed tool run resumes from its captured results so no completed tool call runs twice. Fallback replies identify their actual model/provider; API-key fallbacks carry a prominent billable usage warning. Errors that are not limits are rethrown untouched.

Value

A list with reply (character), session (the updated session environment; also mutated in place), route (the actual model/provider and fallback credential mode), and termination (status done, incomplete, or cancelled, with a machine-readable reason), and audit (the stream path and canonical turn ID, or NULL when recording is disabled).

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.

Serve AgentVoice for live voice clients

Description

Runs the gRPC service a fluffychat live-voice client talks to (AllocateVoice, Converse, ReportTurn). Blocks until interrupted. Run it as its own R process, next to – not inside – the room poll loop.

Usage

voice_serve(
  config = NULL,
  address = NULL,
  hooks = list(),
  poll_ms = 200L,
  max_events = Inf
)

Arguments

Details

Requires the rgrpc and RProtoBuf packages (Suggests), and a media allocator named in the config: voice.allocator (the gpu.ctl base URL) plus voice.allocator_token (the service credential its front requires on every mint). Without either, AllocateVoice refuses and names the missing key.

Voice sessions generate in spoken register: their system prompt carries an instruction to write plain speakable prose (no markdown, numbers said aloud), because the reply is synthesized verbatim. voice.speech_style in the config replaces that instruction's text; typed room chat is unaffected either way.

Value

Invisibly, the number of events handled.

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.