codegen

type ActivityArtifact struct {
	// Name is the logical activity identifier registered with the engine.
	Name string
	// FuncName is the Go function implementing the activity handler.
	FuncName string
	// DefinitionVar is the exported variable name storing the activity definition.
	DefinitionVar string
	// Queue overrides the default queue if provided.
	Queue string
	// RetryPolicy describes the activity retry behavior.
	RetryPolicy engine.RetryPolicy
	// ScheduleToStartTimeout bounds how long the activity may wait in the queue.
	ScheduleToStartTimeout time.Duration
	// StartToCloseTimeout bounds a single activity attempt once execution begins.
	StartToCloseTimeout time.Duration
	// HeartbeatTimeout bounds the maximum gap between emitted activity heartbeats.
	HeartbeatTimeout time.Duration
	// Kind categorizes the activity so templates can render concrete logic.
	Kind ActivityKind
}

type ActivityKind string

type AgentData struct {
	// Genpkg stores the Go import path to the generated root (module/gen).
	Genpkg string
	// Name is the DSL-provided identifier.
	Name string
	// Description is the DSL-provided description for the agent.
	Description string
	// ID is the service-scoped identifier (`service.agent`).
	ID string
	// GoName is the exported Go identifier derived from Name.
	GoName string
	// Slug is a filesystem-safe version of the agent name.
	Slug string
	// Service is the Goa service metadata this agent belongs to.
	Service *service.Data
	// PackageName is the Go package name for generated agent code.
	PackageName string
	// PathName mirrors PackageName but is tailored for directory names.
	PathName string
	// Dir is the output directory for the agent package.
	Dir string
	// ImportPath is the full Go import path to the agent package.
	ImportPath string

	// ConfigType names the generated configuration struct.
	ConfigType string
	// StructName names the generated agent wrapper type.
	StructName string
	// WorkflowFunc is the workflow entry point name.
	WorkflowFunc string
	// WorkflowDefinitionVar stores the exported workflow definition variable name.
	WorkflowDefinitionVar string
	// WorkflowName is the logical workflow identifier registered with the engine.
	WorkflowName string
	// WorkflowQueue is the default workflow task queue.
	WorkflowQueue string
	// ToolSpecsPackage is the package name housing generated tool specs.
	ToolSpecsPackage string
	// ToolSpecsImportPath is the import path for the tool specs package.
	ToolSpecsImportPath string
	// ToolSpecsDir is the filesystem directory containing the tool specs files.
	ToolSpecsDir string
	// RunPolicy captures caps/time budget settings.
	RunPolicy RunPolicyData
	// UsedToolsets lists toolsets referenced via `Use`.
	UsedToolsets []*ToolsetData
	// ExportedToolsets lists toolsets declared via `Export`.
	ExportedToolsets []*ToolsetData
	// AllToolsets concatenates consumed and exported toolsets for convenience.
	AllToolsets []*ToolsetData
	// MethodBackedToolsets lists toolsets that contain at least one tool bound
	// to a Goa service method via BindTo.
	MethodBackedToolsets []*ToolsetData
	// Tools flattens every tool declared across the agent's toolsets.
	Tools []*ToolData
	// MCPToolsets lists the distinct external MCP toolsets referenced via MCPToolset/Use.
	// Each entry captures the helper import/path information required to register
	// the toolset with the runtime at agent registration time.
	MCPToolsets []*MCPToolsetMeta
	// RegistryToolsets lists the distinct registry-backed toolsets referenced via
	// FromRegistry provider. Each entry captures the registry client import/path
	// information required to discover and register the toolset at runtime.
	RegistryToolsets []*RegistryToolsetMeta
	// Runtime captures derived workflow/activity data used by templates.
	Runtime RuntimeData
	// Methods contains the routing strategies for agent methods.
	Methods []*MethodData
}

type CacheData struct {
	// AfterSystem places a cache checkpoint after all system messages.
	AfterSystem bool
	// AfterTools places a cache checkpoint after tool definitions.
	AfterTools bool
}

type CapsData struct {
	// MaxToolCalls caps the number of tool invocations per run (0 = unlimited).
	MaxToolCalls int
	// MaxConsecutiveFailedToolCalls stops execution after N consecutive failures (0 = unlimited).
	MaxConsecutiveFailedToolCalls int
}

