Struct Workspace 

pub struct Workspace { /* private fields */ }

One workspace, resolved: the runtime it borrows, the model, and everything discovered on disk, ready to mint runs from.

Held by reference by every run it mints, so a host keeps one per repository for as long as it wants to send prompts at it. Dropping it does not end the runs already minted — a PreparedRun owns its session — but the MCP connections go with it, and so does the runtime when this held the last Arc.

Send and Sync: the runtime is shared through Arcs and creates sessions from &self, so concurrent minting from one workspace needs no lock of basis’s own.

Implementations

impl Workspace

pub async fn open(path: impl Into<PathBuf>) -> Result<Self, RunError>

Opens path with basis’s defaults: a private runtime with the provider auto-detected from the environment, the newest model it offers, and every convention discovered where convention says to look.

builder is the same call with the knobs exposed — including with_runtime, for the host that opens many workspaces on one Runtime.

pub fn builder(path: impl Into<PathBuf>) -> WorkspaceBuilder

Configures a workspace before opening it.

pub fn prepare(&self, spec: impl Into<RunSpec>) -> Result<PreparedRun, RunError>

Mints a run: a fresh conversation against this workspace.

Synchronous, and deliberately so — everything expensive already happened. What this does is spawn a session on the existing runtime and hand back the PreparedRun that drives it.

The spec’s prompt may be empty. Once a session outlives a turn, a conversation with nothing said yet is a real state — it is what ACP’s session/new opens — so the emptiness check belongs where a prompt is actually sent, which is PreparedRun::execute and PreparedRun::send. (The free run keeps its own up-front check, because a one-shot caller that passed nothing wants to hear about it before a session exists.)

pub fn resume( &self, agent_id: &str, spec: impl Into<RunSpec>, ) -> Result<PreparedRun, RunError>

Picks up a conversation a previous process left behind.

agent_id is PreparedRun::agent_id, not the session id: mentra persists agents, and a session is one process’s view of one. Resuming replays the transcript from the store, so the first turn after this already knows everything the last one did.

The workspace has to be the one the conversation belongs to. Nothing here checks that — mentra’s store is keyed by agent, not by path — so resuming an agent under a workspace it never ran in gives it that workspace’s context and tools alongside its own history.

mentra does not persist a model’s context window (Agent::from_loaded always resumes at None — set_model is the only way back), so a resumed session starts with an unknown one. This reapplies this workspace’s own resolved model exactly when the resumed conversation is still on it and this resume is not also changing reasoning — the same model prepare would have minted — which restores mentra’s own compaction threshold as well as PreparedRun::context_window. A reasoning-changing resume leaves the window unknown so it performs one persisted mutation rather than two. A conversation PreparedRun::set_model had already moved elsewhere keeps whatever that call left it at instead: basis has no window for a model it does not resolve, and forcing this one back would silently undo a choice the caller made.

pub fn fingerprint(&self) -> Snapshot

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

The utility ADR-0014 kept when watch was deleted, on the type its ledger row promised it to. The semantics are crate::fingerprint’s verbatim: a digest over git ls-files plus HEAD, stat only, and every uncertain answer resolving to changed rather than unchanged.

Fingerprints the workspace as it is now, not as it was when the workspace was opened — that is the whole point, since a caller’s loop asks it repeatedly against one long-lived workspace.

Blocking: it spawns git and stats files. An async caller belongs on a blocking thread — tokio::task::spawn_blocking, or the equivalent.

pub fn path(&self) -> &Path

The path this workspace was opened with, which is what its runs are scoped to.

pub fn root(&self) -> &Path

The same directory as discovery resolved it, symlinks followed. What the run header reports, and what fingerprint reads.

pub fn model(&self) -> &str

The model every run from this workspace uses, resolved once.

pub fn provider(&self) -> &str

pub fn context(&self) -> &WorkspaceContext

The context documents discovered at open, weakest precedence first.

pub fn memories(&self) -> &[Memory]

The memories discovered at open, name-ordered, a workspace memory shadowing a global one of the same name.

