extension

package
v0.1.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 18, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package extension composes trusted, application-compiled Agent extensions into immutable runtime generations.

An Extension prepares declarative contributions. A Runtime validates the complete set, starts its lifecycles, and only then atomically publishes a Snapshot. Acquired Activations pin their generation until Release, so a reload never mutates an in-flight Agent or Harness.

This package is not a dynamic code loader or a process sandbox. Embedding applications decide which Go Extensions are compiled and registered.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalid reports an invalid descriptor, contribution, or runtime
	// configuration.
	ErrInvalid = errors.New("extension: invalid")
	// ErrCapabilityUnavailable reports a required capability not supplied by
	// the Runtime.
	ErrCapabilityUnavailable = errors.New("extension: capability unavailable")
	// ErrNotRegistered reports a requested Extension ID absent from the
	// Runtime's immutable registry.
	ErrNotRegistered = errors.New("extension: not registered")
	// ErrNotActive reports an Acquire call before the first successful
	// activation.
	ErrNotActive = errors.New("extension: not active")
	// ErrClosed reports an operation attempted after Runtime.Shutdown.
	ErrClosed = errors.New("extension: runtime closed")
)

Functions

This section is empty.

Types

type Activation 

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

Activation is a lease on one immutable Extension generation.

func (*Activation) Release 

func (a *Activation) Release(ctx context.Context) error

Release drops this generation lease. A retired generation's lifecycles stop in reverse order when its final lease is released. Release is idempotent.

func (*Activation) Snapshot 

func (a *Activation) Snapshot() Snapshot

Snapshot returns a defensive immutable view of the leased generation.

type Asset 

type Asset struct {
	Kind      string
	Name      string
	MediaType string
	Source    string
	Data      []byte
}

Asset is opaque, typed data for an optional application adapter. Core extension code never interprets or executes its Data.

type AssetEntry 

type AssetEntry struct {
	Origin Origin
	Asset  Asset
}

AssetEntry attaches immutable Extension provenance to an Asset.

type Capabilities 

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

Capabilities is an immutable set of feature names. Its zero value is an empty set.

func NewCapabilities 

func NewCapabilities(values ...Capability) Capabilities

NewCapabilities creates a set, ignoring duplicate values.

func (Capabilities) Has 

func (c Capabilities) Has(capability Capability) bool

Has reports whether capability is present.

func (Capabilities) List 

func (c Capabilities) List() []Capability

List returns sorted capability names.

type Capability 

type Capability string

Capability is one stable feature name understood by a Runtime or Bundle. 

const (
	CapabilityTools       Capability = "agent.tools"
	CapabilityHooks       Capability = "agent.hooks"
	CapabilitySkills      Capability = "harness.skills"
	CapabilityPrompts     Capability = "harness.prompts"
	CapabilityMiddleware  Capability = "ai.middleware"
	CapabilityLifecycle   Capability = "extension.lifecycle"
	CapabilityTypedAssets Capability = "extension.assets"
)

Capabilities implemented directly by this package.

type Contribution 

type Contribution struct {
	Tools      []Tool
	Skills     []harness.Skill
	Prompts    []harness.PromptTemplate
	Assets     []Asset
	Middleware []ai.Middleware
	Hooks      Hooks
	Lifecycle  Lifecycle
}

Contribution is the complete declarative output of one Extension.

type Definition 

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

Definition is a function-backed Extension for small integrations and declarative Bundle resources.

func NewDefinition 

func NewDefinition(
	descriptor Descriptor,
	prepare func(context.Context) (Contribution, error),
) (*Definition, error)

NewDefinition validates descriptor and creates a function-backed Extension.

func (*Definition) Descriptor 

func (d *Definition) Descriptor() Descriptor

Descriptor returns a defensive copy of the Extension metadata.

func (*Definition) Prepare 

func (d *Definition) Prepare(ctx context.Context) (Contribution, error)

Prepare invokes the configured contribution function.