type FederationData struct {
	// Include patterns for namespaces to import.
	Include []string
	// Exclude patterns for namespaces to skip.
	Exclude []string
}

type GeneratorData struct {
	// Genpkg is the Go import path to the generated code root (typically `<module>/gen`).
	Genpkg string
	// Services bundles the agent metadata grouped by Goa service.
	Services []*ServiceAgentsData
}

type HistoryData struct {
	// Mode is "keep_recent" or "compress".
	Mode string
	// KeepRecent is the number of recent turns to retain when Mode ==
	// "keep_recent".
	KeepRecent int
	// TriggerAt is the number of turns that must accumulate before
	// compression triggers when Mode == "compress".
	TriggerAt int
	// CompressKeepRecent is the number of recent turns to retain in full
	// fidelity when Mode == "compress".
	CompressKeepRecent int
}

type MCPToolsetMeta struct {
	// ServiceName is the Goa service that declared the MCP server/toolset.
	ServiceName string
	// SuiteName is the MCP server/toolset identifier provided in the service DSL.
	SuiteName string
	// QualifiedName is the canonical toolset identifier (server/toolset name).
	QualifiedName string
	// HelperImportPath is the Go import path for the generated register helper.
	HelperImportPath string
	// HelperAlias is the import alias used inside generated agent code.
	HelperAlias string
	// HelperFunc is the helper function name (Register<Service><Suite>Toolset).
	HelperFunc string
	// ConstName is the generated Go identifier for the agent-local MCP toolset
	// ID constant. Explicit Service/Suite/Alias separators keep provider
	// partitions distinct so different remote bindings cannot collapse into the
	// same Go identifier after sanitization.
	ConstName string
}

type MethodData struct {
	// Name is the name of the method (must match a tool name in the agent's exported toolsets).
	Name string
	// Passthrough defines deterministic forwarding to a Goa service method.
	Passthrough *PassthroughData
}

type PassthroughData struct {
	// Service is the name of the target Goa service.
	Service string
	// Method is the name of the target Goa method.
	Method string
}

type RegistryClientData struct {
	// Name is the DSL-provided registry identifier.
	Name string
	// GoName is the exported Go identifier derived from Name.
	GoName string
	// Description is the DSL-provided description.
	Description string
	// URL is the registry endpoint URL.
	URL string
	// APIVersion is the registry API version (e.g., "v1").
	APIVersion string
	// PackageName is the Go package name for the generated client.
	PackageName string
	// Dir is the output directory for the client package.
	Dir string
	// ImportPath is the full Go import path to the client package.
	ImportPath string
	// Timeout is the HTTP request timeout.
	Timeout time.Duration
	// RetryPolicy contains retry configuration.
	RetryPolicy *RetryPolicyData
	// SyncInterval is how often to refresh the catalog.
	SyncInterval time.Duration
	// CacheTTL is the local cache duration.
	CacheTTL time.Duration
	// SecuritySchemes contains the security requirements.
	SecuritySchemes []*SecuritySchemeData
	// Federation contains federation configuration if present.
	Federation *FederationData
}

type RegistryToolsetMeta struct {
	// RegistryName is the name of the registry source.
	RegistryName string
	// ToolsetName is the name of the toolset in the registry.
	ToolsetName string
	// Version is the optional version pin for the toolset.
	Version string
	// QualifiedName is the canonical toolset identifier.
	QualifiedName string
	// RegistryClientImportPath is the Go import path for the registry client.
	RegistryClientImportPath string
	// RegistryClientAlias is the import alias for the registry client.
	RegistryClientAlias string
}

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

