extensions

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: May 30, 2026 License: MIT Imports: 38 Imported by: 0

Documentation

Overview

Package extensions provides manifest parsing, discovery, declarative asset extraction, and local enablement state for Productize extensions.

Index

Constants

View Source 
const (
	// ManifestFileNameTOML is the preferred manifest filename.
	ManifestFileNameTOML = "extension.toml"
	// ManifestFileNameJSON is the JSON fallback manifest filename.
	ManifestFileNameJSON = "extension.json"
	// DefaultHookPriority is the default priority for hook declarations.
	DefaultHookPriority = 500
	// MinHookPriority is the lowest allowed hook priority.
	MinHookPriority = 0
	// MaxHookPriority is the highest allowed hook priority.
	MaxHookPriority = 1000
)
View Source 
const AuditLogFileName = "extensions.jsonl"
View Source 
const (
	// InstallOriginFileName records where a user-scoped extension was installed from.
	InstallOriginFileName = ".productize-origin.json"
)

Variables

View Source 
var (
	// ErrAuditLoggerNotOpen reports writes before Open.
	ErrAuditLoggerNotOpen = errors.New("audit logger not open")
	// ErrAuditLoggerClosed reports writes after Close begins.
	ErrAuditLoggerClosed = errors.New("audit logger closed")
	// ErrAuditLoggerOpen reports an attempt to open an already-open logger.
	ErrAuditLoggerOpen = errors.New("audit logger already open")
)

Functions

func NewCancelledByExtensionError 

func NewCancelledByExtensionError(method string, path string) *subprocess.RequestError

func NewCapabilityDeniedReasonError 

func NewCapabilityDeniedReasonError(
	method string,
	reason string,
	data map[string]any,
) *subprocess.RequestError

func NewHostCapabilityTokenInvalidError 

func NewHostCapabilityTokenInvalidError(method string, reason string) *subprocess.RequestError

NewHostCapabilityTokenInvalidError reports that a daemon-owned Host API call cannot proceed because the run-scoped capability token context is absent or invalid.

func NewMethodNotFoundError 

func NewMethodNotFoundError(method string) *subprocess.RequestError

NewMethodNotFoundError creates the standard method-not-found response.

func NewNotInitializedError 

func NewNotInitializedError() *subprocess.RequestError

NewNotInitializedError creates the standard not-initialized response.

func NewPathOutOfScopeError 

func NewPathOutOfScopeError(method string, path string, allowedRoots []string) *subprocess.RequestError

func NewRecursionDepthExceededError 

func NewRecursionDepthExceededError(method string, parentRunID string, depth int) *subprocess.RequestError

func NewShutdownInProgressError 

func NewShutdownInProgressError(deadline time.Duration) *subprocess.RequestError

NewShutdownInProgressError creates the standard shutdown-in-progress response.

func RegisterHostServices 

func RegisterHostServices(router *HostAPIRouter, ops KernelOps) error

func ValidateManifest 

func ValidateManifest(ctx context.Context, manifest *Manifest) error

ValidateManifest validates a parsed manifest against Productize's manifest rules.

func WarnCapabilityDenied 

func WarnCapabilityDenied(component, extension string, err error)

WarnCapabilityDenied emits the standardized slog warning that downstream runtime components use when a capability denial occurs.

func WithDaemonHostBridge 

func WithDaemonHostBridge(ctx context.Context, bridge DaemonHostBridge) context.Context

WithDaemonHostBridge binds one daemon-owned host bridge to the run-scope bootstrap context so the extension runtime can preserve daemon ownership for selected Host API callbacks.

func WriteInstallOrigin 

func WriteInstallOrigin(dir string, origin InstallOrigin) error

WriteInstallOrigin persists install provenance into one extension directory.

Types

type ArtifactReadRequest 

type ArtifactReadRequest struct {
	Path string `json:"path"`
}

type ArtifactReadResult 

type ArtifactReadResult struct {
	Path    string `json:"path"`
	Content []byte `json:"content"`
}

type ArtifactWriteRequest 

type ArtifactWriteRequest struct {
	Path    string `json:"path"`
	Content []byte `json:"content"`
}

type ArtifactWriteResult 

type ArtifactWriteResult struct {
	Path         string `json:"path"`
	BytesWritten int    `json:"bytes_written"`
}

type AuditDirection 

type AuditDirection string

AuditDirection identifies the direction of one extension RPC exchange. 

const (
	// AuditDirectionHostToExt identifies a host -> extension call such as execute_hook.
	AuditDirectionHostToExt AuditDirection = "host→ext"
	// AuditDirectionExtToHost identifies an extension -> host call such as host.tasks.create.
	AuditDirectionExtToHost AuditDirection = "ext→host"
)

type AuditEntry 

type AuditEntry struct {
	Timestamp   time.Time
	Extension   string
	Direction   AuditDirection
	Method      string
	Capability  Capability
	Latency     time.Duration
	Result      AuditResult
	ErrorDetail string
}

AuditEntry is the in-memory representation of one extension audit record.

type AuditHandler 

type AuditHandler interface {
	Record(entry AuditEntry) error
}

AuditHandler is the runtime-facing interface for audit recording.

type AuditLogger 

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

AuditLogger owns the append-only extensions.jsonl writer for one run.

func (*AuditLogger) Close 

func (l *AuditLogger) Close(ctx context.Context) error

Close performs the final fsync and closes the audit file, respecting the caller's deadline or cancellation signal.

func (*AuditLogger) Open 

func (l *AuditLogger) Open(runArtifactsPath string) error

Open creates or truncates the run-scoped extensions audit log.

func (*AuditLogger) Path 

func (l *AuditLogger) Path() string

Path reports the absolute path of the audit log file, when opened.

