operationruntime

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package operationruntime owns the provider-neutral capability adapter registry and Agent Operations V1 lifecycle orchestration.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EqualJSONObject 

func EqualJSONObject(left, right []byte) bool

EqualJSONObject compares two JSON objects while preserving numeric tokens.

func IsPossiblePartial 

func IsPossiblePartial(err error) bool

IsPossiblePartial reports whether an execution error requires reconciliation.

func NormalizedResult 

func NormalizedResult(operation string, result json.RawMessage) json.RawMessage

NormalizedResult gives reconciled operations a stable non-empty result.

func PlanRecord 

func PlanRecord(plan grants.ImmutablePlan) state.PlanRecord

PlanRecord converts a canonical immutable plan into the shared state row.

func RecoveredApprovalCommit 

func RecoveredApprovalCommit(grant grants.Grant) (commit, valid bool)

RecoveredApprovalCommit reports whether restart recovery must commit a reserved use and whether the recorded authority state is valid.

Types

type Adapter 

type Adapter[I, P, A any] interface {
	Descriptor() capability.Descriptor
	Decode(target, arguments json.RawMessage) (I, error)
	Resolve(context.Context, I) (P, error)
	Authorize(P) A
	Present(P) agentv1.Presentation
	Execute(context.Context, P) (Outcome, error)
	Reconcile(context.Context, P) (Outcome, error)
}

Adapter is the provider-neutral operation contract. Providers retain their own concrete input, immutable plan, and authorization request types.

type ClientBoundAdapter 

type ClientBoundAdapter[I any] interface {
	ValidateClient(I, string, string) error
}

ClientBoundAdapter binds requester-owned external references after the authenticated client is known and before provider resolution begins.

type Failure 

type Failure struct {
	Code    string
	Message string
}

Failure is a provider-redacted terminal execution error.

type Options 

type Options[I, P, A any] struct {
	Broker              string
	Operations          *agentops.Store
	Registry            *Registry[I, P, A]
	Authorization       *authorization.Coordinator
	Grants              *grants.Store
	Decide              func(policy.Request, policy.DecisionOptions) policy.Decision
	Project             func(A) policy.Request
	SetClient           func(*P, string)
	InputData           func(I) (json.RawMessage, json.RawMessage)
	PlanData            func(P) (json.RawMessage, json.RawMessage)
	Prepare             func(Preparation[P, A]) (authorization.GrantIntent, error)
	Load                func(agentv1.Operation, Adapter[I, P, A]) (P, error)
	PlanDigest          func(grants.Grant) string
	StoredPlan          func(string) (state.PlanRecord, error)
	ValidateExecution   func(grants.Grant) error
	MapSubmissionError  func(error) error
	DefinitiveFailure   func(error) bool
	ExecutionFailure    func(error, error) Failure
	RecordPolicyRefusal func(agentv1.Operation, P, policy.Decision, string)
	RecordOutcome       func(agentv1.Operation, P, string, string, int)
	Notifier            notify.Notifier
	ApprovalMessage     func(grants.Grant, string) notify.ApprovalMessage
	OperatorConfigured  bool
	Now                 func() time.Time
	AuthorizationGrace  time.Duration
	WorkerInterval      time.Duration
	WorkerConcurrency   int
	NotificationLease   time.Duration
}

Options supplies provider semantics and shared durable dependencies. The callbacks encode provider plans and presentation; lifecycle transitions stay inside Runtime.

type Outcome 

type Outcome struct {
	Proven         bool
	Result         json.RawMessage
	UpstreamStatus int
}

Outcome is the stable result of execution or reconciliation. Proven must be true before the runtime records a successful operation.

type PlanCleaner 

type PlanCleaner[P any] interface {
	Cleanup(P) error
}

PlanCleaner removes transient provider material when an operation reaches a terminal state without consuming it.

type PossiblePartialError 

type PossiblePartialError struct{ Err error }

PossiblePartialError marks a multi-call operation that may have changed upstream state before a later call failed. The runtime reconciles it instead of treating the wrapped error as a definitive refusal.

func (*PossiblePartialError) Error 

func (e *PossiblePartialError) Error() string

func (*PossiblePartialError) Unwrap 

func (e *PossiblePartialError) Unwrap() error

type Preparation 

type Preparation[P, A any] struct {
	Plan           P
	Auth           A
	Core           policy.Request
	DescriptorName string
	Client         string
	OperationID    string
	Reason         string
	Decision       policy.Decision
	Direct         bool
	CreatedAt      time.Time
}

Preparation is the immutable provider plan context selected by the shared lifecycle. The provider encodes it into its v1 plan and canonical grant.

