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.
Today, before v1.0
Section titled “Today, before v1.0”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.
What v1.0 will cover
Section titled “What v1.0 will cover”These import paths follow semver from v1.0:
| Path | What lives there |
|---|---|
github.com/go-steer/mast | The library front door: Run, RunWorkload, ListSessions, ResumeSession, ResumeByToken, Pause, AckEffects, WithActor, IsWatchdogHalt. |
github.com/go-steer/mast/cli | The binary, for building your own: Main, and the options that add your models and tools. |
github.com/go-steer/mast/pkg/transcript | The 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/workload | Bundle types — the Go form of workload.yaml. |
github.com/go-steer/mast/pkg/specialists | Specialist spec, registry and loader. |
github.com/go-steer/mast/pkg/budget | Limits and the usage meter. |
Start from the library embed quickstart, which uses only these.
What it will not cover
Section titled “What it will not cover”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.
A covered path can drag one in
Section titled “A covered path can drag one in”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/transcripthands backapproval.Decisionrecords. Their shape is already public as themast.decision/v1JSON thatmast sessions export-decisionsemits, 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.Limitsused 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-methodbudget.Pricerinterface that the meter owns, andpkg/budgetimports 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.
The approval types covered by reference
Section titled “The approval types covered by reference”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 through | Covered |
|---|---|
Detail.AppliedEdits | approval.AppliedEdit |
Detail.Captures | approval.CaptureRecord |
(*Store).Decisions | approval.Decision |
Decision’s fields | approval.Outcome, approval.Scope, approval.Authority, approval.Disposition, and their constants |
CaptureRecord.Revert | approval.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.
Caller identity stays outside
Section titled “Caller identity stays outside”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.
The ADK version is part of the contract
Section titled “The ADK version is part of the contract”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.
Wire protocols version separately
Section titled “Wire protocols version separately”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 CLI is covered
Section titled “The CLI is covered”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>andmast stop. - Exit codes:
0the work completed;1the work was attempted and failed;2the invocation was rejected before any work started;3serve 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.
What v1.0 does not claim
Section titled “What v1.0 does not claim”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.