PtcRunner.Kernel.Capability (PtcRunner v0.14.0)

Copy Markdown View Source

A host-owned route from PTC-Lisp to trusted extension code.

name is the environment-local Lisp tool name. input_schema is the frozen bounded JSON Schema checked before the optional semantic validate callback, budget reservation, and provider invocation. output_schema, when present, checks successful values before they return to Lisp. callback returns {:ok, json_value} or {:error, %PtcRunner.Kernel.ProviderError{}}. Expected transient failures must use ProviderError with an explicit retryable?: true. The dispatcher contains callback raises, exits, throws, and monitored process deaths, but these unclassified failures default to non-retryable. One-argument callbacks receive only normalized arguments. Trusted two-argument callbacks additionally receive a dispatcher-owned invocation context for private observation and safe trace propagation; that context never crosses into Lisp.

description and model_visible control bounded discovery metadata only. They do not grant authority. A capability can be invoked only when the host placed it in the active workflow or mission environment.

Callbacks and validators remain host-owned and are never projected into Lisp values. The dispatcher contains ordinary raises, exits, timeouts, and oversized or invalid results, but capability implementations are trusted BEAM extensions rather than an adversarial-code boundary.

Summary

Types

callback()
callback_result()
invocation_context()
t()

Functions

metadata(capability)

Returns sanitized discovery metadata without the callback or validator.

new(opts)

Constructs a capability from required :name, :callback, and :input_schema options plus optional :output_schema, :effect, :validate, :description, and :model_visible options.

Types

callback()

@type callback() ::
  (map() -> callback_result())
  | (map(), invocation_context() -> callback_result())

callback_result()

@type callback_result() ::
  {:ok, term()} | {:error, PtcRunner.Kernel.ProviderError.t()}

invocation_context()

@type invocation_context() :: %{
  capability_id: binary(),
  inspection_sink: PtcRunner.Kernel.InspectionSink.t() | nil,
  traceparent: binary() | nil
}

t()

@type t() :: %PtcRunner.Kernel.Capability{
  callback: callback(),
  description: binary() | nil,
  effect: :read | :write | :unknown,
  input_schema: map(),
  input_validator: PtcRunner.Kernel.JSONSchema.compiled(),
  model_visible: boolean(),
  name: binary(),
  output_schema: map() | nil,
  output_validator: PtcRunner.Kernel.JSONSchema.compiled() | nil,
  validate: (map() -> :ok | {:error, binary()}) | nil
}

Functions

metadata(capability)

@spec metadata(t()) :: map()

Returns sanitized discovery metadata without the callback or validator.

new(opts)

@spec new(keyword()) :: {:ok, t()} | {:error, :invalid_capability}

Constructs a capability from required :name, :callback, and :input_schema options plus optional :output_schema, :effect, :validate, :description, and :model_visible options.

Names are bounded lower-case identifiers and may contain ., _, /, and -. Descriptions are limited to 4,096 bytes. Schemas use the bounded JSON Schema 2020-12 profile compiled by PtcRunner.Kernel.JSONSchema. Input property and constrained-literal keys must already use their underscore form so recursive Lisp argument normalization cannot change their meaning. Effects are :read, :write, or :unknown and default to :unknown.