toolbox

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Sep 29, 2026 License: AGPL-3.0 Imports: 29 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// ResolutionSatisfied: present and provably usable.
	ResolutionSatisfied = "satisfied"
	// ResolutionUnsatisfied: absent. Refusing locally is possible and names a
	// remedy the caller can act on.
	ResolutionUnsatisfied = "unsatisfied"
	// ResolutionUnknown: present, but existence does not prove operability.
	// Must NOT be reported as satisfied; execution may still proceed under
	// product or target policy, and the provider becomes the authority.
	ResolutionUnknown = "unknown"
)

Resolution states. Operator ruling 7: Resolution is not Boolean, and the existence of a key, binary or process is not proof a provider is operational.

Measured, which is why the third state exists: 

elevenlabs_tts  ELEVENLABS_API_KEY present -> HTTP 402 paid_plan_required
gflow_image     binary present, `gflow status` reports HEALTHY -> CAPTCHA_FAILED

Both would have been reported SATISFIED by a Boolean check, and both fail at the provider. UNKNOWN is the honest answer for a requirement that is present but unproven.

View Source 
const DeadlineSafetyMargin = time.Second

DeadlineSafetyMargin is reserved from any host budget so Facet can still write an envelope after a tool gives up. A tool returning exactly at the deadline is killed before its error can be reported, and the host then sees a dead process rather than a failure it can explain.

Measured: a whole invocation completes in ~0.1s and sha256 over a 200MB artifact takes 0.15s, so one second is roughly 5x the worst case observed.

View Source 
const DefaultHostDeadline = 60 * time.Second

DefaultHostDeadline is the host's deadline_ms default, from compa internal/module/runner.go:43 (DefaultDeadline = 60 * time.Second).

Facet does not own this number and cannot enforce it. It is duplicated here because an estimate must say whether a render fits BEFORE the host has sent a request to read a real deadline_ms from — the whole point of the estimate is to inform the choice of deadline_ms, so it cannot depend on one.

Note the RFC (§8) states 180000 ms while the host SHIPS 60s. The shipped constant is what kills the process, so this tracks the code, not the prose. Raised as a discrepancy in compa's lane rather than resolved here.

Variables

View Source 
var FitsDefaultHostDeadline = DefaultHostDeadline - DeadlineSafetyMargin

FitsDefaultHostDeadline is the longest render that still answers inside the default budget.

DERIVED, never written as a literal. It was previously hardcoded 55, correct when the margin was 5s; the margin later dropped to 1s and the literal did not follow, so for months the estimate warned about renders that had four spare seconds. That is the duplicated-constant defect this codebase fixed in chargeability and determinism, surviving in the estimate because a stale number stays plausible in a way a stale list does not.

Functions

func CanonicalName added in v1.1.0 

func CanonicalName(tool string) string

CanonicalName resolves compatibility aliases to the operation identity reported by envelopes, listings, and module projections.

func ChargeableTools added in v1.0.2 

func ChargeableTools() []string

ChargeableTools lists every Operation that may result in a monetary charge.

Returned as a copy so a caller cannot mutate the source of truth, and exported so conformance tests can assert over the whole set rather than spot-checking names they happen to remember.

func Description added in v1.0.2 

func Description(tool string) string

Description returns the tool's human-readable capability description.

func Deterministic added in v1.0.2 

func Deterministic(tool string) bool

Deterministic reports whether this Operation is a proven deterministic function of its request and inputs.

NOT PROJECTED ONTO THE MODULE WIRE, for the same reason as MayCharge and with the same unblocking event: v1 has no per-Operation effects and is immutable. Published locally through `facet tools list` and `describe`, which is where an agent choosing an Operation reads it today.

func EstimatedCostKnown added in v1.0.2 

func EstimatedCostKnown(tool string) bool

EstimatedCostKnown reports whether a NUMERIC cost amount is known for a canonical tool, which is the only thing cost_known means.

