packspec

type ActionScope struct {
	// DataClasses classes of data the tool touches, as vocabulary terms or free strings.
	DataClasses []string `json:"data_classes,omitempty" yaml:"data_classes,omitempty"`

	// Effect 'read': retrieves, changes nothing. 'write': changes state the operator controls.
	// 'external': causes an effect outside the operator's systems (implies write).
	Effect string `json:"effect,omitempty" yaml:"effect,omitempty"`

	// Extensions opaque annotations about this tool's consequence — a blast radius, a severity score,
	// anything that qualifies what it affects. Never interpreted by this specification. Keys
	// SHOULD be namespaced.
	Extensions map[string]any `json:"extensions,omitempty" yaml:"extensions,omitempty"`

	// Reversibility 'reversible': the prior state can be restored. 'compensable': it cannot, but a defined
	// compensating action limits the harm. 'irreversible': nothing restores the state and
	// nothing compensates. Declare against the world, not the API.
	Reversibility string `json:"reversibility,omitempty" yaml:"reversibility,omitempty"`
}

type AgentDef struct {
	// Description agent description published in the A2A Agent Card. Overrides the prompt's description if
	// set.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Governance governance facts for this agent, overriding metadata.governance by per-field replacement:
	// a field present here replaces the pack value for that field, a field absent inherits.
	// Arrays and extensions replace whole (RFC 0013).
	Governance *Governance `json:"governance,omitempty" yaml:"governance,omitempty"`

	// InputModes MIME types the agent accepts as input. Defaults to ["text/plain"] if omitted.
	InputModes []string `json:"input_modes,omitempty" yaml:"input_modes,omitempty"`

	// OutputModes MIME types the agent can produce as output. Defaults to ["text/plain"] if omitted.
	OutputModes []string `json:"output_modes,omitempty" yaml:"output_modes,omitempty"`

	// State reference to a state key in the pack's workflow.states. When set, invoking this agent
	// runs the pack workflow starting at the named state (following its transitions and loops)
	// instead of executing the member-key prompt once. Requires a top-level workflow. If
	// omitted, the agent is a single-prompt agent.
	State string `json:"state,omitempty" yaml:"state,omitempty"`

	// Tags discovery tags for the agent, used by A2A registries and routers.
	Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"`
}

