agent

type ActionEvent struct {
	Index     int            `json:"index"` // 1-based action counter
	Source    string         `json:"source"`
	Tool      string         `json:"tool"`
	Args      map[string]any `json:"args,omitempty"`
	Status    string         `json:"status"`
	Summary   map[string]any `json:"summary,omitempty"`
	Error     string         `json:"error,omitempty"`
	ElapsedMS int64          `json:"elapsed_ms"`
}

type Agent struct {
	// contains filtered or unexported fields
}

type CapabilityProfile struct {
	RoleClass             string   `json:"role_class,omitempty"`
	Authenticated         bool     `json:"authenticated"`
	Mode                  string   `json:"mode,omitempty"`
	CatalogRevision       string   `json:"catalog_revision,omitempty"`
	AvailableTools        []string `json:"available_tools,omitempty"`
	AvailableSystemRoots  []string `json:"available_system_roots,omitempty"`
	BlockedSystemRoots    []string `json:"blocked_system_roots,omitempty"`
	RecommendedEntrypoint string   `json:"recommended_entrypoint,omitempty"`
	SafetyNotes           []string `json:"safety_notes,omitempty"`
}

type CatalogSearchFeatures struct {
	SemanticRecall bool
	CoverageBatch  bool
}

type ClientFactory func(Config) (ax.AIClient, error)

type Config struct {
	Enabled        bool   `` /* 177-byte string literal not displayed */
	Provider       string `mapstructure:"provider" jsonschema:"title=Agent Provider,default=openai"`
	Model          string `mapstructure:"model" jsonschema:"title=Agent Model"`
	APIKeyEnv      string `mapstructure:"api_key_env" jsonschema:"title=Agent API Key Environment Variable,default=OPENAI_API_KEY"`
	BaseURL        string `mapstructure:"base_url" jsonschema:"title=Agent Provider Base URL"`
	MaxSteps       int    `mapstructure:"max_steps" jsonschema:"title=Agent Max Steps,default=8"`
	TimeoutSeconds int    `mapstructure:"timeout_seconds" jsonschema:"title=Agent Timeout Seconds,default=50"`
	ReadOnly       bool   `mapstructure:"read_only" jsonschema:"title=Force Agent Read-Only,default=false"`
	ReturnTrace    bool   `mapstructure:"return_trace" jsonschema:"title=Return Agent Trace,default=false"`
	// SeedLimit caps the initial query_catalog(search: instruction) seed rows.
	SeedLimit int `mapstructure:"seed_limit" jsonschema:"title=Agent Seed Catalog Limit,default=40"`
	// CatalogDefaultLimit is the default row limit for model-issued catalog queries.
	CatalogDefaultLimit int `mapstructure:"catalog_default_limit" jsonschema:"title=Agent Catalog Default Limit,default=20"`
}

type ErrorInfo struct {
	Message    string         `json:"message"`
	Extensions map[string]any `json:"extensions,omitempty"`
}

type GraphRuntime interface {
	GraphQLHelp(context.Context, map[string]any) (any, error)
	QueryCatalog(context.Context, map[string]any) (any, error)
	ValidateWhereClause(context.Context, map[string]any) (any, error)
	ExecuteSavedQuery(context.Context, map[string]any) (any, error)
	ExecuteGraphQL(context.Context, map[string]any) (any, error)
}

type Option func(*Agent)

type Program interface {
	Forward(context.Context, ax.AIClient, map[string]ax.Value, map[string]ax.Value) (ax.Value, error)
	GetActionLog() ax.Value
	GetUsage() ax.Value
	GetChatLog() ax.Value
	ExportTrace() ax.Value
}

type ProgramFactory func(string, map[string]ax.Value) Program

type Refusal struct {
	Code              string        `json:"code"`
	BlockedAction     string        `json:"blocked_action,omitempty"`
	Because           []string      `json:"because,omitempty"`
	Unblock           []UnblockStep `json:"unblock,omitempty"`
	LawfulAlternative string        `json:"lawful_alternative,omitempty"`
	PolicyFinal       bool          `json:"policy_final,omitempty"`
	Retryable         bool          `json:"retryable,omitempty"`
}

type Request struct {
	Instruction string         `json:"instruction"`
	Context     map[string]any `json:"context,omitempty"`
	Namespace   string         `json:"namespace,omitempty"`
	// TaskID is an owner-scoped correlation label used by the service to load
	// declared task context and append a run trail. Like History, it never
	// satisfies a protocol evidence guard and never grants access.
	TaskID      string `json:"task_id,omitempty"`
	MaxSteps    int    `json:"max_steps,omitempty"`
	ReturnTrace *bool  `json:"return_trace,omitempty"`

	// History carries prior conversation turns for follow-up resolution. It is
	// untrusted model context: it reaches the model only as an ax context field
	// (available to runtime code as inputs.history) and never satisfies a
	// protocol guard — every run must re-establish its own tool evidence.
	History []Turn `json:"history,omitempty"`

	// Capabilities is the caller's role/visibility profile. It is intentionally
	// json:"-" so it can never be supplied or spoofed from the REST body or MCP
	// arguments; the service populates it after unmarshalling the wire request.
	// It is read-only policy input and is not forwarded into the LLM prompt.
	Capabilities *CapabilityProfile `json:"-"`

	// Observer receives one ActionEvent per executed tool action (progress
	// streaming). Server-populated only; never part of the wire request.
	Observer func(ActionEvent) `json:"-"`
}

type Response struct {
	Status   string           `json:"status"`
	Answer   string           `json:"answer,omitempty"`
	Skills   []SkillUsage     `json:"skills,omitempty"`
	Skill    string           `json:"skill,omitempty"` // Deprecated through v3.
	Data     any              `json:"data,omitempty"`
	Evidence any              `json:"evidence,omitempty"`
	Actions  any              `json:"actions,omitempty"`
	Next     any              `json:"next,omitempty"`
	Refusal  *Refusal         `json:"refusal,omitempty"`
	Notices  []ResponseNotice `json:"notices,omitempty"`
	Errors   []ErrorInfo      `json:"errors,omitempty"`
	Usage    any              `json:"usage,omitempty"`
	Trace    any              `json:"trace,omitempty"`
	TraceID  string           `json:"trace_id,omitempty"`
}

type ResponseNotice struct {
	Kind          string   `json:"kind"`
	Message       string   `json:"message"`
	Count         int      `json:"count,omitempty"`
	Since         string   `json:"since,omitempty"`
	WatchIDs      []string `json:"watch_ids,omitempty"`
	TaskIDs       []string `json:"task_ids,omitempty"`
	AnnotationIDs []string `json:"annotation_ids,omitempty"`
}

type SkillUsage struct {
	ID     string `json:"id"`
	Name   string `json:"name,omitempty"`
	Reason string `json:"reason,omitempty"`
	Stage  string `json:"stage,omitempty"`
}

type TruncationInfo struct {
	Roots   []core.TruncatedRootInfo `json:"roots"`
	Message string                   `json:"message"`
}

type Turn struct {
	Role    string `json:"role"`             // "user" or "assistant"
	Content string `json:"content"`          // user instruction or assistant answer
	Status  string `json:"status,omitempty"` // assistant turns: answered/blocked/needs_clarification
	// CatalogIDs are detail ids the prior run inspected — advisory warm-start
	// hints for this run's own discovery, never evidence.
	CatalogIDs []string `json:"catalog_ids,omitempty"`
}

type UnblockStep struct {
	Tool   string         `json:"tool"`
	Args   map[string]any `json:"args,omitempty"`
	Reason string         `json:"reason,omitempty"`
}