types

type BlockConfig struct {
	Type     string   `yaml:"type"`
	Name     string   `yaml:"name,omitempty"`
	Settings Settings `yaml:"settings,omitempty"`

	// Ref names a reusable processor defined under Config.Processors. When set,
	// the block takes its type and base settings from that definition; any
	// Settings here override the referenced ones key-by-key. A block sets either
	// Ref or Type, not both (an inline Type equal to the referenced type is the
	// one allowed overlap).
	Ref string `yaml:"ref,omitempty"`

	// Process is the happy-path block chain of a "handle-errors" block. It is a
	// bare block list, like a flow's Process, so a handle-errors block reads as a
	// mini-flow embedded inline.
	Process []BlockConfig `yaml:"process,omitempty"`
	// Error is the error-path block chain of a "handle-errors" block: it runs when
	// the Process chain errors, with the error exposed as vars.error.
	Error []BlockConfig `yaml:"error,omitempty"`
	// Branches are the parallel flows of a "fork" block.
	Branches []FlowConfig `yaml:"branches,omitempty"`

	// Condition is the boolean expression of an "if" block.
	Condition string `yaml:"condition,omitempty"`
	// Then is the flow an "if" block runs when its condition is true.
	Then *FlowConfig `yaml:"then,omitempty"`
	// Else is the flow an "if" block runs when its condition is false (optional).
	Else *FlowConfig `yaml:"else,omitempty"`

	// Cases are the ordered, condition-guarded flows of a "switch" block.
	Cases []CaseConfig `yaml:"cases,omitempty"`
	// Default is the flow a "switch" block runs when no case matches (optional).
	Default *FlowConfig `yaml:"default,omitempty"`

	// Items is the expression a "foreach" block evaluates to the array it
	// iterates.
	Items string `yaml:"items,omitempty"`
	// As is the variable name a "foreach" block binds each element to; it
	// defaults to "item" when unset.
	As string `yaml:"as,omitempty"`
	// Mode is how a "foreach" block treats its body's results: "iterate" (the
	// default) threads the message through the body once per element, while "map"
	// collects each element's resulting body into an array that replaces the
	// message body.
	Mode string `yaml:"mode,omitempty"`
	// Body is the flow a "foreach", "cache-scope", or "enrich" block runs; foreach
	// runs it once per element, cache-scope runs it on a cache miss, enrich runs it
	// once on an isolated copy of the message.
	Body *FlowConfig `yaml:"body,omitempty"`

	// SetBody is an "enrich" block's CEL expression for the body to propagate back
	// to the message. It is evaluated against the scope's result (the message after
	// the body flow ran on an isolated clone), so it can reference the enriched
	// body/vars. Empty leaves the incoming body unchanged.
	SetBody string `yaml:"setBody,omitempty"`
	// SetVars is an "enrich" block's map of variable name to CEL expression. Each
	// expression is evaluated against the scope's result and set on the message, so
	// the block enriches exactly the variables it names.
	SetVars map[string]string `yaml:"setVars,omitempty"`

	// Key is the cache-key expression of a "cache-scope" block (evaluated per
	// message). TTL is how long a cached entry stays fresh, a duration string
	// ("5m"); empty uses the default and "0" never expires.
	Key string `yaml:"key,omitempty"`
	TTL string `yaml:"ttl,omitempty"`

	// Rules are the assertions of a "validate" block; all must evaluate true or
	// the block rejects the message.
	Rules []RuleConfig `yaml:"rules,omitempty"`
	// OnReject is the shared "filter" slot: the sub-flow a filter block (validate,
	// jwt-validate) runs when it rejects a message, before requesting the flow
	// stop. It shapes the terminal response itself. Empty uses the block's
	// built-in default response.
	OnReject *FlowConfig `yaml:"onReject,omitempty"`
	// RejectStatus is the HTTP status a filter block's built-in default response
	// uses when it rejects (and no OnReject sub-flow is set). Zero applies the
	// block's own default.
	RejectStatus int `yaml:"rejectStatus,omitempty"`

	// Connector names the LLM connector the AI composites (ai-router, ai-agent,
	// ai-retry) call through.
	Connector string `yaml:"connector,omitempty"`
	// Prompt is the routing/task/repair instruction given to the model by the AI
	// composites.
	Prompt string `yaml:"prompt,omitempty"`
	// Guardrail describes when the model should fall back to the Default path; it
	// is used by ai-router and ai-agent.
	Guardrail string `yaml:"guardrail,omitempty"`
	// Routes are the named, described branches of an "ai-router" block. The model
	// picks one; Default is the guardrail taken when it is not confident.
	Routes []RouteConfig `yaml:"routes,omitempty"`
	// Tools are the named, described branches of an "ai-agent" block, each wired
	// to the model as a callable function.
	Tools []ToolConfig `yaml:"tools,omitempty"`
	// Skills are named instruction resources an "ai-agent" can load on demand.
	// The agent is told each skill's name and description up front and is given
	// an implicit load_skill tool to pull a skill's full content (a rendered
	// template resource) into the conversation when it needs it.
	Skills []SkillConfig `yaml:"skills,omitempty"`
	// MaxIterations caps how many tool-calling turns an "ai-agent" runs before
	// falling back to the guardrail (default applied by the builder).
	MaxIterations int `yaml:"maxIterations,omitempty"`
	// MemoryThreadID enables per-thread conversation memory for an "ai-agent": a
	// CEL expression resolved to the thread id whose transcript is loaded before
	// the run and saved after. Empty disables memory.
	MemoryThreadID string `yaml:"memoryThreadId,omitempty"`
	// MemoryMaxTokens is the estimated-token budget for an "ai-agent"'s stored
	// transcript; it is compacted when it exceeds this. Default applied by the builder.
	MemoryMaxTokens int `yaml:"memoryMaxTokens,omitempty"`
	// MemoryCompaction is how an "ai-agent" shrinks memory over budget: "prune"
	// (drop oldest, the default) or "summarize" (fold the oldest turns into a summary).
	MemoryCompaction string `yaml:"memoryCompaction,omitempty"`
	// MaxAttempts caps how many times an "ai-retry" re-runs its Process chain
	// after an LLM-driven revision before falling through to Error (default
	// applied by the builder).
	MaxAttempts int `yaml:"maxAttempts,omitempty"`

	// ServerName is the MCP server name an "mcp-router" reports in its initialize
	// response; it defaults to the block name (then "octo-mcp") when unset.
	ServerName string `yaml:"serverName,omitempty"`
	// Resources are the template resources an "mcp-router" advertises as MCP
	// resources (each with its own uri) and serves on resources/read.
	Resources []MCPResourceConfig `yaml:"resources,omitempty"`
	// Prompts are the template resources an "mcp-router" advertises as MCP prompts
	// (each with named arguments) and renders on prompts/get. The "mcp-router"
	// reuses the Tools slot to expose flows as MCP tools.
	Prompts []MCPPromptConfig `yaml:"prompts,omitempty"`
}

type CaseConfig struct {
	When string     `yaml:"when"`
	Flow FlowConfig `yaml:",inline"`
}

type Config struct {
	Service ServiceConfig `yaml:"service"`
	// Env declares the environment variables this config may reference as ${NAME}
	// in settings values. Referencing an undeclared variable is an error.
	Env        []EnvVar          `yaml:"env,omitempty"`
	Connectors []ConnectorConfig `yaml:"connectors"`
	// Processors holds reusable, named processor definitions that flow blocks
	// reference by name via BlockConfig.Ref, mirroring how Connectors are
	// declared once and referenced by a flow's source.
	Processors []ProcessorConfig `yaml:"processors,omitempty"`
	Flows      []FlowConfig      `yaml:"flows,omitempty"`

	// Resources declares the external resources this config imports: the
	// .env-convention files combined into the runtime environment, and the template
	// resources aliased for reference from blocks and CEL. Declared resources are
	// loaded when the config loads, so a missing or malformed one fails at
	// deployment rather than when a message first references it.
	Resources ResourcesConfig `yaml:"resources,omitempty"`

	// ResolvedEnv holds the declared environment variables resolved to their
	// values (the same map used for ${NAME} substitution), so expressions can
	// read them as env.NAME. Populated during config load; not serialized.
	ResolvedEnv map[string]string `yaml:"-"`
}

type ConnectorConfig struct {
	Name     string   `yaml:"name"`
	Type     string   `yaml:"type"`
	Settings Settings `yaml:"settings,omitempty"`
}

type EnvVar struct {
	Name string `yaml:"name"`
	// Default is the value used when neither the OS environment nor a .env file
	// supplies the variable. The pointer distinguishes an absent default (nil, so a
	// referenced-but-unresolved variable is an error) from an explicit empty
	// default (a value of "").
	Default *string `yaml:"default,omitempty"`
	// Required fails the load when the variable is not supplied by the OS
	// environment or a .env file.
	Required bool `yaml:"required,omitempty"`
}

