Struct SessionSpec 

pub struct SessionSpec {

    pub name: String,
    pub version: String,
    pub description: String,
    pub instruction: String,
    pub greeting: Option<String>,
    pub modality: SpecModality,
    pub voice: Option<String>,
    pub tools: Vec<ToolSpec>,
    pub mcp: Vec<String>,
    pub extract: Vec<ExtractSpec>,
    pub models: ModelsSpec,
    pub decisions: BTreeMap<String, DecisionSpec>,
    pub code: Option<CodeSpec>,
    pub state: BTreeMap<String, StateFieldSpec>,
    pub computed: Vec<ComputedSpec>,
    pub memory: Option<MemorySpec>,
    pub runtime: Option<RuntimeSpec>,
    pub phases: Vec<PhaseSpec>,
    pub initial_phase: Option<String>,
    pub watch: Vec<WatchSpec>,
    pub patterns: Vec<PatternSpec>,
    pub fragments: BTreeMap<String, Flow>,
    pub use_fragments: Vec<UseFragment>,
    pub flow: Option<Flow>,
    pub conversation: Option<ConversationSpec>,
    pub skills: Vec<SkillSpec>,
    pub task_scenarios: Vec<TaskScenario>,
    pub scenarios: Vec<Scenario>,
    pub tests: Vec<SpecTest>,
}

A complete Live session as one JSON document. See the module docs.

Fields

name: String

App name (display and registry identity).

version: String

Spec version tag (freeform, e.g. “1” or “2025-08-24”).

description: String

Human-readable description.

instruction: String

Base system instruction.

greeting: Option<String>

Optional greeting prompt — the model speaks first on connect.

modality: SpecModality

Output modality. Defaults to text.

voice: Option<String>

Voice name for audio sessions (e.g. “Puck”).

tools: Vec<ToolSpec>

Declared tools (mock or HTTP-bound).

mcp: Vec<String>

MCP toolset connection strings — the whole MCP ecosystem as this app’s tool library. Resolved at connect time.

extract: Vec<ExtractSpec>

Out-of-band extraction pipelines.

models: ModelsSpec

The models the spec runs on, by role.

decisions: BTreeMap<String, DecisionSpec>

Questions a decision model (such as Jev) answers about the conversation, by id. Guards name them with the decided atom, and the runtime asks the ones the flow can act on at each decision point. Requires SpecResources::decision_model.

code: Option<CodeSpec>

A code tool: the model runs a short Python program whose functions are the declared tools, each call governed like a direct call. Use it for reads the model would otherwise add up, sort or join itself.

state: BTreeMap<String, StateFieldSpec>

Declared state keys — the session’s data dictionary.

computed: Vec<ComputedSpec>

Computed (derived) state variables.

memory: Option<MemorySpec>

Durable memory: slots projected into state, remember effects, and the ambient recall/manage tools. Requires a MemoryBinding in SpecResources at apply time.

runtime: Option<RuntimeSpec>

Control-plane and voice tuning.

phases: Vec<PhaseSpec>

Conversation phases.

initial_phase: Option<String>

Initial phase name (required when phases is non-empty).

watch: Vec<WatchSpec>

State watchers.

patterns: Vec<PatternSpec>

Temporal patterns (sustained / consecutive-turn conditions).

fragments: BTreeMap<String, Flow>

Reusable flow fragments, spliced via use_fragments.

use_fragments: Vec<UseFragment>

Fragment splice directives.

flow: Option<Flow>

The governed flow DAG (optional — a spec may be phases-only).

conversation: Option<ConversationSpec>

The conversation: stages, slots, digressions, commits, timing and policies, compiled by the conversation compiler. The higher-level alternative to flow; set one or the other. Stage resolvers bind to the declared tools by name.

skills: Vec<SkillSpec>

Reusable capabilities, each with task-private state and operations.

task_scenarios: Vec<TaskScenario>

Model-free journeys through skill activation, approval and cancellation.

scenarios: Vec<Scenario>

Scenarios run against conversation by SessionSpec::run_scenarios: model-free, deterministic.

tests: Vec<SpecTest>

Embedded conformance tests, replayed offline by SessionSpec::run_tests.

Implementations

impl SessionSpec

pub fn code_tool(&self) -> Option<&str>

The code tool’s name, when the spec has one.

pub fn commit_tools(&self) -> BTreeSet<String>

The tools that commit: a conversation stage’s commit (main flow and overlays) and a flow’s commit steps.

pub fn code_functions(&self) -> Vec<String>

The tools a program can call: code.functions, or every declared tool except commits and background tools.

pub fn compile_code_mode( &self, sandbox: Option<Arc<dyn CodeSandbox>>, ) -> Option<CodeMode>

The spec’s code tool, running programs in sandbox (in this process when None). None when the spec has no code.

impl SessionSpec

pub fn to_rust(&self) -> String

The complete main.rs this spec is equivalent to.

pub fn to_cargo_toml(&self) -> String

A Cargo.toml to pair with to_rust.

impl SessionSpec

pub fn compile_decisions(&self, model: Arc<dyn DecisionModel>) -> Decisions

