skills

type ConfigSnapshot ¶

type ConfigSnapshot struct {
	// Driver names the registered factory. Empty → DefaultDriver.
	Driver string
	// DSN is consumed by the `localdb` driver. Bare file path or
	// SQLite `file:` URI; the special `:memory:` sentinel is
	// honoured for tests. `secret:"true"` redaction lives at the
	// config-package boundary.
	DSN string
	// Retrieval opts in to a `Search` ranking mode. The zero value
	// keeps the FTS5 → regex → exact ladder; `RetrievalSemantic`
	// ranks by embedding similarity (requires `Deps.Embedder`).
	Retrieval RetrievalMode
}

ConfigSnapshot is the strict subset of `config.SkillsConfig` the skills package consumes. Keeping a snapshot decouples drivers from the config package's type evolution.

func SnapshotFromConfig(cfg config.SkillsConfig) ConfigSnapshot

type Deps ¶

type Deps struct {
	Bus      events.EventBus
	Embedder Embedder
}

Deps carries the runtime dependencies a skills driver needs.

`Bus` is mandatory so identity-rejection emits + audit events (`skill.upserted`, `skill.deleted`, `skill.pack_overwrite_refused`, `skill.search_executed`) land on the audit pipeline.

**Note** (analog): unlike memory drivers, skills drivers do NOT receive a `state.StateStore`. The `localdb` driver owns its own `skills` + `skills_fts` tables; persistent skill state lives in the driver's own DB, not piggybacked onto the StateStore. The Portico driver (post-V1) will fetch from a remote MCP surface and also has no StateStore need. `Embedder` is the injectable text→vector callable the semantic retrieval mode consumes. OPTIONAL — required only when `cfg.Retrieval == RetrievalSemantic`, ignored otherwise. A semantic config without an Embedder fails loudly at `Open` (mirroring the memory registry's Summarizer/Embedder rule) — never a stub fallback (AGENTS.md §13). Existing callers that construct `Deps{Bus}` keep compiling: the zero value is nil, valid for the default retrieval mode.

type Directory ¶

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

Directory exposes the virtual-directory snapshot. Built once at boot (or per operator-config reload); safe to share across N concurrent goroutines. Per-call state lives on ctx + the args; no mutable field on Directory itself changes after construction.

func NewDirectory(store SkillStore, deps Deps, cfg DirectoryConfig) (*Directory, error)

func (d *Directory) View(ctx context.Context, cap DirectoryCapability) ([]SkillView, error)

type DirectoryCapability ¶

type DirectoryCapability struct {
	// AllowedTools — the set of tool names visible to the run.
	// Used by the filter (subset check) AND the redactor (skills
	// referencing names not in this set get the disallowed-name
	// replacement in Title / Trigger).
	AllowedTools []string `json:"allowed_tools,omitempty"`
	// AllowedNamespaces — namespaces (Skill.RequiredNS) the run may
	// reference.
	AllowedNamespaces []string `json:"allowed_namespaces,omitempty"`
	// AllowedTags — tags (Skill.RequiredTags) the run may reference.
	AllowedTags []string `json:"allowed_tags,omitempty"`
}

DirectoryCapability mirrors the planner-supplied capability envelope the directory consults for filtering + redaction at View time. The shape is identical to internal/skills/tools.CapabilityContext; duplicating the type here avoids the import cycle (`internal/skills/ tools` imports `internal/skills` already). When a caller already holds a `tools.CapabilityContext`, the fields map one-to-one and the conversion is mechanical at the planner boundary.

Concurrent reuse: the struct is a value carried on the args; never mutated in-flight. Multiple goroutines may share a DirectoryCapability value safely.

type DirectoryConfig ¶

type DirectoryConfig struct {
	// Pinned is the operator-declared list of skill names to anchor
	// at the top of every View. Order is preserved across calls.
	// Names that don't exist under the calling identity are dropped
	// silently (config + storage may legitimately disagree; storage
	// wins).
	Pinned []string
	// MaxEntries caps the View length. 0 → DefaultMaxEntries (30).
	// Outside [1, 200] → NewDirectory returns wrapped
	// ErrInvalidConfig.
	MaxEntries int
	// Selection picks the unpinned-partition ordering. Empty →
	// SelectionPinnedThenRecent.
	Selection Selection
}

