script

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.

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 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.