api

type A2AConversationResponse struct {
	Conversation *a2a.Conversation `json:"conversation"`
	Messages     []*a2a.Envelope   `json:"messages"`
}

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

type ActionReq struct {
	Type   string `json:"type"`
	Target string `json:"target,omitempty"`
	Value  any    `json:"value,omitempty"`
}

type AgentInboxRequest struct {
	Name           string `path:"name" description:"Agent name"`
	ConversationID string `query:"conversation_id" description:"Only messages on this conversation"`
	IncludeRead    bool   `query:"include_read" description:"Include messages already read (default: unread only)"`
	Limit          int    `query:"limit" description:"Max results (default: 50)"`
}

type AgentInboxResponse struct {
	Items []a2a.InboxItem `json:"items"`
}

type AgentOverrides struct {
	Model           string   `json:"model,omitempty" description:"Override LLM model"`
	Temperature     *float64 `json:"temperature,omitempty" description:"Override temperature"`
	MaxSteps        int      `json:"max_steps,omitempty" description:"Override max steps"`
	MaxTokens       int      `json:"max_tokens,omitempty" description:"Override max tokens"`
	ReasoningLoop   string   `json:"reasoning_loop,omitempty" description:"Override reasoning loop"`
	SystemPrompt    string   `json:"system_prompt,omitempty" description:"Override system prompt"`
	PersonaRef      string   `json:"persona_ref,omitempty" description:"Override persona reference"`
	InlineSkills    []string `json:"inline_skills,omitempty" description:"Override inline skills"`
	InlineTraits    []string `json:"inline_traits,omitempty" description:"Override inline traits"`
	InlineBehaviors []string `json:"inline_behaviors,omitempty" description:"Override inline behaviors"`
	Tools           []string `json:"tools,omitempty" description:"Override tool list"`
}

type Authorizer interface {
	// Authorize is asked before every route runs, with the request's
	// context. It sees the operation and the context only, not the path
	// parameters or the body, which are bound after it; a rule about one
	// resource belongs in the host's own lookups. A nil error lets the
	// request through. Any other error
	// refuses it with 403, unless it wraps a cortex not-found or scope
	// error, which keeps the status that error has everywhere else in
	// the module. The error's text never reaches the response.
	Authorize(ctx context.Context, op Operation) error
	// DecidedBy is the name resolveCheckpoint records as the deciding
	// person, derived from the request's principal. It replaces any
	// decided_by the request body names. sendAgentMessage's from is not
	// derived: it stays the caller's own name for the sender, used for
	// attribution, while the reply token gates what a reply can resume.
	DecidedBy(ctx context.Context) (string, error)
}

type CancelRunRequest struct {
	RunID string `path:"id" description:"Run ID"`
}

type CheckpointResponse struct {
	cortex.Entity
	ID        id.CheckpointID   `json:"id"`
	RunID     id.AgentRunID     `json:"run_id"`
	AgentID   id.AgentID        `json:"agent_id"`
	Scope     cortex.Scope      `json:"scope"`
	Reason    string            `json:"reason"`
	StepIndex int               `json:"step_index"`
	State     string            `json:"state"`
	Decision  *DecisionResponse `json:"decision,omitempty"`
	Metadata  map[string]any    `json:"metadata,omitempty"`
}

type ClearConversationRequest struct {
	Name      string `path:"name" description:"Agent name"`
	SessionID string `query:"session_id" description:"Session ID; defaults to the agent's default session for the caller's scope"`
}

type CloneAgentRequest struct {
	Name    string `path:"name" description:"Source agent name"`
	NewName string `json:"new_name,omitempty" description:"Name for the clone; auto-generated if omitted"`
}

type ClonePersonaRequest struct {
	Name    string `path:"name" description:"Source persona name"`
	NewName string `json:"new_name,omitempty" description:"Name for the clone; auto-generated if omitted"`
}

type CountSessionsRequest struct {
	Name string `path:"name" description:"Agent name"`
}