Frontmatter only: the index in the system prompt is what a memory costs by default, and the body stays on disk for the model — or a host showing its user what the agent remembers — to read on demand. See crate::memory for the convention.

pub fn skills(&self) -> &[LoadedSkill]

The skills this workspace registered on the runtime, after layering.

Only what this workspace registered. The registry itself is the runtime’s and additive, so on a shared runtime a run may also be able to load_skill what a sibling workspace registered — an accepted consequence of sharing (see WorkspaceBuilder::open).

pub fn templates(&self) -> &[Template]

The prompt templates this workspace defines, after layering, name-ordered. Over ACP these become the client’s commands.

pub fn mcp_servers(&self) -> &[String]

The MCP servers connected at open, by the names that took effect — which is the configured name unless another workspace on the shared runtime already held it, in which case it carries a deterministic suffix. Names only: nothing here echoes a command or a credential.

pub fn declared_tools(&self) -> &[String]

The tools this workspace’s manifests declared, by name, after layering — this workspace’s own first, name-ordered within each manifest.

Names only, for mcp_servers’s reason: nothing here echoes a command or a credential.

pub fn config(&self) -> &Config

What config.json said about this workspace, and which file said it.

The answers here are already in force — the model below is what they resolved to — so this is for the host that reports its own configuration, or that wants to hand the same value to a shared Runtime’s builder rather than read the files twice.

pub fn config_files(&self) -> &[ContextFile]

The config files that took effect, most specific first.

Reported the way .mcp.json’s and .basis/tools.json’s sources are, and for a milder version of their reason: what this file decides — which model, which provider — a run already names in its own header, so the question left is which file said so, and a repository that resolved a model nobody expected should be able to find out in one place.

pub fn declared_tool_files(&self) -> &[ContextFile]

The tool manifests that took effect, most specific first.

A file that says which programs the model may run is the last thing that should apply invisibly, which is why discovery reports its sources the way .mcp.json’s does.

pub fn bind_host_tools( self, tools: Vec<Box<dyn ExecutableTool>>, ) -> Result<Self, RunError>

Binds this reusable generation’s complete checkout-specific host-tool set before its one independent mint.

Consuming makes every failure atomic to the caller: all names are validated against each other and the fresh runtime before the first registration; an unexpected late collision drops the entire generation rather than returning a partially bound workspace. An empty vector is meaningful and marks an explicitly tool-free checkout as bound. A bound tool must finish all work before its call returns; detached work owned only by the tool is outside the tracked reuse guarantee.

pub async fn rebuild_for_reuse(self) -> Result<Self, RunError>

Consumes a clean reusable generation and returns a newly built, prewarmed, unbound replacement.

Rebuild first seals the generation. Any live run, observer guard, detached event forwarder, or prior raw Mentra escape refuses reuse and consumes this entry. Workspace registrations are dropped before Basis demands unique ownership of the old runtime; that runtime is dropped before the provider factory for the replacement is called. Drop alone never invokes this method or the recipe.

This proves the lifecycle Basis owns: attached runs, observers, event forwarders, runtime registrations, and raw-access escapes. It does not claim to scrub Mentra team/background/spawn execution or host tools that detach their own work; strict reusable hosts exclude those names from their exact roster and await every custom-tool effect before returning.

pub fn mentra_runtime(&self) -> &Runtime

The mentra runtime the runs are minted on, for a host that wants mentra’s own surface — the task board, teams, the store — alongside basis’s.

The same bargain as PreparedRun::session: basis does not hide mentra, and reaching past basis’s surface is a supported thing to do rather than a workaround. Renamed from runtime() when ADR-0018 gave basis a Runtime of its own, so the name says whose surface comes back.

On a reusable workspace, calling this method permanently prevents the current generation from being rebuilt. The returned runtime can mint or retain state through handles Basis cannot count, so raw access and safe reuse are deliberately mutually exclusive for that generation.

Trait Implementations

impl Debug for Workspace

Hand-written because neither the runtime nor the registration is Debug material, and because the context documents hold whole files — a derived impl would dump them.

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.