func (*AuditLogger) Record 

func (l *AuditLogger) Record(entry AuditEntry) error

Record appends one JSONL audit record.

type AuditResult 

type AuditResult string

AuditResult identifies whether one audited call succeeded. 

const (
	// AuditResultOK identifies a successful audited call.
	AuditResultOK AuditResult = "ok"
	// AuditResultError identifies a failed audited call.
	AuditResultError AuditResult = "error"
)

type Capability 

type Capability string

Capability declares a manifest capability grant. 

const (
	CapabilityEventsRead        Capability = "events.read"
	CapabilityEventsPublish     Capability = "events.publish"
	CapabilityPromptMutate      Capability = "prompt.mutate"
	CapabilityPlanMutate        Capability = "plan.mutate"
	CapabilityAgentMutate       Capability = "agent.mutate"
	CapabilityJobMutate         Capability = "job.mutate"
	CapabilityRunMutate         Capability = "run.mutate"
	CapabilityReviewMutate      Capability = "review.mutate"
	CapabilityArtifactsRead     Capability = "artifacts.read"
	CapabilityArtifactsWrite    Capability = "artifacts.write"
	CapabilityTasksRead         Capability = "tasks.read"
	CapabilityTasksCreate       Capability = "tasks.create"
	CapabilityRunsStart         Capability = "runs.start"
	CapabilityMemoryRead        Capability = "memory.read"
	CapabilityMemoryWrite       Capability = "memory.write"
	CapabilityProvidersRegister Capability = "providers.register"
	CapabilitySkillsShip        Capability = "skills.ship"
	CapabilityAgentsShip        Capability = "agents.ship"
	CapabilitySubprocessSpawn   Capability = "subprocess.spawn"
	CapabilityNetworkEgress     Capability = "network.egress"
)

Capability values define the supported extension capability taxonomy.

type CapabilityChecker 

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

CapabilityChecker authorizes hook dispatches and Host API calls against the capabilities accepted during the initialize handshake.

func NewCapabilityChecker 

func NewCapabilityChecker(accepted []Capability) CapabilityChecker

NewCapabilityChecker constructs a pure capability checker for one extension session.

func (CapabilityChecker) Check 

func (c CapabilityChecker) Check(target string, required ...Capability) error

Check validates an arbitrary capability requirement list.

func (CapabilityChecker) CheckHook 

func (c CapabilityChecker) CheckHook(hook HookName) error

CheckHook validates one hook event against the accepted capabilities.

func (CapabilityChecker) CheckHostMethod 

func (c CapabilityChecker) CheckHostMethod(method string) error

CheckHostMethod validates one Host API call against the accepted capabilities.

func (CapabilityChecker) Granted 

func (c CapabilityChecker) Granted() []Capability

Granted returns the accepted capability list in a stable order.

func (CapabilityChecker) Has 

func (c CapabilityChecker) Has(capability Capability) bool

Has reports whether the accepted capability set contains one capability.

type CapabilityDeniedError 

type CapabilityDeniedError struct {
	Method  string
	Missing []Capability
	Granted []Capability
}

CapabilityDeniedError reports a structured capability denial.

func (*CapabilityDeniedError) Error 

func (e *CapabilityDeniedError) Error() string

Error returns a stable human-readable error string.

func (*CapabilityDeniedError) MarshalJSON 

func (e *CapabilityDeniedError) MarshalJSON() ([]byte, error)

MarshalJSON serializes the error into the JSON-RPC error payload described by the extension protocol.

func (*CapabilityDeniedError) RequestError 

func (e *CapabilityDeniedError) RequestError() *subprocess.RequestError

RequestError converts the denial to the shared JSON-RPC error type used by the subprocess transport.

type DaemonHostBridge 

type DaemonHostBridge interface {
	HostCapabilityToken() string
	StartRun(ctx context.Context, runtimeCfg *model.RuntimeConfig) (*RunHandle, error)
}

DaemonHostBridge routes daemon-owned Host API callbacks that must remain under daemon lifecycle ownership.

func DaemonHostBridgeFromContext 

func DaemonHostBridgeFromContext(ctx context.Context) DaemonHostBridge

DaemonHostBridgeFromContext returns the daemon-owned host bridge attached to a run-scope bootstrap context, when one has been bound.

type DeclaredProvider 

type DeclaredProvider struct {
	Extension    Ref
	ManifestPath string
	ExtensionDir string
	Manifest     *Manifest
	ProviderEntry
}

DeclaredProvider captures one provider declaration extracted from a manifest.

type DeclaredProviders 

type DeclaredProviders struct {
	IDE    []DeclaredProvider
	Review []DeclaredProvider
	Model  []DeclaredProvider
}

DeclaredProviders groups provider declarations by manifest category.

func ExtractDeclaredProviders 

func ExtractDeclaredProviders(entries []DiscoveredExtension) DeclaredProviders

ExtractDeclaredProviders converts discovered entries into a grouped provider inventory for downstream overlay assembly.

type DeclaredReusableAgent 

type DeclaredReusableAgent struct {
	Extension    Ref
	ManifestPath string
	Pattern      string
	ResolvedPath string
	SourceFS     fs.FS
	SourceDir    string
}

DeclaredReusableAgent captures one resolved reusable-agent path from a manifest.

type DeclaredReusableAgents 

type DeclaredReusableAgents struct {
	Agents []DeclaredReusableAgent
}

DeclaredReusableAgents contains the resolved reusable-agent inventory.

func ExtractDeclaredReusableAgents 

func ExtractDeclaredReusableAgents(entries []DiscoveredExtension) DeclaredReusableAgents

ExtractDeclaredReusableAgents resolves reusable-agent patterns into deterministic path entries for downstream installation flows.