type RunPolicyData struct {
	// TimeBudget is the maximum wall-clock time allocated to the run.
	TimeBudget time.Duration
	// PlanTimeout applies to the Plan and Resume StartToClose timeouts when set.
	PlanTimeout time.Duration
	// ToolTimeout sets the default ExecuteTool StartToClose timeout when set.
	ToolTimeout time.Duration
	// InterruptsAllowed indicates whether human interrupts are honored.
	InterruptsAllowed bool
	// Caps enumerates max tool-call limits.
	Caps CapsData
	// OnMissingFields controls behavior when validation indicates missing
	// fields. Allowed: "finalize" | "await_clarification" | "resume".
	// Empty means unspecified.
	OnMissingFields string
	// History captures conversational history management configuration (if
	// any). When nil, no history policy is configured and callers retain
	// full history.
	History *HistoryData
	// Cache captures prompt caching configuration (if any). Zero value
	// means no cache policy is configured and providers should not emit
	// cache checkpoints unless explicit CacheCheckpointPart messages are
	// present in requests.
	Cache CacheData
}

type RuntimeData struct {
	// Workflow describes the generated workflow definition.
	Workflow WorkflowArtifact
	// Activities enumerates the activity handlers to register.
	Activities []ActivityArtifact
	// ExecuteTool references the activity used to run tools via the workflow engine.
	ExecuteTool *ActivityArtifact
	// PlanActivity references the activity wrapping PlanStart.
	PlanActivity *ActivityArtifact
	// ResumeActivity references the activity wrapping PlanResume.
	ResumeActivity *ActivityArtifact
}

type SecuritySchemeData struct {
	// Name is the security scheme name.
	Name string
	// Kind is the Goa security scheme kind.
	Kind goaexpr.SchemeKind
	// In is where the credential is sent (e.g., "header", "query").
	In string
	// ParamName is the parameter name (e.g., "Authorization").
	ParamName string
	// Scopes lists required OAuth2 scopes.
	Scopes []string
}

type ServerDataData struct {
	// Kind is the server-data kind identifier.
	Kind string
	// Audience declares who this payload is intended for ("timeline", "internal", "evidence").
	Audience string
	// Schema is the typed schema for the server-data payload.
	Schema *goaexpr.AttributeExpr
	// Description describes the observer-facing rendering contract.
	Description string
	// MethodResultField is the bound method result field name when the payload
	// is sourced from a method result field.
	MethodResultField string
}

type ServiceAgentsData struct {
	// Service contains the Goa service metadata from the core generators.
	Service *service.Data
	// Agents lists each agent declared within the service DSL.
	Agents []*AgentData
	// HasMCP indicates whether any agent under this service references external
	// MCP toolsets. Example-phase generators use this to decide whether to emit
	// MCP caller scaffolding/imports.
	HasMCP bool
}

type ToolBoundsData struct {
	// Paging optionally describes cursor-based pagination for this bounded tool.
	Paging *ToolPagingData
	// Projection describes how a generated method-backed executor should project
	// canonical bounds metadata from the bound method result.
	Projection *ToolBoundsProjectionData
}

type ToolBoundsFieldData struct {
	// Name is the Go field name on the bound method result.
	Name string
	// Required reports whether the field is required in the Goa design.
	Required bool
}

type ToolBoundsProjectionData struct {
	Returned       *ToolBoundsFieldData
	Total          *ToolBoundsFieldData
	Truncated      *ToolBoundsFieldData
	NextCursor     *ToolBoundsFieldData
	RefinementHint *ToolBoundsFieldData
}

type ToolConfirmationData struct {
	// Title is an optional UI title shown when prompting for confirmation.
	Title string
	// PromptTemplate is a Go text/template rendered with the tool payload.
	PromptTemplate string
	// DeniedResultTemplate is a Go text/template rendered with the tool payload.
	// The template must render valid JSON for the tool result type.
	DeniedResultTemplate string
}

