Documentation
¶
Overview ¶
Package embed lets mecatui host its OWN mecated server in-process when no external one is running, so a single `mecatui` binary "just works" with no separately-spawned daemon and no TCP port.
It assembles the harness via the SHARED composition layer (internal/app) — the exact same engine, tools, permission policy, and service the standalone mecated binary builds — and serves it over a per-process UNIX socket in a private temp directory. The TUI then dials that socket as an ordinary gRPC client, so the ui/theme/client packages stay pure: they never learn the server is in-process.
Architectural boundary: this package — like cmd/mecatui/client and the cmd/mecatui main — is the ONLY place in the TUI tree allowed to import contracts/gen, grpc, internal/app, internal/adapter/*, and the server adapter. The render packages (ui, theme) and the client package import none of it.
Index ¶
Constants ¶
const DefaultPerfAddr = "127.0.0.1:9099"
DefaultPerfAddr is the loopback default for the opt-in perf admin listener when PerfConfig.Enabled is set but Addr is empty. It is a FIXED, PREDICTABLE loopback port, chosen so an MCP-client config can hardcode the /mcp URL once and reconnect across restarts (an ephemeral ":0" port changes every run, so its URL is unknowable without scraping logs). It is distinct from mecated's own admin default (127.0.0.1:9090) so the two don't collide when co-running. If 9099 is unavailable, Start FAILS with guidance rather than silently falling back — pass --perf-addr 127.0.0.1:0 for an ephemeral port, or another host:port.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type PerfConfig ¶
type PerfConfig struct {
// Enabled turns the whole perf surface on. The zero value (false) means no
// telemetry, no admin listener, no flight recorder, no watchdog.
Enabled bool
// Addr is the loopback HTTP listen address for the admin mux. Empty defaults
// to DefaultPerfAddr (a fixed loopback port). The bound address (with the
// resolved port) is logged and exposed via Server.AdminAddr.
Addr string
// MCP mounts the read-only perf MCP server (internal/adapter/mcpperf) at /mcp on
// the embedded admin mux, so an agent can introspect THIS process's
// runtime/latency/profile state over MCP. Only meaningful with Enabled. The
// admin listener is loopback by construction (DefaultPerfAddr / a loopback Addr),
// and setupPerf FAILS CLOSED if a non-loopback Addr is configured with MCP set:
// the surface is UNAUTHENTICATED and can embed goroutine-derived names/timing
// (decision 6 / CWE-306). When set, a slow-turn ring buffer is wired into the
// embedded engine's sink so list_slow_turns sees real turns.
MCP bool
// GoroutineWarnThreshold arms the live goroutine-leak watchdog (decision 10):
// a background sampler logs slog.Warn whenever runtime.NumGoroutine() exceeds
// this count. 0 (default) disables the alarm; the runtime collector still
// exports the goroutine count as a /metrics series regardless.
GoroutineWarnThreshold int
// GoroutineWarnInterval is how often the watchdog samples NumGoroutine. <= 0
// falls back to the watchdog's own 30s default.
GoroutineWarnInterval time.Duration
// Logger receives the perf-surface startup/teardown lines and the watchdog
// alarms. Nil falls back to slog.Default().
Logger *slog.Logger
}
PerfConfig is the opt-in perf-observability configuration for the embedded server (decision 7 in docs/adr/0018-perf-observability.md). It is OFF by default (the zero value): mecatui hosts a bare gRPC socket with no telemetry, exactly as before. When Enabled, Start arms the SAME runtime-introspection surface mecated exposes — pprof, expvar, the runtime/RSS snapshot, and the execution FlightRecorder — on a loopback HTTP listener, plus the domain-metrics EventSink wired into the embedded engine so turn/tool/latency series render at /metrics.
The motivating incident (a render-starvation + memory-growth freeze in a since-removed tool) was a mecatui process freeze, so goroutines, RSS, pprof, and the flight recorder are exactly the instruments it needed — hence covering the embedded server, not just the standalone daemon.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is a mecated server hosted in the current process, listening on a UNIX socket. Close it to stop serving and release the socket, temp dir, and any composition-owned resources (the MCP manager) plus, when perf is enabled, the admin listener, the watchdog, the flight recorder, and the telemetry providers. It is safe to call Close once.
func Start ¶
Start builds the harness from cfg via internal/app and serves it over a fresh UNIX socket in a private temp directory. The returned Server's Target() is a gRPC dial string a client can connect to immediately (the listener is open before Start returns; serving runs on a background goroutine).
When perf.Enabled, Start ALSO installs the perf-observability surface (decision 7): it builds a telemetry MeterProvider + prometheus registry via the same telemetry.Setup path mecated uses, wires the domain-metrics EventSink into the embedded engine, registers the runtime collector + process-RSS gauge, arms the process-singleton FlightRecorder, optionally arms the goroutine watchdog, and serves the admin mux (/metrics, /debug/pprof/*, /debug/vars, /debug/flightrecorder) on a loopback HTTP listener. All of it is torn down by Server.Close, so an enabled perf surface never leaks a listener, a watchdog goroutine, or the flight recorder's runtime-trace subscription.
ctx governs the lifetime of composition-owned background work (MCP manager, memory consolidation) AND the perf watchdog; cancelling it does NOT stop the gRPC or admin servers — call Close for that. On any setup error Start cleans up everything it created before returning, so the caller never leaks a socket, temp dir, or telemetry resource.
func (*Server) AdminAddr ¶
AdminAddr returns the bound loopback address of the perf admin listener (/metrics, /debug/pprof, /debug/vars, /debug/flightrecorder), or "" when perf is disabled. With an ephemeral DefaultPerfAddr it reflects the actual chosen port, so a caller can log or display where to point a browser/pprof.
func (*Server) Close ¶
Close stops the gRPC server with a bounded graceful-stop window, tears down composition-owned resources with a separate bounded window, and (when perf was enabled) the admin listener, the watchdog, the flight recorder, and the telemetry providers, then removes the socket and its temp directory. It is safe to call once.
func (*Server) RecorderArmed ¶
RecorderArmed reports whether THIS server armed (and therefore owns + will stop) the process FlightRecorder. It is false when perf is disabled, when the recorder failed to start, or when this server coalesced onto a recorder another owner armed — including a second perf-enabled run in the same process after the first run stopped the process-singleton (the sync.Once cannot be re-armed). Tests use it to decide whether /debug/flightrecorder will serve a live snapshot.