type DeclaredSkillPack 

type DeclaredSkillPack struct {
	Extension    Ref
	ManifestPath string
	Pattern      string
	ResolvedPath string
	SourceFS     fs.FS
	SourceDir    string
}

DeclaredSkillPack captures one resolved skill-pack path from a manifest.

type DeclaredSkillPacks 

type DeclaredSkillPacks struct {
	Packs []DeclaredSkillPack
}

DeclaredSkillPacks contains the resolved skill-pack inventory.

func ExtractDeclaredSkillPacks 

func ExtractDeclaredSkillPacks(entries []DiscoveredExtension) DeclaredSkillPacks

ExtractDeclaredSkillPacks resolves skill-pack patterns into deterministic path entries for downstream installation flows.

type DefaultKernelOpsConfig 

type DefaultKernelOpsConfig struct {
	WorkspaceRoot  string
	RunID          string
	ParentRunID    string
	Dispatcher     *kernel.Dispatcher
	EventBus       *events.Bus[events.Event]
	Journal        *journal.Journal
	RuntimeManager model.RuntimeManager
	DaemonBridge   DaemonHostBridge
}

type DiscoveredExtension 

type DiscoveredExtension struct {
	Ref          Ref
	Manifest     *Manifest
	ExtensionDir string
	ManifestPath string
	Enabled      bool
	// contains filtered or unexported fields
}

DiscoveredExtension describes one discovered manifest declaration.

type Discovery 

type Discovery struct {
	WorkspaceRoot   string
	HomeDir         string
	IncludeDisabled bool
	Enablement      *EnablementStore
	BundledFS       fs.FS
}

Discovery scans bundled, user, and workspace extension roots.

func (Discovery) Discover 

func (d Discovery) Discover(ctx context.Context) (DiscoveryResult, error)

Discover scans the three extension levels, resolves precedence, and returns the effective declarations for the configured enablement view.

type DiscoveryFailure 

type DiscoveryFailure struct {
	Source       Source
	ExtensionDir string
	ManifestPath string
	Err          error
}

DiscoveryFailure reports a manifest load failure encountered during scanning.

func (DiscoveryFailure) Error 

func (f DiscoveryFailure) Error() string

func (DiscoveryFailure) Unwrap 

func (f DiscoveryFailure) Unwrap() error

type DiscoveryResult 

type DiscoveryResult struct {
	Discovered     []DiscoveredExtension
	Extensions     []DiscoveredExtension
	Overrides      []OverrideRecord
	Failures       []DiscoveryFailure
	Providers      DeclaredProviders
	SkillPacks     DeclaredSkillPacks
	ReusableAgents DeclaredReusableAgents
}

DiscoveryResult captures raw discovered entries plus the effective set after precedence resolution and enablement filtering.

type EnablementState 

type EnablementState struct {
	Extension Ref
	Enabled   bool
}

EnablementState captures the resolved local enabled state for an extension.

type EnablementStore 

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

EnablementStore persists operator-local enablement choices outside the repository.

func NewEnablementStore 

func NewEnablementStore(ctx context.Context, homeDir string) (*EnablementStore, error)

NewEnablementStore constructs a store rooted at homeDir or the current user's home.

func (*EnablementStore) Disable 

func (s *EnablementStore) Disable(ctx context.Context, ref Ref) error

Disable marks an extension as disabled in the local store.

func (*EnablementStore) Enable 

func (s *EnablementStore) Enable(ctx context.Context, ref Ref) error

Enable marks an extension as enabled in the local store.

func (*EnablementStore) Enabled 

func (s *EnablementStore) Enabled(ctx context.Context, ref Ref) (bool, error)

Enabled resolves whether an extension is enabled for this machine.

func (*EnablementStore) Load 

func (s *EnablementStore) Load(ctx context.Context, ref Ref) (EnablementState, error)

Load reads the stored enablement state for an extension or returns the default policy.

func (*EnablementStore) Save 

func (s *EnablementStore) Save(ctx context.Context, state EnablementState) error

Save persists the provided enablement state.

type EventPublishRequest 

type EventPublishRequest struct {
	Kind    string          `json:"kind"`
	Payload json.RawMessage `json:"payload,omitempty"`
}

type EventPublishResult 

type EventPublishResult struct {
	Seq uint64 `json:"seq,omitempty"`
}

type EventSubscribeRequest 

type EventSubscribeRequest struct {
	Kinds []events.EventKind `json:"kinds"`
}

type EventSubscribeResult 

type EventSubscribeResult struct {
	SubscriptionID string `json:"subscription_id"`
}

type ExtensionCaller 

type ExtensionCaller interface {
	Call(ctx context.Context, method string, params any, result any) error
}

ExtensionCaller abstracts a transport capable of issuing one JSON-RPC-style request to an extension subprocess.

type ExtensionInfo 

type ExtensionInfo struct {
	Name                 string `toml:"name"                   json:"name"`
	Version              string `toml:"version"                json:"version"`
	Description          string `toml:"description"            json:"description"`
	MinProductizeVersion string `toml:"min_productize_version" json:"min_productize_version"`
}

ExtensionInfo contains the identifying metadata for one extension.

type ExtensionState 

type ExtensionState string

ExtensionState captures the runtime lifecycle phase relevant to dispatcher and Host API routing. 

