Skip to content

corteza

0.7.1Package record

AI Agent Runtime

0packages depend
1.8Kdownloads / year
–test coverage
13/13flavors OK

Overview

About

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.

Changes in 0.7.1

New

  • **openai_compatible provider for generic OpenAI-compatible endpoints** (#149). Point corteza at OpenRouter, DeepSeek, DeepInfra, a local proxy, or a corporate gateway via a base_url config key or the --base-url CLI flag (falling back to OPENAI_COMPATIBLE_BASE_URL). The model id is passed through untouched and is required; the API key comes from OPENAI_COMPATIBLE_API_KEY or OPENAI_API_KEY, and a keyless gateway works with neither. A missing endpoint or model is reported at session setup rather than at the first request. turn() applies the endpoint through llm.api::llm_base() scoped to each agent call, so a mid-session /provider switch or a subagent on another provider cannot inherit it. Requires llm.api >= 0.1.9. See vignette("configuration").
Show all changes in 0.7.1Hide the rest of the changes in 0.7.1
  • **Provider-native web search.** The agent loop enables llm.api::agent()'s server-side web search for the hosted providers that support it (anthropic, anthropic_claude, openai, openai_codex, moonshot). On by default, no Tavily key required; the model searches inside its own turn. Toggle with --web-search / --no-web-search, chat(web_search = ), or a web_search key in .corteza/config.json. The Tavily web_search tool remains the fallback for local models.
  • **Matrix /model lists available models and switches by number.** Bare /model (or //model where the client eats single slashes) replies with a numbered menu instead of echoing the current settings: the configured default, the live local Ollama inventory, and any hosted models declared via the new matrix_configure(models =) key ("model provider" strings, since hosted providers cannot be enumerated remotely). /model 3 switches the room session to entry 3, setting model and provider together, so switching from a phone client never needs a typed model name. The typed form /model <name> [provider] is unchanged, and an unreachable Ollama degrades the menu to the configured entries.

Matrix access control

  • **Private conversations and invites are restricted to configured operators.** The new operators key lists the Matrix ids allowed a one-on-one conversation with the bot. A room with one human is answered only when that human is an operator; everyone else gets silence rather than a mention-gated session. Invites are gated on the same list, read from the inviter in the stripped invite_state, and an invite whose inviter cannot be determined is refused. Group rooms are unaffected. Leaving operators unset preserves the previous behavior.
  • **Reply gating counts humans, not members.** Rooms whose only non-bot member is one human are answered without a mention; rooms with two or more humans require a mention (replies count, since clients put the replied-to user in m.mentions) or an open engagement window: after the bot answers someone, that person's plain messages keep getting replies for 5 minutes, ending early when they address someone else. Other bot accounts are declared via the new matrix_configure(bots =) parameter; their messages always require a mention. Room membership is cached per session and refreshed on unknown senders or every 10 minutes, replacing the boot-time DM snapshot that left rooms stuck on stale gating after membership changed. With bots unset, behavior matches the old member-count rule minus the staleness; during a members-API outage the gate fails open for human senders instead of going silent.

Matrix fixes

  • **Non-triggering messages are ingested instead of dropped.** In a room with more than one human, a message that did not warrant a reply was marked seen, given a read receipt, then dropped with a bare next: never appended to the session's history and, because it was already marked seen, never reconsidered. The agent genuinely never saw other people's non-mention messages in a busy room, even though it had "read" them. Gated messages are now appended to history as context; the reply gate and its bot-loop protection are unchanged, only ingestion is. Turns are attributed with a [sender] prefix in rooms with more than one human (both the live poll and the startup backfill), and known bot senders are labeled even in one-human rooms, so the model can tell speakers apart. A lone-human DM is unchanged.
  • **Rooms load project context into the room system prompt.** matrix_new_session() passed a non-NULL system to session_setup() with load_project_context = FALSE, so Matrix bots ran without the project briefing, agent context files, .corteza context_files, and package tool docs that other channels receive. The new matrix_room_system() composes the Matrix identity header with load_context() for the room cwd.

Archiving

  • **Archives are built from a Matrix-visible event ledger, not from provider history.** History holds tool calls and tool results that were never Matrix events, so a restarted process (which rebuilds history from the server's visible messages) could not align with what it had archived, and tool-using rooms re-archived their whole backfill on every restart. Sessions keep a transcript of {event_id, role, content} and a queue of pending events, written where events are seen or sent and drained once archived. Archival keys on Matrix event ids, recognized against a bounded per-room tail of already-archived ids. Transcripts no longer contain tool turns.
  • **Archive progress is persisted per room instead of tracked in memory.** matrix_archive_session() used ingested_through, an index into the in-memory session history, which reset on every restart while startup backfill refilled history from the server. Each restart therefore re-archived the backfilled tail. Progress is now an ordered key tail persisted per room under CORTEZA_STATE_DIR, advanced only after a successful ingest, so a failed archive retries rather than loses turns.
  • **Archives are keyed by room id, not display name.** Room display names and avatars are mutable Matrix state, so archived transcripts use the global Matrix room id for title and source. The room name is retained only as archive-time metadata, which keeps renames from splitting one chat into multiple raw archive identities.

From NEWS.md in the release

Install

Health

CRAN checks
13OK
Slowest check: 4.6 min · r-oldrel-macos-x86_64
Status changes
  • OK13 OK2026-08-05
  • NOTE12 OK, 1 NOTE2026-08-01
  • OK13 OK2026-05-29
  • ERROR12 OK, 1 ERROR2026-05-26
  • OK13 OK2026-05-16
Show 2 earlier changesHide 2 earlier changes
  • ERROR12 OK, 1 ERROR2026-05-14
  • OK6 OK2026-05-05
Advisories

none known

Documentation

In release 0.7.1
README· In the repository, left out of the releaseVignettesYes · 5 · staticNEWSYes · 67% structured · mentions 0.7.1Citation fileNoWebsitenot declared in DESCRIPTION
Help pages
88 (59 internal)includes a package overview page
Examples that run
45%13 run in a plain check (1 of them under a condition) · 1 only when donttest examples are enabled (R CMD check --as-cran) · 15 never run
Exported functions with examples
38%
Documented parameters
97%
Return-value docs
97%
Help pages citing references
0%

Downloads

1.8K
CRAN downloads in the past year
Rank #17,474 · ~5/day · ~149/mo
Daily download trend is not available in this view yet.
23230 days
73790 days
1.8K1 year
Compare downloads with other packages →
Also on48 r2u5 autocran

Repository

21Stars
2Forks
7Open issues
0Open PRs
0Releases
306Commits
4Commit identities
306 commits · Last activity 2026-10-22 · +5% stars, 30d · Default branch at 0.7.1.76, ahead of CRAN 0.7.1 (checked 2026-10-21)
Responsiveness
How these are sampled
PRs merged (all time)
97%
Median days to close, 50 most recently updated closed issues
10
Median days to close, 50 most recently updated closed PRs
0

Stars over time

2026-01-31 · 12026-09-26 · 21
PracticesBeta

3 development-tooling and community-health practices detected across 2 families in the upstream repository

Checks run against github.com/cornball-ai/corteza on 2026-10-21.

Continuous integration (2)
GitHub ActionsR CMD check workflow

The R CMD check workflow runs on Linux and macOS

CRAN release process (1)
cran-comments.md
How this is detected·Detection ruleset v4 (2026-10-20)
AI coding toolsBeta

This repository shows signs of AI coding tools.

  • Claude Codefirst seen 2026-01-29
    Seen in the repository: CLAUDE.md
    Named in .Rbuildignore: .claude, CLAUDE.md
    Pull request it wrote: opened by a project member
    Commits: at least 43 crediting it in the message
Shared conventions any agent may read, so they name no particular tool.
Seen in the repository: AGENTS.md
From outside contributors
  • Claude Code
    Pull requests: 3 from outside contributors, first on 2026-05-07, 1 from forks
Models named in its commits
  • Claude Opus 4.540 commits · Jan to Feb 2026
  • Claude Opus 4.61 commit · Feb 2026
  • Claude Opus 4.81 commit · Sep 2026
  • Code 2.11 commit · May 2026
Counts are commits, not lines of code. Commits by a tool's accounts count once across all of its accounts. Commits crediting it are the largest count among its credit lines, a minimum.How this is detected·Detection ruleset v4 (updated 2026-09-27)

Dependencies

Declared dependencies
17 external dependencies (excludes base and recommended)

Installing corteza adds 12 packages (5 with compiled code, 2.8 MB of source tarballs). Heaviest: jsonlite 1.0 MB, curl 714 KB, digest 231 KB.

Depends (1)
R >= 4.4.0
LinkingTo (0)
none
Enhances (0)
none
Reverse dependencies
0direct
0indirect

Nothing depends on this yet.

People & History

People (4)
Author, Maintainer since 0.6.3 (2026)
Contributor · added in 0.6.9
Contributor · added in 0.6.9
Copyright holder
Releases (4)

Pick two releases to compare their code metrics.

  • 0.7.1Latest
    record
    2026-08-05 · current release · diff ↗
  • 0.7.0
    record
    2026-05-28 · diff ↗ ·
    added 2 exports
    matrix_run_init, matrix_run_step
  • 0.6.9
    record
    2026-05-28 · diff ↗ ·
    removed 4 exports
    cli_worker_drain_events, cli_worker_spawn, worker_dispatch, worker_tool_list
    added 19 exports
    context_limit_for_model, context_usage_pct, corteza_execute_in_chat, corteza_execute_in_chat_retain, default_provider_model, estimate_history_tokens, estimate_live_context_tokens, estimate_text_tokens, estimate_tool_tokens, format_age, format_live_ctx, format_tokens, subagent_collect, subagent_seed_history, subagent_turn_set_id, tool_collect_subagent, tool_exit_plan_mode, tool_task_create, tool_task_update
  • 0.6.3
    record
    2026-05-04
  • R
    R 4.6.0 released · 2026-04-24

Package metadata

First published
2026-05-04
Total releases
4 / 1 yrs
License
Apache License (>= 2)
Minimum R
≥ 4.4.0
Download size
944 KB

Cite

Cite this package

Run in R for the authors' preferred citation:

citation("corteza")
Hernandez, T., cornball.ai, Krzyzaniak, J., & McDermott, G. (2026). corteza: AI Agent Runtime (Version 0.7.1) [Computer software]. https://doi.org/10.32614/CRAN.package.corteza

This package has no citation file, so citation() returns this entry built from DESCRIPTION.

Cite the R Observatory

For a number measured here: a download total, a coverage figure, an archival date.

APA

Balamuta, J. J. (2026). R Observatory: Metrics for corteza version 0.7.1 [Data set]. HJJB, LLC. Data release v2026-10-24. https://doi.org/10.5281/zenodo.21843040

From data release v2026-10-24, which the citation names so these numbers can be found later. More on citing and the projects behind them.

Report a problem with this page →

Privacy choices

These apply to this browser and are stored on this device only. Nothing about your choice is sent to us.

Read the privacy policy