agentfs

type AgentDef ¶

type AgentDef = tool.AgentDef

AgentDef is the pure value object for one agent definition. Phase C2 moved the type WHOLESALE (minus the old Path locator, plus the Origin tier label) to engine/tool as the payload of the tool.AgentDefSource port; this alias keeps every existing literal and signature in this adapter and its consumers compiling unmodified. Where a def was discovered is now the adapter-private detail channel (Discovered.Detail / Registry.Detail), never a field on the value object.

type AgentMCPServer ¶

type AgentMCPServer = tool.AgentMCPServer

AgentMCPServer is one entry of a def's `mcpServers` (reference or inline streamable-HTTP server). Moved to engine/tool alongside AgentDef; aliased here for compatibility (see AgentDef).

type AgentSource ¶

type AgentSource interface {
	Agents(ctx context.Context) ([]Discovered, []SkipError, error)
}

AgentSource is the pluggable EXTENSIBILITY POINT for where agent definitions come from. A Source produces a set of Discovered entries (the AgentDef value object + its adapter-private Detail) together with non-fatal diagnostics (SkipError), and a fatal error only for a genuine infrastructure fault that prevented the source from being consulted at all.

It is the verbatim shape of skills.Source: the local-OS-filesystem layout (DirSource) is just ONE implementation; an embedded default set or a remote registry would satisfy the same interface and slot in via MultiSource without touching the consumer or the AgentDef value object.

Agents(ctx) returns:

• the discovered defs (deterministically ordered by the implementation),
• the non-fatal diagnostics (skipped/duplicate/truncated/shadowed entries),
• a non-nil error ONLY for a hard fault. An absent source (e.g. a missing directory) is "no defs", not an error — agent defs are opt-in.

func ResolveSources(opts ResolveOptions) []AgentSource

explicit (--agents-dir, in flag order)                   [highest]
  > project: <workspace>/.mecatl/agents, <workspace>/.claude/agents
    > user: $XDG_CONFIG_HOME/mecatl/agents (or ~/.config/mecatl/agents),
            ~/.claude/agents                                  [lowest]

type DirSource ¶

type DirSource struct {
	// Dir is the directory to scan. An empty or absent Dir yields no defs (opt-in).
	Dir string
	// Label is an optional human-readable name for this source (e.g. "project",
	// "user", "explicit"), surfaced in diagnostics (it prefixes each Discovered
	// entry's Detail). It does not affect discovery.
	Label string
	// Tier is the admission tier stamped onto every def this source produces
	// (AgentDef.Origin on the port). ResolveSources sets it per conventional
	// location; a zero Tier defaults to tool.AgentOriginExplicit (a
	// hand-constructed source is an operator-configured location).
	Tier tool.AgentOrigin
}

DirSource is the local-OS-filesystem implementation of AgentSource: it produces the defs laid out as <Dir>/<name>.md (flat files) under a single directory.

func (s DirSource) Agents(_ context.Context) ([]Discovered, []SkipError, error)

type Discovered ¶

type Discovered struct {
	Def    AgentDef
	Detail string
}

Discovered is one discovered agent definition together with its adapter-private locator string. The PORT value object (tool.AgentDef, the aliased AgentDef) carries no path/dir/root concept; Detail is the NON-PORT diagnostics channel a reviewer traces a def back through — "<label>: <path>" for a filesystem source, "driver: <target>" for a remote driver. It never crosses the tool.AgentDefSource port.

type FSSource ¶

type FSSource struct {
	// contains filtered or unexported fields
}

FSSource is the FILESYSTEM implementation of the tool.AgentDefSource port: a snapshot of the agent definitions discovered from the composed Source list (explicit dirs + conventional locations). The port carries no path/dir/root concept; the locator business the composition layer's diagnostics still need is exposed as adapter-public NON-PORT methods (Discovered/Detail).