const (
	// ExtensionStateLoaded identifies a session that exists but is not ready yet.
	ExtensionStateLoaded ExtensionState = "loaded"
	// ExtensionStateInitializing identifies a session that is handshaking.
	ExtensionStateInitializing ExtensionState = "initializing"
	// ExtensionStateReady identifies a session that can accept operational calls.
	ExtensionStateReady ExtensionState = "ready"
	// ExtensionStateDraining identifies a session that is shutting down.
	ExtensionStateDraining ExtensionState = "draining"
	// ExtensionStateDegraded identifies a session that stays alive with partial service.
	ExtensionStateDegraded ExtensionState = "degraded"
	// ExtensionStateStopped identifies a session that is no longer serving requests.
	ExtensionStateStopped ExtensionState = "stopped"
)

type HookDeclaration 

type HookDeclaration struct {
	Event    HookName      `toml:"event"    json:"event"`
	Priority int           `toml:"priority" json:"priority,omitempty"`
	Required bool          `toml:"required" json:"required,omitempty"`
	Timeout  time.Duration `toml:"timeout"  json:"timeout,omitempty"`
}

HookDeclaration declares one hook subscription exposed by an extension.

type HookDispatcher 

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

HookDispatcher routes hook invocations across the runtime extension chain for one run.

func NewHookDispatcher 

func NewHookDispatcher(registry *Registry, audit AuditHandler) *HookDispatcher

NewHookDispatcher builds the frozen per-event hook chains for one run.

func (*HookDispatcher) DispatchMutable 

func (d *HookDispatcher) DispatchMutable(ctx context.Context, hook HookName, input any) (any, error)

DispatchMutable executes the chain-of-responsibility for one mutable hook.

func (*HookDispatcher) DispatchObserver 

func (d *HookDispatcher) DispatchObserver(ctx context.Context, hook HookName, payload any)

DispatchObserver fans out one observe-only hook to all subscribers using best-effort asynchronous delivery.

type HookName 

type HookName string

HookName identifies a canonical extension hook event. 

const (
	HookPlanPreDiscover           HookName = "plan.pre_discover"
	HookPlanPostDiscover          HookName = "plan.post_discover"
	HookPlanPreGroup              HookName = "plan.pre_group"
	HookPlanPostGroup             HookName = "plan.post_group"
	HookPlanPrePrepareJobs        HookName = "plan.pre_prepare_jobs"
	HookPlanPreResolveTaskRuntime HookName = "plan.pre_resolve_task_runtime"
	HookPlanPostPrepareJobs       HookName = "plan.post_prepare_jobs"
	HookPromptPreBuild            HookName = "prompt.pre_build"
	HookPromptPostBuild           HookName = "prompt.post_build"
	HookPromptPreSystem           HookName = "prompt.pre_system"
	HookAgentPreSessionCreate     HookName = "agent.pre_session_create"
	HookAgentPostSessionCreate    HookName = "agent.post_session_create"
	HookAgentPreSessionResume     HookName = "agent.pre_session_resume"
	HookAgentOnSessionUpdate      HookName = "agent.on_session_update"
	HookAgentPostSessionEnd       HookName = "agent.post_session_end"
	HookJobPreExecute             HookName = "job.pre_execute"
	HookJobPostExecute            HookName = "job.post_execute"
	HookJobPreRetry               HookName = "job.pre_retry"
	HookRunPreStart               HookName = "run.pre_start"
	HookRunPostStart              HookName = "run.post_start"
	HookRunPreShutdown            HookName = "run.pre_shutdown"
	HookRunPostShutdown           HookName = "run.post_shutdown"
	HookReviewPreFetch            HookName = "review.pre_fetch"
	HookReviewPostFetch           HookName = "review.post_fetch"
	HookReviewPreBatch            HookName = "review.pre_batch"
	HookReviewPostFix             HookName = "review.post_fix"
	HookReviewPreResolve          HookName = "review.pre_resolve"
	HookReviewWatchPreRound       HookName = "review.watch_pre_round"
	HookReviewWatchPostRound      HookName = "review.watch_post_round"
	HookReviewWatchPrePush        HookName = "review.watch_pre_push"
	HookReviewWatchFinished       HookName = "review.watch_finished"
	HookArtifactPreWrite          HookName = "artifact.pre_write"
	HookArtifactPostWrite         HookName = "artifact.post_write"
)

Hook names define the supported extension hook taxonomy.

type HostAPIRouter 

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

HostAPIRouter routes extension -> host calls to registered namespace handlers.

func NewHostAPIRouter 

func NewHostAPIRouter(registry *Registry, audit AuditHandler) *HostAPIRouter

NewHostAPIRouter constructs a router for one run-scoped extension registry.

func (*HostAPIRouter) Handle 

func (r *HostAPIRouter) Handle(
	ctx context.Context,
	extensionName string,
	method string,
	params json.RawMessage,
) (any, error)

Handle routes one Host API request for the named extension session.

func (*HostAPIRouter) RegisterService 

func (r *HostAPIRouter) RegisterService(namespace string, handler HostAPIService) error

RegisterService registers one namespace handler. Callers may pass either `tasks` or `host.tasks`; the router normalizes both to the same namespace key.

type HostAPIService 

type HostAPIService interface {
	Handle(ctx context.Context, extension *RuntimeExtension, verb string, params json.RawMessage) (any, error)
}

HostAPIService handles one registered Host API namespace.

type HostAPIServiceFunc 

type HostAPIServiceFunc func(
	ctx context.Context,
	extension *RuntimeExtension,
	verb string,
	params json.RawMessage,
) (any, error)

HostAPIServiceFunc adapts a function to HostAPIService.

func (HostAPIServiceFunc) Handle 

func (f HostAPIServiceFunc) Handle(
	ctx context.Context,
	extension *RuntimeExtension,
	verb string,
	params json.RawMessage,
) (any, error)

Handle invokes the function-backed service.

type HostServices 

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

func NewHostServices 

func NewHostServices(ops KernelOps) *HostServices

type InstallOrigin 

