harness

Documentation

Overview

Package harness is part of the GoFastr harness.

See docs/harness-architecture.md for the architecture this package implements.

Package harness is the top-level composition of the GoFastr harness. The Harness struct wires the subsystems New() actually constructs today: the control multiplexer + resource catalog, the context reader, the skill registry, the built-in tool registry + permission engine, the credstore + in-process credential helper, the OpenRouter + ZAI providers, the SQLite session store, the file-based memory store, and the hook runner. See docs/harness-architecture.md for the full design (much of it not-yet-built) and § Lifecycle / boot for what is and is not wired.

What New() does NOT do (owned by the CLI subcommand or a later phase): it runs no TOFU ack gate on context or skill files, their SHA-256 hashes are computed and stored but never compared against an approval store; it does not spawn MCP servers (the mcpclient package exists but is not wired into New); and it does not start the control plane transports or the bundled TUI/web clients, which the `gofastr harness` subcommand owns.

Index

• type Config
• type Harness
  • func New(cfg Config) (*Harness, error)
  • func (h *Harness) CreateSession(prov provider.Provider, model string) ids.SessionID
  • func (h *Harness) Shutdown() error

Types

type Config

type Config struct {
	// Profile is the loaded profile (framework.toml or default.toml).
	Profile *profile.Profile

	// WorkingDir is the repo root (used for AGENTS.md walk-upward).
	WorkingDir string

	// XDGConfig and XDGState are the base config + state directories
	// (`~/.config/gofastr/harness/` and `~/.local/share/gofastr/harness/`).
	XDGConfig string
	XDGState  string

	// SkillSearchPaths overrides the default paths
	// (built-in + user-global + project-local).
	SkillSearchPaths []string

	// Logger is the operational logger.
	Logger *logging.Logger

	// AllowProjectHooks gates project-local hooks (§ TOFU rule 13).
	AllowProjectHooks bool

	// CredstorePass is the passphrase used to derive the credstore key.
	// In CI, prefer GOFASTR_HARNESS_MACHINE_KEY env var instead.
	CredstorePass string

	// MachineKey overrides passphrase-derived key (CI path).
	MachineKey []byte
}

Config is the input to New.

type Harness

type Harness struct {
	Config Config
	Logger *logging.Logger

	Providers []provider.Provider
	Tools     *tool.Registry
	Skills    *skill.Registry
	Memory    *memory.Store
	Hooks     *hook.Runner
	Sessions  session.Store
	Creds     credstore.Store
	Helper    helper.Helper
	Perms     *permission.Engine
	Context   *xcontext.Reader

	Mux     *multiplex.Mux
	Catalog *resources.Catalog
	// contains filtered or unexported fields
}

Harness is the composed v0.1 system.

func New

func New(cfg Config) (*Harness, error)

New runs the boot sequence and returns a Harness ready to drive sessions.

func (*Harness) CreateSession

func (h *Harness) CreateSession(prov provider.Provider, model string) ids.SessionID

CreateSession wires a fresh EngineRun bound to the given provider. Returns the SessionID for the caller to attach clients to.

func (*Harness) Shutdown

func (h *Harness) Shutdown() error

Shutdown releases resources held by the Harness. It tears down every per-session run created by CreateSession (cancelling the persistLoop context, closing the engine bus so subscriptions drain, and unregistering the engine from the mux + catalog) before closing the session store.