type ToolData struct {
	// Name is the DSL-provided tool identifier.
	Name string
	// ConstName is a Go-safe exported identifier for referencing this tool
	// in generated code (e.g., AnalyzeData for tool name "analyze_data").
	ConstName string
	// Description is the DSL description for docs and planners.
	Description string
	// QualifiedName is the toolset-scoped identifier (`toolset.tool`).
	QualifiedName string
	// Title is a human-friendly title for presentation (e.g., "Analyze Data").
	// Defaults to a derived value from Name unless explicitly set in the DSL.
	Title string
	// Tags holds optional metadata tags supplied in the DSL.
	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 map[string][]string
	// Args is the Goa attribute describing the tool payload.
	Args *goaexpr.AttributeExpr
	// Return is the Goa attribute describing the tool result.
	Return *goaexpr.AttributeExpr
	// ServerData enumerates server-only payloads emitted alongside the tool
	// result. Server data is never sent to model providers.
	ServerData []*ServerDataData
	// MethodPayloadAttr is the Goa attribute for the bound service payload
	// (resolved user type). Used to generate default payload adapters.
	MethodPayloadAttr *goaexpr.AttributeExpr

	// MethodResultAttr is the Goa attribute for the bound service result
	// (resolved user type). Used to generate default result adapters and to
	// materialize specs when the tool Return is not specified.
	MethodResultAttr *goaexpr.AttributeExpr

	// Toolset links back to the parent toolset metadata.
	Toolset *ToolsetData
	// HasResult indicates whether the tool produces a result value. It is true
	// when either the tool Return is specified in the DSL or the bound service
	// method defines a non-empty result type.
	HasResult bool
	// IsExportedByAgent indicates this tool is exported by an agent (agent-as-tool).
	// Set to true when the tool's toolset is in an agent's Exports block.
	IsExportedByAgent bool
	// ExportingAgentID is the fully qualified agent identifier (e.g., "service.agent_name").
	// Only set when IsExportedByAgent is true.
	ExportingAgentID string

	// IsMethodBacked indicates this tool is bound to a Goa service method via
	// the DSL Method() function. When true, code generation emits client dispatch
	// logic that adapts tool arguments to the method's payload type and maps the
	// method result back to the tool's return type.
	//
	// This enables tools to be implemented by calling existing service endpoints
	// rather than requiring custom executor functions. The binding is established
	// during DSL evaluation (see ToolExpr.Method in expr/toolset.go).
	//
	// Set by newToolData based on expr.Method != nil.
	IsMethodBacked bool
	// MethodGoName is the Goified method name from the bound service method,
	// used to reference the generated client endpoint. For example, if Method()
	// binds to a method named "get_device", MethodGoName will be "GetDevice",
	// matching the generated client function name.
	//
	// Only populated when IsMethodBacked is true.
	MethodGoName string
	// MethodPayloadTypeName is the exact payload type name for the bound method
	// as generated by Goa (e.g., ADGetAlarmsPayload). Empty when not bound.
	MethodPayloadTypeName string
	// MethodResultTypeName is the exact result type name for the bound method
	// as generated by Goa (e.g., ADGetAlarmsResult). Empty when not bound.
	MethodResultTypeName string
	// MethodPayloadTypeRef is the fully-qualified reference for the bound method payload type.
	MethodPayloadTypeRef string
	// MethodResultTypeRef is the fully-qualified reference for the bound method result type.
	MethodResultTypeRef string
	// MethodPayloadLoc is the Goa location for the payload user type when specified via
	// Meta("struct:pkg:path", ...). Nil when the payload is local to the service package
	// or is not a user type.
	MethodPayloadLoc *codegen.Location
	// MethodResultLoc is the Goa location for the result user type when specified via
	// Meta("struct:pkg:path", ...). Nil when the result is local to the service package
	// or is not a user type.
	MethodResultLoc *codegen.Location

	// PayloadAliasesMethod is true when the tool payload user type matches
	// the bound method payload user type or any of its Extend bases. In this
	// case the generated code bypasses the payload adapter and forwards the
	// tool payload directly to the client.
	PayloadAliasesMethod bool
	// ResultAliasesMethod is true when the tool result user type matches the
	// bound method result user type or any of its Extend bases. In this case the
	// generated code bypasses the result adapter and returns the service result
	// directly as the tool result.
	ResultAliasesMethod bool

	// Optional hint templates from DSL
	CallHintTemplate   string
	ResultHintTemplate string

	// InjectedFields contains the names of fields marked for injection via DSL.
	InjectedFields []string

	// Bounds declares the out-of-band bounded-result contract for this tool.
	// When non-nil, codegen emits runtime specs and method-result projection
	// helpers without mutating the semantic result schema.
	Bounds *ToolBoundsData

	// TerminalRun indicates that once this tool executes, the runtime should
	// complete the run immediately (no follow-up PlanResume/finalize turn).
	TerminalRun bool

	// ResultReminder is an optional system reminder 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.
	ResultReminder string

	// Confirmation configures design-time confirmation requirements for this tool.
	Confirmation *ToolConfirmationData

	// PassthroughService is the Goa service name for deterministic forwarding
	// when this tool is part of an exported toolset.
	PassthroughService string
	// PassthroughMethod is the Goa method name for deterministic forwarding
	// when this tool is part of an exported toolset.
	PassthroughMethod string
}