type InstallOrigin struct {
	Remote         string    `json:"remote"`
	Repository     string    `json:"repository,omitempty"`
	Ref            string    `json:"ref,omitempty"`
	Subdir         string    `json:"subdir,omitempty"`
	ResolvedSource string    `json:"resolved_source"`
	InstalledAt    time.Time `json:"installed_at"`
}

InstallOrigin captures provenance metadata for an installed extension.

func LoadInstallOrigin 

func LoadInstallOrigin(dir string) (*InstallOrigin, error)

LoadInstallOrigin loads persisted install provenance from one extension directory.

type KernelOps 

type KernelOps interface {
	CreateTask(ctx context.Context, req TaskCreateRequest) (*Task, error)
	ListTasks(ctx context.Context, workflow string) ([]Task, error)
	GetTask(ctx context.Context, workflow string, number int) (*Task, error)
	StartRun(ctx context.Context, req RunStartRequest) (*RunHandle, error)
	ReadArtifact(ctx context.Context, path string) (*ArtifactReadResult, error)
	WriteArtifact(ctx context.Context, req ArtifactWriteRequest) (*ArtifactWriteResult, error)
	RenderPrompt(ctx context.Context, req PromptRenderRequest) (*PromptRenderResult, error)
	ReadMemory(ctx context.Context, req MemoryReadRequest) (*MemoryReadResult, error)
	WriteMemory(ctx context.Context, req MemoryWriteRequest) (*MemoryWriteResult, error)
	PublishEvent(ctx context.Context, extensionName string, req EventPublishRequest) (*EventPublishResult, error)
}

func NewDefaultKernelOps 

func NewDefaultKernelOps(cfg DefaultKernelOpsConfig) (KernelOps, error)

type Manager 

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

Manager owns the extension runtime state for one run.

func (*Manager) DispatchMutable 

func (m *Manager) DispatchMutable(ctx context.Context, hook HookName, input any) (any, error)

DispatchMutable routes one mutable hook through the priority-ordered chain.

func (*Manager) DispatchMutableHook 

func (m *Manager) DispatchMutableHook(ctx context.Context, hook string, input any) (any, error)

DispatchMutableHook adapts the generic runtime-manager hook interface onto the extension hook dispatcher.

func (*Manager) DispatchObserver 

func (m *Manager) DispatchObserver(ctx context.Context, hook HookName, payload any)

DispatchObserver fans out one observe-only hook using the dispatcher’s existing best-effort semantics.

func (*Manager) DispatchObserverHook 

func (m *Manager) DispatchObserverHook(ctx context.Context, hook string, payload any)

DispatchObserverHook adapts the generic runtime-manager hook interface onto the extension hook dispatcher.

func (*Manager) ResolveReviewProviderBridge 

func (m *Manager) ResolveReviewProviderBridge(name string) (provider.ExtensionBridge, bool)

ResolveReviewProviderBridge returns the run-local extension bridge for one declared review provider when this runtime owns it.

func (*Manager) Shutdown 

func (m *Manager) Shutdown(ctx context.Context) error

Shutdown cooperatively drains every started extension and escalates through the shared subprocess package when a process refuses to exit.

func (*Manager) Start 

func (m *Manager) Start(ctx context.Context) error

Start launches every enabled executable extension and transitions successful sessions to Ready.

func (*Manager) WaitForObserverHooks 

func (m *Manager) WaitForObserverHooks(ctx context.Context) error

WaitForObserverHooks blocks until all queued observer hooks finish.

type Manifest 

type Manifest struct {
	Extension  ExtensionInfo     `toml:"extension"  json:"extension"`
	Subprocess *SubprocessConfig `toml:"subprocess" json:"subprocess,omitempty"`
	Security   SecurityConfig    `toml:"security"   json:"security"`
	Hooks      []HookDeclaration `toml:"hooks"      json:"hooks,omitempty"`
	Resources  ResourcesConfig   `toml:"resources"  json:"resources,omitempty"`
	Providers  ProvidersConfig   `toml:"providers"  json:"providers,omitempty"`
}

Manifest is the parsed extension manifest shared by discovery and runtime tasks.

func LoadManifest 

func LoadManifest(ctx context.Context, dir string) (*Manifest, error)

LoadManifest loads, parses, and validates an extension manifest from dir.

type ManifestDecodeError 

type ManifestDecodeError struct {
	Path   string
	Format ManifestFormat
	Err    error
}

ManifestDecodeError reports that a manifest file could not be decoded.

func (*ManifestDecodeError) Error 

func (e *ManifestDecodeError) Error() string

func (*ManifestDecodeError) Unwrap 

func (e *ManifestDecodeError) Unwrap() error

type ManifestFieldError 

type ManifestFieldError struct {
	Field   string
	Value   string
	Message string
}

ManifestFieldError reports a validation error for one manifest field.

func (*ManifestFieldError) Error 

func (e *ManifestFieldError) Error() string

type ManifestFormat 

type ManifestFormat string

ManifestFormat identifies the on-disk encoding used for a manifest file.

type ManifestNotFoundError 

type ManifestNotFoundError struct {
	Dir            string
	CandidatePaths []string
}

ManifestNotFoundError reports that neither supported manifest file exists in the extension directory.

func (*ManifestNotFoundError) Error 

func (e *ManifestNotFoundError) Error() string

type ManifestValidationError 

type ManifestValidationError struct {
	Path string
	Err  error
}

ManifestValidationError reports that a decoded manifest failed validation.

func (*ManifestValidationError) Error 

func (e *ManifestValidationError) Error() string

func (*ManifestValidationError) Unwrap 

func (e *ManifestValidationError) Unwrap() error

type MemoryReadRequest 

type MemoryReadRequest struct {
	Workflow string `json:"workflow"`
	TaskFile string `json:"task_file,omitempty"`
}

