mast

package module
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 30, 2026 License: Apache-2.0 Imports: 26 Imported by: 0

README

mast

mast is folding into core-agent and is frozen (2026-10-30). go-steer now has one agent harness. mast's distinctive capabilities — the durable write gate and effect outbox, the per-call spend ledger, the scheduling lease, workload bundles and specialists, A2A, the monitoring cycle, the AX task-runner deployment — are landing in core-agent as features, tracked by go-steer/core-agent#1411 and designed in its docs/mast-fold-design.md. The decision and its evidence are on #596. This repository takes security fixes, plus what go-steer/shipmind still runs until it cuts over; v0.10.0 is the terminal feature release; there is no 1.0; the repository will be archived afterwards. New work starts in core-agent.

The agent-infrastructure substrate for unattended, library-embedded, multi-provider, durable agent workloads — built for platform and SRE teams deploying agents into Cloud Run, Kubernetes, and their own Go services. Lean fork of go-steer/core-agent, native to ADK v2.

Current release: v0.10.0 — the terminal feature release; nothing but security fixes follows it. Install, quickstarts, concepts, and the full reference live on the docs site. What changed: CHANGELOG. What's next: roadmap — which now points at core-agent.

Is mast for you?

Short answer, as of 2026-10-30: use core-agent. It is the one harness go-steer maintains, it already runs unattended on a cluster with approval gates, budgets, durable sessions and remote attach, and everything that made mast different is on its way there (#1411). Pick mast only if you are already running it and are waiting on a specific port; say so on the tracking issue so the port is sequenced for you.

The thirty seconds of honesty that used to be here — the long version is Why mast — is kept as the record of the job mast was built for, which is now core-agent's job:

  • Yes, if you're a platform / SRE team putting agents where no human is watching: incident triage in a Cloud Run pod, a scheduled drift monitor, runbook automation behind a webhook, an agent compiled into your own service.
  • No, if you want one simple agent loop in Go with no governance, durability, or operator surface. Use raw ADK v2; mast would be overhead. Come back when the loop must survive restarts, needs budget or permission governance, needs to switch providers without a rewrite, or stops having a human watching it.
  • No, if you're after an interactive coding tool for your laptop. Different product shape: mast runs agents in your infrastructure, not in your editor — no LSP integration, no AST tooling, no syntax-aware diff UI. A scope decision, not a gap.
  • Not the successor to core-agent, either. (2026-10-30: nor its sibling any longer — see the banner above. core-agent is the one harness.)
What installing it looks like today

mast is built to be a thing you install, not a service we run — that is a decision, recorded in docs/positioning.md. It is also a decision the product has not finished paying for, and the honest version before you start:

  • The install is a Helm chart — helm install mast oci://ghcr.io/go-steer/charts/mast --set gcp.projectID=…, plus scripts/setup-wif.sh for the GCP-side IAM. Release binaries, the container image and the chart are signed with keyless cosign and carry a SLSA build provenance attestation naming the commit and workflow they were built from. There is a Terraform module for the whole GKE install in examples/deploy/terraform/ — both halves in one apply, and the only form that can narrow an IAM grant it previously widened. There is still no Homebrew tap and no apt repo (#342).
  • Run one replica for anything scheduled. Extra replicas no longer duplicate the work — one instance takes a lease over the session store and drives the schedules, timed resumes and boot auto-resume, and the others log at ERROR that they are not — but they do not share it either: a passive replica never takes over, so a restart of the pod that died is what brings the cadence back (#345, takeover open as #403).
  • One mast, one tenant. There is no isolation scope on a workload bundle (#344).
  • Config drift is diagnosed, not reconciled. The ConfigMap name is stable and there is no hot reload, so an edit can land on disk and change nothing until you restart the pod. The daemon logs what it loaded and warns when the mounted files stop matching it (#343). There is no CRD, and that one is not a gap — see the doc.

The four pillars

  1. Unattended. Workload bundles declare specialists, tool catalogs, budgets, and HITL policy; webhooks and schedules dispatch turns; a behavioral watchdog and cost ceilings guard the loop. The operator surface is for looking in, not for babysitting.
  2. Library-embedded. mast.RunWorkload(ctx, ...) from inside your own service, with a CI-enforced slim-embed guarantee — pay only for what you import. The governance layer is the same code the daemon runs, not a reduced copy of it: the agent loop, the dispatch shapes, the write gate, the effect outbox, budget ceilings and the behavioral watchdog. What you do not get is the unattended plumbing around a turn — schedules, the monitoring cycle, notifications, auto-resume, drain and the operator listeners live in cmd/mast, not in pkg/, because a host service already has its own. You bring the trigger; mast brings the governance.
  3. Multi-provider. Two vendors — Gemini and Claude, each first-party or on Vertex — and the claim is substitutability, not the count. A specialist declares tier: small | mid | frontier rather than a vendor's model id, the same bundle runs on either backend with no code change, budget metering prices the (backend, model) pair, and a judged eval corpus runs nightly against both so "it still works over there" is measured rather than asserted. A third backend is #312 — and it is the first real test of whether tier: survives a vendor the abstraction was not designed against.
  4. Durable. Sessions live in SQLite or Postgres; approvals and pauses survive kill -9, pod restarts, and cluster migrations, then resume where they stopped — verified, not aspirational.

Audit and governance run through all four: an append-only event log behind every session, an operator gate in front of every mutating call, per-workload cost ceilings, and structured JSON logs with session correlation.

One combination is refused at startup rather than gated, and it is worth knowing before you write a bundle: a workload that enables the planner: and carries a change_executor specialist while hitl.on_mutation asks for approval. invoke_specialist runs its specialist on a runner it constructs itself, and the write gate and the effect outbox are runner plugins — so a mutating call made inside a planner dispatch would neither park nor dry-run, on a bundle that asked for both. The startup error names the specialist and the three ways out: run the same roster under dispatch: coordinator or dispatch: graph, where the gate reaches it, or set hitl.on_mutation: apply if those writes are genuinely meant to fire unattended (which records each dispatched mutation and stops none of them). That refusal is the design rather than containment — it closed #235 on the answer, not on a fix, because an approval comes back through the session event log and a dispatch's session dies with the tool call.

Quick start

Install the binary, then give it a provider — an API key or a Vertex project:

# Gemini API key
export GEMINI_API_KEY=...

# ...or Gemini on Vertex AI, on the service account's own credentials
export GOOGLE_CLOUD_PROJECT=my-project
export GOOGLE_CLOUD_LOCATION=global   # and run with --provider=vertex

# ...or Gemini on Vertex AI express mode: an API key, no project or location
export GOOGLE_GENAI_USE_VERTEXAI=true GOOGLE_API_KEY=...
# Unattended daemon: workload bundle + durable sessions + operator surface
mast --workload=examples/workloads/gke-triage \
     --provider=gemini \
     --session-db=/var/lib/mast/sessions.db \
     --attach-listen=127.0.0.1:8484

# One-shot, same binary: a task-class profile picks the model tier
mast --task=research --provider=gemini "what changed in the last deploy?"

# Operator surface
mast sessions list --session-db=/var/lib/mast/sessions.db

Claude is the same shape: --provider=anthropic with ANTHROPIC_API_KEY, or --provider=anthropic-vertex on the Vertex variables above. --provider alone picks the tier's model; --model pins a specific one; the -vertex half of a pair picks the backend. With neither, mast runs its built-in echo model — which is how the unattended triage quickstart walks the whole inject → approve → kill -9 → resume loop with no credentials and no network.

Point mast-web at the attach address for the browser operator UI. More walkthroughs: library embedding, forking a starter.

Repo Role
go-steer/core-agent Parent project and sibling product: the experimentation/integration substrate. Adapter packages port from here with per-file derivation headers.
go-steer/mast-web Operator-facing web UI over the attach protocol (works with mast and any attach-mode core-agent variant).
go-steer/core-tui Terminal UI for developer / experimentation workflows. Paired with core-agent, not mast.

Contributing

PRs against main; run dev/ci/presubmits/all.sh before pushing (CI runs the identical scripts). Architecture map: DESIGN.md. House rules: AGENTS.md. Scope questions resolve through the design corpus — check the resolved-decisions table before re-proposing something settled.

Early-access note: some sibling repos linked here are private during early access; those links may 404 until they open up.

License

Apache 2.0 — see LICENSE.

Documentation

Overview

Package mast is the top-level convenience API for embedding the mast agent runtime in a Go program — the 90% path for library-embedded consumers (docs/library-api-design.md, "Top-level convenience API"). It delegates to the pkg/ subsystems for everything; no type defined here duplicates a subsystem type: workloads are pkg/workload.Bundle, specialists are pkg/specialists.Spec, session projections are pkg/transcript values, budget ceilings are pkg/budget.Limits.

Stability

This package is one of the five stable-from-v0.1 surfaces (docs/library-api-design.md, import-surface table): it follows semver, and breaking changes get a deprecation cycle. The v0.1 surface is deliberately minimal — Config, Result, Run, RunWorkload, ListSessions, ResumeSession; server mode, lifecycle hooks, and option-func variants land in later versions.

Slim consumers

This is the batteries-included surface: it imports the dispatch subsystems (internal/graph, internal/router, internal/planner), several of which are denylisted for the slim-embed guarantee. Consumers who need the minimal dependency graph (docs/library-api-design.md, "Slim-embed guarantee") must NOT import this package — they compose the slim slice directly (internal/agent, pkg/specialists, optionally pkg/workload, pkg/budget, pkg/transcript), as examples/deploy/slim does.

Example

Programmatic bundle registration, no filesystem:

res, err := mast.RunWorkload(ctx, mast.Config{ModelName: "echo"},
    workload.Bundle{Name: "triage", Specialists: []string{"classify", "_fallback"}},
    []specialists.Spec{
        {Name: "classify", Mode: specialists.ModeSingleTurn, Instruction: "..."},
        {Name: "_fallback", Mode: specialists.ModeTask, Instruction: "..."},
    },
    `{"reason":"CrashLoopBackOff"}`)

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AckEffects added in v0.2.0

func AckEffects(ctx context.Context, cfg Config, sessionID, reason string) error

AckEffects records the operator's acknowledgement of ambiguous prior effects on a session: dangling mutating tool calls from an interrupted turn — persisted up to now — stop tripping the recorded-effect outbox's fail-closed refusal on subsequent turns (docs/durable-execution-design.md, "Recorded-effect outbox"). The caller asserts they checked whether those calls took effect externally. The library twin of `mast sessions resume --ack-effects`.

func IsWatchdogHalt added in v0.10.0

func IsWatchdogHalt(err error) bool

IsWatchdogHalt reports whether err — from Run, RunWorkload, ResumeSession or ResumeByToken — is the behavioral watchdog abandoning a runaway turn, which a bundle declaring `safety.watchdog: enforce` asks for. It sees through wrapping, so an error you annotate keeps its classification.

A halt is not a failure of the work so much as a refusal to keep paying for it: the turn was repeating itself. The budget's own stops are recognized the same way through pkg/budget's ErrExceeded and ErrRefused.

Why a function here rather than the watchdog package's own check: the watchdog is internal (#301), and what an embedder needs from it is this one answer, not its signals or postures.

func ListSessions

func ListSessions(ctx context.Context, cfg Config) ([]transcript.Summary, error)

ListSessions returns the operator projections (pkg/transcript) for every session in Config.Sessions under mast's app name: state (paused/aborted/idle), pending interrupt IDs, last-event times. Thin delegation to pkg/transcript's Store; use that package directly for detail views and abort markers.

func Pause added in v0.2.0

func Pause(ctx context.Context, cfg Config, sessionID string, spec transcript.PauseSpec) (transcript.PauseHandle, error)

Pause gate-pauses a session (plane B of the v0.2 pause/abort surface, docs/durable-execution-design.md "The v0.2 pause/abort mechanics"): every subsequent turn on the session — Run, RunWorkload continuations, ResumeSession — refuses until the pause is resumed with the returned handle's token via ResumeByToken. The pause takes effect at the turn boundary; a turn this process has in flight completes (library embedders own their turn contexts — cancel yours for a hard pause; PauseSpec.Interrupt is daemon machinery and is ignored here). The library twin of `mast sessions pause` / POST /pause.

func WithActor added in v0.10.0

func WithActor(ctx context.Context, name string) context.Context

WithActor returns ctx carrying the name of whoever is behind the call, for the library entry points that record one in an audit field. Today that is ResumeByToken, which writes it into the pause record's ConsumedBy and, on an interrupt resume with no response, into the default {"resumed_by": ...} verdict.

name is recorded as given. An embedder with an authenticated user passes whatever string it wants the audit trail to show — an email, a SPIFFE ID, "alice (asserted by sa:relay)". An empty name is the same as not calling WithActor: the entry point names its own mechanism instead ("library ResumeByToken"), because a caller-less context is an in-process path, not a failed lookup.

Why a string, and why this package owns it

This is the root package's only contact with caller identity, and the root is inside the v1.0 promise (DESIGN.md, "The v1.0 stability promise"). It used to read internal/auth's Caller off the context, which committed a frozen entry point to an unsupported package's context key — a dependency apidiff cannot see, because a context key is not part of any signature.

Caller identity is moving to go-steer/purser, shared with core-agent (docs/sibling-sync.md). purser is pre-1.0 and says its API will move when mast and core-agent migrate onto it, so naming its Caller here would freeze a type its owner has not frozen. DESIGN.md's rule for an input the consumer constructs, from a dependency already scheduled to change, is to own a narrow interface instead; everything the audit field has ever recorded is one string, so that is the interface. An embedder whose HTTP stack puts a purser Caller on the request context copies it across in one line.

Types

type Config

type Config struct {
	// Model is an explicit ADK model to drive every agent. Takes
	// precedence over ModelName. Use this to inject a custom or fake
	// model.LLM.
	Model model.LLM

	// ModelName constructs a built-in model when Model is nil: "echo"
	// (in-process fake, no credentials — the testing surface) or a
	// "gemini-*" model id (Vertex/Gemini via ADK). It also selects the
	// usage pricing rate; when Model is set and ModelName is empty,
	// pricing falls back to Model.Name().
	ModelName string

	// Sessions is the ADK session service runs execute against. Nil
	// means a fresh in-memory service per call — no durability, and no
	// resume across calls. Pass a shared service (ADK's
	// session/database over SQLite/Postgres, or one InMemoryService
	// reused across calls) to get durable pause/resume and
	// ListSessions.
	Sessions adksession.Service

	// Logger receives construction and turn logs. Nil disables
	// logging.
	Logger *slog.Logger

	// Budget overrides the budget ceilings for the run. Nil derives
	// limits from the workload bundle's budget block (Run has no
	// bundle, so nil means unlimited). A zero RatePer1K is filled from
	// the model's flat spike pricing so Result.Usage.CostUSD is never
	// silently zero-rated.
	Budget *budget.Limits

	// FinalReport grants a specialist stopped by a ceiling one model
	// call to write its report with, with every other tool withdrawn.
	// It is a separate knob from Budget because it is a policy and not
	// a ceiling: a bundle that declares budget.final_report gets it
	// whether or not the caller overrode the ceilings above. See
	// pkg/budget/finalreport.go.
	FinalReport bool
}

Config bundles the common knobs for Run/RunWorkload/ResumeSession. The zero value is not runnable: a model (Model or ModelName) is required. Everything else defaults sensibly — in-memory sessions, no logging, bundle-derived budget.

type Result

type Result struct {
	// Output is the turn's final output: the last node output or model
	// text the runner emitted. When the turn parked on a HITL
	// interrupt, Output holds whatever the run produced before
	// pausing; inspect ListSessions for the pending interrupt.
	Output string

	// SessionID identifies the session the turn ran in. Pass it to
	// ResumeSession (with a durable Config.Sessions) to continue a
	// paused run.
	SessionID string

	// Usage is the session's cumulative usage after the turn.
	Usage Usage

	// Exhausted lists the specialists whose own ceilings can no longer
	// admit a call, with the arithmetic behind each.
	//
	// A specialist here did not stop the run: it was refused, the
	// coordinator was handed that refusal as an answer and routed on, and
	// the turn finished normally (v0.6 W10.3). That is the point of a
	// per-specialist cap, and it is also why this field exists — a run
	// that quietly lost half its roster returns the same nil error as one
	// that did not, and an unattended caller has nowhere else to find out.
	// The workload's own ceiling is not reported here; it comes back as an
	// error, because there is nothing left to route to.
	Exhausted []budget.Trip
}

Result is the outcome of one library-run turn.

func ResumeByToken added in v0.2.0

func ResumeByToken(ctx context.Context, cfg Config, bundle workload.Bundle, specs []specialists.Spec, token string, response any) (*Result, error)

ResumeByToken resumes a pause by its resume token (minted by Pause, by the planner's pause_session tool, or by a graph RequestInput helper). A gate-pause resume clears the gate and runs no turn — nothing was parked; the returned Result carries only the session ID. An interrupt-pause resume drives the normal resume turn (response nil defaults to {"resumed_by": <the WithActor name, or "library ResumeByToken">}, the same string recorded as the pause record's ConsumedBy — name a logged-in user on ctx with WithActor and the audit record names them), and the token is consumed once the resume FunctionResponse is durably appended — a turn that fails before the append leaves the token live for retry. Expired tokens refuse with transcript.ErrTokenExpired (the pause remains); replays refuse with transcript.ErrAlreadyResumed. The library twin of `mast sessions resume --token`.

func ResumeSession

func ResumeSession(ctx context.Context, cfg Config, bundle workload.Bundle, specs []specialists.Spec, sessionID, interruptID string, response any) (*Result, error)

ResumeSession feeds an operator verdict back into a session that parked on a HITL interrupt (a durable RequestInput; see transcript.Detail.Pending for pending interrupt IDs and response schemas). bundle and specs must describe the same workload the session was started with — the resume turn is executed by a runner over the same root shape — and Config.Sessions must be the service (or database) holding the session.

The wire shape is the spike-2-verified resume contract: a user turn carrying a FunctionResponse whose ID equals the pending interrupt ID, with response under the "response" key. Sessions carrying an operator abort marker are refused.

func Run

func Run(ctx context.Context, cfg Config, instruction, input string) (*Result, error)

Run is the single-agent convenience: one Chat-mode agent with the given system instruction, one turn on input. No workload, no specialists, no dispatch — the "hello world" of embedding mast.

func RunWorkload

func RunWorkload(ctx context.Context, cfg Config, bundle workload.Bundle, specs []specialists.Spec, input string) (*Result, error)

RunWorkload executes one turn of a programmatically-registered workload: bundle and specs are plain values (the same types pkg/workload and pkg/specialists loaders produce from files — no filesystem is touched here), input is the turn's user message.

The dispatch shape is chosen from the roster, mirroring cmd/mast's semantics: the supervisor-body planner when bundle.Planner.Enabled; the workflow-graph LLM-as-router when the roster carries a SingleTurn classifier and a "_fallback" Task specialist; the SubAgents coordinator otherwise.

The bundle's budget block (or Config.Budget) is enforced while the turn streams; crossing a ceiling aborts the run with an error wrapping budget.ErrExceeded. bundle.Budget.MaxWallclockSeconds bounds the whole turn.

type Usage

type Usage struct {
	// Tokens is the total token count across all model calls.
	Tokens int64
	// CostUSD is the derived cost (flat spike pricing; see pkg/budget).
	CostUSD float64
	// ModelCalls is the number of model calls ("turns" in mast's
	// budget vocabulary).
	ModelCalls int
}

Usage is the run's cumulative usage snapshot, taken from the pkg/budget meter after the turn completes.

Directories

Path Synopsis
Package cli is the mast binary, for building your own.
Package cli is the mast binary, for building your own.
cmd
mast command
Command mast is the entry point for the mast agent runtime.
Command mast is the entry point for the mast agent runtime.
dev
pricing-diff command
Command pricing-diff prints core-models' built-in price table, one sorted line per row, for dev/ci/pricing-diff.sh to diff between two pins.
Command pricing-diff prints core-models' built-in price table, one sorted line per row, for dev/ci/pricing-diff.sh to diff between two pins.
upstream-drift command
Command upstream-drift reports how far mast's ported files have fallen behind the go-steer/core-agent commits they were copied from.
Command upstream-drift reports how far mast's ported files have fallen behind the go-steer/core-agent commits they were copied from.
examples
deploy/ax/entrypoint command
Command ax-mast-entry runs a one-shot mast turn as an AX task command.
Command ax-mast-entry runs a one-shot mast turn as an AX task command.
deploy/slim command
Command slim is the reference consumer for the slim-embed guarantee (docs/library-api-design.md, "Slim-embed guarantee"): a single-file host service embedding exactly one mast control loop in-process — a SingleTurn classifier feeding one Task specialist — with in-memory sessions and nothing else.
Command slim is the reference consumer for the slim-embed guarantee (docs/library-api-design.md, "Slim-embed guarantee"): a single-file host service embedding exactly one mast control loop in-process — a SingleTurn classifier feeding one Task specialist — with in-memory sessions and nothing else.
workflows/fan-out-fan-in command
Command fan-out-fan-in is the forkable starter for workflow shape #1 (fan-out-fan-in) from docs/workflow-scaffolding-design.md:
Command fan-out-fan-in is the forkable starter for workflow shape #1 (fan-out-fan-in) from docs/workflow-scaffolding-design.md:
workflows/llm-as-router command
Command llm-as-router is the forkable starter for workflow shape #7 (LLM-as-router) from docs/workflow-scaffolding-design.md:
Command llm-as-router is the forkable starter for workflow shape #7 (LLM-as-router) from docs/workflow-scaffolding-design.md:
internal
a2a
Package a2a implements the v0.1 synchronous A2A client from docs/a2a-design.md ("Mast as A2A client", client-only phasing row): agent-card discovery and caching, JSON-RPC 2.0 message/send on the single A2A v0.3 endpoint (A2A-Version header, bearer auth from an env-var reference), direct-message and task-opened reply handling with bounded tasks/get polling to a terminal state, and tasks/cancel on caller cancellation.
Package a2a implements the v0.1 synchronous A2A client from docs/a2a-design.md ("Mast as A2A client", client-only phasing row): agent-card discovery and caching, JSON-RPC 2.0 message/send on the single A2A v0.3 endpoint (A2A-Version header, bearer auth from an env-var reference), direct-message and task-opened reply handling with bounded tasks/get polling to a terminal state, and tasks/cancel on caller cancellation.
agent
Package agent provides the bucket-1 shim over ADK v2's runner and llmagent primitives.
Package agent provides the bucket-1 shim over ADK v2's runner and llmagent primitives.
attach
Package attach implements live-tail + inject over HTTP/SSE for headless core-agent deployments.
Package attach implements live-tail + inject over HTTP/SSE for headless core-agent deployments.
attachadapter
Package attachadapter bridges a mast serve-daemon session into internal/attach's Registrant contract, so operator frontends (mast-web) can list, tail, and inject into sessions over the attach protocol.
Package attachadapter bridges a mast serve-daemon session into internal/attach's Registrant contract, so operator frontends (mast-web) can list, tail, and inject into sessions over the attach protocol.
auth
Package auth defines the per-caller identity primitive used by the multi-session attach layer.
Package auth defines the per-caller identity primitive used by the multi-session attach layer.
cli
Package cli is the mast binary: serve mode, one-shot mode, and the `mast sessions` / `mast stop` subcommands.
Package cli is the mast binary: serve mode, one-shot mode, and the `mast sessions` / `mast stop` subcommands.
compose
Package compose wires a workload bundle plus its specialist specs into a runnable root agent.
Package compose wires a workload bundle plus its specialist specs into a runnable root agent.
config
Package config implements v0.1 of the `.agents/` discovery and loading rules from docs/config-layout-design.md.
Package config implements v0.1 of the `.agents/` discovery and loading rules from docs/config-layout-design.md.
digest
Package digest consolidates the digesting primitives mast uses to keep large tool responses out of the parent context.
Package digest consolidates the digesting primitives mast uses to keep large tool responses out of the parent context.
effects
Package effects implements the recorded-effect outbox (docs/durable-execution-design.md, "Recorded-effect outbox"): the runtime guard that makes mutating-tool re-execution ambiguity visible and blocking instead of silent, under mast's declared at-least-once contract.
Package effects implements the recorded-effect outbox (docs/durable-execution-design.md, "Recorded-effect outbox"): the runtime guard that makes mutating-tool re-execution ambiguity visible and blocking instead of silent, under mast's declared at-least-once contract.
envelope
Package envelope defines the on-the-wire payload shapes mast accepts on its inject endpoint.
Package envelope defines the on-the-wire payload shapes mast accepts on its inject endpoint.
evals
Package evals is the v0.3 parity harness: it loads the scenario corpus and the intent table, and (as the workstream lands) scores a recorded run against them.
Package evals is the v0.3 parity harness: it loads the scenario corpus and the intent table, and (as the workstream lands) scores a recorded run against them.
evals/cmd/evals command
Command evals runs the v0.3 parity eval suite (docs/v0.3-plan.md W0.4).
Command evals runs the v0.3 parity eval suite (docs/v0.3-plan.md W0.4).
evals/cmd/outcome command
Command outcome runs the O tier: the outcome evals (#297, docs/outcome-evals-design.md).
Command outcome runs the O tier: the outcome evals (#297, docs/outcome-evals-design.md).
evals/differentiators
Package differentiators holds the v0.3 eval scenarios that the upstream LangChain SRE harness structurally cannot express (docs/v0.3-plan.md W0.3).
Package differentiators holds the v0.3 eval scenarios that the upstream LangChain SRE harness structurally cannot express (docs/v0.3-plan.md W0.3).
evals/harness
Package harness is the runnable form of the v0.3 parity eval suite (docs/v0.3-plan.md W0.4): the thing scripts/evals.sh invokes and CI gates on.
Package harness is the runnable form of the v0.3 parity eval suite (docs/v0.3-plan.md W0.4): the thing scripts/evals.sh invokes and CI gates on.
evals/judge
Package judge is the metered tier of the v0.3 parity eval suite (docs/v0.3-plan.md W0.5): the 31-scenario corpus scored against a real model, which is the only tier that produces a LangChain-comparable number.
Package judge is the metered tier of the v0.3 parity eval suite (docs/v0.3-plan.md W0.5): the 31-scenario corpus scored against a real model, which is the only tier that produces a LangChain-comparable number.
evals/outcome
Package outcome is the O tier's corpus: the fixture-role catalog, the case schema, and the loader that refuses a corpus which cannot measure what it claims to.
Package outcome is the O tier's corpus: the fixture-role catalog, the case schema, and the loader that refuses a corpus which cannot measure what it claims to.
eventlog
Package eventlog is the durable, append-only audit log that backs agent.Agent's session.Service.
Package eventlog is the durable, append-only audit log that backs agent.Agent's session.Service.
federation
Package federation implements the v0.1 slice of docs/federation-design.md: the frozen Adapter interface, reference parsing for `<scheme>://<name>[/<skill>]` remote-agent references, a scheme-keyed adapter registry, and the planner-facing `invoke_remote_agent` tool.
Package federation implements the v0.1 slice of docs/federation-design.md: the frozen Adapter interface, reference parsing for `<scheme>://<name>[/<skill>]` remote-agent references, a scheme-keyed adapter registry, and the planner-facing `invoke_remote_agent` tool.
graph
Fan-out dispatch (docs/v0.3-plan.md W3): N analysts run concurrently over the same incident, one synthesis specialist merges what they return into a single report.
Fan-out dispatch (docs/v0.3-plan.md W3): N analysts run concurrently over the same incident, one synthesis specialist merges what they return into a single report.
inject
Package inject implements the HTTP endpoint that receives edge-trigger payloads (from k8s-event-watcher and any other source speaking the envelope.InjectPayload shape) and dispatches them into the mast runtime.
Package inject implements the HTTP endpoint that receives edge-trigger payloads (from k8s-event-watcher and any other source speaking the envelope.InjectPayload shape) and dispatches them into the mast runtime.
injectedauth
Package injectedauth supports running mast where Google credentials are added to outbound requests by an egress gateway instead of being held by the process, as in an Agent Substrate sandbox with credential injection.
Package injectedauth supports running mast where Google credentials are added to outbound requests by an egress gateway instead of being held by the process, as in an Agent Substrate sandbox with credential injection.
instruction
Package instruction loads project + user "agent memory" files (typically AGENTS.md) into the system prompt.
Package instruction loads project + user "agent memory" files (typically AGENTS.md) into the system prompt.
kvwindow
Package kvwindow is the one shape mast reports a model server's KV-cache activity in, and the one fold that sums windows, shared by GET /sessions/{id}/usage (internal/attach) and the judged eval board (internal/evals/harness) so the two cannot drift.
Package kvwindow is the one shape mast reports a model server's KV-cache activity in, and the one fold that sums windows, shared by GET /sessions/{id}/usage (internal/attach) and the judged eval board (internal/evals/harness) so the two cannot drift.
mcp
Package mcp wires MCP toolsets for the workloads mast runs.
Package mcp wires MCP toolsets for the workloads mast runs.
modelretry
Package modelretry waits out a provider that says "not now".
Package modelretry waits out a provider that says "not now".
modeltext
Package modeltext reads the caller-facing text out of a model response part (#370).
Package modeltext reads the caller-facing text out of a model response part (#370).
modeltier
Package modeltier classifies LLM model IDs into capability tiers (frontier / mid / small) used to tune behavior whose right setting depends on how powerfully the model reasons.
Package modeltier classifies LLM model IDs into capability tiers (frontier / mid / small) used to tune behavior whose right setting depends on how powerfully the model reasons.
monitor
The ack vocabulary (v0.5 W4.6) — the two argument names mast fills in when it forwards an operator's acknowledgement.
The ack vocabulary (v0.5 W4.6) — the two argument names mast fills in when it forwards an operator's acknowledgement.
notify
Package notify is the egress client for switchboard's outbound message ingress (v0.5 W4.5) — the half of unattended monitoring that speaks.
Package notify is the egress client for switchboard's outbound message ingress (v0.5 W4.5) — the half of unattended monitoring that speaks.
observability
Package observability holds mast's telemetry surface: the FIXED Prometheus metric registry, and env-gated OTel trace-export setup.
Package observability holds mast's telemetry surface: the FIXED Prometheus metric registry, and env-gated OTel trace-export setup.
permissions
Package permissions implements the central permission gate that decides whether each tool invocation may proceed.
Package permissions implements the central permission gate that decides whether each tool invocation may proceed.
planner
Package planner implements the v0.1 scaffold of the supervisor-body planner from docs/orchestration-design.md ("The planner", shape C with light D flavor): a Task-mode LlmAgent whose tool vocabulary is the workload's execution vocabulary.
Package planner implements the v0.1 scaffold of the supervisor-body planner from docs/orchestration-design.md ("The planner", shape C with light D flavor): a Task-mode LlmAgent whose tool vocabulary is the workload's execution vocabulary.
providers/mock
Package mock ships a credential-free scripted LLM provider for offline testing of agent flows.
Package mock ships a credential-free scripted LLM provider for offline testing of agent flows.
providers/usage
Package usage carries the provider-usage record that genai's UsageMetadata has no room for.
Package usage carries the provider-usage record that genai's UsageMetadata has no room for.
router
Package router assembles the top-level agent for a workload: a Chat-mode coordinator with the workload's specialists as SubAgents.
Package router assembles the top-level agent for a workload: a Chat-mode coordinator with the workload's specialists as SubAgents.
serverauth
Package serverauth holds the request-admission seams shared by mast's network server surfaces (A2A — internal/a2a; AG-UI — internal/agui): pluggable bearer authentication (TokenValidator → Principal, with per-surface scope checks) and pluggable rate limiting (RateLimiter, in ratelimit.go).
Package serverauth holds the request-admission seams shared by mast's network server surfaces (A2A — internal/a2a; AG-UI — internal/agui): pluggable bearer authentication (TokenValidator → Principal, with per-surface scope checks) and pluggable rate limiting (RateLimiter, in ratelimit.go).
toolcatalog
Package toolcatalog assembles the tool declarations a real mast turn puts in front of a model, and states what each one promises the model it accepts.
Package toolcatalog assembles the tool declarations a real mast turn puts in front of a model, and states what each one promises the model it accepts.
transcript
Operator acknowledgements — the durable half of the v0.5 W4.6 ack path (docs/v0.5-plan.md).
Operator acknowledgements — the durable half of the v0.5 W4.6 ack path (docs/v0.5-plan.md).
usagetrack
Package usagetrack folds a session's metered model calls into the token breakdown `GET /sessions/{id}/usage` promises.
Package usagetrack folds a session's metered model calls into the token breakdown `GET /sessions/{id}/usage` promises.
version
Package version centralizes build-identity reporting for cmd/mast and any surface that advertises the build (attach capabilities frames, agent cards).
Package version centralizes build-identity reporting for cmd/mast and any surface that advertises the build (attach capabilities frames, agent cards).
pkg
approval
Package approval is the write gate: the seam where a mutating tool call stops and waits for an operator (docs/v0.3-plan.md W2, hitl_policy.on_mutation).
Package approval is the write gate: the seam where a mutating tool call stops and waits for an operator (docs/v0.3-plan.md W2, hitl_policy.on_mutation).
budget
Package budget meters model usage against workload budget ceilings.
Package budget meters model usage against workload budget ceilings.
specialists
Package specialists loads specialist files from disk and turns them into ADK v2 agents.
Package specialists loads specialist files from disk and turns them into ADK v2 agents.
transcript
Package transcript is the operator's read projection over mast's sessions: list them, show one — its state, its pending interrupts, the edits and captures its approvals recorded — export its approval decisions, and look up a resume token.
Package transcript is the operator's read projection over mast's sessions: list them, show one — its state, its pending interrupts, the edits and captures its approvals recorded — export its approval decisions, and look up a resume token.
workload
Package workload loads workload bundles — the declarative operational profile for a mast deployment.
Package workload loads workload bundles — the declarative operational profile for a mast deployment.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL