agent

type AgentExpr struct {
	eval.DSLFunc

	// Name is the unique identifier for this agent.
	Name string
	// Description provides a human-readable explanation of the
	// agent's purpose and capabilities.
	Description string
	// Service is the Goa service expression this agent is
	// associated with.
	Service *goaexpr.ServiceExpr
	// Used contains the toolsets this agent consumes from other
	// agents or services.
	Used *ToolsetGroupExpr
	// Exported contains the toolsets this agent exposes for other
	// agents to consume.
	Exported *ToolsetGroupExpr
	// RunPolicy defines runtime execution and resource constraints
	// for this agent.
	RunPolicy *RunPolicyExpr
}

type CacheExpr struct {
	eval.DSLFunc

	// Policy is the run policy expression this cache configuration
	// belongs to.
	Policy *RunPolicyExpr
	// AfterSystem places a cache checkpoint after all system messages.
	AfterSystem bool
	// AfterTools places a cache checkpoint after tool definitions.
	AfterTools bool
}

type CapsExpr struct {
	// Policy is the run policy expression this caps configuration
	// belongs to.
	Policy *RunPolicyExpr
	// MaxToolCalls is the maximum number of tool invocations
	// allowed in a single run.
	MaxToolCalls int
	// MaxConsecutiveFailedToolCall is the maximum number of
	// consecutive tool failures before the run is terminated.
	MaxConsecutiveFailedToolCall int
}

type FederationExpr struct {
	eval.DSLFunc

	// Include specifies glob patterns for namespaces to import from
	// the federated source. If empty, all namespaces are included.
	Include []string
	// Exclude specifies glob patterns for namespaces to skip from
	// the federated source.
	Exclude []string
}

type HistoryExpr struct {
	eval.DSLFunc

	// Policy is the run policy expression this history configuration
	// belongs to.
	Policy *RunPolicyExpr
	// Mode selects the history strategy.
	Mode HistoryMode
	// KeepRecent is the number of recent turns to retain when
	// ModeKeepRecent is selected.
	KeepRecent int
	// TriggerAt is the number of turns that must accumulate before
	// compression triggers when ModeCompress is selected.
	TriggerAt int
	// CompressKeepRecent is the number of recent turns to retain in full
	// fidelity when ModeCompress is selected.
	CompressKeepRecent int
}

type HistoryMode string

type ProviderExpr struct {
	// Kind identifies the provider type (local, MCP, registry).
	Kind ProviderKind
	// MCPService is the Goa service name that owns the MCP server
	// definition. Used when Kind is ProviderMCP.
	MCPService string
	// MCPToolset is the MCP server name for this toolset. Used when
	// Kind is ProviderMCP.
	MCPToolset string
	// Registry references the registry source for this toolset.
	// Used when Kind is ProviderRegistry.
	Registry *RegistryExpr
	// ToolsetName is the name of the toolset in the registry.
	// Used when Kind is ProviderRegistry.
	ToolsetName string
	// Version pins the toolset to a specific version.
	// Used when Kind is ProviderRegistry.
	Version string
}

type ProviderKind int

type RegistryExpr struct {
	eval.DSLFunc

	// Name is the unique identifier for this registry within the design.
	Name string
	// Description provides a human-readable explanation of the
	// registry's purpose.
	Description string
	// URL is the registry endpoint URL.
	URL string
	// APIVersion is the registry API version (e.g., "v1", "2024-11-05").
	// Defaults to "v1" for Anthropic-compatible registries.
	APIVersion string
	// Requirements contains the security requirements for authenticating
	// with this registry. References Goa security schemes.
	Requirements []*goaexpr.SecurityExpr
	// SyncInterval specifies how often to refresh the registry catalog.
	SyncInterval time.Duration
	// CacheTTL specifies local cache duration for registry data.
	CacheTTL time.Duration
	// Timeout specifies HTTP request timeout for registry operations.
	Timeout time.Duration
	// RetryPolicy configures retry behavior for failed requests.
	RetryPolicy *RetryPolicyExpr
	// Federation configures external registry import settings.
	Federation *FederationExpr
}

type RetryPolicyExpr struct {
	// MaxRetries is the maximum number of retry attempts.
	MaxRetries int
	// BackoffBase is the initial backoff duration between retries.
	BackoffBase time.Duration
	// BackoffMax is the maximum backoff duration between retries.
	BackoffMax time.Duration
}