type MemoryReadResult 

type MemoryReadResult struct {
	Path            string `json:"path"`
	Content         string `json:"content"`
	Exists          bool   `json:"exists"`
	NeedsCompaction bool   `json:"needs_compaction"`
}

type MemoryWriteRequest 

type MemoryWriteRequest struct {
	Workflow string           `json:"workflow"`
	TaskFile string           `json:"task_file,omitempty"`
	Content  string           `json:"content"`
	Mode     memory.WriteMode `json:"mode,omitempty"`
}

type MemoryWriteResult 

type MemoryWriteResult struct {
	Path         string `json:"path"`
	BytesWritten int    `json:"bytes_written"`
}

type OpenRunScopeOptions 

type OpenRunScopeOptions = model.OpenRunScopeOptions

OpenRunScopeOptions controls whether executable extensions should be initialized as part of the early run bootstrap.

type OverrideRecord 

type OverrideRecord struct {
	Name   string
	Winner OverrideSubject
	Loser  OverrideSubject
	Reason string
}

OverrideRecord describes which higher-precedence declaration won for one name.

type OverrideSubject 

type OverrideSubject struct {
	Source       Source
	ManifestPath string
	Version      string
}

OverrideSubject captures one declaration participating in precedence.

type PromptIssueRef 

type PromptIssueRef struct {
	Name     string `json:"name"`
	AbsPath  string `json:"abs_path,omitempty"`
	Content  string `json:"content,omitempty"`
	CodeFile string `json:"code_file,omitempty"`
}

type PromptMemoryContext 

type PromptMemoryContext struct {
	Directory               string `json:"directory,omitempty"`
	WorkflowPath            string `json:"workflow_path,omitempty"`
	TaskPath                string `json:"task_path,omitempty"`
	WorkflowNeedsCompaction bool   `json:"workflow_needs_compaction,omitempty"`
	TaskNeedsCompaction     bool   `json:"task_needs_compaction,omitempty"`
}

type PromptRenderParams 

type PromptRenderParams struct {
	Name        string                      `json:"name,omitempty"`
	Round       int                         `json:"round,omitempty"`
	Provider    string                      `json:"provider,omitempty"`
	PR          string                      `json:"pr,omitempty"`
	ReviewsDir  string                      `json:"reviews_dir,omitempty"`
	BatchGroups map[string][]PromptIssueRef `json:"batch_groups,omitempty"`
	AutoCommit  bool                        `json:"auto_commit,omitempty"`
	Mode        model.ExecutionMode         `json:"mode,omitempty"`
	Memory      *PromptMemoryContext        `json:"memory,omitempty"`
}

type PromptRenderRequest 

type PromptRenderRequest struct {
	Template string             `json:"template"`
	Params   PromptRenderParams `json:"params"`
}

type PromptRenderResult 

type PromptRenderResult struct {
	Rendered string `json:"rendered"`
}

type ProviderBootstrap 

type ProviderBootstrap struct {
	ModelFlag             string   `toml:"model_flag"               json:"model_flag,omitempty"`
	ReasoningEffortFlag   string   `toml:"reasoning_effort_flag"    json:"reasoning_effort_flag,omitempty"`
	AddDirFlag            string   `toml:"add_dir_flag"             json:"add_dir_flag,omitempty"`
	DefaultAccessModeArgs []string `toml:"default_access_mode_args" json:"default_access_mode_args,omitempty"`
	FullAccessModeArgs    []string `toml:"full_access_mode_args"    json:"full_access_mode_args,omitempty"`
}

ProviderBootstrap declares typed ACP bootstrap flags for an IDE provider.

type ProviderEntry 

type ProviderEntry struct {
	Name               string             `toml:"name"                 json:"name"`
	Kind               ProviderKind       `toml:"kind"                 json:"kind,omitempty"`
	Target             string             `toml:"target"               json:"target,omitempty"`
	Command            string             `toml:"command"              json:"command,omitempty"`
	DisplayName        string             `toml:"display_name"         json:"display_name,omitempty"`
	SetupAgentName     string             `toml:"setup_agent_name"     json:"setup_agent_name,omitempty"`
	DefaultModel       string             `toml:"default_model"        json:"default_model,omitempty"`
	SupportsAddDirs    *bool              `toml:"supports_add_dirs"    json:"supports_add_dirs,omitempty"`
	UsesBootstrapModel *bool              `toml:"uses_bootstrap_model" json:"uses_bootstrap_model,omitempty"`
	DocsURL            string             `toml:"docs_url"             json:"docs_url,omitempty"`
	InstallHint        string             `toml:"install_hint"         json:"install_hint,omitempty"`
	FullAccessModeID   string             `toml:"full_access_mode_id"  json:"full_access_mode_id,omitempty"`
	FixedArgs          []string           `toml:"fixed_args"           json:"fixed_args,omitempty"`
	ProbeArgs          []string           `toml:"probe_args"           json:"probe_args,omitempty"`
	Env                map[string]string  `toml:"env"                  json:"env,omitempty"`
	Fallbacks          []ProviderLauncher `toml:"fallbacks"            json:"fallbacks,omitempty"`
	Bootstrap          *ProviderBootstrap `toml:"bootstrap"            json:"bootstrap,omitempty"`
	Metadata           map[string]string  `toml:"metadata"             json:"metadata,omitempty"`
}

ProviderEntry declares one provider overlay entry from a manifest.

type ProviderKind 

type ProviderKind string

ProviderKind declares the runtime behavior of one manifest provider entry. 

const (
	// ProviderKindAlias delegates to another host-owned provider by name.
	ProviderKindAlias ProviderKind = "alias"
	// ProviderKindExtension is implemented by the declaring extension subprocess.
	ProviderKindExtension ProviderKind = "extension"
)