type Descriptor 

type Descriptor struct {
	ID       string
	Version  string
	Requires []Capability
	Optional []Capability
}

Descriptor identifies one compiled Extension and its capability contract.

type Diagnostic 

type Diagnostic struct {
	Severity   Severity
	Origin     Origin
	Capability Capability
	Message    string
}

Diagnostic reports an optional capability or resource condition that did not prevent activation.

type Extension 

type Extension interface {
	Descriptor() Descriptor
	Prepare(context.Context) (Contribution, error)
}

Extension prepares one declarative Contribution. Prepare must not start long-lived resources; use Contribution.Lifecycle for that work.

type Hooks 

type Hooks struct {
	Observe          func(context.Context, agent.Event)
	BeforeTool       func(context.Context, agent.ToolCallInfo) agent.ToolDecision
	AfterTool        func(context.Context, agent.ToolResultInfo) *agent.ToolResultOverride
	PrepareTurn      func(context.Context, agent.RunInfo) agent.TurnUpdate
	TransformContext func(context.Context, []ai.Message) ([]ai.Message, error)
}

Hooks are the Agent lifecycle functions contributed by an Extension. ComposeHooks defines their deterministic composition semantics.

func ComposeHooks 

func ComposeHooks(values ...Hooks) Hooks

ComposeHooks combines Hook sets in argument order. Observers fan out; gates stop at the first non-Allow decision; mutators form ordered pipelines.

func (Hooks) AgentOptions 

func (h Hooks) AgentOptions() []agent.Option

AgentOptions returns one Agent option for each configured Hook family.

type Lifecycle 

type Lifecycle interface {
	Start(context.Context) error
	Stop(context.Context) error
}

Lifecycle owns long-lived resources for one Extension generation.

type Option 

type Option func(*config) error

Option configures a Runtime.

func WithCapabilities 

func WithCapabilities(capabilities ...Capability) Option

WithCapabilities adds application-specific capability names used during Extension negotiation.

func WithExtensions 

func WithExtensions(extensions ...Extension) Option

WithExtensions registers trusted, application-compiled Extensions. The registry is immutable after New returns.

type Origin 

type Origin struct {
	ExtensionID string
	Version     string
}

Origin records which Extension contributed a runtime value.

type PromptEntry 

type PromptEntry struct {
	Origin   Origin
	Template harness.PromptTemplate
}

PromptEntry attaches immutable Extension provenance to a prompt template.

type Runtime 

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

Runtime validates and atomically publishes immutable Extension generations. It is safe for concurrent Acquire and activation, creates no goroutines, and never invokes Extension callbacks while holding its state mutex.

Example 
package main

import (
	"context"
	"fmt"

	"github.com/rsbin1178/pips/agent/extension"
	"github.com/rsbin1178/pips/agent/harness"
)

func main() {
	ctx := context.Background()
	review, _ := extension.NewDefinition(extension.Descriptor{
		ID:      "review",
		Version: "1.0.0",
	}, func(context.Context) (extension.Contribution, error) {
		return extension.Contribution{Skills: []harness.Skill{{
			Name:        "review",
			Description: "Review a code change.",
			Content:     "Review carefully.",
		}}}, nil
	})

	runtime, _ := extension.New()
	activation, _ := runtime.Activate(ctx, review)
	snapshot := activation.Snapshot()
	fmt.Println(snapshot.Generation(), snapshot.Descriptors()[0].ID, snapshot.Skills()[0].Name)

	_ = activation.Release(ctx)
	_ = runtime.Shutdown(ctx)

}

Output:
1 review review

func New 

func New(options ...Option) (*Runtime, error)

New creates an empty Runtime with built-in contribution capabilities.

func (*Runtime) Acquire 

func (r *Runtime) Acquire() (*Activation, error)

Acquire leases the current generation. Release the returned Activation when its Agent or Harness run has finished.

func (*Runtime) Activate 