type RootExpr struct {
	// Agents is the collection of all agent expressions defined in the
	// design.
	Agents []*AgentExpr
	// ServiceExports holds toolsets exported directly by services.
	ServiceExports []*ServiceExportsExpr
	// Toolsets is the collection of all standalone toolset expressions not
	// owned by an agent.
	Toolsets []*ToolsetExpr
	// Registries is the collection of all registry expressions defined
	// in the design.
	Registries []*RegistryExpr
	// DisableAgentDocs controls whether agent-specific documentation
	// generation is suppressed.
	DisableAgentDocs bool
}

type RunPolicyExpr struct {
	eval.DSLFunc

	// Agent is the agent expression this policy applies to.
	Agent *AgentExpr
	// DefaultCaps specifies default per-run limits on tool usage.
	DefaultCaps *CapsExpr
	// TimeBudget is the maximum duration a run may execute before
	// being terminated.
	TimeBudget time.Duration
	// PlanTimeout applies to both Plan and Resume activities when set.
	PlanTimeout time.Duration
	// ToolTimeout is the default ExecuteTool activity timeout when set.
	ToolTimeout time.Duration
	// InterruptsAllowed indicates whether the agent can be
	// interrupted during execution.
	InterruptsAllowed bool
	// OnMissingFields controls behavior when validation indicates
	// missing fields.  Allowed values: "finalize" |
	// "await_clarification" | "resume". Empty means unspecified.
	OnMissingFields string
	// History configures how the runtime prunes or compresses
	// conversational history before planner invocations.
	History *HistoryExpr
	// Cache configures prompt caching hints for planner/model calls.
	Cache *CacheExpr
}

type ServerDataExpr struct {
	eval.DSLFunc

	// Kind identifies the logical kind of this server data (for example,
	// "atlas.time_series" for UI charts).
	Kind string

	// Audience declares who this server-data payload is intended for.
	//
	// Contract:
	//   - "timeline": persisted and eligible for UI rendering and transcript export.
	//   - "internal": tool-composition attachment; not persisted or rendered.
	//   - "evidence": provenance references; persisted separately from timeline cards.
	//
	// Audience is set by the DSL layer. When not explicitly configured, it
	// defaults to "timeline".
	Audience string

	// Description is the observer-facing description of this server-data payload.
	// It is typically used by UIs and sinks to explain rendering behavior.
	Description string

	// Schema describes the typed payload. It must be non-empty.
	Schema *goaexpr.AttributeExpr

	// Source describes how to populate the server-data payload. When set,
	// code generation uses it to derive the server-data payload from the tool's
	// bound method result.
	Source *ServerDataSourceExpr

	// Tool links this server-data declaration to its owning tool. It is set by
	// the DSL layer and used for schema naming and validation.
	Tool *ToolExpr
}

type ServerDataSourceExpr struct {
	// MethodResultField names the bound method result field used as the source
	// payload (for example, "Evidence").
	MethodResultField string
}

type ServiceExportsExpr struct {
	eval.DSLFunc

	// Service is the Goa service that owns these exported toolsets.
	Service *goaexpr.ServiceExpr
	// Toolsets is the collection of toolset expressions exported
	// by the service.
	Toolsets []*ToolsetExpr
}

type ToolBoundsExpr struct {
	// Tool is the owning tool declaration.
	Tool *ToolExpr
	// Paging optionally describes cursor-based pagination for this bounded tool.
	Paging *ToolPagingExpr
}

type ToolConfirmationExpr struct {
	// Title is an optional title presented in the confirmation UI.
	Title string

	// PromptTemplate is a Go text/template rendered with the tool payload to
	// produce the operator-facing confirmation prompt.
	PromptTemplate string

	// DeniedResultTemplate is a Go text/template rendered with the tool payload to
	// produce canonical JSON for the denied tool result. The rendered JSON must
	// decode successfully using the tool result codec.
	DeniedResultTemplate string
}

