bundle

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: 17 Imported by: 0

Documentation

Overview

Package bundle loads bounded local Bundles and activates their declarative resources through an extension.Runtime.

A Bundle is distribution metadata, not executable Go code. Its manifest may select trusted Extensions already registered by the embedding application and may contribute Agent Skills, prompt templates, and opaque typed assets. Scripts bundled beside a Skill remain files: this package never executes them or implicitly turns them into Tools.

Index

Examples

Constants

View Source 
const DefaultManifestPath = "pips-bundle.json"

DefaultManifestPath is the conventional manifest path within a bundle.

View Source 
const SchemaV1Alpha1 = "pips.bundle/v1alpha1"

SchemaV1Alpha1 is the P0 Bundle manifest schema.

Variables

View Source 
var (
	// ErrInvalid reports malformed configuration, manifests, filters, or paths.
	ErrInvalid = errors.New("bundle: invalid")
	// ErrUnsupportedSchema reports a manifest schema this version cannot load.
	ErrUnsupportedSchema = errors.New("bundle: unsupported schema")
	// ErrUntrusted reports a bundle rejected by the selected trust policy.
	ErrUntrusted = errors.New("bundle: untrusted")
	// ErrLimitExceeded reports a manifest, resource, or bundle over its bound.
	ErrLimitExceeded = errors.New("bundle: limit exceeded")
	// ErrDuplicate reports duplicate bundle or component identities.
	ErrDuplicate = errors.New("bundle: duplicate")
	// ErrClosed reports use of a disk Loader after Close.
	ErrClosed = errors.New("bundle: loader closed")
)

Functions

func Activate 

func Activate(
	ctx context.Context,
	runtime *extension.Runtime,
	bundles ...*Bundle,
) (*extension.Activation, error)

Activate resolves every bundle's registered Extensions, adds its declarative resources, and atomically activates the complete generation. Duplicate Bundle identities or selected Extension IDs are rejected instead of applying implicit scope precedence.

Types

type AssetSpec 

type AssetSpec struct {
	Kind      string `json:"kind"`
	Name      string `json:"name"`
	Path      string `json:"path"`
	MediaType string `json:"media_type,omitempty"`
}

AssetSpec declares one opaque typed asset file.

type Bundle 

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

Bundle is one fully decoded and validated manifest selection. Its methods return defensive copies and it contains no open files or running resources.

func (*Bundle) Activate 

func (b *Bundle) Activate(
	ctx context.Context,
	runtime *extension.Runtime,
) (*extension.Activation, error)

Activate resolves and activates this Bundle alone.

Example 
package main

import (
	"context"
	"fmt"
	"testing/fstest"

	"github.com/rsbin1178/pips/agent/bundle"
	"github.com/rsbin1178/pips/agent/catalog"
	"github.com/rsbin1178/pips/agent/extension"
)

func main() {
	ctx := context.Background()
	loader, _ := bundle.New(fstest.MapFS{
		"pips-bundle.json": &fstest.MapFile{Data: []byte(`{
			"schema":"pips.bundle/v1alpha1",
			"id":"project-review",
			"version":"1.0.0",
			"extensions":["audit"],
			"skills":["skills/review/SKILL.md"]
		}`)},
		"skills/review/SKILL.md": &fstest.MapFile{Data: []byte(`---
name: review
description: Review a code change.
---
Review carefully.`)},
		// Bundled scripts remain ordinary files and are never registered as Tools.
		"skills/review/scripts/check.sh": &fstest.MapFile{Data: []byte("exit 0")},
	})

	bundle, _ := loader.Load(ctx, bundle.DefaultManifestPath, bundle.Settings{
		Scope: bundle.ScopeProject,
		Trust: bundle.TrustApproved,
	})
	audit, _ := extension.NewDefinition(extension.Descriptor{
		ID: "audit", Version: "1.0.0",
	}, func(context.Context) (extension.Contribution, error) {
		return extension.Contribution{}, nil
	})
	runtime, _ := extension.New(extension.WithExtensions(audit))
	activation, _ := bundle.Activate(ctx, runtime)
	snapshot := activation.Snapshot()
	tools, _ := snapshot.Catalog().Snapshot(ctx, catalog.AllowAll("example", catalog.RiskPrivileged))

	fmt.Println(snapshot.Generation())
	fmt.Println(snapshot.Descriptors()[0].ID, snapshot.Descriptors()[1].ID)
	fmt.Println(snapshot.Skills()[0].Name, len(tools))

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

}

Output:
1
audit bundle:project-review
review 0

func (*Bundle) Assets 

