Crate basis 

basis — the in-process SDK of basis, an embeddable agent harness built on Mentra.

This crate is the harness itself: workspace discovery (AGENTS.md, skills, templates, .basis/tools.json, .mcp.json), the run lifecycle, one event stream, and the seams a host plugs into (approval, hooks). It carries no protocol, no transport and no terminal code, so an embedder’s dependency graph states what they actually use (ADR-0011).

Embedding surfaces, in order of preference:

1. In-process: depend on this crate (Rust hosts).
2. ACP: basis-acp serves the Agent Client Protocol (JSON-RPC 2.0 over stdio) over this crate’s event stream, for editors and web UIs. It is reached from the binary with the explicit basis serve --acp command.
3. Subprocess: basis spawn --json streams JSONL events for scripts and CI; basis run remains a compatibility alias.

The core has no opinions: task-specific behavior enters through data — the prompt, the workspace (AGENTS.md, skills, templates, .mcp.json), and config — never through code in this crate.

Three shapes

Workspace is the SDK’s shape (ADR-0010). Opening one settles everything that belongs to a repository rather than to a prompt — context documents, the resolved model, skills, templates, hooks, MCP connections — and then mints runs from it without doing any of that again:

let workspace = basis::Workspace::open("/repo").await?;
let mut run = workspace.prepare("what does this repo do?")?;
let report = run.execute(basis::CollectingSink::default()).await?;

run and run_with_approver are the one-prompt shape: a path and a prompt in, a report out, with a workspace opened and dropped around it. They are wrappers over the same open-and-prepare — so nothing behaves differently for having gone through one.

Runtime is the process’s shape (ADR-0018), and only the N-repository host sees it: what changes when the host changes — provider and credential, the history store, the host’s interceptors — is built once and every workspace borrows it through an Arc. Workspace::open builds a private one behind the scenes, so the other two shapes never name it.

Features

• mcp (default) — .mcp.json discovery and the MCP binding of the tool contract. Built without it, the crate has no MCP concept at all: no McpConfig on a run, no servers registered, and a run header that names none (ADR-0012). Custom tools remain, because MCP was only ever one of the ways to reach them: tools::declared is core, and a workspace’s .basis/tools.json works in a build that has never heard of MCP.

Re-exports

pub use approval::AllowAll;

pub use approval::ApprovalAnswer;

pub use approval::ApprovalDecision;

pub use approval::ApprovalGate;

pub use approval::ApprovalRequest;

pub use approval::Approver;

pub use approval::DenyAll;

pub use branch::BranchError;

pub use branch::EntryKind;

pub use branch::TranscriptEntry;

pub use budget::BudgetPool;

pub use compaction::Compaction;

pub use config::CONFIG_SCHEMA_VERSION;

pub use config::Config;

pub use config::ConfigError;

pub use config::DEFAULT_GLOBAL_CONFIG_FILE;

pub use config::DEFAULT_WORKSPACE_CONFIG_FILE;

pub use config::Setting;

pub use context::ContextConfig;

pub use context::ContextDocument;

pub use context::ContextError;

pub use context::ContextScope;

pub use context::DEFAULT_CONTEXT_FALLBACK_FILE;

pub use context::DEFAULT_CONTEXT_FILE;

pub use context::SystemPrompt;

pub use context::WorkspaceContext;

pub use error::RunError;

pub use event::EVENT_SCHEMA_VERSION;

pub use event::Event;

pub use event::EventLine;

pub use event::JsonlWriter;

pub use event::Mutability;

pub use event::RunOutcome;

pub use event::SkillSummary;

pub use event::TemplateSummary;

pub use fingerprint::Fingerprint;

pub use fingerprint::Snapshot;

pub use hooks::HOOK_SCHEMA_VERSION;

pub use hooks::HookCall;

pub use hooks::HookConfigError;

pub use hooks::HookEvent;

pub use hooks::HookOutcome;

pub use hooks::HookRequest;

pub use hooks::HookResponse;

pub use hooks::HookRunner;

pub use hooks::HookSpec;

pub use hooks::HooksConfig;

pub use hooks::HooksSource;

pub use hooks::Interceptor;

pub use hooks::InterceptorError;

pub use hooks::OnFailure;

pub use mcp::DEFAULT_GLOBAL_MCP_FILE;

pub use mcp::DEFAULT_WORKSPACE_MCP_FILE;

pub use mcp::McpConfig;

pub use mcp::McpError;

