PtcRunner.Kernel.Dispatcher (PtcRunner v0.15.0)

Copy Markdown View Source

Internal bounded capability invocation boundary.

Dispatch validates normalized arguments, atomically reserves environment and provider-task budgets in PtcRunner.Kernel.RunState, emits canonical attempt events, runs the trusted callback in a monitored heap-limited process, and constructs the uniform Lisp result envelope. An error capability-stopped event carries the closed envelope kind and reason; an unrecognized atom is retained only as a one-way fingerprint, and details stay off that event. Completion is checked against run closure so late results cannot re-enter Lisp.

Mission failures after callback entry are classified with the capability's declared effect. Read failures keep an explicit typed provider retry policy. Unclassified callback raises, exits, throws, and monitored process deaths default to non-retryable in both environments; Dispatcher-owned provider timeouts remain retryable. Write and unknown failures are non-retryable and carry mutation_state: :indeterminate when invocation may have reached external state and the outcome is unknown. A trusted ProviderError with dispatch_provenance: :not_dispatched or :dispatched preserves its specific policy without exposing that internal provenance. Workflow capabilities also retain explicit provider-owned retry policy. Before a mission provider publishes a terminal policy failure, its monitored callback records that classification in RunState so a subsequent evaluator kill cannot make the agent repeat the call.

A pre-callback input-schema rejection may add up to three schema-authored argument violations to the Lisp error envelope. The rejected arguments, undeclared property names, and opaque semantic-validator reasons remain withheld. Enum and const literals are never included. After static input validation, a request schema is compiled with PtcRunner.Kernel.JSONSchema.compile_bounded/3 and stored only on the private invocation. A schema together with a non-empty tools list is invalid_arguments before reservation. A proven-invalid request schema is invalid_arguments even when the selected alias declares structured output unsupported. A live alias whose structured_output_mode is unsupported then refuses a compiled schema request as provider_error/structured_output_unsupported before reservation. Compiler unavailability uses the same capability_unavailable/input_validation_unavailable category, with no dispatch. Provider JSON-object bytes are decoded in a bounded worker before the compiled request schema validates the object; only a structured_output envelope then reaches Lisp. If bounded output validation itself becomes unavailable after dispatch, Dispatcher returns capability_unavailable/output_validation_unavailable rather than treating the provider result as invalid. A live llm-request also carries one absolute llm_request_deadline_ms sampled immediately before admission. Dispatcher enforces that cutoff through the provider worker and structured output validation; when it wins over enclosing run/workflow clocks the public result is retryable timeout/llm_request_timeout. Replay calls receive nil and stay on the enclosing provider-worker clocks.

Summary

Functions

Dispatches one capability through the bounded, context-aware boundary.

Functions

dispatch(state, environment, arg3, name, arguments, dispatch_context, event_sink, inspection_sink)

@spec dispatch(
  PtcRunner.Kernel.RunState.t(),
  :workflow | :mission,
  map(),
  binary(),
  map(),
  map(),
  term(),
  term()
) :: map()

Dispatches one capability through the bounded, context-aware boundary.