type ToolExpr struct {
	eval.DSLFunc

	// Name is the unique identifier for this tool within its toolset.
	Name string

	// Title is an optional human-friendly display title. When empty, codegen
	// derives a title from Name (e.g., "analyze_sensor_patterns" -> "Analyze Sensor Patterns").
	Title string

	// Description provides a human-readable explanation of what the
	// tool does.
	Description string

	// Tags are labels for categorizing and filtering this tool.
	Tags []string

	// Meta carries arbitrary design-time metadata attached to the tool via DSL.
	// Keys map to one or more values, matching Goa's Meta conventions.
	Meta goaexpr.MetaExpr

	// Args defines the input parameter schema for this tool.
	Args *goaexpr.AttributeExpr

	// Return defines the output result schema for this tool.
	Return *goaexpr.AttributeExpr

	// ServerData declares typed server-only data emitted alongside the canonical
	// tool result. Server data is never serialized into model provider requests.
	//
	// Each entry declares a Kind identifier and a schema type. Code generation
	// produces a JSON codec per entry so values can be marshaled into canonical
	// JSON bytes and decoded reliably by runtimes and downstream consumers.
	ServerData []*ServerDataExpr

	// Toolset is the toolset expression that owns this tool.
	Toolset *ToolsetExpr

	// Method is the resolved Goa service method this tool is bound
	// to, if any.
	Method *goaexpr.MethodExpr

	// ExportPassthrough defines deterministic forwarding for this tool
	// when it is part of an exported toolset.
	ExportPassthrough *ToolPassthroughExpr

	// Optional display hint templates declared in the DSL.
	CallHintTemplate   string
	ResultHintTemplate string

	// InjectedFields are fields marked as infrastructure-only.
	InjectedFields []string

	// Bounds declares the out-of-band bounded-result contract for this tool.
	// When non-nil, runtimes require planner.ToolResult.Bounds and generated
	// method-backed executors project canonical bound fields from service
	// method results without polluting the semantic result schema.
	Bounds *ToolBoundsExpr

	// TerminalRun indicates that once this tool executes, the runtime should
	// terminate the run immediately without requesting a follow-up planner
	// PlanResume/finalization turn. It is set via the TerminalRun DSL helper.
	TerminalRun bool

	// ResultReminder is an optional system reminder that is injected into
	// the conversation after the tool result is returned. It provides
	// backstage guidance to the model about how to interpret or present
	// the result (for example, "The user sees a rendered graph of this
	// data"). The reminder is wrapped in <system-reminder> tags by the
	// runtime.
	ResultReminder string

	// Confirmation configures design-time confirmation requirements for this tool.
	// When non-nil, the runtime requests an external confirmation before executing
	// the tool (unless runtime overrides supersede the confirmation).
	Confirmation *ToolConfirmationExpr
	// contains filtered or unexported fields
}

type ToolPagingExpr struct {
	// CursorField is the name of the optional String field in the tool payload
	// that carries the paging cursor for retrieving the next page.
	CursorField string
	// NextCursorField is the canonical field name for the next-page cursor in
	// the paging contract.
	NextCursorField string
}

type ToolPassthroughExpr struct {
	TargetService string
	TargetMethod  string
}

type ToolsetExpr struct {
	eval.DSLFunc

	// Name is the unique identifier for this toolset within the design.
	// Root-level validation enforces that defining toolsets (Origin == nil)
	// use globally unique names so tooling can treat toolset IDs as simple
	// names.
	Name string

	// Description provides a human-readable explanation of the
	// toolset's purpose.
	Description string

	// Tags are labels for categorizing and filtering this toolset.
	Tags []string

	// Meta carries arbitrary design-time metadata attached to the toolset via DSL.
	// Keys map to one or more values, matching Goa's Meta conventions.
	Meta goaexpr.MetaExpr

	// Agent is the agent expression that owns this toolset, if any.
	// When nil, the toolset is either top-level or attached to a
	// service export.
	Agent *AgentExpr

	// Tools is the collection of tool expressions in this toolset.
	Tools []*ToolExpr

	// Provider configures the source/executor for this toolset.
	// When nil, the toolset is local with inline schemas.
	Provider *ProviderExpr

	// PublishTo specifies registries where this toolset should be
	// published when exported.
	PublishTo []*RegistryExpr

	// Origin references the original defining toolset when this toolset
	// is a reference/alias (e.g., consumed under Uses or via AgentToolset).
	// When nil, this toolset is the defining origin.
	Origin *ToolsetExpr
}

type ToolsetGroupExpr struct {
	eval.DSLFunc

	// Agent is the agent expression that owns this toolset group.
	Agent *AgentExpr
	// Toolsets is the collection of toolset expressions in this
	// group.
	Toolsets []*ToolsetExpr
}