type ProviderLauncher 

type ProviderLauncher struct {
	Command   string   `toml:"command"    json:"command"`
	FixedArgs []string `toml:"fixed_args" json:"fixed_args,omitempty"`
	ProbeArgs []string `toml:"probe_args" json:"probe_args,omitempty"`
}

ProviderLauncher declares one fallback launcher for an IDE provider.

type ProvidersConfig 

type ProvidersConfig struct {
	IDE    []ProviderEntry `toml:"ide"    json:"ide,omitempty"`
	Review []ProviderEntry `toml:"review" json:"review,omitempty"`
	Model  []ProviderEntry `toml:"model"  json:"model,omitempty"`
}

ProvidersConfig declares provider overlays exported by an extension.

type Ref 

type Ref struct {
	Name          string
	Source        Source
	WorkspaceRoot string
}

Ref identifies an extension instance for local enablement resolution.

type Registry 

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

Registry stores runtime extensions by name for dispatcher and router lookup.

func NewRegistry 

func NewRegistry(extensions ...*RuntimeExtension) (*Registry, error)

NewRegistry constructs a runtime registry from the provided entries.

func (*Registry) Add 

func (r *Registry) Add(extension *RuntimeExtension) error

Add inserts one runtime extension into the registry.

func (*Registry) Extensions 

func (r *Registry) Extensions() []*RuntimeExtension

Extensions returns all registered runtime extensions in deterministic name order.

func (*Registry) Get 

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

Get looks up one runtime extension by name.

type ResourcesConfig 

type ResourcesConfig struct {
	Skills []string `toml:"skills" json:"skills,omitempty"`
	Agents []string `toml:"agents" json:"agents,omitempty"`
}

ResourcesConfig declares declarative assets shipped with an extension.

type ReviewProviderBridge 

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

ReviewProviderBridge lazily reuses an active extension session when one is already running for the workspace, or starts a standalone single-extension manager the first time a review provider is invoked.

func NewReviewProviderBridge 

func NewReviewProviderBridge(
	entry DeclaredProvider,
	workspaceRoot string,
	invokingCommand string,
) (*ReviewProviderBridge, error)

NewReviewProviderBridge constructs a lazy bridge for one extension-backed review provider declaration.

func (*ReviewProviderBridge) Close 

func (b *ReviewProviderBridge) Close() error

func (*ReviewProviderBridge) FetchReviews 

func (b *ReviewProviderBridge) FetchReviews(
	ctx context.Context,
	providerName string,
	req provider.FetchRequest,
) ([]provider.ReviewItem, error)

func (*ReviewProviderBridge) ResolveIssues 

func (b *ReviewProviderBridge) ResolveIssues(
	ctx context.Context,
	providerName string,
	pr string,
	issues []provider.ResolvedIssue,
) error

type RunConfig 

type RunConfig struct {
	WorkspaceRoot          string              `json:"workspace_root,omitempty"`
	Name                   string              `json:"name,omitempty"`
	Round                  int                 `json:"round,omitempty"`
	Provider               string              `json:"provider,omitempty"`
	PR                     string              `json:"pr,omitempty"`
	ReviewsDir             string              `json:"reviews_dir,omitempty"`
	TasksDir               string              `json:"tasks_dir,omitempty"`
	AutoCommit             bool                `json:"auto_commit,omitempty"`
	Concurrent             int                 `json:"concurrent,omitempty"`
	BatchSize              int                 `json:"batch_size,omitempty"`
	IDE                    string              `json:"ide,omitempty"`
	Model                  string              `json:"model,omitempty"`
	AddDirs                []string            `json:"add_dirs,omitempty"`
	TailLines              int                 `json:"tail_lines,omitempty"`
	ReasoningEffort        string              `json:"reasoning_effort,omitempty"`
	AccessMode             string              `json:"access_mode,omitempty"`
	Mode                   model.ExecutionMode `json:"mode,omitempty"`
	OutputFormat           model.OutputFormat  `json:"output_format,omitempty"`
	Verbose                bool                `json:"verbose,omitempty"`
	Persist                bool                `json:"persist,omitempty"`
	RunID                  string              `json:"run_id,omitempty"`
	PromptText             string              `json:"prompt_text,omitempty"`
	PromptFile             string              `json:"prompt_file,omitempty"`
	ReadPromptStdin        bool                `json:"read_prompt_stdin,omitempty"`
	IncludeCompleted       bool                `json:"include_completed,omitempty"`
	IncludeResolved        bool                `json:"include_resolved,omitempty"`
	TimeoutMS              int64               `json:"timeout_ms,omitempty"`
	MaxRetries             int                 `json:"max_retries,omitempty"`
	RetryBackoffMultiplier float64             `json:"retry_backoff_multiplier,omitempty"`
}

type RunHandle 

type RunHandle struct {
	RunID       string `json:"run_id"`
	ParentRunID string `json:"parent_run_id,omitempty"`
}

type RunScope 

type RunScope struct {
	Artifacts         model.RunArtifacts
	Journal           *journal.Journal
	EventBus          *events.Bus[events.Event]
	ExtensionsEnabled bool
	Manager           *Manager
}

RunScope owns the run resources that must exist before planning starts.

func OpenRunScope 

func OpenRunScope(
	ctx context.Context,
	cfg *model.RuntimeConfig,
	opts OpenRunScopeOptions,
) (*RunScope, error)

OpenRunScope allocates run artifacts, opens the journal, constructs the event bus, and optionally constructs the extension manager before planning.

func (*RunScope) Close 

func (s *RunScope) Close(ctx context.Context) error

