script

type BindingFunc ¶ added in v0.4.7

type BindingFunc func(ctx context.Context) (name string, value any)

BindingFunc creates a named binding for script execution. The returned name becomes the global variable name in the script scope.

type Env ¶

type Env struct {
	// Config is script-level configuration, accessible as a global in the script.
	Config map[string]any

	// Bindings maps names to host objects injected into the script's global scope.
	// Each value is typically a map[string]any of Go functions callable from the script.
	Bindings map[string]any
}

Env carries per-execution configuration and host bindings.

func BuildEnv(ctx context.Context, config map[string]any, fns ...BindingFunc) *Env

type EnvBuilder ¶ added in v0.4.7

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

EnvBuilder assembles per-execution script environments.

Ordinary bindings run first in the order they were added. Late bindings run after ordinary bindings and receive the Env being built, including the final bindings map. If multiple bindings return the same name, the later binding wins. This preserves the map-based Env semantics while making order-sensitive bindings such as runtime.execScript explicit.

func NewEnvBuilder(config map[string]any) *EnvBuilder

func (b *EnvBuilder) Add(fns ...BindingFunc) *EnvBuilder

func (b *EnvBuilder) AddLate(fns ...LateBindingFunc) *EnvBuilder

func (b *EnvBuilder) Build(ctx context.Context) *Env

type ErrorKind ¶ added in v0.3.3

type ErrorKind string

ErrorKind enumerates the errdefs categories scripts may set on signal.error({ kind, message }). Only categories that can plausibly originate from script logic are exposed — auth, rate-limit, timeout and similar wire-level classifications stay in the Go layer where they are produced.

Unknown kinds passed by a script degrade to ErrorKindInternal in SignalToError so a typo in script land cannot escape as an unclassified error.

const (
	// ErrorKindValidation marks user-input / config validation
	// failures. Maps to [errdefs.Validation] (HTTP 400).
	ErrorKindValidation ErrorKind = "validation"

	// ErrorKindNotFound marks a lookup the script performed that
	// returned nothing. Maps to [errdefs.NotFound] (HTTP 404).
	ErrorKindNotFound ErrorKind = "not_found"

	// ErrorKindBudgetExceeded marks a per-run / per-tenant budget
	// (token, cost, iteration count) the script self-detected.
	// Maps to [errdefs.BudgetExceeded] (HTTP 429).
	ErrorKindBudgetExceeded ErrorKind = "budget_exceeded"

	// ErrorKindPolicyDenied marks a policy-layer refusal raised from
	// inside the script (tool allow-list, role check, …). Maps to
	// [errdefs.PolicyDenied] (HTTP 403).
	ErrorKindPolicyDenied ErrorKind = "policy_denied"

	// ErrorKindNotAvailable marks a transient unavailability of a
	// dependency the script needed (e.g. a knowledge store down).
	// Maps to [errdefs.NotAvailable] (HTTP 503).
	ErrorKindNotAvailable ErrorKind = "not_available"

	// ErrorKindInternal is the default fallback for uncategorised
	// script-side errors. Maps to [errdefs.Internal] (HTTP 500).
	ErrorKindInternal ErrorKind = "internal"
)

type LateBindingFunc ¶ added in v0.4.7

type LateBindingFunc func(ctx context.Context, env *Env) (name string, value any)

LateBindingFunc creates a named binding after ordinary bindings are built. The Env argument exposes the final bindings map so late bindings can capture the same map passed to the runtime.

type Runtime ¶

type Runtime interface {
	Exec(ctx context.Context, name, source string, env *Env) (*Signal, error)
}

Runtime executes scripts with injected host bindings. Implementations must be safe for concurrent use.

type Signal ¶

type Signal struct {
	Type    string         `json:"type"`
	Kind    string         `json:"kind,omitempty"`
	Message string         `json:"message,omitempty"`
	Detail  map[string]any `json:"detail,omitempty"`
}

Signal represents a control signal from a script back to the host.

Type is always one of "interrupt" / "error" / "done" — the three outcomes a script can choose to surface besides "ran to completion".

Kind is a per-Type sub-classifier:

• For Type "error" it carries an errdefs category name (see ErrorKind). SignalToError maps it onto the matching errdefs wrapper; unknown values degrade to ErrorKindInternal so a typo in script land cannot escape as an unclassified error.
• For Type "interrupt" it carries an engine.Cause string. Unknown values degrade to engine.CauseCustom for the same reason.
• For Type "done" Kind is unused.

Message is the human-readable detail. Detail is freeform structured metadata scripts may attach; it is preserved across host translation but is not inspected by SignalToError today.