mast

package module

v0.1.2 Latest Latest Go to latest Published: Jul 31, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/go-steer/mast

Links

Open Source Insights

README ¶

mast

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.

Status: v0.1.2 — Phase 1 complete; shutdown contract adversarially hardened. All eleven v0.1 exit criteria from docs/fork-design.md are green, including live-credential verification of the multi-provider one-shot path and attach-mode reachability from mast-web. Docs: go-steer.github.io/mast.

Is mast for you?

Thirty seconds of honesty before anything else:

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. You're in the right place; keep reading.
You're a developer who wants brilliant interactive coding at your laptop. Use Claude Code, Antigravity, or Cursor. That experience is downstream of model + IDE investment this substrate doesn't compete with — and doesn't try to.
You want one simple agent loop in Go — no governance, no durability, no operator surface. Use raw ADK v2; that niche is ADK's, and mast would be overhead. Come back when the loop must survive restarts, needs budget or permission governance, needs to switch providers without code changes, or stops having a human watching it.

The four pillars

Unattended. Runs without a human watching: workload bundles declare specialists, tool catalogs, budgets, and HITL policy; envelopes dispatch turns via webhook; watchdog + cost ceilings guard the loop; the operator surface (attach + mast-web, mast sessions) is for looking in, not for babysitting.
Library-embedded. A Go library first (mast.RunWorkload(ctx, ...) from your own service, with a CI-enforced slim-embed guarantee — pay only for what you import) and a standalone binary second (mast serve for Cloud Run / GKE / systemd). Same subsystems in both shapes.
Multi-provider. The same config runs Gemini or Claude (first-party or Vertex) — switch with a flag, not a rewrite. Task-class profiles pick sensible model tiers per job; budget metering prices both.
Durable. Sessions live in SQLite or Postgres via ADK's session store; HITL pauses survive kill -9, pod restarts, and cluster migrations, and resume where they stopped — verified, not aspirational.

Audit and governance run through all four: an append-only event log behind every session, permission gating, per-workload cost ceilings, and structured JSON logs with session correlation.

Quick start

# Unattended daemon: workload bundle + durable sessions + operator surface
mast --workload=examples/workloads/gke-triage \
     --session-db=/var/lib/mast/sessions.db \
     --attach-listen=127.0.0.1:8484

# One-shot, same binary: 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

Point mast-web at the attach address for the browser operator UI. Full walkthroughs — unattended triage, forking a workflow starter, library embedding — live on the docs site.

What ships in v0.1

Workflow-graph and SubAgents dispatch on ADK v2; specialists (subagent-as-tool with budgets and tool allowlists); workload bundles + .agents/ discovery; durable HITL; budget metering with cost and turn caps; the provider adapters (Gemini built-in-tool layer, Anthropic first-party + Vertex, Vertex context caching, scripted replay); the attach operator surface (HTTP/SSE) with mast-web reachability; sessions CLI; observability (Prometheus counters + env-gated OTel trace export); the synchronous A2A v0.3 client and federation interface; forkable workflow starters; Cloud Run / GKE deploy recipes. Details: CHANGELOG and the design corpus.

What `mast` is not

Not a Claude Code competitor — see the routing above; this is a deliberate scope decision, not a gap.
Not the successor to core-agent. Sibling products with different jobs: mast is the platform-agent runtime; core-agent stays the experimentation + integration substrate. Both are maintained.
Not a framework sampler. The interop surfaces (MCP now; A2A server, AG-UI in v0.2) exist so workloads compose with the ecosystem, not to chase every protocol.

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). House rules in 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 (pkg/graph, pkg/router, pkg/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 (pkg/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 ¶

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

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

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.

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
}

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
}

Result is the outcome of one library-run turn.

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.

Source Files ¶

View all Source files

mast.go

Directories ¶

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

Path	Synopsis
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.
examples
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
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.
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
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 pkg/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 pkg/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.
budget Package budget meters model usage against workload budget ceilings.	Package budget meters model usage against workload budget ceilings.
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.
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.
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 Package graph assembles the workload's triage flow as an explicit ADK v2 workflow graph — the LLM-as-router shape from docs/workflow-scaffolding-design.md (#7), as sketched in docs/triage-demo-plan.md:	Package graph assembles the workload's triage flow as an explicit ADK v2 workflow graph — the LLM-as-router shape from docs/workflow-scaffolding-design.md (#7), as sketched in docs/triage-demo-plan.md:
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.
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.
mcp Package mcp wires MCP toolsets for the workloads mast ships.	Package mcp wires MCP toolsets for the workloads mast ships.
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.
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.
pricing Package pricing resolves a model's per-million-token rates across a layered set of sources so usage costs stay accurate as new models ship and operators add overrides.	Package pricing resolves a model's per-million-token rates across a layered set of sources so usage costs stay accurate as new models ship and operators add overrides.
providers/anthropic Package anthropic adapts Anthropic / Claude to the ADK's model.LLM interface.	Package anthropic adapts Anthropic / Claude to the ADK's model.LLM interface.
providers/gemini Package gemini wraps an ADK Gemini model.LLM with the behavior mast needs for unattended operation: server-side built-in tool injection (Google Search / URL Context / Code Execution), Vertex explicit context-cache stamping, empty-response detection + retry, and cache-eviction recovery.	Package gemini wraps an ADK Gemini model.LLM with the behavior mast needs for unattended operation: server-side built-in tool injection (Google Search / URL Context / Code Execution), Vertex explicit context-cache stamping, empty-response detection + retry, and cache-eviction recovery.
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/vertexcache Package vertexcache owns the lifecycle of a single Vertex explicit context cache — Create at agent startup, Refresh on TTL pressure, Delete on session unregister.	Package vertexcache owns the lifecycle of a single Vertex explicit context cache — Create at agent startup, Refresh on TTL pressure, Delete on session unregister.
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.
specialists Package specialists loads specialist .tmpl files from disk and turns them into ADK v2 agents.	Package specialists loads specialist .tmpl files from disk and turns them into ADK v2 agents.
taskclass
transcript Package session is the operator-facing read/inspect surface over ADK's session store (docs/durable-execution-design.md, "Operator-facing surface").	Package session is the operator-facing read/inspect surface over ADK's session store (docs/durable-execution-design.md, "Operator-facing surface").
watchdog
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.

README ¶

mast

Is mast for you?

The four pillars

Quick start

What ships in v0.1

What mast is not

Related repos

Contributing

License

Documentation ¶

Overview ¶

Stability ¶

Slim consumers ¶

Example ¶

Index ¶

Constants ¶

Variables ¶

Functions ¶

func ListSessions ¶

Types ¶

type Config ¶

type Result ¶

func ResumeSession ¶

func Run ¶

func RunWorkload ¶

type Usage ¶

Source Files ¶

Directories ¶

What `mast` is not