func (b *Bundle) Assets() []extension.Asset

Assets returns selected opaque assets with defensive data copies.

func (*Bundle) Diagnostics 

func (b *Bundle) Diagnostics() []Diagnostic

Diagnostics returns non-fatal load diagnostics.

func (*Bundle) ExtensionIDs 

func (b *Bundle) ExtensionIDs() []string

ExtensionIDs returns selected registered Extension IDs in manifest order.

func (*Bundle) Manifest 

func (b *Bundle) Manifest() Manifest

Manifest returns a defensive copy of the bundle manifest.

func (*Bundle) Prompts 

func (b *Bundle) Prompts() []harness.PromptTemplate

Prompts returns selected prompt templates.

func (*Bundle) Scope 

func (b *Bundle) Scope() Scope

Scope returns the application-selected bundle scope.

func (*Bundle) Skills 

func (b *Bundle) Skills() []harness.Skill

Skills returns selected Agent Skills with defensive metadata copies.

type ComponentFilter 

type ComponentFilter struct {
	Include []string
	Exclude []string
}

ComponentFilter narrows one component kind. A nil Include means all declared values; a non-nil empty Include means none. Exclude is then applied to the included set. Every filter value must exist in the manifest.

type Diagnostic 

type Diagnostic struct {
	Component string
	Path      string
	Message   string
}

Diagnostic is a non-fatal, path-scoped load condition.

type Filters 

type Filters struct {
	Extensions ComponentFilter
	Skills     ComponentFilter
	Prompts    ComponentFilter
	Assets     ComponentFilter
}

Filters independently narrow each manifest component kind. Extensions are filtered by registered ID; Skills, Prompts, and Assets are filtered by their declared path.

type Limits 

type Limits struct {
	MaxManifestBytes int64
	MaxResourceBytes int64
	MaxTotalBytes    int64
	MaxResources     int
}

Limits bound all reads performed for one Bundle. Resource bytes include Skill manifests, prompt templates, and asset data, but not the separately bounded manifest.

func DefaultLimits 

func DefaultLimits() Limits

DefaultLimits returns conservative P0 local-bundle limits.

type Loader 

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

Loader decodes Bundles from one filesystem boundary. It never opens network connections or executes files found in that filesystem.

func New 

func New(fsys fs.FS, options ...Option) (*Loader, error)

New creates a Loader over fsys. The caller retains ownership of fsys.

func Open 

func Open(root string, options ...Option) (*Loader, error)

Open creates a Loader rooted at a local directory. The os.Root-backed filesystem prevents symlinks from escaping root. Close the Loader when it is no longer needed.

func (*Loader) Close 

func (l *Loader) Close() error

Close releases a disk root opened by Open. It does not close filesystems supplied to New and is idempotent.

func (*Loader) Load 

func (l *Loader) Load(
	ctx context.Context,
	manifestPath string,
	settings Settings,
) (*Bundle, error)

Load decodes one manifest and all filtered declarative resources. Resource paths are relative to the manifest's directory.

type Manifest 

type Manifest struct {
	Schema      string                 `json:"schema"`
	ID          string                 `json:"id"`
	Version     string                 `json:"version"`
	Description string                 `json:"description,omitempty"`
	Requires    []extension.Capability `json:"requires,omitempty"`
	Optional    []extension.Capability `json:"optional,omitempty"`
	Extensions  []string               `json:"extensions,omitempty"`
	Skills      []string               `json:"skills,omitempty"`
	Prompts     []string               `json:"prompts,omitempty"`
	Assets      []AssetSpec            `json:"assets,omitempty"`
}

Manifest is the strict JSON contract for one local bundle.

type Option 

type Option func(*loaderConfig) error

Option configures a Loader.

func WithLimits 

func WithLimits(limits Limits) Option

WithLimits replaces all Loader bounds. Every field must be positive.

type Scope 

type Scope string

Scope identifies who selected a Bundle source. Scope does not come from the bundle itself, so a manifest cannot promote its own trust level. 

const (
	ScopeManaged   Scope = "managed"
	ScopeUser      Scope = "user"
	ScopeProject   Scope = "project"
	ScopeTemporary Scope = "temporary"
)

Supported Bundle scopes.

type Settings 

type Settings struct {
	Scope   Scope
	Trust   TrustDecision
	Filters Filters
}

Settings are application-owned selection metadata for one Load call.

type TrustDecision 

type TrustDecision uint8

TrustDecision is the application's explicit trust state for a Bundle. 

const (
	TrustUnspecified TrustDecision = iota
	TrustDenied
	TrustApproved
)

Bundle trust states.

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.