Control environments

Keep routine setup out of the model's way, and decide separately whether the model can inspect or repair an environment when something breaks. Lifecycle policy and management tools are independent choices.

Start with a working session and provider from Environments. The snippets below extend your existing sessions.create options; method names and input schemas come from your chosen provider.

Choose who starts the environment

Environments, including the host created for inline tools, use the automatic lifecycle by default. Leave the setting out for ordinary setup, or use environment.lifecycle to override specific bindings:

const session = await brain.sessions.create({
  agentloop: { name: "pi" },
  environment: { lifecycle: { bindings: { workspace: "manual" } } },
  model,
  tools,
});

• automatic runs setup when the session or instance is created.
• manual leaves the binding declared until an authorized caller runs setup. Calling a tool before then returns environment_not_ready without running it.

Place management tools somewhere independent of the environment they manage. The harness runs outside these Environments.

environment.lifecycle.default sets the policy for bindings without an override, and defaults to automatic. For example, environment: { lifecycle: { default: "manual" } } makes every binding manual.

Ending a session detaches environments that were set up; deleting it tears them down. The Env decides what those operations mean for its resources. Cleanup also applies after manual setup, so it never depends on the model remembering a final tool call. Failures never trigger automatic retries, replacement allocation or migration.

Optionally give the model control

Install @aexhq/env by following its package guide, then import it and grant only the operations it needs:

import { env } from "@aexhq/env";

const debug = env({
  environments: [{ environment: "workspace", permissions: ["read", "call"], methods: ["inspect"] }],
});
// Include debug in sessions.create({ agentloop: { name: "pi" }, tools: [debug, ...taskTools], ... }).

Like other inline tools, this Tool runs in your application's host by default. Leave out management Tools for fully managed operation, or include one for diagnostics or manual setup. Its name and package mean nothing special to Brain: you could write the same Tool with tool(...) and ctx.environments.

get reads Brain's recorded state; it isn't a health probe. For live inspection, call an Env method: ctx.environments.call(reference, "inspect", input). Each Env declares its own methods and schemas and may manage browser tabs, jobs or other resources through them. Brain has no universal resource API and no built-in env.inspect operation.

Use the shared service

Tools and environmentHandler operations use ctx.environments under their own grants. Custom harnesses use ctx.environments, and the session owner can call session.environments directly:

const views = await session.environments.list();
const workspace = views.find(view => view.reference.name === "workspace");
if (!workspace) throw new Error("workspace environment is missing");
await session.environments.setup(workspace.reference);
const health = await session.environments.call(workspace.reference, "inspect", {});

The service offers list, get, create, update, setup, delete and call. A reference is a name plus a declaration sequence. Hold on to the returned reference, and fetch current state after a replacement: old references can't control a new incarnation with the same name.

To allow dynamic instances, the application adds template: { max_instances, configuration_schema } to a binding and grants create. The count includes the original binding. New instances inherit its driver, methods, placement authority, lifecycle and grants, and can't pick a different URL, credential or implementation. update validates against the template schema and only works before the first setup attempt.

const extra = await session.environments.create("workspace", "second", { region: "eu" });
// Automatic templates set up extra immediately; manual templates leave it declared.
await session.environments.delete(extra.reference);

A custom harness with a read grant can list environments during a turn to discover new instances and their authorized tools. Dispatch includes environment_sequence from the current reference, and calls that were already admitted keep their original target. Bundled upstream adapters require a fixed Tool placement catalogue for a native session; dynamic catalogues require a custom harness.

Respond to failures

Brain records transport failures even when the tool never starts. Envs can also emit environment, resource and operation observations through their scoped reporter. These are durable data, and the Agentloop decides how to present them to the model. The official loops add them to context without dressing them up as successful tool results.

• Resource failures are scoped. Losing one resource doesn't make the whole environment unavailable.
• Uncertain operations hold capacity. An uncertain lifecycle operation keeps its instance capacity until the Env reports a resolution naming that operation.
• Replacement is explicit. A method declared with effect: "replace" changes the incarnation and requires idle execution. An extension can't replace its own environment.

Interrupting stops automatic activations until the next explicit message, and startup never replays effects or old activations. See the protocol for reporter lifetime and authorization, and Write an environment for authoring.