agent

type AgentQuestion struct {
	ID          string           `json:"id"`
	Question    string           `json:"question"`
	Detail      string           `json:"detail,omitempty"`
	Header      string           `json:"header"` // short tab label (max 12 chars)
	Type        string           `json:"type,omitempty"`
	Options     []QuestionOption `json:"options,omitempty"`
	MultiSelect bool             `json:"multi_select,omitempty"` // true = checkboxes, false = radio
	Required    bool             `json:"required,omitempty"`
}

type CapabilityInfo struct {
	Name             string         `json:"name"`
	Kind             CapabilityKind `json:"kind"`
	RiskLevel        string         `json:"risk_level"`
	DeterminismScore float64        `json:"determinism_score"`
	Idempotent       bool           `json:"idempotent"`
	LatencyProfile   string         `json:"latency_profile,omitempty"`
	CostProfile      string         `json:"cost_profile,omitempty"`
}

type CapabilityKind string

type CreateTaskRequest struct {
	Goal           string `json:"goal"`
	ConversationID string `json:"conversation_id,omitempty"`
	Context        string `json:"context,omitempty"` // recent conversation context for the agent
}

type CriterionResult struct {
	Criterion string `json:"criterion"`
	Status    string `json:"status"`
	Evidence  string `json:"evidence,omitempty"`
}

type GroundTruthState struct {
	Files    map[string]GroundedFileFact    `json:"files,omitempty"`
	Commands map[string]GroundedCommandFact `json:"commands,omitempty"`
	Calls    map[string]GroundedToolCall    `json:"calls,omitempty"`
	Results  map[string]GroundedToolResult  `json:"results,omitempty"`
}

type GroundTruthStateStore struct{}

type GroundedCommandFact struct {
	ToolCallID string    `json:"tool_call_id"`
	Tool       string    `json:"tool"`
	Command    string    `json:"command,omitempty"`
	ArgsHash   string    `json:"args_hash,omitempty"`
	ExitCode   int       `json:"exit_code"`
	OutputHash string    `json:"output_hash,omitempty"`
	ObservedAt time.Time `json:"observed_at"`
}

type GroundedExecution struct {
	Call    GroundedToolCall   `json:"call"`
	Result  GroundedToolResult `json:"result"`
	Updates []StateUpdate      `json:"updates,omitempty"`
}

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

type GroundedFileFact struct {
	Path           string    `json:"path"`
	Exists         bool      `json:"exists"`
	Size           int64     `json:"size,omitempty"`
	ContentSHA256  string    `json:"content_sha256,omitempty"`
	LastObservedBy string    `json:"last_observed_by,omitempty"`
	LastMutatedBy  string    `json:"last_mutated_by,omitempty"`
	ObservedAt     time.Time `json:"observed_at,omitempty"`
}

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

type GroundedResponse struct {
	Summary string          `json:"summary"`
	Claims  []ResponseClaim `json:"claims"`
}

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

type GroundedRuntimeConfig struct {
	PlannerLLM        LLMCaller
	ResponderLLM      LLMCaller
	Registry          *tools.Registry
	Executor          *tools.Executor
	Store             *Store
	StateStore        *GroundTruthStateStore
	Planner           *GroundedPlanner
	GroundedExecutor  *GroundedExecutor
	Verifier          *GroundedVerifier
	AskHandler        func(ctx context.Context, task *Task, argsJSON string) string
	ConfirmToolCall   func(ctx context.Context, task *Task, step PlanStep, nextTool PlannerToolCall) error
	KnowledgeResolver LoopKnowledgeResolver
	KnowledgeTrace    func(task *Task, trace loopKnowledgeTrace)
	Secret            []byte
	MaxPlannerRounds  int
}

type GroundedStepResult struct {
	Output             string
	VerifiedOutput     string
	GroundingStatus    string
	VerificationErrors []string
}

type GroundedToolCall struct {
	ToolCallID   string         `json:"tool_call_id"`
	TaskID       string         `json:"task_id"`
	StepIndex    int            `json:"step_index"`
	PlannerRound int            `json:"planner_round"`
	Tool         string         `json:"tool"`
	Args         map[string]any `json:"args"`
	CreatedAt    time.Time      `json:"created_at"`
}