type FlowConfig struct {
	Name    string        `yaml:"name,omitempty"`
	Source  *SourceConfig `yaml:"source,omitempty"`
	Process []BlockConfig `yaml:"process"`
	// Error is the root flow's error path: when the Process chain returns an
	// error, the runtime exposes it as vars.error and runs this chain; on success
	// its output becomes the flow's result (recovery). It is a bare block chain,
	// like Process. Root flows only.
	Error   []BlockConfig `yaml:"error,omitempty"`
	Workers int           `yaml:"workers,omitempty"`
	Buffer  int           `yaml:"buffer,omitempty"`
	// Pool sizes the shared worker pool the root flow owns and passes down to
	// composite blocks that schedule work concurrently (e.g. a fork's branches).
	// Root flows only; defaults when unset.
	Pool int `yaml:"pool,omitempty"`
}

type FlowEvent struct {
	// Kind is the lifecycle outcome this event records.
	Kind FlowEventKind
	// Flow is the name of the flow the message is travelling through.
	Flow string
	// Block is the type or name of the block where the event originated. It is
	// empty for source-level events.
	Block string
	// EventID is the Message.EventID this event concerns.
	EventID string
	// OccurredAt is when the event was published.
	OccurredAt time.Time
	// Err is set only for FlowEventFailed.
	Err error
	// Result is the message at the terminal event: the flow's output for
	// FlowEventCompleted, or the input message for FlowEventDropped and
	// FlowEventFailed. It is nil for FlowEventStarted. Subscribers must treat
	// it as read-only; it lets request/response sources return the final
	// payload to a caller correlated by EventID.
	Result *Message
}

type FlowEventKind string

type MCPPromptArg struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description,omitempty"`
	Required    bool   `yaml:"required,omitempty"`
}

type MCPPromptConfig struct {
	Name        string         `yaml:"name"`
	Description string         `yaml:"description,omitempty"`
	Arguments   []MCPPromptArg `yaml:"arguments,omitempty"`
	Resource    string         `yaml:"resource"`
}

type MCPResourceConfig struct {
	URI         string `yaml:"uri"`
	Name        string `yaml:"name"`
	Description string `yaml:"description,omitempty"`
	MimeType    string `yaml:"mimeType,omitempty"`
	Resource    string `yaml:"resource"`
}

type Message struct {
	// EventID uniquely identifies this message. It is generated at
	// construction time and is stable for the life of the message.
	EventID string `json:"event_id"`

	// CorrelationID groups related messages across a logical flow. It is
	// caller-supplied and may be empty.
	CorrelationID string `json:"correlation_id,omitempty"`

	// Variables holds arbitrary per-message values keyed by name. Use the
	// typed accessors on Variables rather than asserting types directly.
	Variables Variables `json:"variables,omitempty"`

	// Body is the decoded JSON payload. Pipeline stages may mutate it in
	// place; SetBodyJSON and BodyJSON bridge to and from wire bytes.
	Body any `json:"body,omitempty"`

	// BodySchema is the JSON Schema describing Body, stored as raw JSON.
	// Validation of Body against BodySchema lives in the core module, which
	// may depend on a schema library; types stays dependency-free.
	BodySchema json.RawMessage `json:"body_schema,omitempty"`

	// RawContent marks Body as carrying a raw, non-JSON payload in the shape
	// {contentType, rawData}. Raw-aware connectors (e.g. the http source) serve
	// rawData with the given MIME type instead of JSON-encoding Body. Defaults
	// to false; JSON remains the contract for every message that does not opt in.
	RawContent bool `json:"raw_content,omitempty"`
}

type ProcessorConfig struct {
	Name     string   `yaml:"name"`
	Type     string   `yaml:"type"`
	Settings Settings `yaml:"settings,omitempty"`
}

type ResourcesConfig struct {
	Env       []string           `yaml:"env,omitempty"`
	Templates []TemplateResource `yaml:"templates,omitempty"`
}

type RouteConfig struct {
	Name        string        `yaml:"name"`
	Description string        `yaml:"description"`
	Process     []BlockConfig `yaml:"process"`
}

type RuleConfig struct {
	Expr    string `yaml:"expr"`
	Message string `yaml:"message,omitempty"`
}

type ServiceConfig struct {
	Name        string `yaml:"name"`
	Environment string `yaml:"environment,omitempty"`
}

type Settings map[string]any

type SkillConfig struct {
	Name        string `yaml:"name"`
	Description string `yaml:"description"`
	Resource    string `yaml:"resource"`
}

type SourceConfig struct {
	// Connector is the Name of a configured connector instance, not its Type.
	Connector string   `yaml:"connector"`
	Type      string   `yaml:"type"`
	Settings  Settings `yaml:"settings,omitempty"`
}

type TemplateResource struct {
	Resource string `yaml:"resource"`
	As       string `yaml:"as,omitempty"`
}

type ToolConfig struct {
	Name        string        `yaml:"name"`
	Description string        `yaml:"description"`
	InputSchema string        `yaml:"inputSchema,omitempty"`
	Process     []BlockConfig `yaml:"process"`
}

type Variables map[string]any