gomode

README

Go Mode

Go Mode provides a reusable host contract and a native Android shell for backend-hosted web applications. The repository contains the Go discovery handler, MCP and OAuth 2.1 transports, WebRTC voice gateway, generated API SDKs, and a SolidJS browser integration package.

Host applications own user accounts, authorization policy, product APIs, content, and the MCP tools and resources they expose. The Android app connects to a host through /.well-known/gomode.json and renders its web frontend.

Packages

• Go module github.com/maruel/gomode: discovery manifest and voice token contracts.
  • mcp/, oauth/, sse/: reusable HTTP protocol implementations.
  • voicegateway/: standalone or embedded WebRTC voice gateway.
• sdk/: generated TypeScript, Kotlin, and Swift protocol clients plus the Halo Android SDK.
• web/src/: @maruel/gomode SolidJS browser integration.
• android/gomode/: native WebView, voice, notifications, settings, and Halo shell.

See the server library guide to integrate a host. See on-device models for local-agent candidates and the LFM2.5-2.6B LiteRT export tooling.

Documentation

Overview

Package gomode defines Go Mode service discovery and voice token contracts.

Index

• Constants
• func EncodeServiceSigningPublicKey(k ed25519.PublicKey) (string, error)
• func IssueServiceScopedToken(c *ScopedTokenClaims, k ed25519.PrivateKey) (string, error)
• func NewHandler(settings *Settings) (http.Handler, error)
• func ParseServiceSigningPublicKey(s string) (ed25519.PublicKey, error)
• func SDKAPI() apispec.Config[string]
• type ErrorBody
• type ErrorResponse
• type LocationActivation
  • func (l LocationActivation) IsZero() bool
• type LocationWiFi
  • func (w LocationWiFi) IsZero() bool
• type PhysicalPosition
  • func (p PhysicalPosition) IsZero() bool
• type ScopedTokenClaims
  • func VerifyServiceScopedToken(token string, k ed25519.PublicKey, audience string) (*ScopedTokenClaims, error)
  • func (c *ScopedTokenClaims) Validate(audience string) error
• type Settings
  • func (s *Settings) Validate() error
• type SkillActivation
  • func (a SkillActivation) IsZero() bool
• type SkillFrontmatter
  • func (f *SkillFrontmatter) Validate() error
• type SkillGoMode
• type SkillMCPServer
  • func (s *SkillMCPServer) Validate() error
• type ToolGroup
  • func (g *ToolGroup) Validate() error
• type VoiceGatewaySettings
  • func (s *VoiceGatewaySettings) Validate() error
• type WebShellSettings

Constants

const ScopedTokenAudience = "voice-gateway"

ScopedTokenAudience is the expected audience for service-issued gateway tokens.

Functions

func EncodeServiceSigningPublicKey

func EncodeServiceSigningPublicKey(k ed25519.PublicKey) (string, error)

EncodeServiceSigningPublicKey returns the importable form of an Ed25519 public key.

func IssueServiceScopedToken

func IssueServiceScopedToken(c *ScopedTokenClaims, k ed25519.PrivateKey) (string, error)

IssueServiceScopedToken signs a short-lived service-scoped gateway token.

func NewHandler

func NewHandler(settings *Settings) (http.Handler, error)

NewHandler returns a Go Mode service metadata HTTP handler.

func ParseServiceSigningPublicKey

func ParseServiceSigningPublicKey(s string) (ed25519.PublicKey, error)

ParseServiceSigningPublicKey parses an imported Ed25519 public key.

func SDKAPI

func SDKAPI() apispec.Config[string]

SDKAPI returns the SDK generation specification for the Go Mode service discovery API.

Types

type ErrorBody

type ErrorBody struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

ErrorBody describes a Go Mode API error.

type ErrorResponse

type ErrorResponse struct {
	Error   ErrorBody      `json:"error"`
	Details map[string]any `json:"details,omitempty"`
}

ErrorResponse is the standard JSON error envelope for Go Mode SDK clients.

type LocationActivation

type LocationActivation struct {
	WiFi             LocationWiFi     `json:"wifi,omitzero"             yaml:"wifi,omitempty"`
	PhysicalPosition PhysicalPosition `json:"physicalPosition,omitzero" yaml:"physicalPosition,omitempty"`
}

LocationActivation groups one location-based activation signal for a skill.

func (LocationActivation) IsZero

func (l LocationActivation) IsZero() bool

IsZero reports whether the location activation has no trigger.

type LocationWiFi

type LocationWiFi struct {
	// SSIDs are Wi-Fi network names that can activate the skill.
	SSIDs []string `json:"ssids,omitempty,omitzero" yaml:"ssids,omitempty"`
}

LocationWiFi matches any one of the configured Wi-Fi SSIDs.

func (LocationWiFi) IsZero

func (w LocationWiFi) IsZero() bool

IsZero reports whether there are no Wi-Fi SSIDs.

type PhysicalPosition

type PhysicalPosition struct {
	// Name is a user-facing label for this physical position.
	Name      string  `json:"name"      yaml:"name"`
	Latitude  float64 `json:"latitude"  yaml:"latitude"`
	Longitude float64 `json:"longitude" yaml:"longitude"`
	// RadiusMeters is the activation radius around the latitude and longitude.
	RadiusMeters float64 `json:"radiusMeters" yaml:"radiusMeters"`
}

PhysicalPosition matches a named latitude and longitude within RadiusMeters.

func (PhysicalPosition) IsZero

func (p PhysicalPosition) IsZero() bool

IsZero reports whether no physical position is configured.

type ScopedTokenClaims