type Registry 

type Registry[I, P, A any] struct {
	// contains filtered or unexported fields
}

Registry is an immutable adapter registry keyed by catalog operation name.

func NewRegistry 

func NewRegistry[I, P, A any](options RegistryOptions, adapters ...Adapter[I, P, A]) (*Registry[I, P, A], error)

NewRegistry validates adapters against their provider-owned catalog.

func (*Registry[I, P, A]) Lookup 

func (r *Registry[I, P, A]) Lookup(name string) (Adapter[I, P, A], bool)

Lookup returns the adapter for one exact operation name.

func (*Registry[I, P, A]) Names 

func (r *Registry[I, P, A]) Names() []string

Names returns the sorted registered operation names.

func (*Registry[I, P, A]) ValidateCoverage 

func (r *Registry[I, P, A]) ValidateCoverage(provider string, descriptors []capability.Descriptor) error

ValidateCoverage ensures every catalog entry advertised as an implemented execution operation has an adapter.

type RegistryOptions 

type RegistryOptions struct {
	Provider        string
	Descriptor      func(string) (capability.Descriptor, bool)
	RequiresAdapter func(capability.Descriptor) bool
}

RegistryOptions supplies provider catalog ownership without teaching the shared registry provider vocabulary.

type Runtime 

type Runtime[I, P, A any] struct {
	// contains filtered or unexported fields
}

Runtime drives one provider's generic Agent V1 operation lifecycle.

func New 

func New[I, P, A any](options Options[I, P, A]) (*Runtime[I, P, A], error)

New validates and constructs a provider-neutral lifecycle runtime.

func (*Runtime[I, P, A]) Advance 

func (r *Runtime[I, P, A]) Advance(ctx context.Context, operation agentv1.Operation)

Advance synchronizes approval state and dispatches one approved operation.

func (*Runtime[I, P, A]) AdvanceAll 

func (r *Runtime[I, P, A]) AdvanceAll(ctx context.Context)

AdvanceAll advances every unfinished operation once.

func (*Runtime[I, P, A]) Cancel 

func (r *Runtime[I, P, A]) Cancel(_ context.Context, client, id string) (agentv1.Operation, error)

Cancel cancels a pending or approved operation and its approval authority.

func (*Runtime[I, P, A]) CancelGrant 

func (r *Runtime[I, P, A]) CancelGrant(grant grants.Grant, client string) error

CancelGrant cancels or revokes one requester-owned approval grant.

func (*Runtime[I, P, A]) Execute 

func (r *Runtime[I, P, A]) Execute(ctx context.Context, operation agentv1.Operation)

Execute consumes authority, executes once, and reconciles ambiguity.

func (*Runtime[I, P, A]) FailExecution 

func (r *Runtime[I, P, A]) FailExecution(operation agentv1.Operation, plan P, executionErr, reconcileErr error)

FailExecution records one provider-redacted execution or reconciliation failure.

func (*Runtime[I, P, A]) Load 

func (r *Runtime[I, P, A]) Load(operation agentv1.Operation) (Adapter[I, P, A], P, error)

Load loads and provider-validates an immutable operation plan.

func (*Runtime[I, P, A]) ReconcileInterrupted 

func (r *Runtime[I, P, A]) ReconcileInterrupted(ctx context.Context, operation agentv1.Operation)

ReconcileInterrupted proves an executing operation after restart without replaying the mutation.

func (*Runtime[I, P, A]) Recover 

func (r *Runtime[I, P, A]) Recover(ctx context.Context)

Recover reconciles executing operations and advances other unfinished work.

func (*Runtime[I, P, A]) RecoverApproval 

func (r *Runtime[I, P, A]) RecoverApproval(operation agentv1.Operation) agentv1.Operation

RecoverApproval repairs an operation interrupted between grant and plan binding.

func (*Runtime[I, P, A]) Start 

func (r *Runtime[I, P, A]) Start(ctx context.Context)

Start recovers unfinished work and starts worker dispatch.

func (*Runtime[I, P, A]) Submit 

func (r *Runtime[I, P, A]) Submit(ctx context.Context, client string, request agentv1.SubmitRequest) (agentv1.Operation, bool, error)

Submit validates, resolves, authorizes, and durably submits an operation.

func (*Runtime[I, P, A]) Succeed 

func (r *Runtime[I, P, A]) Succeed(operation agentv1.Operation, plan P, result json.RawMessage, reserved bool, detail string)

Succeed records a proven provider result and settles reserved authority.

func (*Runtime[I, P, A]) Wait 

func (r *Runtime[I, P, A]) Wait()

Wait waits for lifecycle workers after their context is canceled.

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.