DirectoryConfig configures one Directory instance.

func DirectoryFromConfig(cfg config.SkillsConfig, fallbackMaxEntries int) DirectoryConfig

type Embedder ¶ added in v1.4.0

type Embedder interface {
	Embed(ctx context.Context, texts []string) ([][]float32, error)
}

Embedder is the injectable text→vector callable the semantic retrieval mode consumes — the consumer-side-interface shape the memory subsystem's `Summarizer` established. The canonical implementation is constructed via the embeddings factory (`internal/embeddings`); any `embeddings.Embedder` satisfies this interface.

Concurrent-reuse contract: one `Embedder` instance is safe to share across N concurrent goroutines. Implementers MUST honour `ctx.Done()`.

type Factory ¶

type Factory func(cfg ConfigSnapshot, deps Deps) (SkillStore, error)

Factory builds a `SkillStore` from a `ConfigSnapshot` + `Deps`. Drivers expose one `Factory` each via `init()` → `Register`.

type ListFilter ¶

type ListFilter struct {
	Scope    Scope
	TaskType string
	Tags     []string // any-of match against the skill's `Tags`
	Limit    int
	Offset   int
}

ListFilter narrows the rows `List` returns. Zero-value fields are matched as "any". Drivers cap `Limit` at 1000; `Limit == 0` falls back to the driver default (100).

type Origin ¶

type Origin string

Origin is the provenance of a skill — the pack import path or the in-runtime generator path. The two flavors share storage but their conflict semantics differ: a `Generated` skill MAY NOT overwrite a `PackImport` skill of the same name.

const (
	// OriginPack — imported from a Skills.md pack (lands the
	// importer). Pack rows are immutable from the generator's
	// perspective: `Upsert` refuses to overwrite with
	// `ErrPackOverwriteRefused` when incoming Origin != OriginPack.
	OriginPack Origin = "pack"
	// OriginGenerated — produced by the in-runtime generator
	// (`skill_propose(persist=true)`). Generated→Generated
	// is last-write-wins gated by `ContentHash` change.
	OriginGenerated Origin = "generated"
)

type RankedSkill ¶

type RankedSkill struct {
	Skill Skill
	Score float64
	Path  string
}

RankedSkill carries the search-time relevance score + the path that produced it. `Path` is one of `"fts5" | "regex" | "exact"`; callers (the planner tools) surface it for observability only — it is not part of the ranking math.

`Score` is the normalised 0.0–1.0 score:

• FTS5 path: `bm25 → 1/(1+raw) → min-max normalised`.
• Regex path: `name fullmatch=0.95 | name match=0.90 | name search=0.85 | body search=0.75`.
• Exact path: 1.0 (lowercase equality on `name | title | trigger | tags`).

type RetrievalMode ¶ added in v1.4.0

type RetrievalMode string

RetrievalMode declares the opt-in `Search` ranking shape.

const (
	// RetrievalDefault — the zero value: the token-savvy FTS5 →
	// regex → exact ladder.
	RetrievalDefault RetrievalMode = ""
	// RetrievalSemantic — rank by embedding similarity over the
	// identity-scoped catalog (result path `PathSemantic`). Requires
	// `Deps.Embedder` — no stub fallback. Capability filtering,
	// redaction, and the budgeter apply unchanged downstream.
	RetrievalSemantic RetrievalMode = "semantic"
)

type Scope ¶

type Scope string

Scope is the operator-declared visibility of a skill.

