Runtime or host work represented as data.
Effects generalize the old pending-action shape. An action is now one effect kind; future capabilities such as retrieval or search can use the same contract without changing turn decisions. Action effects carry their owning module and mounted scope as first-class fields; payload data cannot override that trusted runtime origin.
Summary
Functions
Returns the Action Language text encoded in an action effect payload.
Marks a policy-gated effect as approved without executing it.
Associates an Effect with its owning Instance Run.
Marks an effect as cancelled.
Marks an effect as completed with a result.
Returns the stable key used for protection and dispatch checks.
Returns whether an effect is ready for its host capability boundary.
Marks an effect as failed with an error.
Returns hooks attached to an effect payload.
Returns the stable key that an action adapter can use to deduplicate retries.
Normalizes a terminal effect into a host-facing outcome.
Returns the module that owned the route which staged the effect.
Returns the planner that produced the action, when present.
Restores a persisted effect without inventing a missing scope.
Returns the approved provider schema hash, when present.
Returns the Agent or mounted-Skill scope that staged the effect.
Returns the selected tool encoded in an action effect payload.
Returns the source encoded in an effect payload.
Builds a pending effect outside a routed Skill context.
Builds a pending action effect with a trusted owner and scope.
Returns whether an effect reached a terminal lifecycle state.
Returns the provider identifier encoded in an action effect.
Marks an effect as waiting on a policy gate.
Types
@type status() ::
:pending | :waiting_policy | :approved | :completed | :failed | :cancelled
@type t() :: %Spectre.Effect{ args: map(), error: term(), id: term(), idempotency_key: String.t(), kind: atom(), metadata: map(), mode: atom() | nil, name: atom() | String.t() | nil, owner: module() | nil, payload: map(), policy: term(), result: term(), run_id: String.t() | nil, scope: Spectre.Definition.scope() | nil, status: status() }
Functions
Returns the Action Language text encoded in an action effect payload.
Marks a policy-gated effect as approved without executing it.
Approval is a durable state transition. The host may execute the effect only after the approved state has been persisted.
Associates an Effect with its owning Instance Run.
Extension-owned Effect builders should use
Spectre.Context.lifecycle_run_id/1 and bind the returned value before
staging. Passing nil preserves the stateless and Session compatibility
lifecycle.
Marks an effect as cancelled.
Marks an effect as completed with a result.
Returns the stable key used for protection and dispatch checks.
Returns whether an effect is ready for its host capability boundary.
Policy-gated effects become executable only after their durable
:waiting_policy -> :approved transition.
Marks an effect as failed with an error.
Returns hooks attached to an effect payload.
Returns the stable key that an action adapter can use to deduplicate retries.
Normalizes a terminal effect into a host-facing outcome.
Older adapters may have stored {:ok, value} or {:error, reason} inside
a completed effect. These shapes are flattened for backwards compatibility.
Non-terminal effects return nil.
Returns the module that owned the route which staged the effect.
Legacy persisted effects may not carry an owner and return nil.
Returns the planner that produced the action, when present.
Restores a persisted effect without inventing a missing scope.
Durable codecs use this behavior for legacy state. An unscoped restored effect remains observable but must be rejected by the execution boundary.
Returns the approved provider schema hash, when present.
@spec scope(t()) :: Spectre.Definition.scope() | nil
Returns the Agent or mounted-Skill scope that staged the effect.
Older persisted effects may not carry a scope and return nil.
Returns the selected tool encoded in an action effect payload.
Returns the source encoded in an effect payload.
Builds a pending effect outside a routed Skill context.
Effects staged through this generic compatibility API default to Agent scope.
Routed actions should use stage_action/3 so ownership cannot be omitted.
@spec stage_action(map() | struct(), module(), Spectre.Definition.scope()) :: t()
Builds a pending action effect with a trusted owner and scope.
Explicit origin arguments replace any owner or scope supplied by the action payload. Both deterministic DSL actions and model-planned actions use this constructor.
Returns whether an effect reached a terminal lifecycle state.
@spec via(t()) :: Spectre.Action.provider_ref()
Returns the provider identifier encoded in an action effect.
Effects written before provider separation default to the local Elixir provider.
Marks an effect as waiting on a policy gate.