The decisions bank as the runtime’s Decisions, over model. Questions read outside a flow (phase transitions, patterns) are standing: asked at every caller turn.

impl SessionSpec

pub fn to_project(&self, language: ProjectLanguage) -> Vec<ProjectFile>

A project in language that runs this spec. See the module docs for what each language generates.

pub fn to_project_with( &self, language: ProjectLanguage, options: &ProjectOptions, ) -> Vec<ProjectFile>

to_project with options.

impl SessionSpec

pub fn compile_tasks( &self, resources: &SpecResources, ) -> Result<TaskRuntime, String>

Compile local skill definitions into the runtime used by Live.

pub async fn trace_tasks( &self, steps: &[TaskStep], ) -> Result<(Vec<TaskTraceSnapshot>, TaskSessionSnapshot), Vec<String>>

Replay commands with declared mock tools only. Attached implementations, HTTP bindings and MCP servers never execute in this path.

pub async fn trace_tasks_with_resources( &self, steps: &[TaskStep], resources: &SpecResources, ) -> Result<(Vec<TaskTraceSnapshot>, TaskSessionSnapshot), Vec<String>>

Replay with explicitly supplied controlled memory services. Tool implementations and extraction providers remain disabled; a supplied memory binding executes its project/ingest/remember methods and must be an operator-controlled fixture.

pub async fn run_task_scenarios(&self) -> Vec<ScenarioReport>

Run every declared task journey through the shared offline runtime.

impl SessionSpec

pub fn uses_default_extraction_model(&self) -> bool

Whether some extraction (the spec’s or a skill’s extract entries) names no model, so it runs on the host’s extraction_llm.

pub fn requires_extraction(&self) -> bool

Whether root or task definitions need an out-of-band extraction model.

pub fn requires_memory(&self) -> bool

Whether root or task definitions use the contextual memory binding.

pub fn from_value(value: Value) -> Result<Self, String>

Parse a spec from a JSON value. Accepts a full document or a bare flow ({"steps": [...]}), which is wrapped in a default spec.

pub fn json_schema() -> Value

The JSON Schema of the spec document itself — for editor autocomplete and for validating machine-authored specs at generation time.

pub fn tool_names(&self) -> Vec<String>

Declared tool names (mock/HTTP; MCP names resolve at connect).

pub fn effective_flow(&self) -> Result<Flow, Vec<String>>

The flow with every use_fragments directive spliced in.

pub fn state_keys_written(&self) -> BTreeSet<String>

Every state key the session declares a writer for: tool set_state and save_response_as, extraction names and promotion targets, phase and watcher set effects.

pub async fn run_scenarios(&self) -> Vec<ScenarioReport>

Run scenarios against the conversation, in order. Resolvers are stubbed: a scenario supplies their values with set steps.

pub fn validate(&self) -> SpecValidation

Validate the whole document: flow compilation (with the declared tool registry), fragment splicing, phase-guard restrictions, HTTP-binding support, and the read/write state-key diff.

pub fn validate_for_replay(&self) -> SpecValidation

Validate for scripted offline replay, where declared tools use mock effects and never open HTTP or MCP connections.

Checks the original document, including conflicting tool bindings. Only the requirement to compile HTTP transport support is omitted.

pub fn build_dispatcher(&self, state: &State) -> ToolDispatcher

Build the dispatcher of declared tools bound to state.

pub fn build_dispatcher_with( &self, state: &State, resources: &SpecResources, ) -> ToolDispatcher

Build the dispatcher of declared tools bound to state, calling the in-process implementations in resources where it has them. Tools bound to the same MCP server share one connection.

pub fn run_tests(&self) -> Vec<TestReport>

Run the embedded test suite offline (no model, no network) — scripted events replayed through the real FlowStack. Includes installed skill workflow tests, named skill/test.

pub fn sandboxed(&self, allow: &BindingAllowlist) -> (SessionSpec, Vec<String>)

A copy of this spec that reaches only what allow permits, and one note per binding it disabled.

mcp entries not in the allowlist are removed. A tool whose http binding is not allowed becomes a mock: it returns its canned response and still writes set_state, so the flow behaves the same way offline. Use this before apply on any spec you did not write, such as one posted by a browser.

pub fn apply( &self, live: Live, state: &State, resources: &SpecResources, ) -> Result<Live, String>

Configure a Live builder from this spec.

state is the session state the declared tools bind to — pass the same one via .state (this method does). Returns an error when the spec fails validation or requires a resource resources lacks. Everything code-only (callbacks, custom guards, middleware) is added on the returned builder afterwards.

Tool bindings run as written. For a spec you did not write, call sandboxed first.

Trait Implementations

impl Clone for SessionSpec

fn clone(&self) -> SessionSpec

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SessionSpec

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SessionSpec

fn default() -> SessionSpec

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for SessionSpec

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl JsonSchema for SessionSpec

fn schema_name() -> String

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn is_referenceable() -> bool

Whether JSON Schemas generated for this type should be re-used where possible using the $ref keyword.

impl Serialize for SessionSpec

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.