SNAPSHOT SEMANTICS: discovery runs ONCE at construction (NewMultiSource over the given sources) and the defs are retained in memory, so ListAgentDefs is stable for the life of the source — the build-once trust-gate invariant (an untrusted workspace's project tier is gated at SOURCE CONSTRUCTION, in ResolveSources).

func (s *FSSource) Detail(name string) (string, bool)

func (s *FSSource) Discovered() []Discovered

func (s *FSSource) ListAgentDefs(_ context.Context) ([]AgentDef, error)

type MultiSource ¶

type MultiSource struct {
	// contains filtered or unexported fields
}

MultiSource composes an ORDERED list of Sources into one, with a defined precedence on name collisions and aggregated diagnostics.

PRECEDENCE (collision rule): EARLIER sources win. When two sources both produce a def with the same effective name, the one from the earlier source is kept and the later one is SHADOWED — dropped, with a SkipError notice. Callers order the slice highest-precedence-first; ResolveSources builds it as explicit > project > user.

A fatal error from ANY source is returned immediately (with the diagnostics gathered so far). Output is sorted by name for deterministic, cache-stable ordering.

func NewMultiSource(sources ...AgentSource) MultiSource

func (m MultiSource) Agents(ctx context.Context) ([]Discovered, []SkipError, error)

type Registry ¶

type Registry struct {
	// contains filtered or unexported fields
}

Registry is an immutable, name-indexed view of the discovered agent definitions: the ONE registry both consumers (the Subagent tool now; the team member factory in a later slice) share. It is built once at composition time from a resolved Source and never mutated thereafter, so it is safe to read concurrently.

Alongside the port-shaped defs it retains each def's adapter-private locator (Discovered.Detail), exposed via Detail for composition-layer diagnostics — the NON-PORT replacement for the old AgentDef.Path field.

func NewRegistry(defs []AgentDef) *Registry

func NewRegistryDiscovered(discovered []Discovered) *Registry

func (r *Registry) Detail(name string) string

func (r *Registry) Get(name string) (AgentDef, bool)

func (r *Registry) Len() int

func (r *Registry) List() []AgentDef

type ResolveEnv ¶

type ResolveEnv struct {
	Getenv      func(string) string
	UserHomeDir func() (string, error)
}

ResolveEnv abstracts the process environment so a resolver is testable with a fake home / XDG, without touching the real one. The composition root binds OSEnv (the real os funcs); tests pass a fake.

trimmed to the fields this adapter uses; the root xdgconfig.ResolveEnv also carries ReadFile for permconfig/soul.

mirrors internal/adapter/xdgconfig.ResolveEnv EXACTLY (minus ReadFile) — keep byte-identical; carried because engine must not import the root module (fstools precedent, #269).

type ResolveOptions ¶

type ResolveOptions struct {
	// Explicit are operator-configured directories (e.g. from a repeatable
	// --agents-dir flag), highest precedence, in the order given. Always honoured
	// regardless of Conventional.
	Explicit []string
	// Conventional, when true, adds the built-in conventional project- and
	// user-level locations (lower precedence than Explicit). Default false: a
	// strict opt-in.
	Conventional bool
	// Workspace is the session workspace root used to resolve the project-level
	// conventional paths. Only consulted when Conventional is true and non-empty.
	Workspace string
	// IncludeProjectTier, when true, admits the PROJECT-tier conventional locations
	// (<workspace>/.mecatl/agents, <workspace>/.claude/agents). The composition layer
	// sets it false when the workspace is UNTRUSTED (Workspace-Trust feature, Phase
	// 2a) so a cloned repo's project agent defs cannot steer the model before the
	// operator trusts it; the user-tier and explicit sources stay active regardless.
	// It gates ONLY the project tier. Mirrors skills.ResolveOptions.IncludeProjectTier.
	//
	// ZERO-VALUE NOTE: false by default; callers set it explicitly. Composition uses
	// the folded trust bool. Only Conventional==true makes the project tier eligible.
	IncludeProjectTier bool
}

ResolveOptions configures the known-path resolver. The zero value resolves NOTHING (no explicit paths, conventional set OFF) — discovery stays strictly opt-in unless the operator asks for it, since a def body steers the model.

type SkipError ¶

type SkipError struct {
	// Path is the <name>.md (or directory) the problem was found at.
	Path string
	// Reason is a short, human-readable description of the problem.
	Reason string
	// Fatal reports whether the def was DROPPED (true) or KEPT-but-ADJUSTED
	// (false, the zero value). See the type doc-comment.
	Fatal bool
}

SkipError records one diagnostic from discovery. It carries a structural two-way split via Fatal — NOT a string-matched one — so the composition root can word the log honestly instead of overloading "skipped":

• Fatal == true: the def was DROPPED (excluded from the registry). Causes: it could not be read, its frontmatter was malformed / missing a required field, a duplicate name within a directory, or it was SHADOWED by a higher-precedence source.
• Fatal == false (the zero value): the def was KEPT but ADJUSTED — a non-fatal modification was applied (e.g. its description/body was truncated to a cap, an mcpServers entry was skipped, or an unsupported memory tier was ignored). The def is still in the registry.

Discovery keeps scanning rather than aborting and returns the collected diagnostics so the composition root can surface them. A SkipError is never returned as a Source's fatal error.

func (e SkipError) Error() string