pub use mcp::McpServer;

pub use mcp::McpSource;

pub use memory::MemoryConfig;

pub use memory::WorkspaceMemoryRoot;

pub use run::Bound;

pub use run::Bounds;

pub use run::CollectingSink;

pub use run::Compacted;

pub use run::Effort;

pub use run::EventFanIn;

pub use run::EventSink;

pub use run::FnSink;

pub use run::MergedEvents;

pub use run::NullSink;

pub use run::OutputReport;

pub use run::OutputSpec;

pub use run::PreparedRun;

pub use run::PromptPart;

pub use run::RunContext;

pub use run::RunReport;

pub use run::RunUsage;

pub use run::TaggedEvent;

pub use run::TaggedSink;

pub use run::TurnOptions;

pub use run::run;

pub use run::run_with_approver;

pub use runtime::Runtime;

pub use runtime::RuntimeBuilder;

pub use shell::ShellAccess;

pub use skills::SkillsConfig;

pub use skills::SkillsSource;

pub use store::PersistedSession;

pub use templates::Template;

pub use templates::TemplateError;

pub use templates::TemplateSource;

pub use templates::TemplatesConfig;

pub use tools::ChildContext;

pub use tools::ChildSpec;

pub use tools::SpawnTool;

pub use tools::declared::DEFAULT_GLOBAL_TOOLS_FILE;

pub use tools::declared::DEFAULT_WORKSPACE_TOOLS_FILE;

pub use tools::declared::DeclaredToolError;

pub use tools::declared::TOOLS_SCHEMA_VERSION;

pub use tools::declared::ToolsConfig;

pub use tools::declared::ToolsSource;

pub use workspace::RunSpec;

pub use workspace::ToolRoster;

pub use workspace::Workspace;

pub use workspace::WorkspaceBuilder;

Modules

approval

Asking before the agent does something consequential.

branch

Returning to an earlier point in a conversation.

budget

One token allowance, spent by several runs at once.

compaction

What a workspace’s agent forgets, and when.

config

.basis/config.json — what a repository says about which model runs in it.

context

Discovery of workspace context files (AGENTS.md and friends).

error

What can go wrong, named once at the root.

event

basis’s event stream: one schema, many surfaces.

fingerprint

A cheap stand-in for everything in the workspace a run could see.

hooks

Interception: a say over tool calls, from the host’s code or from the workspace’s.

mcp

Discovery of .mcp.json — the MCP servers a workspace wants connected.

memory

The memory directory convention — files, not a subsystem (D2).

provider

Choosing a provider and finding its credential.

run

One prompt against one workspace: the smallest complete thing basis does.

runtime

The process-scoped substrate every workspace borrows.

shell

Whether a run may execute commands.

skills

Discovery of the skills directories.

store

Where basis’s conversations are persisted, and how they are scoped.

templates

Discovery of prompt templates — the /command convention.

tools

The tool contract’s bindings that live in basis.

workspace

A workspace opened once, minting runs cheaply.

Structs

CancellationToken

The signal a caller trips to stop a turn.

ModelInfo

The per-turn steering seam, whole: the trait a host implements and every type its signatures make that host name.

ReasoningOptions

The per-turn steering seam, whole: the trait a host implements and every type its signatures make that host name.

RoundAdjustment

The per-turn steering seam, whole: the trait a host implements and every type its signatures make that host name.

RoundContext

The per-turn steering seam, whole: the trait a host implements and every type its signatures make that host name.

RoundToolResult

The per-turn steering seam, whole: the trait a host implements and every type its signatures make that host name.

Enums

BuiltinProvider

Builtin provider families Mentra can construct from presets.

ContentBlock

The per-turn steering seam, whole: the trait a host implements and every type its signatures make that host name.

ModelSelector

Selection strategy used when resolving a model from a provider.

ReasoningChange

The per-turn steering seam, whole: the trait a host implements and every type its signatures make that host name.

RoundBoundary

The per-turn steering seam, whole: the trait a host implements and every type its signatures make that host name.

RoundDecision

The per-turn steering seam, whole: the trait a host implements and every type its signatures make that host name.

ToolSideEffectLevel

How far outside this process a call reaches: nothing, this machine’s state, another process, or the world.

Traits

Provider

Transport-neutral interface implemented by model providers.

RoundStrategy

The per-turn steering seam, whole: the trait a host implements and every type its signatures make that host name.

Attribute Macros

async_trait