type GroundedToolResult struct {
	ToolCallID string    `json:"tool_call_id"`
	Tool       string    `json:"tool"`
	ExitCode   int       `json:"exit_code"`
	OK         bool      `json:"ok"`
	Result     any       `json:"result,omitempty"`
	Stderr     string    `json:"stderr,omitempty"`
	AuthTag    string    `json:"auth_tag"`
	StartedAt  time.Time `json:"started_at"`
	FinishedAt time.Time `json:"finished_at"`
}

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

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

type LLMCaller interface {
	Chat(ctx context.Context, req llm.ChatRequest) (*llm.ChatResponse, error)
}

type LoopKnowledgeResolver interface {
	ResolveLoopContext(ctx context.Context, req knowledge.LoopContextRequest) (*knowledge.LoopContextResult, error)
}

type MemoryRecaller interface {
	Recall(ctx context.Context, query string, limit int) ([]MemoryResult, error)
}

type MemoryResult struct {
	Content  string
	Score    float32
	Metadata map[string]string
}

type PlanStep struct {
	Index       int        `json:"index"`
	Description string     `json:"description"`
	Status      StepStatus `json:"status"`
	Output      string     `json:"output,omitempty"`
	StartedAt   *time.Time `json:"started_at,omitempty"`
	CompletedAt *time.Time `json:"completed_at,omitempty"`
}

type PlannerAssertion struct {
	Type string `json:"type"`
	Path string `json:"path,omitempty"`
	Tool string `json:"tool,omitempty"`
}

type PlannerDecision struct {
	Status     PlannerDecisionStatus `json:"status"`
	Reason     string                `json:"reason"`
	NextTool   *PlannerToolCall      `json:"next_tool,omitempty"`
	Assertions []PlannerAssertion    `json:"assertions,omitempty"`
}

type PlannerDecisionStatus string

type PlannerInput struct {
	Model              string
	Goal               string
	PlanSummary        string
	Step               PlanStep
	PlannerRound       int
	MaxRounds          int
	GroundState        *GroundTruthState
	ToolCatalog        []llm.Tool
	PriorToolCallIDs   []string
	PreviousViolations []string
	KnowledgeContext   string
	RoutingContract    string
	CoordinationCtx    string
}

type PlannerToolCall struct {
	Tool string         `json:"tool"`
	Args map[string]any `json:"args"`
}

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

type QuestionAnswer struct {
	QuestionID string   `json:"question_id"`
	Values     []string `json:"values"` // selected option values or free text
	OtherText  string   `json:"other_text,omitempty"`
}

type QuestionOption struct {
	Label       string `json:"label"`
	Description string `json:"description,omitempty"`
	Value       string `json:"value"`
}

type ResponderInput struct {
	Model              string
	Goal               string
	Step               PlanStep
	GroundState        *GroundTruthState
	PriorToolCallIDs   []string
	PreviousViolations []string
}

type ResponseClaim struct {
	Type        ResponseClaimType `json:"type"`
	Text        string            `json:"text,omitempty"`
	ToolCallIDs []string          `json:"tool_call_ids,omitempty"`
	Path        string            `json:"path,omitempty"`
	Value       string            `json:"value,omitempty"`
	Excerpt     string            `json:"excerpt,omitempty"`
}

type ResponseClaimType string

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

type RunnerConfig struct {
	MaxConcurrent int
	TaskTimeout   time.Duration
	AskTimeout    time.Duration
	AutoReflect   bool
	// AskTimeoutAction controls timeout behavior: "error" (default) | "default".
	AskTimeoutAction string
	// MaxToolRoundsPerStep controls tool loop budget per plan step.
	MaxToolRoundsPerStep int
}

type RuntimeAuditEvent struct {
	Timestamp  time.Time       `json:"timestamp"`
	From       RuntimeState    `json:"from,omitempty"`
	To         RuntimeState    `json:"to,omitempty"`
	Reason     string          `json:"reason,omitempty"`
	Capability *CapabilityInfo `json:"capability,omitempty"`
	Error      string          `json:"error,omitempty"`
}