type CountSessionsResponse struct {
	Count int64 `json:"count"`
}

type CreateAgentRequest struct {
	Name            string         `json:"name" description:"Unique agent name"`
	Description     string         `json:"description,omitempty"`
	SystemPrompt    string         `json:"system_prompt" description:"Agent system prompt"`
	Model           string         `json:"model,omitempty" description:"LLM model (default: smart)"`
	Tools           []string       `json:"tools,omitempty" description:"Tool names (flat mode)"`
	MaxSteps        int            `json:"max_steps,omitempty"`
	MaxTokens       int            `json:"max_tokens,omitempty"`
	Temperature     float64        `json:"temperature,omitempty"`
	ReasoningLoop   string         `json:"reasoning_loop,omitempty"`
	PersonaRef      string         `json:"persona_ref,omitempty" description:"Persona name reference"`
	InlineSkills    []string       `json:"inline_skills,omitempty"`
	InlineTraits    []string       `json:"inline_traits,omitempty"`
	InlineBehaviors []string       `json:"inline_behaviors,omitempty"`
	Guardrails      map[string]any `json:"guardrails,omitempty"`
	Metadata        map[string]any `json:"metadata,omitempty"`
}

type CreateBehaviorRequest struct {
	Name          string         `json:"name" description:"Unique behavior name"`
	Description   string         `json:"description,omitempty"`
	Triggers      []TriggerReq   `json:"triggers,omitempty"`
	Actions       []ActionReq    `json:"actions,omitempty"`
	Priority      int            `json:"priority,omitempty"`
	RequiresSkill string         `json:"requires_skill,omitempty"`
	RequiresTrait string         `json:"requires_trait,omitempty"`
	Metadata      map[string]any `json:"metadata,omitempty"`
}

type CreateOrchestrationRequest struct {
	Name         string                      `json:"name" description:"Unique orchestration name"`
	Description  string                      `json:"description,omitempty"`
	Strategy     string                      `json:"strategy" description:"sequential|parallel|router|hierarchical|debate"`
	Participants []orchestration.Participant `json:"participants" description:"Agents taking part, with optional roles"`
	Settings     orchestration.Settings      `json:"settings,omitempty"`
	Metadata     map[string]any              `json:"metadata,omitempty"`
}

type CreatePersonaRequest struct {
	Name               string               `json:"name" description:"Unique persona name"`
	Description        string               `json:"description,omitempty"`
	Identity           string               `json:"identity" description:"Self-description for system prompt"`
	Skills             []SkillAssignmentReq `json:"skills,omitempty"`
	Traits             []TraitAssignmentReq `json:"traits,omitempty"`
	Behaviors          []string             `json:"behaviors,omitempty"`
	CognitiveStyle     map[string]any       `json:"cognitive_style,omitempty"`
	CommunicationStyle map[string]any       `json:"communication_style,omitempty"`
	Perception         map[string]any       `json:"perception,omitempty"`
	Metadata           map[string]any       `json:"metadata,omitempty"`
}