type AgentStep struct {
	Input *StepInput `json:"input,omitempty" yaml:"input,omitempty"`

	Kind any `json:"kind" yaml:"kind"`

	OutputSchema string `json:"output_schema,omitempty" yaml:"output_schema,omitempty"`

	PromptTask string `json:"prompt_task" yaml:"prompt_task"`

	// Termination REQUIRED. The condition under which the bounded loop exits. Without an explicit
	// termination predicate, an agent step is invalid.
	Termination *TerminationPredicate `json:"termination" yaml:"termination"`

	// Tools subset of the pack's tools available to this agent step. Acts as a per-step scoped tool
	// registry.
	Tools []string `json:"tools,omitempty" yaml:"tools,omitempty"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type AgentsConfig struct {
	// Entry prompt key of the entry agent — the default agent that receives incoming requests.
	Entry string `json:"entry" yaml:"entry"`

	// Members map of prompt key to agent definition. Each key must match a prompt defined in the pack's
	// prompts object.
	Members map[string]*AgentDef `json:"members" yaml:"members"`
}

type AllOfPredicate struct {
	AllOf []*Predicate `json:"all_of" yaml:"all_of"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type AnyOfPredicate struct {
	AnyOf []*Predicate `json:"any_of" yaml:"any_of"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type ArtifactDef struct {
	// Description human-readable description of what this artifact contains and how it's used.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Mode how the artifact is updated across visits. 'replace' overwrites the previous value on
	// each visit. 'append' accumulates content across visits (e.g., a log). Defaults to
	// 'replace'.
	Mode *string `json:"mode,omitempty" yaml:"mode,omitempty"`

	// Type MIME type indicating the artifact's content type. Used by runtimes to determine
	// serialization and presentation.
	Type string `json:"type" yaml:"type"`
}

type AudioConfig struct {
	// AllowedFormats list of allowed audio formats
	AllowedFormats []string `json:"allowed_formats,omitempty" yaml:"allowed_formats,omitempty"`

	// MaxDurationSec maximum audio duration in seconds
	MaxDurationSec *int `json:"max_duration_sec,omitempty" yaml:"max_duration_sec,omitempty"`

	// MaxSizeMB maximum file size in megabytes
	MaxSizeMB *int `json:"max_size_mb,omitempty" yaml:"max_size_mb,omitempty"`

	// RequireMetadata whether audio metadata (title, description) is required
	RequireMetadata *bool `json:"require_metadata,omitempty" yaml:"require_metadata,omitempty"`
}

type BranchStep struct {
	// Else step ID to execute when the predicate evaluates false.
	Else string `json:"else,omitempty" yaml:"else,omitempty"`

	Kind any `json:"kind" yaml:"kind"`

	Predicate *Predicate `json:"predicate" yaml:"predicate"`

	// Then step ID to execute when the predicate evaluates true.
	Then string `json:"then" yaml:"then"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type ComparePredicate struct {
	Op string `json:"op" yaml:"op"`

	// Path reference to a value via dot-notation against the composition's input and step outputs.
	// Example: '${classify.output.intent}'.
	Path string `json:"path" yaml:"path"`

	// Value literal comparison value (string, number, boolean, or array for in/not_in).
	Value any `json:"value" yaml:"value"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type Composition struct {
	// Description human-readable description of what this composition does.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Engine runtime-specific configuration (e.g. budgets, telemetry, scheduling hints). Opaque escape
	// hatch with no schema enforcement.
	Engine map[string]any `json:"engine,omitempty" yaml:"engine,omitempty"`

	// InputSchema reference to a JSON Schema declaring the structured input shape. Path or fragment
	// reference.
	InputSchema string `json:"input_schema,omitempty" yaml:"input_schema,omitempty"`

	// Output step ID whose output is the composition's output. If omitted, runtimes should treat the
	// last step's output as the composition output.
	Output string `json:"output,omitempty" yaml:"output,omitempty"`

	// OutputSchema reference to a JSON Schema declaring the structured output shape.
	OutputSchema string `json:"output_schema,omitempty" yaml:"output_schema,omitempty"`

	// Steps ordered array of step definitions. Order is logical; control flow is determined by the
	// steps themselves (sequential by default; branches and parallels alter flow).
	Steps []*Step `json:"steps" yaml:"steps"`

	// Version composition format version. Currently 1.
	Version int `json:"version" yaml:"version"`
}

type ContentPart struct {
	// Media media reference (required when type is 'image', 'audio', or 'video')
	Media *MediaReference `json:"media,omitempty" yaml:"media,omitempty"`

	// Text text content (required when type is 'text')
	Text string `json:"text,omitempty" yaml:"text,omitempty"`

	// Type type of content part. Common types include: text, image, audio, video, document. Custom
	// types are allowed for extensibility.
	Type string `json:"type" yaml:"type"`
}

type DocumentConfig struct {
	// AllowedFormats list of allowed document formats
	AllowedFormats []string `json:"allowed_formats,omitempty" yaml:"allowed_formats,omitempty"`

	// ExtractionMode how to extract content from documents. 'text' extracts text only, 'structured' preserves
	// formatting, 'raw' keeps original binary format.
	ExtractionMode *string `json:"extraction_mode,omitempty" yaml:"extraction_mode,omitempty"`

	// MaxPages maximum number of pages/sheets for paginated documents
	MaxPages *int `json:"max_pages,omitempty" yaml:"max_pages,omitempty"`

	// MaxSizeMB maximum file size in megabytes
	MaxSizeMB *int `json:"max_size_mb,omitempty" yaml:"max_size_mb,omitempty"`

	// RequireMetadata whether document metadata (title, author, description) is required
	RequireMetadata *bool `json:"require_metadata,omitempty" yaml:"require_metadata,omitempty"`
}

type Eval struct {
	// Description human-readable description of what this eval measures and why it matters.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Enabled whether this eval is active. Allows temporarily disabling evals without removing them.
	Enabled *bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`

	// Groups eval group tags for organizing and filtering evals.
	Groups []string `json:"groups,omitempty" yaml:"groups,omitempty"`

	// ID unique identifier for this eval within its scope (prompt-level or pack-level).
	ID string `json:"id" yaml:"id"`

	// Message human-readable message describing the eval result or failure reason.
	Message string `json:"message,omitempty" yaml:"message,omitempty"`

	// Metric prometheus-style metric declaration describing the output shape of this eval. Runtimes
	// use this to expose results to monitoring systems.
	Metric *MetricDef `json:"metric,omitempty" yaml:"metric,omitempty"`

	// Params type-specific configuration for the eval. Structure depends on the eval type — runtimes
	// interpret these based on the type field.
	Params map[string]any `json:"params,omitempty" yaml:"params,omitempty"`

	// SamplePercentage percentage of turns or sessions to sample when trigger is sample_turns or
	// sample_sessions. Ignored for other trigger types.
	SamplePercentage *float64 `json:"sample_percentage,omitempty" yaml:"sample_percentage,omitempty"`

	// Threshold pass/fail threshold for the eval score.
	Threshold *EvalThreshold `json:"threshold,omitempty" yaml:"threshold,omitempty"`

	// Trigger when this eval should be triggered.
	Trigger string `json:"trigger" yaml:"trigger"`

	// Type the assertion type that determines how this eval is executed. Not an enum — runtimes
	// define and register their own types.
	Type string `json:"type" yaml:"type"`

	// When conditional expression that determines whether this eval runs for a given turn or session.
	When map[string]any `json:"when,omitempty" yaml:"when,omitempty"`
}

type EvalThreshold struct {
	// Operator comparison operator for the threshold.
	Operator string `json:"operator,omitempty" yaml:"operator,omitempty"`

	// Value the threshold value to compare against.
	Value *float64 `json:"value,omitempty" yaml:"value,omitempty"`
}

type ExistsPredicate struct {
	Exists bool `json:"exists" yaml:"exists"`

	Path string `json:"path" yaml:"path"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type GenericMediaTypeConfig struct {
	// AllowedFormats list of allowed file formats/extensions
	AllowedFormats []string `json:"allowed_formats,omitempty" yaml:"allowed_formats,omitempty"`

	// MaxSizeMB maximum file size in megabytes
	MaxSizeMB *int `json:"max_size_mb,omitempty" yaml:"max_size_mb,omitempty"`

	// RequireMetadata whether metadata is required for this media type
	RequireMetadata *bool `json:"require_metadata,omitempty" yaml:"require_metadata,omitempty"`

	// ValidationParams custom validation parameters specific to this media type. Structure depends on the type.
	ValidationParams map[string]any `json:"validation_params,omitempty" yaml:"validation_params,omitempty"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type Governance struct {
	// AccountableOwner the role, team or function answerable for this agent. Prefer a durable identifier over a
	// named individual.
	AccountableOwner string `json:"accountable_owner,omitempty" yaml:"accountable_owner,omitempty"`

	// ApprovedEnvironments environments this pack has been cleared to run in. Open strings, because environment
	// names are organisation-specific. Absence means undeclared, not cleared everywhere and not
	// cleared nowhere.
	ApprovedEnvironments []string `json:"approved_environments,omitempty" yaml:"approved_environments,omitempty"`

	// AutonomyLevel how far the agent acts without a human in the loop, as designed and tested. 'suggests':
	// produces output, a human performs any action. 'acts_with_approval': acts, but each
	// consequential action is approved first. 'acts_with_oversight': acts on its own, a human
	// monitors and can intervene or reverse. 'acts_autonomously': acts without a human in the
	// loop.
	AutonomyLevel string `json:"autonomy_level,omitempty" yaml:"autonomy_level,omitempty"`

	// Capabilities capabilities the agent exercises, as vocabulary terms or free strings. Some capabilities
	// carry obligations regardless of sector, so this is not covered by
	// intended_deployment_contexts.
	Capabilities []string `json:"capabilities,omitempty" yaml:"capabilities,omitempty"`

	// Extensions opaque annotations for external tooling. Never interpreted by this specification. Keys
	// SHOULD be namespaced.
	Extensions map[string]any `json:"extensions,omitempty" yaml:"extensions,omitempty"`

	// ForeseeableMisuse uses the author considers out of bounds and reasonably foreseeable.
	ForeseeableMisuse []string `json:"foreseeable_misuse,omitempty" yaml:"foreseeable_misuse,omitempty"`

	// IntendedDeploymentContexts sectors or settings the agent is built for, as vocabulary terms or free strings. Distinct
	// from metadata.domain, which is a discovery tag.
	IntendedDeploymentContexts []string `json:"intended_deployment_contexts,omitempty" yaml:"intended_deployment_contexts,omitempty"`

	// IntendedPurpose what the agent is built to do, stated by its author. Free text.
	IntendedPurpose string `json:"intended_purpose,omitempty" yaml:"intended_purpose,omitempty"`

	// OperatorRole the declaring organisation's role for this agent, as a vocabulary term or free string.
	OperatorRole string `json:"operator_role,omitempty" yaml:"operator_role,omitempty"`

	// RequiresAIDisclosure whether the agent must disclose that it is an AI to the people interacting with it. The
	// runtime decides which of its interfaces this applies to.
	RequiresAIDisclosure *bool `json:"requires_ai_disclosure,omitempty" yaml:"requires_ai_disclosure,omitempty"`

	// RiskClassification the risk classification assigned to this agent, as a vocabulary term or free string. A
	// namespaced term carries both the framework and the value, so no separate framework field
	// is needed; a second classification under another framework belongs in extensions.
	RiskClassification string `json:"risk_classification,omitempty" yaml:"risk_classification,omitempty"`

	// Vocabularies prefix to IRI map for CURIE values used in this block. The dpv, eu-aiact and ai prefixes
	// are well-known defaults and need not be declared.
	Vocabularies map[string]string `json:"vocabularies,omitempty" yaml:"vocabularies,omitempty"`
}

type ImageConfig struct {
	// AllowedFormats list of allowed image formats
	AllowedFormats []string `json:"allowed_formats,omitempty" yaml:"allowed_formats,omitempty"`

	// DefaultDetail default detail level for image processing. 'low' uses fewer tokens, 'high' provides more
	// detail, 'auto' lets the model decide.
	DefaultDetail *string `json:"default_detail,omitempty" yaml:"default_detail,omitempty"`

	// MaxImagesPerMsg maximum number of images allowed per message
	MaxImagesPerMsg *int `json:"max_images_per_msg,omitempty" yaml:"max_images_per_msg,omitempty"`

	// MaxSizeMB maximum file size in megabytes
	MaxSizeMB *int `json:"max_size_mb,omitempty" yaml:"max_size_mb,omitempty"`

	// RequireCaption whether image captions are required
	RequireCaption *bool `json:"require_caption,omitempty" yaml:"require_caption,omitempty"`
}

type InlineSkill struct {
	// Description brief description of what this skill provides.
	Description string `json:"description" yaml:"description"`

	// Instructions the skill's instructions or knowledge content. Loaded into the agent's context when the
	// skill is activated.
	Instructions string `json:"instructions" yaml:"instructions"`

	// Name human-readable name for this skill.
	Name string `json:"name" yaml:"name"`
}

type MediaConfig struct {
	// Audio audio-specific configuration and constraints
	Audio *AudioConfig `json:"audio,omitempty" yaml:"audio,omitempty"`

	// Document document-specific configuration and constraints (PDFs, CAD files, spreadsheets, etc.)
	Document *DocumentConfig `json:"document,omitempty" yaml:"document,omitempty"`

	// Enabled whether multimodal content is enabled for this prompt
	Enabled bool `json:"enabled" yaml:"enabled"`

	// Examples example multimodal messages showing how to use media with this prompt
	Examples []*MultimodalExample `json:"examples,omitempty" yaml:"examples,omitempty"`

	// Image image-specific configuration and constraints
	Image *ImageConfig `json:"image,omitempty" yaml:"image,omitempty"`

	// SupportedTypes list of supported media types for this prompt. Common types include: image, audio, video,
	// document, model3d, archive. Custom types are allowed - each type should have a
	// corresponding configuration object (e.g., 'foo' type requires a 'foo' field with
	// GenericMediaTypeConfig or a specific schema).
	SupportedTypes []string `json:"supported_types,omitempty" yaml:"supported_types,omitempty"`

	// Video video-specific configuration and constraints
	Video *VideoConfig `json:"video,omitempty" yaml:"video,omitempty"`
}

type MediaReference struct {
	// Base64 base64-encoded media data. Use for small files or when embedding is preferred.
	Base64 string `json:"base64,omitempty" yaml:"base64,omitempty"`

	// Caption caption or description for the media
	Caption string `json:"caption,omitempty" yaml:"caption,omitempty"`

	// Detail detail level for image processing (images only). Overrides default_detail from
	// ImageConfig.
	Detail string `json:"detail,omitempty" yaml:"detail,omitempty"`

	// FilePath path to media file (relative to pack or absolute). Validated at compile time.
	FilePath string `json:"file_path,omitempty" yaml:"file_path,omitempty"`

	// MimeType MIME type of the media file
	MimeType string `json:"mime_type" yaml:"mime_type"`

	// URL URL to media file. Must be publicly accessible or require authentication.
	URL string `json:"url,omitempty" yaml:"url,omitempty"`
}

type MetricDef struct {
	// Name metric name. Should follow Prometheus naming conventions (snake_case, namespace prefix
	// recommended).
	Name string `json:"name" yaml:"name"`

	// Range optional value bounds. Useful for gauge metrics with known ranges.
	Range *MetricDefRange `json:"range,omitempty" yaml:"range,omitempty"`

	// Type prometheus metric type that describes the value semantics.
	Type string `json:"type" yaml:"type"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type MetricDefRange struct {
	// Max maximum expected value
	Max *float64 `json:"max,omitempty" yaml:"max,omitempty"`

	// Min minimum expected value
	Min *float64 `json:"min,omitempty" yaml:"min,omitempty"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type MiddlewareConfig struct {
	// Config type-specific configuration for the middleware
	Config map[string]any `json:"config,omitempty" yaml:"config,omitempty"`

	// Type middleware type identifier
	Type string `json:"type" yaml:"type"`
}

type ModelOverride struct {
	// Parameters model-specific parameter overrides
	Parameters *Parameters `json:"parameters,omitempty" yaml:"parameters,omitempty"`

	// SystemTemplate complete replacement system template for this model (overrides the base template entirely)
	SystemTemplate string `json:"system_template,omitempty" yaml:"system_template,omitempty"`

	// SystemTemplatePrefix text prepended to the system template for this model
	SystemTemplatePrefix string `json:"system_template_prefix,omitempty" yaml:"system_template_prefix,omitempty"`

	// SystemTemplateSuffix text appended to the system template for this model
	SystemTemplateSuffix string `json:"system_template_suffix,omitempty" yaml:"system_template_suffix,omitempty"`
}

type MultimodalExample struct {
	// Description description of what this example demonstrates
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Name name identifying this example
	Name string `json:"name" yaml:"name"`

	// Parts message content parts (text and/or media)
	Parts []*ContentPart `json:"parts" yaml:"parts"`

	// Role message role (typically 'user' or 'assistant')
	Role string `json:"role" yaml:"role"`
}

type NotPredicate struct {
	Not *Predicate `json:"not" yaml:"not"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type Pack struct {
	// Schema JSON Schema reference for validation and IDE support
	Schema *string `json:"$schema,omitempty" yaml:"$schema,omitempty"`

	// Agents agent configuration mapping prompts to A2A-compatible agent definitions. Enables
	// multi-agent orchestration via the Agent-to-Agent protocol.
	Agents *AgentsConfig `json:"agents,omitempty" yaml:"agents,omitempty"`

	// Compilation information about when and how this pack was compiled. Generated automatically by the
	// packc compiler.
	Compilation *PackCompilation `json:"compilation,omitempty" yaml:"compilation,omitempty"`

	// Compositions map of composition name to composition definition (RFC 0010). Each composition declares a
	// named step graph that a runtime may invoke as a structured-input/structured-output unit.
	// Compositions are reached only through workflow states whose orchestration is
	// 'composition'. Optional; packs without it are unaffected.
	Compositions map[string]*Composition `json:"compositions,omitempty" yaml:"compositions,omitempty"`

	// Description detailed description of the pack's purpose, use cases, and contents. Supports markdown
	// formatting.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Evals pack-level eval definitions that apply across all prompts. Useful for cross-cutting
	// quality concerns like brand consistency or safety checks. Prompt-level evals with the
	// same id override pack-level evals.
	Evals []*Eval `json:"evals,omitempty" yaml:"evals,omitempty"`

	// Fragments shared template fragments that can be referenced by any prompt in the pack. Fragments are
	// reusable text blocks resolved at compile time. Keys are fragment names, values are
	// fragment content.
	Fragments map[string]string `json:"fragments,omitempty" yaml:"fragments,omitempty"`

	// ID unique identifier for the pack. Used for referencing and caching. Should be lowercase
	// with hyphens.
	ID string `json:"id" yaml:"id"`

	// Metadata optional pack-level metadata for categorization, discovery, and operational planning.
	Metadata *PackMetadata `json:"metadata,omitempty" yaml:"metadata,omitempty"`

	// Name human-readable name for the pack. Displayed in UIs and documentation.
	Name string `json:"name" yaml:"name"`

	// Prompts map of task_type to prompt configuration. Each key is a task type (e.g., 'support',
	// 'sales') and each value is a complete prompt definition. A pack must contain at least one
	// prompt.
	Prompts map[string]*Prompt `json:"prompts" yaml:"prompts"`

	// Requires external resources the pack needs to run (RFC 0012). Optional; when present, validated
	// strictly. Reserved for future requirement categories (e.g. tools, skills).
	Requires *PackRequires `json:"requires,omitempty" yaml:"requires,omitempty"`

	// Skills skill sources for progressive-disclosure knowledge loading. Each entry is either a string
	// (path or package reference), a SkillPathSource object, or an InlineSkill object.
	Skills []*SkillSource `json:"skills,omitempty" yaml:"skills,omitempty"`

	// TemplateEngine template engine configuration shared across all prompts in the pack. Defines how
	// variables are substituted and fragments are resolved.
	TemplateEngine *PackTemplateEngine `json:"template_engine" yaml:"template_engine"`

	// Tools tool definitions that can be referenced by prompts. Tools enable the LLM to call external
	// functions. Keys are tool names, values are tool specifications following the JSON Schema
	// for function calling.
	Tools map[string]*Tool `json:"tools,omitempty" yaml:"tools,omitempty"`

	// Version pack version following Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH). Can optionally
	// include 'v' prefix. Use MAJOR for breaking changes, MINOR for new features, PATCH for bug
	// fixes. This version tracks the pack as a whole, while individual prompts can have
	// independent versions.
	Version string `json:"version" yaml:"version"`

	// Workflow workflow configuration defining a state machine over the pack's prompts. Each state
	// references a prompt key and declares event-driven transitions.
	Workflow *WorkflowConfig `json:"workflow,omitempty" yaml:"workflow,omitempty"`
}

type PackCompilation struct {
	// CompiledWith version of the packc compiler used to create this pack
	CompiledWith string `json:"compiled_with" yaml:"compiled_with"`

	// CreatedAt ISO 8601 timestamp when the pack was compiled
	CreatedAt string `json:"created_at" yaml:"created_at"`

	// Schema pack format schema version used
	Schema string `json:"schema" yaml:"schema"`

	// Source optional source configuration file path
	Source string `json:"source,omitempty" yaml:"source,omitempty"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type PackMetadata struct {
	// CostEstimate cost estimation for using this pack
	CostEstimate *PackMetadataCostEstimate `json:"cost_estimate,omitempty" yaml:"cost_estimate,omitempty"`

	// Domain domain or category for this pack
	Domain string `json:"domain,omitempty" yaml:"domain,omitempty"`

	// Governance governance facts about the agent this pack defines (RFC 0013).
	Governance *Governance `json:"governance,omitempty" yaml:"governance,omitempty"`

	// Language primary language code (ISO 639-1)
	Language string `json:"language,omitempty" yaml:"language,omitempty"`

	// Tags tags for categorization and discovery
	Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type PackMetadataCostEstimate struct {
	// AvgCostUSD average cost per execution in USD
	AvgCostUSD *float64 `json:"avg_cost_usd,omitempty" yaml:"avg_cost_usd,omitempty"`

	// MaxCostUSD maximum cost per execution in USD
	MaxCostUSD *float64 `json:"max_cost_usd,omitempty" yaml:"max_cost_usd,omitempty"`

	// MinCostUSD minimum cost per execution in USD
	MinCostUSD *float64 `json:"min_cost_usd,omitempty" yaml:"min_cost_usd,omitempty"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type PackRequires struct {
	// Providers logical model-provider requirements. Each entry is a string shorthand (an 'llm'
	// requirement with that key) or a ProviderRequirement object.
	Providers []*ProviderRequirement `json:"providers,omitempty" yaml:"providers,omitempty"`
}

type PackTemplateEngine struct {
	// Features optional list of supported template features beyond basic substitution.
	Features []string `json:"features,omitempty" yaml:"features,omitempty"`

	// Syntax variable substitution syntax pattern. Defines how variables appear in templates.
	Syntax string `json:"syntax" yaml:"syntax"`

	// Version template engine version. Use 'v1' for the current stable version.
	Version string `json:"version" yaml:"version"`
}

type ParallelStep struct {
	Branches []*Step `json:"branches" yaml:"branches"`

	Kind any `json:"kind" yaml:"kind"`

	Reduce *Reducer `json:"reduce" yaml:"reduce"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type Parameters struct {
	// FrequencyPenalty penalty for token frequency (-2 to 2). Positive values reduce repetition.
	FrequencyPenalty *float64 `json:"frequency_penalty,omitempty" yaml:"frequency_penalty,omitempty"`

	// MaxTokens maximum number of tokens to generate in the response
	MaxTokens *int `json:"max_tokens,omitempty" yaml:"max_tokens,omitempty"`

	// PresencePenalty penalty for token presence (-2 to 2). Positive values encourage new topics.
	PresencePenalty *float64 `json:"presence_penalty,omitempty" yaml:"presence_penalty,omitempty"`

	// Temperature sampling temperature (0-2). Higher values make output more random, lower values more
	// deterministic.
	Temperature *float64 `json:"temperature,omitempty" yaml:"temperature,omitempty"`

	// TopK top-k sampling parameter. Limits to top K tokens. Null means no limit.
	TopK *int `json:"top_k,omitempty" yaml:"top_k,omitempty"`

	// TopP nucleus sampling parameter (0-1). Alternative to temperature for controlling randomness.
	TopP *float64 `json:"top_p,omitempty" yaml:"top_p,omitempty"`
}

type PipelineConfig struct {
	// Middleware middleware components with their configurations. Applied in order during pipeline
	// execution.
	Middleware []*MiddlewareConfig `json:"middleware,omitempty" yaml:"middleware,omitempty"`

	// Stages ordered list of pipeline stages. Common stages: 'template', 'provider', 'validator'
	Stages []string `json:"stages" yaml:"stages"`
}

type Predicate struct {
	AllOf []*Predicate `json:"all_of,omitempty" yaml:"all_of,omitempty"`

	AnyOf []*Predicate `json:"any_of,omitempty" yaml:"any_of,omitempty"`

	Exists *bool `json:"exists,omitempty" yaml:"exists,omitempty"`

	Not *Predicate `json:"not,omitempty" yaml:"not,omitempty"`

	Op string `json:"op,omitempty" yaml:"op,omitempty"`

	// Path reference to a value via dot-notation against the composition's input and step outputs.
	// Example: '${classify.output.intent}'.
	Path string `json:"path,omitempty" yaml:"path,omitempty"`

	// Value literal comparison value (string, number, boolean, or array for in/not_in).
	Value any `json:"value,omitempty" yaml:"value,omitempty"`
}

type Prompt struct {
	// Description detailed description of this prompt's purpose and behavior
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Evals eval definitions scoped to this prompt. These evals assess the quality of responses
	// generated by this specific prompt. Prompt-level evals with the same id override
	// pack-level evals.
	Evals []*Eval `json:"evals,omitempty" yaml:"evals,omitempty"`

	// ID unique identifier for this prompt, typically matching the task_type key
	ID string `json:"id" yaml:"id"`

	// Media multimodal content configuration for this prompt. Defines supported media types and
	// validation rules.
	Media *MediaConfig `json:"media,omitempty" yaml:"media,omitempty"`

	// ModelOverrides model-specific template modifications. Keys are model names (e.g., 'claude-3-opus',
	// 'gpt-4'), values are override configurations.
	ModelOverrides map[string]*ModelOverride `json:"model_overrides,omitempty" yaml:"model_overrides,omitempty"`

	// Name human-readable name for this prompt
	Name string `json:"name" yaml:"name"`

	// Parameters LLM generation parameters like temperature and max_tokens
	Parameters *Parameters `json:"parameters,omitempty" yaml:"parameters,omitempty"`

	// Pipeline pipeline configuration defining processing stages and middleware
	Pipeline *PipelineConfig `json:"pipeline,omitempty" yaml:"pipeline,omitempty"`

	// SystemTemplate the system prompt template. Use template syntax (e.g., {{variable}}) for variable
	// substitution. This is the core instruction that guides the LLM's behavior.
	SystemTemplate string `json:"system_template" yaml:"system_template"`

	// TestedModels model testing results documenting which models have been tested with this prompt and
	// their performance
	TestedModels []*TestedModel `json:"tested_models,omitempty" yaml:"tested_models,omitempty"`

	// ToolPolicy policy governing how tools can be used by this prompt
	ToolPolicy *ToolPolicy `json:"tool_policy,omitempty" yaml:"tool_policy,omitempty"`

	// Tools list of tool names that this prompt is allowed to use. Tools must be defined in the
	// pack-level 'tools' object.
	Tools []string `json:"tools,omitempty" yaml:"tools,omitempty"`

	// Validators validation rules (guardrails) applied to LLM responses
	Validators []*Validator `json:"validators,omitempty" yaml:"validators,omitempty"`

	// Variables variable definitions for this prompt. Variables are placeholders in the template that are
	// replaced with actual values at runtime.
	Variables []*Variable `json:"variables,omitempty" yaml:"variables,omitempty"`

	// Version prompt version following Semantic Versioning 2.0.0. Independent from pack version,
	// allowing individual prompts to evolve separately.
	Version string `json:"version" yaml:"version"`
}

type PromptStep struct {
	// Input optional input binding. Variables resolved against the composition's input and prior
	// steps' outputs.
	Input *StepInput `json:"input,omitempty" yaml:"input,omitempty"`

	Kind any `json:"kind" yaml:"kind"`

	// OutputSchema reference to a JSON Schema for the expected output shape. Runtimes parse the LLM response
	// against this schema.
	OutputSchema string `json:"output_schema,omitempty" yaml:"output_schema,omitempty"`

	// PromptTask reference to a prompt key defined in the pack's prompts object.
	PromptTask string `json:"prompt_task" yaml:"prompt_task"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type ProviderCapabilities struct {
	// EmbeddingDimensions required embedding vector dimensionality (for role 'embedding').
	EmbeddingDimensions *int `json:"embedding_dimensions,omitempty" yaml:"embedding_dimensions,omitempty"`

	// MinContextTokens minimum context window, in tokens, the provider must support.
	MinContextTokens *int `json:"min_context_tokens,omitempty" yaml:"min_context_tokens,omitempty"`

	// Modalities media types the provider must handle. Reuses the media-type vocabulary
	// (MediaConfig.supported_types, RFC 0004). Common: 'text', 'image', 'audio', 'video',
	// 'document'.
	Modalities []string `json:"modalities,omitempty" yaml:"modalities,omitempty"`

	// StructuredOutput whether the provider must support structured/JSON output.
	StructuredOutput *bool `json:"structured_output,omitempty" yaml:"structured_output,omitempty"`

	// ToolUse whether the provider must support tool/function calling.
	ToolUse *bool `json:"tool_use,omitempty" yaml:"tool_use,omitempty"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type ProviderRequirement struct {
	Capabilities *ProviderCapabilities `json:"capabilities,omitempty" yaml:"capabilities,omitempty"`

	// Description human-readable explanation of the provider's purpose and the capabilities it should have.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Key logical name the runtime resolves this provider by (e.g. 'default', 'embeddings',
	// 'judge'). 'default' is reserved for the primary LLM.
	Key string `json:"key,omitempty" yaml:"key,omitempty"`

	// Required whether the pack cannot run without this provider. Optional requirements degrade features
	// rather than blocking startup.
	Required *bool `json:"required,omitempty" yaml:"required,omitempty"`

	// Role the kind of model required. Open set; runtimes MAY extend (validators must not reject
	// unknown roles). Suggested values (PromptKit roles): 'llm', 'embedding', 'tts', 'stt',
	// 'image', 'inference'.
	Role string `json:"role,omitempty" yaml:"role,omitempty"`

	// Shorthand holds the scalar form of this union when the pack used it
	// instead of the object form. The spec defines what it expands to; this
	// type preserves it verbatim rather than inventing the expansion.
	Shorthand string `json:"-" yaml:"-"`
}

type Reducer struct {
	// Into field name under which the merged result is placed on the parallel step's output.
	// Subsequent steps reference it as ${<parallelStepId>.output.<into>}.
	Into string `json:"into" yaml:"into"`

	// Strategy v1 conventional values: 'append' (extend lists), 'replace' (last write wins), 'barrier'
	// (collect all outputs into a named map). Free-form string; additional reducers reserved
	// for future RFCs.
	Strategy string `json:"strategy" yaml:"strategy"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type SkillPathSource struct {
	// Path path to a skill directory, file, or package reference.
	Path string `json:"path" yaml:"path"`

	// Preload if true, load this skill source eagerly at pack initialization rather than on demand.
	Preload *bool `json:"preload,omitempty" yaml:"preload,omitempty"`
}

type SkillSource struct {
	// Description brief description of what this skill provides.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Instructions the skill's instructions or knowledge content. Loaded into the agent's context when the
	// skill is activated.
	Instructions string `json:"instructions,omitempty" yaml:"instructions,omitempty"`

	// Name human-readable name for this skill.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// Path path to a skill directory, file, or package reference.
	Path string `json:"path,omitempty" yaml:"path,omitempty"`

	// Preload if true, load this skill source eagerly at pack initialization rather than on demand.
	Preload *bool `json:"preload,omitempty" yaml:"preload,omitempty"`

	// Shorthand holds the scalar form of this union when the pack used it
	// instead of the object form. The spec defines what it expands to; this
	// type preserves it verbatim rather than inventing the expansion.
	Shorthand string `json:"-" yaml:"-"`
}

type Step struct {
	// Args argument bindings. Variables resolved against the composition's input and prior steps'
	// outputs.
	Args map[string]any `json:"args,omitempty" yaml:"args,omitempty"`

	Branches []*Step `json:"branches,omitempty" yaml:"branches,omitempty"`

	// DependsOn optional explicit predecessor step IDs. If omitted, the step sequentially follows the
	// prior step in steps[]. Required when steps run after a branch or parallel and need to
	// declare a join point.
	DependsOn []string `json:"depends_on,omitempty" yaml:"depends_on,omitempty"`

	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Else step ID to execute when the predicate evaluates false.
	Else string `json:"else,omitempty" yaml:"else,omitempty"`

	// ID stable identifier for this step. Must be unique within the composition. Used for output
	// references, eval attachment, and trace records.
	ID string `json:"id,omitempty" yaml:"id,omitempty"`

	// Input optional input binding. Variables resolved against the composition's input and prior
	// steps' outputs.
	Input *StepInput `json:"input,omitempty" yaml:"input,omitempty"`

	// Kind step kind. v1 conventional values: 'prompt', 'agent', 'tool', 'branch', 'parallel'.
	// Free-form string with documented conventional values; runtimes may support additional
	// vendor-namespaced kinds (e.g. 'omnia.judge').
	Kind string `json:"kind,omitempty" yaml:"kind,omitempty"`

	// Modifiers optional declarative modifiers (retry, eval attachment). Modifier semantics are
	// runtime-defined.
	Modifiers *StepModifiers `json:"modifiers,omitempty" yaml:"modifiers,omitempty"`

	// OutputSchema reference to a JSON Schema for the expected output shape. Runtimes parse the LLM response
	// against this schema.
	OutputSchema string `json:"output_schema,omitempty" yaml:"output_schema,omitempty"`

	Predicate *Predicate `json:"predicate,omitempty" yaml:"predicate,omitempty"`

	// PromptTask reference to a prompt key defined in the pack's prompts object.
	PromptTask string `json:"prompt_task,omitempty" yaml:"prompt_task,omitempty"`

	Reduce *Reducer `json:"reduce,omitempty" yaml:"reduce,omitempty"`

	// Termination REQUIRED. The condition under which the bounded loop exits. Without an explicit
	// termination predicate, an agent step is invalid.
	Termination *TerminationPredicate `json:"termination,omitempty" yaml:"termination,omitempty"`

	// Then step ID to execute when the predicate evaluates true.
	Then string `json:"then,omitempty" yaml:"then,omitempty"`

	// Tool reference to a tool key defined in the pack's tools object.
	Tool string `json:"tool,omitempty" yaml:"tool,omitempty"`

	// Tools subset of the pack's tools available to this agent step. Acts as a per-step scoped tool
	// registry.
	Tools []string `json:"tools,omitempty" yaml:"tools,omitempty"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type StepInput struct {
	// Object is set when the value is a JSON object.
	Object map[string]any `json:"-" yaml:"-"`
	// String is set when the value is a JSON string.
	String string `json:"-" yaml:"-"`
}

type StepModifiers struct {
	// Eval references to eval keys defined in the pack's evals object (RFC 0006). Runtimes may
	// execute these inline or post-Send.
	Eval []string `json:"eval,omitempty" yaml:"eval,omitempty"`

	Retry *StepModifiersRetry `json:"retry,omitempty" yaml:"retry,omitempty"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type StepModifiersRetry struct {
	MaxAttempts *int `json:"max_attempts,omitempty" yaml:"max_attempts,omitempty"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type TerminationPredicate struct {
	MaxSteps *int `json:"max_steps,omitempty" yaml:"max_steps,omitempty"`

	// ToolCalled tool name; agent terminates when the LLM successfully invokes this tool.
	ToolCalled string `json:"tool_called,omitempty" yaml:"tool_called,omitempty"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type TestedModel struct {
	// AvgCost average cost per execution in USD
	AvgCost *float64 `json:"avg_cost,omitempty" yaml:"avg_cost,omitempty"`

	// AvgLatencyMs average response latency in milliseconds
	AvgLatencyMs *float64 `json:"avg_latency_ms,omitempty" yaml:"avg_latency_ms,omitempty"`

	// AvgTokens average number of tokens used per response
	AvgTokens *float64 `json:"avg_tokens,omitempty" yaml:"avg_tokens,omitempty"`

	// Date date when the model was tested (YYYY-MM-DD)
	Date string `json:"date" yaml:"date"`

	// Model specific model identifier
	Model string `json:"model" yaml:"model"`

	// Notes additional notes about model performance or observations
	Notes string `json:"notes,omitempty" yaml:"notes,omitempty"`

	// Provider LLM provider name
	Provider string `json:"provider" yaml:"provider"`

	// SuccessRate success rate (0-1) from test runs
	SuccessRate *float64 `json:"success_rate,omitempty" yaml:"success_rate,omitempty"`
}

type Tool struct {
	// ActionScope what this tool can affect (RFC 0013). Describes consequence; does not gate anything.
	ActionScope *ActionScope `json:"action_scope,omitempty" yaml:"action_scope,omitempty"`

	// Description clear description of what the tool does. The LLM uses this to decide when to call the
	// tool.
	Description string `json:"description" yaml:"description"`

	// Extensions opaque annotations about this tool. Never interpreted by this specification. Keys SHOULD
	// be namespaced.
	Extensions map[string]any `json:"extensions,omitempty" yaml:"extensions,omitempty"`

	// Name tool name used for referencing and calling
	Name string `json:"name" yaml:"name"`

	// Parameters JSON Schema defining the tool's parameters. Follows JSON Schema specification.
	Parameters *ToolParameters `json:"parameters,omitempty" yaml:"parameters,omitempty"`
}

type ToolParameters struct {
	// Properties parameter definitions
	Properties map[string]map[string]any `json:"properties" yaml:"properties"`

	// Required list of required parameter names
	Required []string `json:"required,omitempty" yaml:"required,omitempty"`

	// Type must be 'object' for tool parameters
	Type string `json:"type" yaml:"type"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type ToolPolicy struct {
	// Blocklist list of tool names that are not allowed for this prompt (overrides tools list)
	Blocklist []string `json:"blocklist,omitempty" yaml:"blocklist,omitempty"`

	// MaxRounds maximum number of LLM → tool → LLM cycles allowed per turn
	MaxRounds *int `json:"max_rounds,omitempty" yaml:"max_rounds,omitempty"`

	// MaxToolCallsPerTurn maximum number of tool calls allowed in a single turn
	MaxToolCallsPerTurn *int `json:"max_tool_calls_per_turn,omitempty" yaml:"max_tool_calls_per_turn,omitempty"`

	// ToolChoice 'auto' lets the LLM decide when to use tools, 'required' forces tool use, 'none' disables
	// tools
	ToolChoice *string `json:"tool_choice,omitempty" yaml:"tool_choice,omitempty"`
}

type ToolStep struct {
	// Args argument bindings. Variables resolved against the composition's input and prior steps'
	// outputs.
	Args map[string]any `json:"args,omitempty" yaml:"args,omitempty"`

	Kind any `json:"kind" yaml:"kind"`

	// Tool reference to a tool key defined in the pack's tools object.
	Tool string `json:"tool" yaml:"tool"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type Validator struct {
	// Enabled whether this validator is active. Allows temporarily disabling validators without
	// removing them.
	Enabled *bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`

	// FailOnViolation DEPRECATED as of v1.7.0, removed in v2.0.0 (RFC 0015). Ignored — validators always
	// enforce. A triggered validator rewrites or blocks the assistant message regardless of
	// this value. To disable a validator, use 'enabled: false'. For observation without
	// enforcement, declare an eval and assert on its score instead.
	FailOnViolation *bool `json:"fail_on_violation,omitempty" yaml:"fail_on_violation,omitempty"`

	// Message user-facing message returned when the validator blocks content.
	Message string `json:"message,omitempty" yaml:"message,omitempty"`

	// Params validator-specific parameters
	Params map[string]any `json:"params,omitempty" yaml:"params,omitempty"`

	// Type the validator type that determines how validation is performed. Not an enum — runtimes
	// define and register their own validator types.
	Type string `json:"type" yaml:"type"`
}

type Variable struct {
	// Binding declares how this variable is automatically populated from runtime context.
	Binding *VariableBinding `json:"binding,omitempty" yaml:"binding,omitempty"`

	// Default default value used when variable is not provided. Cannot be set if required is true.
	Default any `json:"default,omitempty" yaml:"default,omitempty"`

	// Description human-readable description of the variable's purpose
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Example example value showing expected format and content
	Example any `json:"example,omitempty" yaml:"example,omitempty"`

	// Name variable name used in templates (e.g., {{name}})
	Name string `json:"name" yaml:"name"`

	// Required whether this variable must be provided. Required variables without values will cause an
	// error.
	Required bool `json:"required" yaml:"required"`

	// Type data type of the variable
	Type string `json:"type" yaml:"type"`

	// Validation validation rules applied to the variable value at runtime
	Validation *VariableValidation `json:"validation,omitempty" yaml:"validation,omitempty"`
}

type VariableBinding struct {
	// AutoPopulate whether this variable is automatically populated at runtime without caller input.
	AutoPopulate *bool `json:"auto_populate,omitempty" yaml:"auto_populate,omitempty"`

	// Field the field name within the binding source to extract.
	Field string `json:"field,omitempty" yaml:"field,omitempty"`

	// Filter optional filter expression applied to the bound value.
	Filter string `json:"filter,omitempty" yaml:"filter,omitempty"`

	// Kind the binding source kind.
	Kind string `json:"kind,omitempty" yaml:"kind,omitempty"`
}

type VariableValidation struct {
	// Enum list of allowed values
	Enum []any `json:"enum,omitempty" yaml:"enum,omitempty"`

	// MaxLength maximum string length (for string types)
	MaxLength *int `json:"max_length,omitempty" yaml:"max_length,omitempty"`

	// Maximum maximum numeric value (for number types)
	Maximum *float64 `json:"maximum,omitempty" yaml:"maximum,omitempty"`

	// MinLength minimum string length (for string types)
	MinLength *int `json:"min_length,omitempty" yaml:"min_length,omitempty"`

	// Minimum minimum numeric value (for number types)
	Minimum *float64 `json:"minimum,omitempty" yaml:"minimum,omitempty"`

	// Pattern regular expression pattern (for string types)
	Pattern string `json:"pattern,omitempty" yaml:"pattern,omitempty"`
}

type VideoConfig struct {
	// AllowedFormats list of allowed video formats
	AllowedFormats []string `json:"allowed_formats,omitempty" yaml:"allowed_formats,omitempty"`

	// MaxDurationSec maximum video duration in seconds
	MaxDurationSec *int `json:"max_duration_sec,omitempty" yaml:"max_duration_sec,omitempty"`

	// MaxSizeMB maximum file size in megabytes
	MaxSizeMB *int `json:"max_size_mb,omitempty" yaml:"max_size_mb,omitempty"`

	// RequireMetadata whether video metadata (title, description) is required
	RequireMetadata *bool `json:"require_metadata,omitempty" yaml:"require_metadata,omitempty"`
}

type WorkflowBudget struct {
	// MaxToolCalls maximum total tool calls across all states in the workflow.
	MaxToolCalls *int `json:"max_tool_calls,omitempty" yaml:"max_tool_calls,omitempty"`

	// MaxTotalVisits maximum total state visits across all states in the workflow. This is a global safety net
	// independent of per-state max_visits.
	MaxTotalVisits *int `json:"max_total_visits,omitempty" yaml:"max_total_visits,omitempty"`

	// MaxWallTimeSec maximum wall-clock time in seconds for the entire workflow execution.
	MaxWallTimeSec *int `json:"max_wall_time_sec,omitempty" yaml:"max_wall_time_sec,omitempty"`
}

type WorkflowConfig struct {
	// Engine optional runtime engine configuration for workflow execution. Hosts standardized fields
	// like 'budget' for resource limits, alongside runtime-specific hints (timeout,
	// concurrency, etc.).
	Engine *WorkflowConfigEngine `json:"engine,omitempty" yaml:"engine,omitempty"`

	// Entry name of the initial state. Must match a key in the states object.
	Entry string `json:"entry" yaml:"entry"`

	// States map of state name to state definition. Each state references a prompt and declares
	// transitions.
	States map[string]*WorkflowState `json:"states" yaml:"states"`

	// Version workflow schema version. Use 1 for the current stable format.
	Version int `json:"version" yaml:"version"`
}

type WorkflowConfigEngine struct {
	// Budget resource budget for workflow execution. Provides safety limits to prevent unbounded loops.
	Budget *WorkflowBudget `json:"budget,omitempty" yaml:"budget,omitempty"`

	// Extra carries properties the schema allows but does not name.
	// This def is additionalProperties:true — an envelope the spec expects
	// runtimes to extend — so unknown keys are preserved here rather than
	// dropped. Marshaled back as top-level properties, not nested.
	Extra map[string]any `json:"-" yaml:"-"`
}

type WorkflowState struct {
	// Artifacts named artifact slots for lightweight, structured metadata that flows across state visits.
	// Artifacts should be pointers (commit SHAs, URIs), compact representations (schemas,
	// summaries, diffs), or small structured results — not bulk data. Artifact values are
	// available to the prompt as template variables under the 'artifacts' namespace (e.g.,
	// {{artifacts.commit_sha}}).
	Artifacts map[string]*ArtifactDef `json:"artifacts,omitempty" yaml:"artifacts,omitempty"`

	// Composition reference to a composition key defined in the pack's compositions object (RFC 0010).
	// Required when orchestration is 'composition'; absent otherwise.
	Composition string `json:"composition,omitempty" yaml:"composition,omitempty"`

	// Control who holds the next turn after entering this state (RFC 0014). 'user' yields the
	// conversation to the user (default, and the behavior of every state before v1.7.0).
	// 'agent' runs another agent round in this state without yielding, for transient routing or
	// processing states. Orthogonal to 'orchestration', which declares who initiates a
	// transition rather than who holds the turn after one; inert on states reached via
	// 'external' orchestration. Bounded by terminal states, max_visits and the workflow budget
	// — it introduces no new limits.
	Control *string `json:"control,omitempty" yaml:"control,omitempty"`

	// Description human-readable description of this state's purpose.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// MaxVisits maximum number of times this state can be entered during a single workflow execution.
	// When the limit is reached, the workflow transitions to the state named in on_max_visits.
	// If on_max_visits is not set, the workflow terminates.
	MaxVisits *int `json:"max_visits,omitempty" yaml:"max_visits,omitempty"`

	// OnEvent map of event name to target state name. When the named event fires, the workflow
	// transitions to the target state.
	OnEvent map[string]string `json:"on_event,omitempty" yaml:"on_event,omitempty"`

	// OnMaxVisits target state to transition to when max_visits is reached. Must reference a key in the
	// states object. If omitted and max_visits is reached, the workflow terminates with a
	// budget-exhausted status.
	OnMaxVisits string `json:"on_max_visits,omitempty" yaml:"on_max_visits,omitempty"`

	// Orchestration how the state is orchestrated. 'internal' = agent controls transitions (default).
	// 'external' = system controls transitions. 'hybrid' = both. 'composition' = the referenced
	// composition fully handles the state's orchestration (work + transitions): the composition
	// runs end-to-end, and on completion its output may map to on_event transitions or
	// terminate the state. The composition mode is exclusive; it is not mixed with
	// internal/external/hybrid on the same state.
	Orchestration *string `json:"orchestration,omitempty" yaml:"orchestration,omitempty"`

	// Persistence whether conversation context is kept (persistent) or reset (transient) on entry.
	Persistence string `json:"persistence,omitempty" yaml:"persistence,omitempty"`

	// PromptTask reference to a prompt key defined in the pack's prompts object. Required for
	// orchestration modes 'internal', 'external', 'hybrid' (or when orchestration is omitted,
	// default 'internal'); not used in 'composition' mode.
	PromptTask string `json:"prompt_task,omitempty" yaml:"prompt_task,omitempty"`

	// Skills skill filter for this workflow state. A path to a skill directory/file that scopes which
	// skills are available in this state, or the literal 'none' to disable skills.
	Skills string `json:"skills,omitempty" yaml:"skills,omitempty"`

	// Terminal if true, this state is a terminal state. The workflow completes after this state's prompt
	// executes. Terminal states should not declare on_event transitions.
	Terminal *bool `json:"terminal,omitempty" yaml:"terminal,omitempty"`
}