integrations

Documentation

Overview

Package integrations turns an Extension's "integration" surface into callable tools. An integration is a set of named operations that share one base URL, one auth scheme, and one governed HTTP transport. Each operation is a declarative flow: the common case is a single request, but an operation may chain steps (fetch, reshape, branch, loop) without any compiled code. Loading an Extension that declares an integration surface mounts its operations as tools the agent can call; the credential is resolved by name from the vault at call time and never lives in the spec.

This package is the bridge between three lower layers: the Extension model and its handler registry, the declarative flow interpreter, and the shared request transport with its auth providers. It owns none of those mechanisms; it composes them so that "an API integration" is just an Extension with an integration block.

Index

• func RegisterWith(reg *extension.Registry, opts ...Option) error
• type AuditFunc
• type Denial
• type Handler
  • func NewHandler(opts ...Option) *Handler
  • func (h *Handler) Capability() string
  • func (h *Handler) OnLoad(_ context.Context, m extension.Mount) error
  • func (h *Handler) OnUnload(_ context.Context, id string) error
  • func (h *Handler) Tools(id string) []mission.Tool
• type Operation
• type Option
  • func WithAudit(a AuditFunc) Option
  • func WithClock(c clock.Clock) Option
  • func WithCredentials(c *credential.Store) Option
  • func WithLimits(l flow.Limits) Option
  • func WithSecrets(s secret.Source) Option
  • func WithTransport(t *request.Transport) Option
• type Spec

Functions

func RegisterWith

func RegisterWith(reg *extension.Registry, opts ...Option) error

RegisterWith registers an integration-surface handler on an extension registry, so a store loading an Extension with an integration block turns it into tools.

Types

type AuditFunc

type AuditFunc func(Denial)

AuditFunc receives a Denial when a role check refuses a credential. The host wires it to its audit log; the integrations package stays decoupled from any log backend.

type Denial

type Denial struct {
	Principal      string
	Integration    string
	Credential     string
	CredentialRole credential.Role
	RequiredRole   credential.Role
}

Denial records a credential refused for an operation because its role was below the operation's required role. It is handed to the audit recorder (see WithAudit) so a host can write it to the event log with the caller's principal.

type Handler

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

Handler is the extension.Point for the "integration" surface. It builds an integration's operations into tools backed by the flow interpreter and the shared transport, tracks them per extension, and exposes them through the tool-bridge. It is safe for concurrent use.

func NewHandler

func NewHandler(opts ...Option) *Handler

NewHandler builds an integration-surface handler.

func (*Handler) Capability

func (h *Handler) Capability() string

Capability is the surface key this handler serves.

func (*Handler) OnLoad

func (h *Handler) OnLoad(_ context.Context, m extension.Mount) error

OnLoad builds the integration's operations into tools. It validates the surface block and every operation flow up front, and constructs the auth provider from the extension's auth spec, so a misconfigured integration is rejected at load rather than failing at first call.

func (*Handler) OnUnload

func (h *Handler) OnUnload(_ context.Context, id string) error

OnUnload drops the tools mounted for an extension. It is idempotent.

func (*Handler) Tools

func (h *Handler) Tools(id string) []mission.Tool

Tools returns the tools mounted for an extension id, satisfying extension.ToolSource so the loader surfaces them to the agent.

type Operation

type Operation struct {
	Name        string          `json:"name"`
	Description string          `json:"description,omitempty"`
	Input       json.RawMessage `json:"input,omitempty"`
	Role        credential.Role `json:"role,omitempty"`
	Flow        json.RawMessage `json:"flow"`
}

Operation is one callable tool. Name and Description are what the model sees; Input is the JSON Schema for the tool's arguments (the values the flow reads as config); Flow is the declarative procedure that runs when the tool is invoked. Role is the credential role the operation requires: when a credential store is configured, a credential below this role is refused before the flow runs. An empty role requires no particular privilege.

type Option

type Option func(*Handler)

Option configures a Handler.

func WithAudit

func WithAudit(a AuditFunc) Option

WithAudit sets the recorder notified when a role check refuses a credential.

func WithClock

func WithClock(c clock.Clock) Option

WithClock sets the clock oauth2 token expiry is measured against (default clock.System). Tests pass a manual clock for determinism.

func WithCredentials

func WithCredentials(c *credential.Store) Option

WithCredentials sets the credential store used to resolve an integration's credential by name or default and to enforce operation roles. Without it, the extension's auth credential reference is treated as a direct vault reference and no role is enforced (the zero-config behaviour).

func WithLimits

func WithLimits(l flow.Limits) Option

WithLimits sets the resource caps every operation flow runs under.

func WithSecrets

func WithSecrets(s secret.Source) Option

WithSecrets sets the vault the auth providers resolve credentials from. The default reads the process environment.

func WithTransport

func WithTransport(t *request.Transport) Option

WithTransport sets the HTTP transport requests are dispatched through. The default is a fresh transport (anti-SSRF dialer, bounded retries, per-host rate limiting).

type Spec

type Spec struct {
	Operations []Operation `json:"operations"`
}

Spec is the typed "integration" surface block of an Extension manifest: the set of operations the integration exposes. The connection details (base URL, auth) live on the enclosing Extension spec and are shared by every operation, so they are declared once.