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 its neighbours are the one-prompt shape: a RunConfig in, a report out, with a workspace opened and dropped around it. They are wrappers over the same path — RunConfig::split is the seam — 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 context::ContextConfig;

pub use context::ContextDocument;

pub use context::ContextError;

pub use context::ContextScope;

pub use context::DEFAULT_CONTEXT_FILE;

pub use context::WorkspaceContext;

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 lifecycle::Cancellation;

pub use lifecycle::LifecycleError;

pub use lifecycle::Supervisor;

pub use lifecycle::TaskContext;

pub use lifecycle::TaskHandle;

pub use lifecycle::TaskId;

pub use lifecycle::TaskState;

pub use lifecycle::WaitError;

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 run::Bound;

pub use run::CollectingSink;

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::RunConfig;

pub use run::RunContext;

pub use run::RunError;

pub use run::RunReport;

pub use run::RunUsage;

pub use run::TaggedEvent;

pub use run::TaggedSink;

pub use run::TurnOptions;

pub use run::resume;

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

context

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

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.

lifecycle

Structured task ownership for attached agent work.

mcp

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

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

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.

Enums

BuiltinProvider

Builtin provider families Mentra can construct from presets.

ModelSelector

Selection strategy used when resolving a model from a provider.

ToolSideEffectLevel

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

Attribute Macros

async_trait