func (r *Runtime) Activate(
	ctx context.Context,
	extensions ...Extension,
) (*Activation, error)

Activate prepares, validates, starts, and publishes one complete generation. The returned Activation is a lease and must be released. When retirement of an unleased prior generation fails, both the installed Activation and a cleanup error are returned.

func (*Runtime) Capabilities 

func (r *Runtime) Capabilities() Capabilities

Capabilities returns the immutable Runtime capability set.

func (*Runtime) Resolve 

func (r *Runtime) Resolve(ids ...string) ([]Extension, error)

Resolve returns registered Extensions matching IDs in caller order. An empty ID list resolves to an empty result; it never implicitly selects the complete registry.

func (*Runtime) Shutdown 

func (r *Runtime) Shutdown(ctx context.Context) error

Shutdown retires the current generation and rejects future activation. Any leased generation stops when its final Activation is released.

type Severity 

type Severity uint8

Severity classifies a non-fatal activation diagnostic. 

const (
	SeverityUnknown Severity = iota
	SeverityWarning
)

Diagnostic severities.

type SkillEntry 

type SkillEntry struct {
	Origin Origin
	Skill  harness.Skill
}

SkillEntry attaches immutable Extension provenance to a Harness Skill.

type Snapshot 

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

Snapshot is an immutable view of one successfully activated generation. Keep the Activation that produced it leased until every user of the Snapshot has finished.

func (Snapshot) AgentOptions 

func (s Snapshot) AgentOptions(
	ctx context.Context,
	policy catalog.Policy,
) ([]agent.Option, error)

AgentOptions authorizes Extension tools and returns the complete Agent option set for this Snapshot.

func (Snapshot) Assets 

func (s Snapshot) Assets() []AssetEntry

Assets returns opaque typed assets with Extension provenance and defensive copies of their data.

func (Snapshot) Catalog 

func (s Snapshot) Catalog() *catalog.Catalog

Catalog returns the immutable catalog of Extension tools.

func (Snapshot) Descriptors 

func (s Snapshot) Descriptors() []Descriptor

Descriptors returns the activated Extension descriptors in registration order.

func (Snapshot) Diagnostics 

func (s Snapshot) Diagnostics() []Diagnostic

Diagnostics returns non-fatal activation diagnostics.

func (Snapshot) Generation 

func (s Snapshot) Generation() uint64

Generation returns the monotonically increasing Runtime generation.

func (Snapshot) HarnessOptions 

func (s Snapshot) HarnessOptions(
	ctx context.Context,
	policy catalog.Policy,
) ([]harness.Option, error)

HarnessOptions authorizes Extension tools and returns Harness resources and Agent hooks. The Harness owns its event recorder, so observers are installed through harness.WithOnEvent rather than agent.WithOnEvent.

func (Snapshot) Hooks 

func (s Snapshot) Hooks() Hooks

Hooks returns the composed Agent hooks for this generation.

func (Snapshot) Model 

func (s Snapshot) Model(model ai.LanguageModel) ai.LanguageModel

Model wraps model with activated AI middleware in registration order.

func (Snapshot) PromptEntries 

func (s Snapshot) PromptEntries() []PromptEntry

PromptEntries returns prompt templates with Extension provenance.

func (Snapshot) Prompts 

func (s Snapshot) Prompts() []harness.PromptTemplate

Prompts returns the activated prompt templates without provenance wrappers.

func (Snapshot) SkillEntries 

func (s Snapshot) SkillEntries() []SkillEntry

SkillEntries returns activated Skills with Extension provenance.

func (Snapshot) Skills 

func (s Snapshot) Skills() []harness.Skill

Skills returns the activated Harness skills without provenance wrappers.

type Tool 

type Tool struct {
	Value agent.Tool
	Risk  catalog.Risk
	Tags  []string
}

Tool is one Agent tool plus the policy metadata assigned before it enters a Catalog. Runtime supplies Extension provenance from the Descriptor.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.