Skip to content

Stability and versioning

mast is pre-1.0. Nothing on this page is a promise yet — it is the promise mast would have made at v1.0, published so you could decide what to depend on.

This page is the what. Compatibility and deprecations is the how: what counts as breaking, how long a deprecation lasts before the thing goes away, and how long a release is supported.

Every exported path may change in any release. In practice the paths listed below are the ones under active compatibility discipline and the ones least likely to move; the rest have changed between minor releases and will again.

Restarting version numbers at v0.1.0 is what dropped mast’s inherited API stability promises when it forked from core-agent. v1.0 is the release that makes them again — that, and nothing more, is what the number will mean.

These import paths follow semver from v1.0:

PathWhat lives there
github.com/go-steer/mastThe library front door: Run, RunWorkload, ListSessions, ResumeSession, ResumeByToken, Pause, AckEffects, WithActor, IsWatchdogHalt.
github.com/go-steer/mast/cliThe binary, for building your own: Main, and the options that add your models and tools.
github.com/go-steer/mast/pkg/transcriptThe operator’s read projection over sessions: list, show, export decisions, look up a resume token. Pausing and resuming go through the root package.
github.com/go-steer/mast/pkg/workloadBundle types — the Go form of workload.yaml.
github.com/go-steer/mast/pkg/specialistsSpecialist spec, registry and loader.
github.com/go-steer/mast/pkg/budgetLimits and the usage meter.

Start from the library embed quickstart, which uses only these.

Everything else. Most of it is not importable at all: the servers, providers, MCP, auth, pricing, the dispatch shapes and the rest of the runtime live under internal/, where Go refuses an import from outside the module.

One package under pkg/ is importable and still not supported: approval, apart from the types listed below. A minor release may change or remove the rest of it.

The direction is that you customize mast by writing your own main.go around the binary, not by importing its runtime packages; see #301. If you need something that is internal today, open an issue saying what you are building — a package with a named consumer is the kind that gets an extension point.

The list above is not quite a partition. If a covered package names a type from an unsupported one in an exported signature, that type is covered too, whatever this page says — you cannot change it without breaking the covered package.

The two lists have been reconciled, and there were two kinds of leak:

  • A type you only ever receive. pkg/transcript hands back approval.Decision records. Their shape is already public as the mast.decision/v1 JSON that mast sessions export-decisions emits, so it is committed either way, and a Go copy of it would just be a second name for one schema. These are listed as covered rather than replaced — see below.
  • A type you have to construct. budget.Limits used to take a *pricing.Catalog, which meant committing the catalog’s constructor, its config-discovery options and its rate struct — none of which is about budgets, and all of which is still moving as mast adds backends. The field is now a one-method budget.Pricer interface that the meter owns, and pkg/budget imports nothing else from mast.

The rule, if you are reading your own dependency on mast the same way: prefer receiving a type over constructing one.

Eight declarations from pkg/approval are covered at v1.0 because pkg/transcript hands them to you. The rest of pkg/approval is not.

You reach it throughCovered
Detail.AppliedEditsapproval.AppliedEdit
Detail.Capturesapproval.CaptureRecord
(*Store).Decisionsapproval.Decision
Decision’s fieldsapproval.Outcome, approval.Scope, approval.Authority, approval.Disposition, and their constants
CaptureRecord.Revertapproval.ProposedChange

Reading them is safe. Depending on anything else in pkg/approval — the write gate’s plugin, the grant machinery, the encoders — is not.

The list is enforced by a test that walks pkg/transcript’s exported declarations and follows their fields, so a new leak fails the build rather than quietly enlarging this page’s promise.

mast’s own auth and serverauth packages are internal for a specific reason: caller identity is moving to go-steer/purser, a library shared with core-agent, and when mast adopts it those two packages are deleted. That is meant to happen in a minor release, so nothing covered reaches them. Being internal is not enough on its own — Go lets an exported signature name an internal type, and a context key appears in no signature — so a test enforces it, counting a context key as well as a type in a signature.

For an embedder, that comes down to one call. To have ResumeByToken record who spent a token, name them on the context:

ctx = mast.WithActor(ctx, "alice@example.com")
res, err := mast.ResumeByToken(ctx, cfg, bundle, specs, token, nil)

The name is recorded as you give it. Without one, the audit record names the mechanism, library ResumeByToken. Setting auth.WithCaller worked before this change and no longer does: ResumeByToken stopped reading mast’s auth package when it moved out of the promise.

mast.Config takes two types from ADK, by design, so you can inject your own model or session store:

cfg := mast.Config{
Model: myModel, // google.golang.org/adk/v2/model.LLM
Sessions: mySessions, // google.golang.org/adk/v2/session.Service
}

Go’s semantic import versioning makes adk/v3/model.LLM a different type from adk/v2/model.LLM, so when mast moves to a new ADK major your code will not compile against it until you move too. That is a breaking change, so an ADK major bump ships as a mast major. Such a release carries no other breaking changes: the migration is your import paths and nothing else.

The attach, A2A and AG-UI surfaces and the inject endpoint are consumed by programs mast’s compiler never sees, so they do not follow mast’s Go major. They carry their own version information — the attach capabilities frame, the A2A agent card — and you should feature-detect against that, not against mast’s release number. A protocol addition will not force a Go major, and a Go major will not invalidate a client speaking the older frame.

The workload bundle schema versions independently for the same reason: it is edited by people who never import Go, and a new YAML key should not cost anyone a major upgrade. It carries a schema_version: of its own — currently 1, and omitting it means 1 — which moves when a key changes shape or meaning, not when a key is added.

The mast binary is a first-class consumer shape, and its callers are shell scripts, systemd units and Kubernetes manifests — none of which a compiler can warn. Promised from v1.0:

  • Flag names and their meanings.
  • Subcommands and their verbs — mast sessions <verb> and mast stop.
  • Exit codes: 0 the work completed; 1 the work was attempted and failed; 2 the invocation was rejected before any work started; 3 serve mode’s shutdown drain expired with sessions still interrupted (their work is durable but unfinished — this is the code to restart on).

Not promised, and safe to change in any release: log lines, stdout prose, --help wording, and metric names — which have no compatibility rule, despite what this page said until 2026-09-14. The metrics page is held to a real scrape in both directions, but that gate keeps the documentation honest; it does not protect a dashboard. A rename ships with a changelog entry and nothing more.

It is not a production-readiness badge. It says the API stops moving — and, through the compatibility policy, what it costs to move it anyway.

What backs the release today is an outcome-evaluation tier that gates every tag, per-version acceptance suites, and a cluster-permission matrix measured against live GKE. What does not exist yet is a published threat model — worth knowing for a product whose whole premise is an agent acting while nobody watches. Track it on the roadmap.