type ScopedTokenClaims struct {
	ServiceKind       string    `json:"serviceKind"`
	ServiceInstanceID string    `json:"serviceInstanceID"`
	BackendOrigin     string    `json:"backendOrigin"`
	Subject           string    `json:"sub"`
	Capabilities      []string  `json:"capabilities"`
	Audience          string    `json:"aud"`
	Expiry            time.Time `json:"exp"`
}

ScopedTokenClaims are the service-issued claims required to create a voice session.

func VerifyServiceScopedToken

func VerifyServiceScopedToken(token string, k ed25519.PublicKey, audience string) (*ScopedTokenClaims, error)

VerifyServiceScopedToken validates a service-scoped gateway token.

func (*ScopedTokenClaims) Validate

func (c *ScopedTokenClaims) Validate(audience string) error

Validate returns an error if c cannot authorize a service-bound voice session.

type Settings

type Settings struct {
	Service string `json:"service"`
	// ServiceVersion is the host product version. It is informational and does
	// not participate in Go Mode compatibility checks.
	ServiceVersion string `json:"serviceVersion,omitempty"`
	// APIVersion is the Go Mode discovery schema version. A client must reject
	// manifests with an API version it does not explicitly support.
	APIVersion int              `json:"apiVersion"`
	WebShell   WebShellSettings `json:"webShell"`
}

Settings is the service compatibility document consumed by Go Mode clients.

func (*Settings) Validate

func (s *Settings) Validate() error

Validate returns an error if s is not a well-formed Go Mode discovery manifest.

type SkillActivation

type SkillActivation struct {
	// Locations are local physical-location and Wi-Fi hints that make this skill
	// an activation candidate.
	Locations []LocationActivation `json:"locations,omitempty" yaml:"locations,omitempty"`
}

SkillActivation carries hints the shell matches against current context to decide when to load a skill. Matching is on-device: the service never receives the user's context or location just because a skill was considered.

func (SkillActivation) IsZero

func (a SkillActivation) IsZero() bool

IsZero reports whether activation hints are absent for json omitzero.

type SkillFrontmatter

type SkillFrontmatter struct {
	Name        string      `json:"name"        yaml:"name"`
	Description string      `json:"description" yaml:"description"`
	GoMode      SkillGoMode `json:"gomode"      yaml:"gomode"`
}

SkillFrontmatter is the YAML frontmatter schema for a Go Mode SKILL.md file.

The Markdown body carries human and model instructions. The frontmatter carries machine-readable activation hints and the MCP tool allowlist that the native shell can register when the skill becomes active.

func (*SkillFrontmatter) Validate

func (f *SkillFrontmatter) Validate() error

Validate returns an error if f is not a well-formed Go Mode skill frontmatter.

type SkillGoMode

type SkillGoMode struct {
	Activation SkillActivation  `json:"activation,omitzero" yaml:"activation,omitempty"`
	MCPServers []SkillMCPServer `json:"mcpServers"          yaml:"mcpServers"`
}

SkillGoMode contains Go Mode-specific SKILL.md frontmatter fields.

type SkillMCPServer

type SkillMCPServer struct {
	Name     string `json:"name"     yaml:"name"`
	Endpoint string `json:"endpoint" yaml:"endpoint"`
	// ProtocolVersion is the MCP protocol version spoken by this endpoint.
	ProtocolVersion string `json:"protocolVersion" yaml:"protocolVersion"`
	AuthRequired    bool   `json:"authRequired"    yaml:"authRequired"`
	// Tools is the explicit allowlist of MCP tool names activated by the skill.
	Tools []string `json:"tools" yaml:"tools"`
}

SkillMCPServer declares which tools from an MCP endpoint belong to one skill.

func (*SkillMCPServer) Validate

func (s *SkillMCPServer) Validate() error

Validate returns an error if s is not a well-formed skill MCP server entry.

type ToolGroup

type ToolGroup struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Endpoint    string `json:"endpoint"`
	// ProtocolVersion is the MCP protocol version spoken by this group endpoint.
	// The shell sends it on MCP requests so each group can be checked and
	// upgraded independently during protocol migrations.
	ProtocolVersion string `json:"protocolVersion"`
	AuthRequired    bool   `json:"authRequired"`
	// SkillURL points to the SKILL.md file whose frontmatter defines activation,
	// instructions, and the MCP tool subset for this skill.
	SkillURL string `json:"skillUrl,omitempty"`
}

ToolGroup describes a bootstrap MCP tool group advertised by the manifest.

A tool group is the compatibility manifest's compact view of a Go Mode skill. The authoritative context, activation hints, and tool subset live in the skill's SKILL.md frontmatter; the manifest stays small so clients can decide whether native features are compatible before loading skill files.

func (*ToolGroup) Validate

func (g *ToolGroup) Validate() error

Validate returns an error if g is not a well-formed tool group manifest entry.

type VoiceGatewaySettings

type VoiceGatewaySettings struct {
	Required      bool   `json:"required"`
	URL           string `json:"url,omitempty"`
	AuthRequired  bool   `json:"authRequired,omitempty"`
	TokenEndpoint string `json:"tokenEndpoint,omitempty"`
}

VoiceGatewaySettings describes the preferred voice gateway for this service.

func (*VoiceGatewaySettings) Validate

func (s *VoiceGatewaySettings) Validate() error

Validate returns an error if s is not a well-formed voice gateway manifest entry.

type WebShellSettings

type WebShellSettings struct {
	// BridgeVersion is the hosted-frontend/native bridge contract version. A
	// shell must reject manifests whose bridge version differs from the bridge
	// version implemented by that shell.
	BridgeVersion int                  `json:"bridgeVersion"`
	ToolGroups    []ToolGroup          `json:"toolGroups"`
	VoiceGateway  VoiceGatewaySettings `json:"voiceGateway"`
}

WebShellSettings describes the hosted frontend's native-shell contract.