Spectre.Skill.Runtime (Spectre v0.3.0)

Immutable, host-governed registry for compiled and runtime Skills.

Mount, replacement and disable are explicit authority-checked operations with revision compare-and-swap. Routing is fail-closed, prompt capacity reserves the kernel window first, and continuations remain pinned to the exact content-addressed Skill generation that created them.

Summary

Types

continuation()

entry()

lifecycle()

t()

Functions

capability(atom)

Returns the stable host capability required for one lifecycle action.

claim_continuation(runtime, mount_id, continuation_id, opts \\ [])

Pins a caller-owned continuation to the current exact Skill generation.

continuation(runtime, continuation_id)

Resolves the exact active or retired Definition pinned by a continuation.

disable(runtime, mount_id, opts \\ [])

Disables a mount immediately or drains its owned continuations.

mount(runtime, mount_id, source, opts \\ [])

Mounts one compiled or runtime Definition after all gates pass.

mounts(runtime)

Returns a deterministic summary of all current mounts.

new(agent, authority, opts \\ [])

Creates an empty Skill runtime under an effective Authority Envelope.

new!(agent, authority, opts \\ [])

Creates a Skill runtime or raises with its stable validation reason.

release_continuation(runtime, continuation_id, opts \\ [])

Releases one continuation and completes any exhausted drain.

replace(runtime, mount_id, source, opts \\ [])

Atomically replaces a mount and drains its pinned generation if needed.

respond(runtime, input, context \\ %{}, opts \\ [])

Builds a reply or registered Operation Request without executing it.

route(runtime, input, context \\ %{})

Returns the active route selected across mounted Skills.

status(runtime, mount_id)

Returns a stable lifecycle projection for one mount.

Types

continuation()

@type continuation() :: %{mount_id: term(), definition_ref: String.t()}

entry()

@type entry() :: %{
  mount_id: term(),
  definition: Spectre.Skill.Definition.t(),
  state: lifecycle(),
  mounted_revision: non_neg_integer(),
  routing_projection: Spectre.Projection.t()
}

lifecycle()

@type lifecycle() :: :active | :draining | :disabled

t()

@type t() :: %Spectre.Skill.Runtime{
  agent: module(),
  authority: Spectre.Authority.Envelope.t(),
  continuations: %{optional(String.t()) => continuation()},
  index_profile: Spectre.Router.IndexProfile.t(),
  kernel_prompt_tokens: non_neg_integer(),
  max_prompt_tokens: pos_integer(),
  mounts: %{optional(term()) => entry()},
  per_skill_prompt_cap: pos_integer(),
  retired: %{optional({term(), String.t()}) => entry()},
  revision: non_neg_integer()
}

Functions

capability(atom)

@spec capability(:mount | :replace | :disable) :: String.t()

Returns the stable host capability required for one lifecycle action.

claim_continuation(runtime, mount_id, continuation_id, opts \\ [])

@spec claim_continuation(t(), term(), String.t(), keyword()) ::
  {:ok, t()} | {:error, term()}

Pins a caller-owned continuation to the current exact Skill generation.

continuation(runtime, continuation_id)

@spec continuation(t(), String.t()) ::
  {:ok, Spectre.Skill.Definition.t()} | {:error, term()}

Resolves the exact active or retired Definition pinned by a continuation.

disable(runtime, mount_id, opts \\ [])

@spec disable(t(), term(), keyword()) :: {:ok, t()} | {:error, term()}

Disables a mount immediately or drains its owned continuations.

mount(runtime, mount_id, source, opts \\ [])

@spec mount(t(), term(), term(), keyword()) :: {:ok, t()} | {:error, term()}

Mounts one compiled or runtime Definition after all gates pass.

mounts(runtime)

@spec mounts(t()) :: [map()]

Returns a deterministic summary of all current mounts.

new(agent, authority, opts \\ [])

@spec new(module(), Spectre.Authority.Envelope.t() | map() | keyword(), keyword()) ::
  {:ok, t()} | {:error, term()}

Creates an empty Skill runtime under an effective Authority Envelope.

new!(agent, authority, opts \\ [])

@spec new!(module(), Spectre.Authority.Envelope.t() | map() | keyword(), keyword()) ::
  t()

Creates a Skill runtime or raises with its stable validation reason.

release_continuation(runtime, continuation_id, opts \\ [])

@spec release_continuation(t(), String.t(), keyword()) ::
  {:ok, t()} | {:error, term()}

Releases one continuation and completes any exhausted drain.

replace(runtime, mount_id, source, opts \\ [])

@spec replace(t(), term(), term(), keyword()) :: {:ok, t()} | {:error, term()}

Atomically replaces a mount and drains its pinned generation if needed.

respond(runtime, input, context \\ %{}, opts \\ [])

@spec respond(t(), term(), map(), keyword()) ::
  {:ok, Spectre.Skill.Runtime.Response.t(), t()} | {:error, term()}

Builds a reply or registered Operation Request without executing it.

route(runtime, input, context \\ %{})

@spec route(t(), term(), map()) :: {:ok, map()} | {:error, term()}

Returns the active route selected across mounted Skills.

status(runtime, mount_id)

@spec status(t(), term()) :: {:ok, map()} | {:error, term()}

Returns a stable lifecycle projection for one mount.