const (
	// ScopeSession — visible only inside the originating session.
	// The narrowest scope; cross-session visibility requires an
	// explicit promotion (RFC §6.7 "isolation
	// conformance"). The storage layer's identity filter already
	// pins rows to a `(tenant, user, session)` triple; ScopeSession
	// is the matching declared-scope marker for rows that should
	// stay session-local.
	ScopeSession Scope = "session"
	// ScopeProject — visible inside the operator-declared project
	// only. The generator default per RFC §6.7.
	ScopeProject Scope = "project"
	// ScopeTenant — visible to every project inside the same tenant.
	ScopeTenant Scope = "tenant"
	// ScopeGlobal — visible to every tenant. Reserved for operator-
	// managed shared skills.
	ScopeGlobal Scope = "global"
)

type Selection ¶

type Selection string

Selection picks the unpinned-partition ordering. Pinned skills always come first; Selection orders only the unpinned remainder (and the secondary ordering inside the Extra-pinned subset).

const (
	// SelectionPinnedThenRecent — pinned first, then most-recently-
	// updated skills (UpdatedAt DESC, Name ASC).
	SelectionPinnedThenRecent Selection = "pinned_then_recent"
	// SelectionPinnedThenTop — pinned first, then most-used skills
	// (UseCount DESC, Name ASC). Library-level only at V1.1.x: no
	// production path increments UseCount, so the OPERATOR config
	// validator rejects `skills.directory.selection: pinned_then_top`
	// as not-yet-wired. An
	// embedder that maintains UseCount through Upsert itself may use
	// this Selection directly.
	SelectionPinnedThenTop Selection = "pinned_then_top"
)

type Skill ¶

type Skill struct {
	Name           string
	Title          string
	Description    string
	Trigger        string
	TaskType       string
	Tags           []string
	Steps          []string
	Preconditions  []string
	FailureModes   []string
	RequiredTools  []string
	RequiredNS     []string
	RequiredTags   []string
	Origin         Origin
	OriginRef      string
	Scope          Scope
	ScopeTenantID  string
	ScopeProjectID string
	ContentHash    string
	CreatedAt      time.Time
	UpdatedAt      time.Time
	LastUsed       time.Time
	UseCount       int
	Extra          map[string]any
}

Skill is the canonical skill record. The struct is the storage envelope drivers persist; the planner-facing tools wrap it with capability filtering + redaction at injection time.

Validation rules at `validate`:

• `Name` non-empty
• `Trigger` non-empty (planner-visible match cue)
• `Steps` non-empty (at least one step)
• `Origin` ∈ {OriginPack, OriginGenerated}
• `Scope` ∈ {ScopeSession, ScopeProject, ScopeTenant, ScopeGlobal}

func (s Skill) Validate() error

type SkillDeletedPayload ¶

type SkillDeletedPayload struct {
	events.SafeSealed
	Name string
}

SkillDeletedPayload reports a successful delete. SafePayload by construction.

type SkillIdentityRejectedPayload ¶

type SkillIdentityRejectedPayload struct {
	events.SafeSealed
	Operation string
	Reason    string
}

SkillIdentityRejectedPayload mirrors `memory.MemoryIdentityRejectedPayload`. Operation is the rejected method name ("Upsert", "Get", "Search", "Delete", "List"); Reason is a short static string indicating which component was missing.

type SkillPackOverwriteRefusedPayload ¶

type SkillPackOverwriteRefusedPayload struct {
	events.SafeSealed
	Name           string
	ExistingOrigin Origin
	IncomingOrigin Origin
}

SkillPackOverwriteRefusedPayload reports a refused upsert against an existing `Origin=pack` row. `IncomingOrigin` names the offender; the store left the row untouched. SafePayload by construction.

type SkillSearchExecutedPayload ¶

type SkillSearchExecutedPayload struct {
	events.SafeSealed
	QueryHash string // first 16 hex chars of sha256(lowercased query)
	Path      string // "fts5" | "regex" | "exact"
	Limit     int
	ResultN   int
}

SkillSearchExecutedPayload reports a `Search` execution. `QueryHash` is a sha256 hex prefix of the lowercased query so repeated identical searches are correlatable for tracing without leaking the raw text. SafePayload by construction.

type SkillStore ¶