Exported so conformance can assert the projection reads THIS rather than inferring from may_charge. In Facet's current tool set the two are exact inverses for every tool, so a value comparison cannot tell them apart -- a mutation setting cost_known = !may_charge passed every value assertion. The inverse relationship is an accident of today's tools, not the contract.

func ExternalWriteFor added in v1.0.2 

func ExternalWriteFor(tool string) bool

func LookPathForTest added in v1.0.2 

func LookPathForTest(program string) (string, error)

LookPathForTest exposes the resolution seam so a sibling package can verify that a host-supplied grant was actually installed rather than only validated.

func MayCharge added in v1.0.2 

func MayCharge(tool string) bool

MayCharge reports whether invoking this Operation may result in a monetary charge to the operator.

NOT PROJECTED ONTO THE MODULE WIRE, and here is the unblocking event rather than just the state: xibodev.module/v1 carries effects only on the Capability, and v1 is immutable. A host reads capability.Effects at registration to build its tool description, so per-Operation effects have nowhere to land until the v2 effects shape exists. That shape is compa's to publish; when it does, this becomes a mapping rather than a move.

Unwired because there is no wire, not because it was forgotten. Those look identical from outside, which is why this says which one it is.

Independent of cost_known, which answers a different question: whether a numeric amount is known. Both combinations are legal and both occur here — every chargeable Operation has an unknown amount (may_charge=true, cost_known=false), and edge_tts reaches the network with a known amount of zero (may_charge=false, cost_known=true).

Approval policy must key on THIS, never on cost_known. Verified before this existed: edge_tts declared cost_known=true and ran without consent while reaching an external service.

func Names 

func Names() []string

Names returns a defensive copy of the exact public tool catalog.

func NetworkFor added in v1.0.2 

func NetworkFor(tool string) bool

NetworkFor and ExternalWriteFor expose the canonical per-tool effects so a PROJECTION can derive its pessimistic union instead of restating it.

Exported for exactly that reason: a capability that dispatches any canonical tool must declare the worst case any of them can do, and a hardcoded literal there is a second effects table waiting to drift.

func Parameters added in v1.0.2 

func Parameters(tool string) map[string]any

Parameters returns the JSON Schema for the tool's input parameters.

func ProjectArguments added in v1.0.2 

func ProjectArguments(args map[string]any, workspace string) map[string]any

Project-relative explicit file arguments must not resolve against the server's working directory. URLs and prose remain unchanged, including nested clips.

func SetBinaryPaths added in v1.0.2 

func SetBinaryPaths(paths map[string]string)

SetBinaryPaths replaces the resolution override. A nil or empty map restores ordinary PATH lookup, which is what the human-facing `facet tools` CLI uses.

Names are matched case-insensitively and without any extension, so a host may supply "ffmpeg" for ffmpeg.exe.

func SetBundleRoot added in v1.0.2 

func SetBundleRoot(path string)

SetBundleRoot installs the host-supplied bundle location for one invocation. An empty value restores ordinary discovery, which is what the CLI uses.

func V2ArtifactKinds added in v1.0.2 

func V2ArtifactKinds() map[string]V2ArtifactKind

V2ArtifactKinds returns the artifact kinds Facet actually emits.

Every kind here is referenced by at least one Operation's `produces`, and every `produces` entry names a kind here. A kind nothing produces is the declared-but-never-emitted defect; a produces entry naming no kind is a dangling reference. Both are asserted in tests.

func ValidateRequest added in v1.1.0 

func ValidateRequest(tool string, data []byte) error

ValidateRequest validates a concrete request through the canonical estimate path. Estimates execute no production work, but they do enforce semantic requirements such as real input files and operation-specific constraints.

func ValidateRequestShape added in v1.1.0 

func ValidateRequestShape(tool string, data []byte) error

ValidateRequestShape validates a request against the canonical JSON schema without requiring intermediate files to exist yet.

Types

type Envelope 