type RuntimeEvent struct {
	ID           string    `json:"id"`
	TaskID       string    `json:"task_id"`
	StepIndex    int       `json:"step_index"`
	PlannerRound int       `json:"planner_round"`
	EventType    string    `json:"event_type"`
	PayloadJSON  string    `json:"payload_json"`
	CreatedAt    time.Time `json:"created_at"`
}

type RuntimeState string

type SelfReflector interface {
	Reflect(ctx context.Context, input selfreflect.Input) (*selfreflect.Result, error)
}

type StateUpdate struct {
	UpdateID      string         `json:"update_id"`
	ToolCallID    string         `json:"tool_call_id"`
	Kind          string         `json:"kind"`
	Path          string         `json:"path,omitempty"`
	Exists        bool           `json:"exists,omitempty"`
	Size          int64          `json:"size,omitempty"`
	ContentSHA256 string         `json:"content_sha256,omitempty"`
	ObservedAt    time.Time      `json:"observed_at"`
	Metadata      map[string]any `json:"metadata,omitempty"`
}

type StepStatus string

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

type Task struct {
	ID                 string                 `json:"id"`
	UserID             string                 `json:"user_id"`
	ConversationID     string                 `json:"conversation_id,omitempty"`
	Goal               string                 `json:"goal"`
	Plan               []PlanStep             `json:"plan,omitempty"`
	Status             TaskStatus             `json:"status"`
	RuntimeState       RuntimeState           `json:"runtime_state,omitempty"`
	RuntimeAudit       []RuntimeAuditEvent    `json:"runtime_audit,omitempty"`
	SuccessCriteria    []string               `json:"success_criteria,omitempty"`
	FallbackPlan       []string               `json:"fallback_plan,omitempty"`
	CurrentStep        int                    `json:"current_step"`
	Progress           int                    `json:"progress"` // 0-100
	Result             string                 `json:"result,omitempty"`
	VerifiedOutput     string                 `json:"verified_output,omitempty"`
	VerificationErrors []string               `json:"verification_errors,omitempty"`
	GroundingStatus    string                 `json:"grounding_status,omitempty"`
	Metadata           map[string]interface{} `json:"metadata,omitempty"`
	Error              string                 `json:"error,omitempty"`
	CreatedAt          time.Time              `json:"created_at"`
	UpdatedAt          time.Time              `json:"updated_at"`
	WorkspaceRoot      string                 `json:"-"`

	GroundState *GroundTruthState `json:"-"`
}

type TaskEvent struct {
	TaskID     string          `json:"task_id"`
	EventType  string          `json:"event_type"` // task_created, task_planning, task_progress, task_step_completed, task_reflection_started, task_reflection_completed, task_completed, task_failed, task_question
	StepIndex  int             `json:"step_index,omitempty"`
	Progress   int             `json:"progress,omitempty"`
	Message    string          `json:"message,omitempty"`
	Output     string          `json:"output,omitempty"`
	DurationMs int64           `json:"duration_ms,omitempty"` // step execution time in milliseconds
	Questions  []AgentQuestion `json:"questions,omitempty"`   // for task_question events
	FromState  RuntimeState    `json:"from_state,omitempty"`
	ToState    RuntimeState    `json:"to_state,omitempty"`
}

type TaskEventObserver interface {
	HandleTaskEvent(event TaskEvent)
}

type TaskKind string

type TaskStatus string

type VerificationContext struct {
	TaskKind        TaskKind
	Goal            string
	SuccessCriteria []string
	FallbackPlan    []string
	PlannedSteps    []string
}

type VerificationDecision struct {
	Valid      bool
	Violations []string
	Status     string
	Output     string
}

type VerificationResult struct {
	Status            string            `json:"status"`
	Summary           string            `json:"summary"`
	CriteriaResults   []CriterionResult `json:"criteria_results"`
	SuggestedRecovery string            `json:"suggested_recovery,omitempty"`
	ExecutedChecks    []string          `json:"executed_checks"`
}