session

Documentation

Overview

Package session is the supported host-side Toolbox lifecycle: validate a manifest, launch one guarded process, approve its catalog, authorize exact requests, invoke them, emit redacted audit events, and clean up.

Index

• Constants
• type AuditEvent
• type AuditFunc
  • func (f AuditFunc) Record(ctx context.Context, event AuditEvent) error
• type AuditPhase
• type AuditSink
• type CallError
  • func (e *CallError) Error() string
  • func (e *CallError) Unwrap() error
• type CallRequest
• type CallResult
• type ErrorCode
• type Options
• type RetryClass
• type Scope
• type ToolboxSession
  • func Open(ctx context.Context, options Options) (_ *ToolboxSession, err error)
  • func (s *ToolboxSession) Call(ctx context.Context, input CallRequest) (*CallResult, error)
  • func (s *ToolboxSession) Catalog() *coretoolbox.CatalogSnapshot
  • func (s *ToolboxSession) Close() error
  • func (s *ToolboxSession) DescribeTool(ctx context.Context, name string) (*coretoolbox.ApprovedTool, error)

Constants

const DefaultMaxRequestBytes = 1 << 20

Types

type AuditEvent

type AuditEvent struct {
	Phase           AuditPhase
	Timestamp       time.Time
	SessionID       string
	RequestID       string
	ObjectiveID     string
	TaskID          string
	TraceID         string
	ReleaseID       string
	InvocationID    string
	Toolbox         string
	Tool            string
	PrincipalID     string
	OrganizationID  string
	CatalogDigest   string
	RequestDigest   string
	AuthorizationID string
	DecisionPath    string
	ErrorCode       ErrorCode
	Duration        time.Duration
	ContentItems    int
	StructuredItems int
	HasToolError    bool
}

AuditEvent is deliberately redacted by construction.

type AuditFunc

type AuditFunc func(context.Context, AuditEvent) error

AuditFunc adapts a function to AuditSink.

func (AuditFunc) Record

func (f AuditFunc) Record(ctx context.Context, event AuditEvent) error

type AuditPhase

type AuditPhase string

AuditPhase identifies one lifecycle transition. Events contain identities and digests, never raw arguments, results, credentials, or authorization tokens.

const (
	AuditDiscovery AuditPhase = "discovery"
	AuditDescribe  AuditPhase = "describe"
	AuditAuthorize AuditPhase = "authorize"
	AuditInvoke    AuditPhase = "invoke"
	AuditResult    AuditPhase = "result"
	AuditDeny      AuditPhase = "deny"
	AuditCancel    AuditPhase = "cancellation"
	AuditCleanup   AuditPhase = "cleanup"
)

type AuditSink

type AuditSink interface {
	Record(context.Context, AuditEvent) error
}

AuditSink receives ordered lifecycle events. An error before invocation is fail-closed; an error after invocation is returned with the result preserved.

type CallError

type CallError struct {
	Code  ErrorCode
	Op    string
	Err   error
	Retry RetryClass
}

CallError preserves the machine category and underlying error for errors.Is.

func (*CallError) Error

func (e *CallError) Error() string

func (*CallError) Unwrap

func (e *CallError) Unwrap() error

type CallRequest

type CallRequest struct {
	Name      string
	Arguments *structpb.Struct
	Roots     []string
	Resource  string
	Timeout   time.Duration

	// Correlation is never used as authority. Principal, tenant, environment,
	// and release authority remain session-owned.
	RequestID    string
	ObjectiveID  string
	TaskID       string
	QueryID      string
	ResultBudget *policy.ResultBudget
}

CallRequest contains no principal or credential fields; those always come from the session. Resource is copied into arguments["resource"] and conflicts are rejected so policy and plugin see one identical binding.

type CallResult

type CallResult struct {
	Response        *toolboxv0.CallToolResponse
	InvocationID    string
	AuthorizationID string
	CatalogDigest   string
	RequestDigest   string
	DecisionPath    string
	Retry           RetryClass
	RequestID       string
	ObjectiveID     string
	TaskID          string
	TraceID         string
	ReleaseID       string
}

CallResult carries only safe correlation and protocol output. The scoped token and signing secret never leave Session.

type ErrorCode

type ErrorCode string

ErrorCode is the stable machine-readable category returned by Call.

const (
	ErrorValidation         ErrorCode = "validation"
	ErrorPolicyDenied       ErrorCode = "policy_denied"
	ErrorTimeout            ErrorCode = "timeout"
	ErrorCanceled           ErrorCode = "canceled"
	ErrorBackendUnavailable ErrorCode = "backend_unavailable"
	ErrorTransport          ErrorCode = "transport"
	ErrorTool               ErrorCode = "tool_error"
	ErrorPartialResult      ErrorCode = "partial_result"
	ErrorProtocol           ErrorCode = "protocol_error"
	ErrorInternal           ErrorCode = "internal_failure"
	ErrorAudit              ErrorCode = "audit_error"
	ErrorClosed             ErrorCode = "session_closed"
)

type Options

type Options struct {
	Manifest  *resources.Toolbox
	Workspace string
	Principal *policy.Principal
	Decider   policy.Decider
	Scope     Scope

	// Launch controls only the OS admission choice. Zero-value admission is
	// promoted to production. Local tests must explicitly select AdmissionLocal.
	Launch launch.Options

	Environment     []string
	StartupTimeout  time.Duration
	DialTimeout     time.Duration
	LogWriter       io.Writer
	DefaultTTL      time.Duration
	MaxRequestBytes int

	SessionID string
	Audit     AuditSink
}

Options owns all trusted session composition. Security options are not exposed as raw manager.LoadOption values, preventing callers from overriding the bound principal, callback PDP, scoped secret, or production admission.

type RetryClass

type RetryClass string

RetryClass is advice only; ToolboxSession never retries implicitly.

const (
	RetryNever     RetryClass = "never"
	RetrySafe      RetryClass = "safe"
	RetryReconcile RetryClass = "reconcile_before_retry"
)

type Scope

type Scope struct {
	TenantID    string
	Environment string
	ReleaseID   string
	ApprovalID  string
}

Scope is trusted host/session authority, never accepted from tool arguments. These values are stamped into the plugin environment and scoped token so the verifier can independently reject cross-tenant or cross-environment calls.

type ToolboxSession

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

ToolboxSession owns one process, catalog snapshot, evaluator, and principal.

func Open

func Open(ctx context.Context, options Options) (_ *ToolboxSession, err error)

Open validates and launches a complete guarded Toolbox session. Discovery and manifest/catalog admission finish before the Session is returned.

func (*ToolboxSession) Call

func (s *ToolboxSession) Call(ctx context.Context, input CallRequest) (*CallResult, error)

Call authorizes and invokes one exact request with a single-use scoped token.

func (*ToolboxSession) Catalog

func (s *ToolboxSession) Catalog() *coretoolbox.CatalogSnapshot

Catalog returns a deep copy of the approved snapshot.

func (*ToolboxSession) Close

func (s *ToolboxSession) Close() error

Close terminates the plugin and records cleanup. It is idempotent.

func (*ToolboxSession) DescribeTool

func (s *ToolboxSession) DescribeTool(ctx context.Context, name string) (*coretoolbox.ApprovedTool, error)

DescribeTool performs phase two of discovery on demand and pins the exact descriptor digest for the lifetime of the session. A toolbox that changes a selected descriptor after approval is rejected instead of silently widening the contract beneath an existing session.