type Envelope struct {
	OK        bool       `json:"ok"`
	Tool      string     `json:"tool,omitempty"`
	Operation string     `json:"operation"`
	Result    any        `json:"result,omitempty"`
	Error     *ToolError `json:"error,omitempty"`
	Warnings  []string   `json:"warnings"`
	Execution Execution  `json:"execution"`
}

func CLI 

func CLI(args []string) (Envelope, bool)

func Run added in v1.0.2 

func Run(tool string, data []byte) Envelope

Run executes a tool operation in 'run' mode with raw JSON input.

func RunContext added in v1.0.2 

func RunContext(ctx context.Context, tool string, data []byte) Envelope

RunContext carries cancellation into media execution and network requests.

type Execution 

type Execution struct {
	Provider      string   `json:"provider"`
	Network       bool     `json:"network"`
	ExternalWrite bool     `json:"external_write"`
	EstimatedCost *float64 `json:"estimated_cost"`
	ActualCost    *float64 `json:"actual_cost"`
}

type ToolError 

type ToolError struct {
	Code      string         `json:"code"`
	Message   string         `json:"message"`
	Retryable bool           `json:"retryable"`
	Details   map[string]any `json:"details"`
}

type V2ArtifactKind added in v1.0.2 

type V2ArtifactKind struct {
	Kind      string `json:"kind"`
	MediaType string `json:"media_type"`
	// Validator is deliberately ABSENT for every Facet kind. The field exists
	// so a `document` kind could name one; Facet has no document artifacts.
	Validator *V2Validator `json:"validator,omitempty"`
}

V2ArtifactKind is one declared output type.

type V2Effects added in v1.0.2 

type V2Effects struct {
	Network       bool `json:"network"`
	ExternalWrite bool `json:"external_writes"`
	MayCharge     bool `json:"may_charge"`
	CostKnown     bool `json:"cost_known"`
	Deterministic bool `json:"deterministic"`
}

V2Effects is an Operation's declared effects.

may_charge and cost_known are INDEPENDENT and neither is inferred from the other. Five Facet tools are networked and free (edge_tts, pexels_video, pixabay_video, wikimedia, direct_clip_search): cost known, amount zero, no charge. Eight may charge and their amount is unknowable before the call.

type V2Operation added in v1.0.2 

type V2Operation struct {
	ID           string          `json:"id"`
	Title        string          `json:"title"`
	Effects      V2Effects       `json:"effects"`
	Requirements []V2Requirement `json:"requirements"`
	// Produces names artifact kinds declared in the descriptor's
	// artifact_kinds map. An Operation naming a kind that is not declared is a
	// dangling reference the host reports.
	Produces []string `json:"produces,omitempty"`
	// Implementations are the interchangeable ways this Operation runs. More
	// than one is a multi-Implementation Operation, NOT a Composite: a
	// Composite would require a typed child-Operation graph, and selecting
	// between renderers is not that.
	Implementations []string `json:"implementations,omitempty"`
}

V2Operation is the semantic unit: what this Operation MEANS, as opposed to what the capability surface exposes.

func V2Operations added in v1.0.2 

func V2Operations() []V2Operation

V2Operations projects every public tool as an Operation.

Sorted so the descriptor is byte-stable: an unordered map would make two identical modules produce different bytes and defeat digest comparison.

type V2Requirement added in v1.0.2 

type V2Requirement struct {
	Name string `json:"name"`
	Kind string `json:"kind"`
	// Strength is "mandatory" or "preferred" -- the frozen vocabulary. A
	// preferred requirement that is
	// unsatisfied degrades the Operation rather than blocking it.
	Strength string `json:"strength"`
	// Resolution is SATISFIED, UNSATISFIED or UNKNOWN — never collapsed to a
	// boolean. A present credential resolves UNKNOWN because holding a key is
	// not proof the provider will serve you.
	Resolution string `json:"resolution"`
}

V2Requirement is one thing an Operation needs, with how badly it needs it.

type V2Validator added in v1.0.2 

type V2Validator struct {
	Type   string `json:"type"`
	Schema string `json:"schema"`
}

V2Validator names a check over an artifact's own content.

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.