type CreateSessionRequest struct {
	Name     string         `path:"name" description:"Agent name"`
	Title    string         `json:"title,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type CreateSkillRequest struct {
	Name                 string            `json:"name" description:"Unique skill name"`
	Description          string            `json:"description,omitempty"`
	Tools                []ToolBindingReq  `json:"tools,omitempty" description:"Tool bindings with mastery"`
	Knowledge            []KnowledgeRefReq `json:"knowledge,omitempty" description:"Knowledge sources"`
	SystemPromptFragment string            `json:"system_prompt_fragment,omitempty"`
	Dependencies         []string          `json:"dependencies,omitempty"`
	DefaultProficiency   string            `json:"default_proficiency,omitempty"`
	Metadata             map[string]any    `json:"metadata,omitempty"`
}

type CreateTraitRequest struct {
	Name        string         `json:"name" description:"Unique trait name"`
	Description string         `json:"description,omitempty"`
	Dimensions  []DimensionReq `json:"dimensions,omitempty"`
	Influences  []InfluenceReq `json:"influences,omitempty"`
	Category    string         `json:"category,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

type DecisionResponse struct {
	Approved  bool      `json:"approved"`
	DecidedBy string    `json:"decided_by,omitempty"`
	Reason    string    `json:"reason,omitempty"`
	DecidedAt time.Time `json:"decided_at"`
}

type DeleteAgentRequest struct {
	Name string `path:"name" description:"Agent name"`
}

type DeleteBehaviorRequest struct {
	Name string `path:"name" description:"Behavior name"`
}

type DeleteOrchestrationRequest struct {
	Name string `path:"name" description:"Orchestration name"`
}

type DeletePersonaRequest struct {
	Name string `path:"name" description:"Persona name"`
}

type DeleteSessionRequest struct {
	Name      string `path:"name" description:"Agent name"`
	SessionID string `path:"id" description:"Session ID"`
}

type DeleteSkillRequest struct {
	Name string `path:"name" description:"Skill name"`
}

type DeleteTraitRequest struct {
	Name string `path:"name" description:"Trait name"`
}

type DimensionReq struct {
	Name      string  `json:"name"`
	LowLabel  string  `json:"low_label"`
	HighLabel string  `json:"high_label"`
	Value     float64 `json:"value"`
}

type GetA2AConversationRequest struct {
	ID string `path:"id" description:"Conversation ID"`
}

type GetAgentRequest struct {
	Name string `path:"name" description:"Agent name"`
}

type GetBehaviorRequest struct {
	Name string `path:"name" description:"Behavior name"`
}

type GetConversationRequest struct {
	Name      string `path:"name" description:"Agent name"`
	Limit     int    `query:"limit"`
	SessionID string `query:"session_id" description:"Session ID; defaults to the agent's default session for the caller's scope"`
}

type GetConversationResponse struct {
	Messages []memory.Message `json:"messages"`
}

type GetOrchestrationRequest struct {
	Name string `path:"name" description:"Orchestration name"`
}

type GetOrchestrationRunRequest struct {
	ID string `path:"id" description:"Orchestration run ID"`
}

type GetPersonaRequest struct {
	Name string `path:"name" description:"Persona name"`
}

type GetRunRequest struct {
	RunID string `path:"id" description:"Run ID"`
}

type GetSessionRequest struct {
	Name      string `path:"name" description:"Agent name"`
	SessionID string `path:"id" description:"Session ID"`
}

type GetSkillRequest struct {
	Name string `path:"name" description:"Skill name"`
}

type GetToolSchemaRequest struct {
	Name string `path:"name" description:"Tool name"`
}

type GetTraitRequest struct {
	Name string `path:"name" description:"Trait name"`
}

type InfluenceReq struct {
	Target    string  `json:"target"`
	Value     any     `json:"value"`
	Condition string  `json:"condition,omitempty"`
	Weight    float64 `json:"weight,omitempty"`
}

type KnowledgeRefReq struct {
	Source     string `json:"source"`
	InjectMode string `json:"inject_mode,omitempty"`
	Priority   int    `json:"priority,omitempty"`
}

type ListA2AConversationsRequest struct {
	Status string `query:"status" description:"Filter by status: open|closed|expired"`
	Limit  int    `query:"limit" description:"Max results (default: 50)"`
	Offset int    `query:"offset" description:"Results to skip"`
}

type ListA2AConversationsResponse struct {
	Items []*a2a.Conversation `json:"items"`
}

type ListAgentsRequest struct {
	Limit  int `query:"limit" description:"Max results (default: 50)"`
	Offset int `query:"offset" description:"Results to skip"`
}

type ListAgentsResponse struct {
	Items []*agent.Config `json:"items"`
}

type ListBehaviorsRequest struct {
	Limit  int `query:"limit"`
	Offset int `query:"offset"`
}

type ListBehaviorsResponse struct {
	Items []*behavior.Behavior `json:"items"`
}

type ListCheckpointsRequest struct {
	Limit  int `query:"limit"`
	Offset int `query:"offset"`
}

type ListCheckpointsResponse struct {
	Items []*CheckpointResponse `json:"items"`
}

type ListOrchestrationRunsRequest struct {
	Status string `query:"status" description:"Filter by status: running|waiting|completed|failed"`
	Limit  int    `query:"limit"`
	Offset int    `query:"offset"`
}

type ListOrchestrationRunsResponse struct {
	Items []*orchestration.Run `json:"items"`
}

type ListOrchestrationsRequest struct {
	Limit  int `query:"limit" description:"Max results (default: 50)"`
	Offset int `query:"offset" description:"Results to skip"`
}

type ListOrchestrationsResponse struct {
	Items []*orchestration.Config `json:"items"`
}

type ListPersonasRequest struct {
	Limit  int `query:"limit"`
	Offset int `query:"offset"`
}

type ListPersonasResponse struct {
	Items []*persona.Persona `json:"items"`
}

type ListRunsRequest struct {
	Limit  int `query:"limit"`
	Offset int `query:"offset"`
}

type ListRunsResponse struct {
	Items []*run.Run `json:"items"`
}

type ListSessionsRequest struct {
	Name   string `path:"name" description:"Agent name"`
	Limit  int    `query:"limit"`
	Offset int    `query:"offset"`
}

type ListSessionsResponse struct {
	Items []*session.Session `json:"items"`
}

type ListSkillsRequest struct {
	Limit  int `query:"limit"`
	Offset int `query:"offset"`
}

type ListSkillsResponse struct {
	Items []*skill.Skill `json:"items"`
}

type ListToolsRequest struct{}

type ListToolsResponse struct {
	Items []ToolResponse `json:"items"`
}

type ListTraitsRequest struct {
	Limit    int    `query:"limit"`
	Offset   int    `query:"offset"`
	Category string `query:"category" description:"Filter by category"`
}

type ListTraitsResponse struct {
	Items []*trait.Trait `json:"items"`
}

type Operation struct {
	// ID is the route's OpenAPI operation id, such as "resolveCheckpoint".
	ID string
	// Write is true when the route's method is not GET or HEAD.
	Write bool
}

type Option func(*API)

type PlanningDetailRequest struct {
	ID string `path:"id"`
}

type PlanningListRequest struct {
	After string `query:"after" optional:"true"`
	Limit int    `query:"limit" optional:"true"`
}

type PreviewPromptRequest struct {
	Name string `path:"name" description:"Agent name"`
}

type PreviewPromptResponse struct {
	Prompt string `json:"prompt"`
}

type ReplayRunRequest struct {
	RunID string `path:"id" description:"Run ID"`
	After string `query:"after" optional:"true" description:"Opaque cursor from the previous replay page"`
	Limit int    `query:"limit" optional:"true" description:"Page size from 1 to 128; zero uses 128"`
}

type ReplayStreamRequest struct {
	ReplayRunRequest
	LastEventID string `header:"Last-Event-ID" optional:"true" description:"Resume cursor from the last complete SSE page"`
}

type ResolveCheckpointRequest struct {
	CheckpointID string `path:"id" description:"Checkpoint ID"`
	Decision     string `json:"decision" description:"approved or rejected"`
	// DecidedBy is the deciding person as the caller asserts it. With an
	// Authorizer installed it is ignored and the decider comes from
	// Authorizer.DecidedBy; without one it is recorded as sent.
	DecidedBy string `json:"decided_by,omitempty" description:"Deciding person; ignored when the host installs an authorizer"`
	// Reason is what a rejection puts on the failed run, so whoever finds
	// the run later reads why a person stopped it rather than a bare
	// "rejected".
	Reason string `json:"reason,omitempty" description:"Why the decision was made; recorded on the run when rejecting"`
}

type ResultContentRequest struct {
	RunID    string `path:"id" description:"Run ID"`
	ResultID string `path:"result_id" description:"Committed result ID"`
}

type RunAgentRequest struct {
	Name      string          `path:"name" description:"Agent name"`
	Input     string          `json:"input" description:"User input"`
	Overrides *AgentOverrides `json:"overrides,omitempty" description:"Configuration overrides"`
}

type RunAgentResponse struct {
	StopReason         string `json:"stop_reason,omitempty"`
	VerificationStatus string `json:"verification_status"`
	PublicationStatus  string `json:"publication_status"`
	ResultRef          string `json:"result_ref,omitempty"`
	RunID              string `json:"run_id"`
	Output             string `json:"output"`
	State              string `json:"state"`
	StepCount          int    `json:"step_count"`
	TokensUsed         int    `json:"tokens_used"`
	DurationMs         int64  `json:"duration_ms"`
}

type RunOrchestrationRequest struct {
	Name  string `path:"name" description:"Orchestration name"`
	Input string `json:"input" description:"Initial input for the orchestration"`
}

type RunOrchestrationResponse struct {
	RunID      string `json:"run_id"`
	Status     string `json:"status"`
	Strategy   string `json:"strategy"`
	Output     string `json:"output"`
	DurationMs int64  `json:"duration_ms"`
}

type SendMessageRequest struct {
	Name           string `path:"name" description:"Recipient agent name"`
	From           string `` /* 139-byte string literal not displayed */
	Content        string `json:"content" description:"The message body"`
	Performative   string `json:"performative,omitempty" description:"FIPA-ACL speech act (default: inform)"`
	ConversationID string `json:"conversation_id,omitempty" description:"Continue an existing conversation"`
	InReplyTo      string `json:"in_reply_to,omitempty" description:"Reply-with token of the ask this answers"`
	Ontology       string `json:"ontology,omitempty" description:"Optional subject-matter label"`
}

type SkillAssignmentReq struct {
	SkillName   string `json:"skill_name"`
	Proficiency string `json:"proficiency,omitempty"`
}

type StreamAgentRequest struct {
	Name      string          `path:"name" description:"Agent name"`
	Input     string          `json:"input" description:"User input"`
	Overrides *AgentOverrides `json:"overrides,omitempty" description:"Configuration overrides"`
}

type StreamEvent struct {
	Event string `json:"event"`
	Data  any    `json:"data"`
}

type ToolBindingReq struct {
	ToolName   string `json:"tool_name"`
	Mastery    string `json:"mastery,omitempty"`
	Guidance   string `json:"guidance,omitempty"`
	PreferWhen string `json:"prefer_when,omitempty"`
}

type ToolResponse struct {
	Name        string `json:"name"`
	Description string `json:"description"`
	// Kind is where the tool comes from: builtin, registered or external.
	Kind string `json:"kind" description:"builtin, registered or external"`
	// RetrySafe is whether the tool may run again after a crash.
	RetrySafe bool `json:"retry_safe"`
}

type TraitAssignmentReq struct {
	TraitName       string             `json:"trait_name"`
	DimensionValues map[string]float64 `json:"dimension_values,omitempty"`
}

type TriggerReq struct {
	Type    string `json:"type"`
	Pattern string `json:"pattern,omitempty"`
}

type UpdateAgentRequest struct {
	Name            string         `path:"name" description:"Agent name"`
	Description     string         `json:"description,omitempty"`
	SystemPrompt    string         `json:"system_prompt,omitempty"`
	Model           string         `json:"model,omitempty"`
	Tools           []string       `json:"tools,omitempty"`
	MaxSteps        int            `json:"max_steps,omitempty"`
	MaxTokens       int            `json:"max_tokens,omitempty"`
	Temperature     float64        `json:"temperature,omitempty"`
	ReasoningLoop   string         `json:"reasoning_loop,omitempty"`
	PersonaRef      string         `json:"persona_ref,omitempty"`
	InlineSkills    []string       `json:"inline_skills,omitempty"`
	InlineTraits    []string       `json:"inline_traits,omitempty"`
	InlineBehaviors []string       `json:"inline_behaviors,omitempty"`
	Guardrails      map[string]any `json:"guardrails,omitempty"`
	Metadata        map[string]any `json:"metadata,omitempty"`
}

type UpdateBehaviorRequest struct {
	Name          string         `path:"name" description:"Behavior name"`
	Description   string         `json:"description,omitempty"`
	Triggers      []TriggerReq   `json:"triggers,omitempty"`
	Actions       []ActionReq    `json:"actions,omitempty"`
	Priority      int            `json:"priority,omitempty"`
	RequiresSkill string         `json:"requires_skill,omitempty"`
	RequiresTrait string         `json:"requires_trait,omitempty"`
	Metadata      map[string]any `json:"metadata,omitempty"`
}

type UpdateConfigRequest struct {
	DefaultModel         string  `json:"default_model,omitempty"`
	DefaultMaxSteps      int     `json:"default_max_steps,omitempty"`
	DefaultMaxTokens     int     `json:"default_max_tokens,omitempty"`
	DefaultTemperature   float64 `json:"default_temperature,omitempty"`
	DefaultReasoningLoop string  `json:"default_reasoning_loop,omitempty"`
}

type UpdateOrchestrationRequest struct {
	Name         string                      `path:"name" description:"Orchestration name"`
	Description  string                      `json:"description,omitempty"`
	Strategy     string                      `json:"strategy,omitempty"`
	Participants []orchestration.Participant `json:"participants,omitempty"`
	Settings     *orchestration.Settings     `json:"settings,omitempty"`
	Metadata     map[string]any              `json:"metadata,omitempty"`
}

type UpdatePersonaRequest struct {
	Name               string               `path:"name" description:"Persona name"`
	Description        string               `json:"description,omitempty"`
	Identity           string               `json:"identity,omitempty"`
	Skills             []SkillAssignmentReq `json:"skills,omitempty"`
	Traits             []TraitAssignmentReq `json:"traits,omitempty"`
	Behaviors          []string             `json:"behaviors,omitempty"`
	CognitiveStyle     map[string]any       `json:"cognitive_style,omitempty"`
	CommunicationStyle map[string]any       `json:"communication_style,omitempty"`
	Perception         map[string]any       `json:"perception,omitempty"`
	Metadata           map[string]any       `json:"metadata,omitempty"`
}

type UpdateSessionRequest struct {
	Name      string         `path:"name" description:"Agent name"`
	SessionID string         `path:"id" description:"Session ID"`
	Title     string         `json:"title,omitempty"`
	Metadata  map[string]any `json:"metadata,omitempty"`
}

type UpdateSkillRequest struct {
	Name                 string            `path:"name" description:"Skill name"`
	Description          string            `json:"description,omitempty"`
	Tools                []ToolBindingReq  `json:"tools,omitempty"`
	Knowledge            []KnowledgeRefReq `json:"knowledge,omitempty"`
	SystemPromptFragment string            `json:"system_prompt_fragment,omitempty"`
	Dependencies         []string          `json:"dependencies,omitempty"`
	DefaultProficiency   string            `json:"default_proficiency,omitempty"`
	Metadata             map[string]any    `json:"metadata,omitempty"`
}

type UpdateTraitRequest struct {
	Name        string         `path:"name" description:"Trait name"`
	Description string         `json:"description,omitempty"`
	Dimensions  []DimensionReq `json:"dimensions,omitempty"`
	Influences  []InfluenceReq `json:"influences,omitempty"`
	Category    string         `json:"category,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

type VerificationFailureResponse struct {
	Error   string                   `json:"error"`
	Code    int                      `json:"code"`
	Details *run.VerificationFailure `json:"details,omitempty"`
}