toolbox

Documentation

Overview

Package toolbox contains the small process-level conventions shared by standalone Codefly toolbox plugins.

Index

• Constants
• func DigestCallToolRequest(request *toolboxv0.CallToolRequest) (string, error)
• func Environment(key, fallback string) string
• func EnvironmentList(key string) []string
• func RedactWithSchema(schema *structpb.Struct, value any) any
• func ValidateArguments(schema, arguments *structpb.Struct) error
• func ValidateSchema(schema *structpb.Struct) error
• func Version() string
• type ApprovedTool
• type CatalogSnapshot
  • func NewCatalogSnapshot(identity *toolboxv0.IdentityResponse, ...) (*CatalogSnapshot, error)
  • func SnapshotServer(ctx context.Context, server toolboxv0.ToolboxServer) (*CatalogSnapshot, error)
  • func (s *CatalogSnapshot) ApproveTool(name string, description *toolboxv0.DescribeToolResponse) (*ApprovedTool, error)
  • func (s *CatalogSnapshot) Clone() *CatalogSnapshot
  • func (s *CatalogSnapshot) HasTool(name string) bool
  • func (s *CatalogSnapshot) ToolNames() []string
• type IdempotencyClass
  • func ParseIdempotency(value string) (IdempotencyClass, error)

Constants

const RedactedValue = "[REDACTED]"

const RequireBoundAuthorizationEnvironment = "CODEFLY_TOOLBOX_REQUIRE_BOUND_AUTHZ"

RequireBoundAuthorizationEnvironment makes the plugin guard require catalog and exact-request digests on every scoped authorization. Production manager admission sets it after caller-provided environment values.

const VersionEnvironment = "CODEFLY_TOOLBOX_VERSION"

Functions

func DigestCallToolRequest

func DigestCallToolRequest(request *toolboxv0.CallToolRequest) (string, error)

DigestCallToolRequest returns a deterministic digest of the exact protobuf request (tool name, structured arguments, and roots).

func Environment

func Environment(key, fallback string) string

Environment returns an environment value or a fallback when it is unset.

func EnvironmentList

func EnvironmentList(key string) []string

EnvironmentList parses a comma-separated environment variable, trimming whitespace and omitting empty entries.

func RedactWithSchema

func RedactWithSchema(schema *structpb.Struct, value any) any

RedactWithSchema returns a JSON-shaped copy safe for diagnostics. Schema fields marked writeOnly, x-codefly-sensitive, or with a sensitive x-codefly-classification are replaced. Unknown object fields and values with no schema are redacted fail-closed.

func ValidateArguments

func ValidateArguments(schema, arguments *structpb.Struct) error

ValidateArguments compiles the approved JSON Schema and validates arguments. Missing or malformed schemas fail closed: every production tool contract must describe its input, even when that input is an empty object.

func ValidateSchema

func ValidateSchema(schema *structpb.Struct) error

ValidateSchema checks only the descriptor contract, without requiring that an empty argument object satisfy fields required at invocation time.

func Version

func Version() string

Version returns the version injected by the host, or the development value used when a toolbox binary is launched directly.

Types

type ApprovedTool

type ApprovedTool struct {
	Summary     *toolboxv0.ToolSummary
	Description *toolboxv0.DescribeToolResponse
	Digest      string
	Idempotency IdempotencyClass
}

ApprovedTool is the second discovery phase. Digest binds the toolbox identity, complete summary catalog, and this exact full descriptor.

type CatalogSnapshot

type CatalogSnapshot struct {
	Identity  *toolboxv0.IdentityResponse
	Summaries *toolboxv0.ListToolSummariesResponse
	Digest    string
}

CatalogSnapshot is the immutable first phase of toolbox discovery: identity plus lightweight summaries. Full descriptions are deliberately excluded so hosts can fetch and approve only the selected tool immediately before use.

func NewCatalogSnapshot

func NewCatalogSnapshot(
	identity *toolboxv0.IdentityResponse,
	summaries *toolboxv0.ListToolSummariesResponse,
) (*CatalogSnapshot, error)

NewCatalogSnapshot validates, canonicalizes, clones, and hashes first-phase discovery. Wire ordering does not affect the digest.

func SnapshotServer

func SnapshotServer(ctx context.Context, server toolboxv0.ToolboxServer) (*CatalogSnapshot, error)

SnapshotServer discovers only identity and summaries. Plugin guards and external hosts both call ApproveTool for the selected action, preventing the legacy eager ListTools behavior from creeping back into the host contract.

func (*CatalogSnapshot) ApproveTool

func (s *CatalogSnapshot) ApproveTool(name string, description *toolboxv0.DescribeToolResponse) (*ApprovedTool, error)

ApproveTool validates a phase-two descriptor against the phase-one catalog and returns the digest the host must bind into scoped authorization.

func (*CatalogSnapshot) Clone

func (s *CatalogSnapshot) Clone() *CatalogSnapshot

Clone returns a deep copy suitable for exposing outside a session.

func (*CatalogSnapshot) HasTool

func (s *CatalogSnapshot) HasTool(name string) bool

HasTool reports whether name was present in phase-one discovery.

func (*CatalogSnapshot) ToolNames

func (s *CatalogSnapshot) ToolNames() []string

ToolNames returns the canonical sorted catalog names.

type IdempotencyClass

type IdempotencyClass string

IdempotencyClass is the closed, host-interpreted ToolSpec idempotency set. Unknown or free-text values can never authorize an automatic retry.

const (
	IdempotencyUnknown       IdempotencyClass = "unknown"
	IdempotencySafe          IdempotencyClass = "idempotent"
	IdempotencySideEffecting IdempotencyClass = "side_effecting"
)

func ParseIdempotency

func ParseIdempotency(value string) (IdempotencyClass, error)

ParseIdempotency converts the protocol field into its closed semantic set. Empty remains a supported explicit unknown for existing tool definitions.