type ToolPagingData struct {
	CursorField     string
	NextCursorField string
}

type ToolsetData struct {
	// Expr is the original toolset expression.
	Expr *agentsExpr.ToolsetExpr
	// Name is the DSL-specified toolset identifier.
	Name string
	// Title is a human-friendly display name derived from Name.
	Title string
	// Description captures the DSL description for docs/registries.
	Description string
	// Tags attaches toolset-level tags used by policy/filtering at registration time.
	Tags []string
	// ServiceName identifies the owning Goa service (blank for global toolsets).
	ServiceName string
	// SourceServiceName maintains the original service that declared the toolset
	// (used for external providers such as MCP). Defaults to ServiceName.
	SourceServiceName string
	// SourceService points to the Goa service that originally declared the toolset.
	// For external providers (e.g., MCP) this differs from the consuming agent service.
	SourceService *service.Data
	// SourceServiceImports caches the user type imports for the source service. This
	// enables tool spec generation to reference external service types.
	SourceServiceImports map[string]*codegen.ImportSpec
	// QualifiedName is the toolset-scoped identifier (`toolset`).
	QualifiedName string
	// TaskQueue is the derived Temporal/engine queue for tool execution.
	TaskQueue string
	// Kind states whether this toolset is consumed, exported, or global.
	Kind ToolsetKind
	// Agent references the owning agent when one exists.
	Agent *AgentData
	// PathName is the filesystem-safe slug for the toolset.
	PathName string
	// PackageName is the Go package name for generated helper code.
	PackageName string
	// PackageImportPath is the Go import path to that helper package.
	PackageImportPath string
	// Dir is the filesystem target for toolset-specific files.
	Dir string
	// SpecsPackageName is the Go package name for per-toolset specs/types/codecs.
	SpecsPackageName string
	// SpecsImportPath is the import path for per-toolset specs/types/codecs.
	SpecsImportPath string
	// SpecsDir is the filesystem directory for per-toolset specs/types/codecs.
	SpecsDir string
	// AgentToolsPackage is the package name for exported tool helpers.
	AgentToolsPackage string
	// AgentToolsDir is the filesystem directory for exported tool helpers.
	AgentToolsDir string
	// AgentToolsImportPath is the Go import path for exported agent tool helpers
	// (provider side). It is populated for exported toolsets and propagated to
	// Used toolsets that consume the same provider so consumer agents can
	// reference provider agent-as-tool registrations.
	AgentToolsImportPath string
	// Tools lists the tools defined inside the toolset.
	Tools []*ToolData
	// MCP describes the external MCP helper metadata when this toolset references
	// an MCP server/toolset.
	MCP *MCPToolsetMeta
	// Registry describes the registry metadata when this toolset is sourced
	// from a registry via FromRegistry provider.
	Registry *RegistryToolsetMeta
	// NeedsAdapter indicates whether any method-backed tool in this toolset
	// requires an adapter for payload or result mapping (i.e., the tool
	// payload/result do not alias the bound method types). When false, the
	// generated service toolset can bypass adapters entirely.
	NeedsAdapter bool
	// IsRegistryBacked indicates whether this toolset is sourced from a
	// registry. When true, tool schemas are resolved at runtime via the
	// registry client rather than being generated at compile time.
	IsRegistryBacked bool
}

type ToolsetKind string

type WorkflowArtifact struct {
	// FuncName is the Go function name implementing the workflow handler.
	FuncName string
	// DefinitionVar is the exported variable name holding the workflow definition.
	DefinitionVar string
	// Name is the logical workflow identifier registered with the engine.
	Name string
	// Queue is the default workflow task queue.
	Queue string
}