Close tears down the optional manager, then flushes the journal, then closes the event bus.

func (*RunScope) RunArtifacts 

func (s *RunScope) RunArtifacts() model.RunArtifacts

RunArtifacts reports the run artifact paths owned by the scope.

func (*RunScope) RunEventBus 

func (s *RunScope) RunEventBus() *events.Bus[events.Event]

RunEventBus reports the run-scoped event bus.

func (*RunScope) RunJournal 

func (s *RunScope) RunJournal() *journal.Journal

RunJournal reports the run journal owned by the scope.

func (*RunScope) RunManager 

func (s *RunScope) RunManager() model.RuntimeManager

RunManager reports the optional extension manager bound to the scope.

type RunStartRequest 

type RunStartRequest struct {
	Runtime RunConfig `json:"runtime"`
}

type RuntimeExtension 

type RuntimeExtension struct {
	Name         string
	Ref          Ref
	Manifest     *Manifest
	ManifestPath string
	ExtensionDir string
	Caller       ExtensionCaller
	Capabilities CapabilityChecker
	// contains filtered or unexported fields
}

RuntimeExtension stores the runtime metadata required by the dispatcher and Host API router for one extension session.

func (*RuntimeExtension) DefaultHookTimeout 

func (e *RuntimeExtension) DefaultHookTimeout() time.Duration

DefaultHookTimeout reports the per-run default timeout applied when a hook declaration omits an explicit timeout.

func (*RuntimeExtension) EventSubscription 

func (e *RuntimeExtension) EventSubscription() (string, []runtimeevents.EventKind)

EventSubscription reports the current subscription identifier and filter.

func (*RuntimeExtension) SetDefaultHookTimeout 

func (e *RuntimeExtension) SetDefaultHookTimeout(timeout time.Duration)

SetDefaultHookTimeout stores the per-run default hook timeout negotiated for this extension session.

func (*RuntimeExtension) SetEventSubscription 

func (e *RuntimeExtension) SetEventSubscription(subscriptionID string, kinds []runtimeevents.EventKind)

SetEventSubscription records the server-side event filter for the extension.

func (*RuntimeExtension) SetShutdownDeadline 

func (e *RuntimeExtension) SetShutdownDeadline(deadline time.Duration)

SetShutdownDeadline overrides the shutdown deadline used for router gating.

func (*RuntimeExtension) SetState 

func (e *RuntimeExtension) SetState(state ExtensionState)

SetState updates the current runtime state.

func (*RuntimeExtension) ShutdownDeadline 

func (e *RuntimeExtension) ShutdownDeadline() time.Duration

ShutdownDeadline reports the currently configured graceful-shutdown deadline.

func (*RuntimeExtension) State 

func (e *RuntimeExtension) State() ExtensionState

State reports the current runtime state.

func (*RuntimeExtension) WantsEvent 

func (e *RuntimeExtension) WantsEvent(kind runtimeevents.EventKind) bool

WantsEvent reports whether the extension should receive one bus event. An empty subscription filter means the extension receives all events.

type SecurityConfig 

type SecurityConfig struct {
	Capabilities []Capability `toml:"capabilities" json:"capabilities"`
}

SecurityConfig declares the capabilities requested by an extension.

type Source 

type Source string

Source identifies where an extension was discovered. 

const (
	// SourceBundled identifies bundled extensions embedded in the Productize binary.
	SourceBundled Source = "bundled"
	// SourceUser identifies user-scoped extensions installed under the user's home directory.
	SourceUser Source = "user"
	// SourceWorkspace identifies workspace-scoped extensions stored in the repository.
	SourceWorkspace Source = "workspace"
)

type SubprocessConfig 

type SubprocessConfig struct {
	Command           string            `toml:"command"             json:"command"`
	Args              []string          `toml:"args"                json:"args,omitempty"`
	Env               map[string]string `toml:"env"                 json:"env,omitempty"`
	ShutdownTimeout   time.Duration     `toml:"shutdown_timeout"    json:"shutdown_timeout,omitempty"`
	HealthCheckPeriod time.Duration     `toml:"health_check_period" json:"health_check_period,omitempty"`
}

SubprocessConfig configures the extension subprocess entrypoint.

type Task 

type Task struct {
	Workflow     string   `json:"workflow"`
	Number       int      `json:"number"`
	Path         string   `json:"path"`
	Status       string   `json:"status"`
	Title        string   `json:"title,omitempty"`
	Type         string   `json:"type,omitempty"`
	Complexity   string   `json:"complexity,omitempty"`
	Dependencies []string `json:"dependencies,omitempty"`
	Body         string   `json:"body,omitempty"`
}

type TaskCreateRequest 

type TaskCreateRequest struct {
	Workflow    string          `json:"workflow"`
	Title       string          `json:"title"`
	Body        string          `json:"body"`
	Frontmatter TaskFrontmatter `json:"frontmatter"`
	UpdateIndex bool            `json:"update_index,omitempty"`
}

type TaskFrontmatter 

type TaskFrontmatter struct {
	Status       string   `json:"status"`
	Type         string   `json:"type"`
	Complexity   string   `json:"complexity,omitempty"`
	Dependencies []string `json:"dependencies,omitempty"`
}

type UnknownCapabilityTargetError 

type UnknownCapabilityTargetError struct {
	Kind string
	Name string
}

UnknownCapabilityTargetError reports attempts to authorize an unknown method or hook event.

func (*UnknownCapabilityTargetError) Error 

func (e *UnknownCapabilityTargetError) Error() string

Error returns a stable human-readable error string.

Source Files

View all Source files

Directories

Path Synopsis
Package builtin anchors the embedded extension discovery root.
 Package builtin anchors the embedded extension discovery root.

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.