type SkillStore interface {
	// Upsert inserts or updates `skill` under the identity-scoped
	// `(tenant, user, session, scope, name)` key. Conflict policy
	// (RFC §6.7):
	//
	//   - existing.Origin == "pack" && skill.Origin != "pack" →
	//     `ErrPackOverwriteRefused` AND
	//     `skill.pack_overwrite_refused` emit. Row left untouched.
	//   - existing.Origin == "generated" && skill.Origin ==
	//     "generated" && existing.ContentHash == skill.ContentHash →
	//     idempotent no-op; emit a single `skill.upserted` for
	//     observability with `idempotent=true` payload field.
	//   - otherwise: last-write-wins; emit `skill.upserted` with
	//     `idempotent=false`.
	Upsert(ctx context.Context, id identity.Quadruple, skill Skill) error

	// Get returns the skill identified by `name` under the supplied
	// identity. Missing → `ErrSkillNotFound`.
	Get(ctx context.Context, id identity.Quadruple, name string) (Skill, error)

	// List returns the filtered, paged skills under the supplied
	// identity. Ordering is deterministic: `(UpdatedAt DESC,
	// Name ASC)`.
	List(ctx context.Context, id identity.Quadruple, filter ListFilter) ([]Skill, error)

	// Search returns up to `limit` skills ranked by the FTS5 →
	// regex → exact ladder. `limit == 0` falls back
	// to 20. The driver picks the first path that returns rows;
	// later paths run only when earlier ones produced nothing.
	// Emits `skill.search_executed` with the path that produced the
	// result.
	Search(ctx context.Context, id identity.Quadruple, query string, limit int) ([]RankedSkill, error)

	// Delete removes the named skill under the identity. Missing →
	// `ErrSkillNotFound`. Emits `skill.deleted` on success.
	Delete(ctx context.Context, id identity.Quadruple, name string) error

	// Close releases the driver's resources. Subsequent method
	// calls return `ErrStoreClosed`. Close is idempotent.
	Close(ctx context.Context) error
}

SkillStore is Harbor's mandatory skill-storage interface. A single surface; every V1 driver (`localdb` here; Portico post-V1) implements every method. No `Supports*` ceremony per AGENTS.md §4.4.

Identity-mandatory contract:

• Every method validates the identity `Quadruple` at the boundary. Empty tenant / user / session returns wrapped `ErrIdentityRequired` AND emits one `skill.identity_rejected` event on the bus.

Concurrent-reuse contract:

• One instance is safe to share across N concurrent goroutines. Mutable state is internally synchronised; per-call state lives in `ctx` and the supplied `Quadruple`, never on the driver.

func Open(_ context.Context, cfg ConfigSnapshot, deps Deps) (SkillStore, error)

func OpenDriver(name string, cfg ConfigSnapshot, deps Deps) (SkillStore, error)

type SkillUpsertedPayload ¶

type SkillUpsertedPayload struct {
	events.SafeSealed
	Name        string
	Origin      Origin
	Scope       Scope
	ContentHash string
	Idempotent  bool // true → existing row's hash matched; no write occurred
}

SkillUpsertedPayload reports a successful upsert. SafePayload by construction — all fields are bounded enumerable strings / ints / booleans; no caller-controlled bytes leak through.

type SkillView ¶

type SkillView struct {
	Name     string `json:"name"`
	Title    string `json:"title,omitempty"`
	Trigger  string `json:"trigger,omitempty"`
	TaskType string `json:"task_type,omitempty"`
	// Pinned is true when the skill was anchored by either
	// DirectoryConfig.Pinned (config-time) or Skill.Extra["pinned"]
	// (runtime-time). Surfaced for Console rendering; inert to the
	// planner's reasoning.
	Pinned bool `json:"pinned"`
}

SkillView is the planner-visible projection of a Skill returned by Directory.View. Four content fields plus a Pinned marker; the rest of the Skill is dropped at the boundary so the View is cheap to inject and Console-renderable without leaking storage-layer detail.