feat: add search functionality and count methods for various entities

- Implemented search functionality for agents, behaviors, personas, skills, traits, and runs using regex matching.
- Added Count methods for agents, behaviors, checkpoints, personas, runs, skills, and traits to return the total number of items matching the specified filters.
- Created migrations for new collections in MongoDB for agents, runs, steps, tool calls, memories, checkpoints, skills, traits, behaviors, and personas.

Author: juicycleff

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help build run test clean fmt lint lint-fix vet tidy deps install dev hot check coverage b r t c f l lf v check-deps
+.PHONY: help build run test clean fmt lint lint-fix vet tidy deps install dev hot check coverage b r t c f l lf v check-deps templ templ-watch
 
 # Default target
 .DEFAULT_GOAL := help
@@ -53,6 +53,10 @@ help:
 	@echo "  make docs           - Serve documentation locally"
 	@echo "  make docs-build     - Build documentation"
 	@echo ""
+	@echo "$(GREEN)Code Generation:$(NC)"
+	@echo "  make templ        - Generate templ files"
+	@echo "  make templ-watch  - Watch and regenerate templ files on change"
+	@echo ""
 	@echo "$(GREEN)Other:$(NC)"
 	@echo "  make all            - Run check, test, and build"
 	@echo "  make help (h)       - Show this help message"
@@ -100,7 +104,7 @@ clean c:
 fmt f:
 	@echo "$(BLUE)Formatting code...$(NC)"
 	@gofmt -s -w .
-	@command -v goimports >/dev/null 2>&1 && goimports -w -local github.com/xraph/ctrlplane . || echo "$(YELLOW)goimports not found, skipping (run: go install golang.org/x/tools/cmd/goimports@latest)$(NC)"
+	@command -v goimports >/dev/null 2>&1 && goimports -w -local github.com/xraph/cortex . || echo "$(YELLOW)goimports not found, skipping (run: go install golang.org/x/tools/cmd/goimports@latest)$(NC)"
 	@echo "$(GREEN)✓ Formatting complete$(NC)"
 
 ## lint (l): Run linter
@@ -178,6 +182,8 @@ deps:
 	@go install github.com/cosmtrek/air@latest
 	@echo "Installing golangci-lint..."
 	@command -v golangci-lint >/dev/null 2>&1 || curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(shell go env GOPATH)/bin
+	@echo "Installing templ..."
+	@go install github.com/a-h/templ/cmd/templ@latest
 	@echo "$(GREEN)✓ Development dependencies installed$(NC)"
 
 ## check-deps: Check if required tools are installed
@@ -186,6 +192,7 @@ check-deps:
 	@command -v goimports >/dev/null 2>&1 && echo "$(GREEN)✓ goimports$(NC)" || echo "$(YELLOW)✗ goimports (run: make deps)$(NC)"
 	@command -v golangci-lint >/dev/null 2>&1 && echo "$(GREEN)✓ golangci-lint$(NC)" || echo "$(YELLOW)✗ golangci-lint (run: make deps)$(NC)"
 	@command -v air >/dev/null 2>&1 && echo "$(GREEN)✓ air$(NC)" || echo "$(YELLOW)✗ air (run: make deps)$(NC)"
+	@command -v templ >/dev/null 2>&1 && echo "$(GREEN)✓ templ$(NC)" || echo "$(YELLOW)✗ templ (run: make deps)$(NC)"
 
 ## mod-download: Download modules
 mod-download:
@@ -210,8 +217,21 @@ docs-build:
 	@cd docs && pnpm install && pnpm build
 	@echo "$(GREEN)✓ Documentation built$(NC)"
 
-## all: Run check, test, and build
-all: check test build
+## templ: Generate templ files
+templ:
+	@echo "$(BLUE)Generating templ files...$(NC)"
+	@command -v templ >/dev/null 2>&1 || { echo "$(RED)templ not found. Install: go install github.com/a-h/templ/cmd/templ@latest$(NC)"; exit 1; }
+	templ generate ./dashboard/...
+	@echo "$(GREEN)✓ Templ generation complete$(NC)"
+
+## templ-watch: Watch and regenerate templ files
+templ-watch:
+	@echo "$(BLUE)Watching templ files...$(NC)"
+	@command -v templ >/dev/null 2>&1 || { echo "$(RED)templ not found. Install: go install github.com/a-h/templ/cmd/templ@latest$(NC)"; exit 1; }
+	templ generate --watch ./dashboard/...
+
+## all: Run templ generate, check, test, and build
+all: templ check test build
 	@echo "$(GREEN)✓ All tasks complete$(NC)"
 
 # Short aliases

agent/config.go

@@ -50,11 +50,13 @@ type Store interface {
 	Update(ctx context.Context, config *Config) error
 	Delete(ctx context.Context, agentID id.AgentID) error
 	List(ctx context.Context, filter *ListFilter) ([]*Config, error)
+	CountAgents(ctx context.Context, filter *ListFilter) (int64, error)
 }
 
-// ListFilter controls pagination for agent listing.
+// ListFilter controls pagination and filtering for agent listing.
 type ListFilter struct {
 	AppID  string
+	Search string
 	Limit  int
 	Offset int
 }

api/agent_handler.go

@@ -8,11 +8,12 @@ import (
 
 	"github.com/xraph/cortex"
 	"github.com/xraph/cortex/agent"
+	"github.com/xraph/cortex/engine"
 	"github.com/xraph/cortex/id"
 )
 
 func (a *API) registerAgentRoutes(router forge.Router) error {
-	g := router.Group("/cortex", forge.WithGroupTags("agents"))
+	g := router.Group("", forge.WithGroupTags("agents"))
 
 	if err := g.POST("/agents", a.createAgent,
 		forge.WithSummary("Create agent"),
@@ -87,6 +88,16 @@ func (a *API) registerAgentRoutes(router forge.Router) error {
 		return fmt.Errorf("register agent routes: %w", err)
 	}
 
+	if err := g.POST("/agents/:name/preview-prompt", a.previewPrompt,
+		forge.WithSummary("Preview prompt"),
+		forge.WithDescription("Returns the computed system prompt for the agent without executing."),
+		forge.WithOperationID("previewPrompt"),
+		forge.WithResponseSchema(http.StatusOK, "Computed prompt", &PreviewPromptResponse{}),
+		forge.WithErrorResponses(),
+	); err != nil {
+		return fmt.Errorf("register agent routes: %w", err)
+	}
+
 	return nil
 }
 
@@ -132,7 +143,7 @@ func (a *API) getAgent(ctx forge.Context, _ *GetAgentRequest) (*agent.Config, er
 	return cfg, ctx.JSON(http.StatusOK, cfg)
 }
 
-func (a *API) listAgents(ctx forge.Context, req *ListAgentsRequest) ([]*agent.Config, error) {
+func (a *API) listAgents(ctx forge.Context, req *ListAgentsRequest) (*ListAgentsResponse, error) {
 	agents, err := a.eng.ListAgents(ctx.Context(), &agent.ListFilter{
 		AppID:  cortex.AppFromContext(ctx.Context()),
 		Limit:  defaultLimit(req.Limit),
@@ -141,7 +152,8 @@ func (a *API) listAgents(ctx forge.Context, req *ListAgentsRequest) ([]*agent.Co
 	if err != nil {
 		return nil, fmt.Errorf("list agents: %w", err)
 	}
-	return agents, ctx.JSON(http.StatusOK, agents)
+	resp := &ListAgentsResponse{Items: agents}
+	return resp, ctx.JSON(http.StatusOK, resp)
 }
 
 func (a *API) updateAgent(ctx forge.Context, req *UpdateAgentRequest) (*agent.Config, error) {
@@ -210,12 +222,91 @@ func (a *API) deleteAgent(ctx forge.Context, _ *DeleteAgentRequest) (*struct{},
 	return nil, ctx.NoContent(http.StatusNoContent)
 }
 
-func (a *API) runAgent(_ forge.Context, _ *RunAgentRequest) (*struct{}, error) {
-	// TODO: implement agent execution in phase 2
-	return nil, forge.NotFound("agent execution not yet implemented")
+func (a *API) runAgent(ctx forge.Context, req *RunAgentRequest) (*RunAgentResponse, error) {
+	if req.Input == "" {
+		return nil, forge.BadRequest("input is required")
+	}
+
+	appID := cortex.AppFromContext(ctx.Context())
+	r, err := a.eng.RunAgent(ctx.Context(), appID, req.Name, req.Input, mapOverrides(req.Overrides))
+	if err != nil {
+		return nil, mapStoreError(err)
+	}
+
+	var durationMs int64
+	if r.StartedAt != nil && r.CompletedAt != nil {
+		durationMs = r.CompletedAt.Sub(*r.StartedAt).Milliseconds()
+	}
+
+	resp := &RunAgentResponse{
+		RunID:      r.ID.String(),
+		Output:     r.Output,
+		State:      string(r.State),
+		StepCount:  r.StepCount,
+		TokensUsed: r.TokensUsed,
+		DurationMs: durationMs,
+	}
+	return resp, ctx.JSON(http.StatusOK, resp)
 }
 
-func (a *API) streamAgent(_ forge.Context, _ *StreamAgentRequest) (*struct{}, error) {
-	// TODO: implement streaming agent execution in phase 2
-	return nil, forge.NotFound("agent streaming not yet implemented")
+func (a *API) streamAgent(ctx forge.Context, req *StreamAgentRequest) (*struct{}, error) {
+	if req.Input == "" {
+		return nil, forge.BadRequest("input is required")
+	}
+
+	ctx.SetHeader("Content-Type", "text/event-stream")
+	ctx.SetHeader("Cache-Control", "no-cache")
+	ctx.SetHeader("Connection", "keep-alive")
+	ctx.SetHeader("X-Accel-Buffering", "no")
+
+	appID := cortex.AppFromContext(ctx.Context())
+	events := make(chan engine.StreamEvent, 64)
+
+	if err := a.eng.StreamAgent(ctx.Context(), appID, req.Name, req.Input, mapOverrides(req.Overrides), events); err != nil {
+		return nil, mapStoreError(err)
+	}
+
+	for evt := range events {
+		if err := ctx.WriteSSE(string(evt.Type), evt.Data); err != nil {
+			break
+		}
+	}
+
+	return nil, nil
+}
+
+func (a *API) previewPrompt(ctx forge.Context, _ *PreviewPromptRequest) (*PreviewPromptResponse, error) {
+	appID := cortex.AppFromContext(ctx.Context())
+	ag, err := a.eng.GetAgentByName(ctx.Context(), appID, ctx.Param("name"))
+	if err != nil {
+		return nil, mapStoreError(err)
+	}
+
+	// Use the engine's prompt builder for a consistent preview.
+	prompt := a.eng.BuildSystemPrompt(ctx.Context(), ag, nil)
+
+	resp := &PreviewPromptResponse{
+		Prompt: prompt,
+	}
+	return resp, ctx.JSON(http.StatusOK, resp)
+}
+
+// mapOverrides converts API-layer overrides to engine-layer overrides.
+func mapOverrides(o *AgentOverrides) *engine.RunOverrides {
+	if o == nil {
+		return nil
+	}
+	return &engine.RunOverrides{
+		Model:           o.Model,
+		Temperature:     o.Temperature,
+		MaxSteps:        o.MaxSteps,
+		MaxTokens:       o.MaxTokens,
+		ReasoningLoop:   o.ReasoningLoop,
+		SystemPrompt:    o.SystemPrompt,
+		PersonaRef:      o.PersonaRef,
+		InlineSkills:    o.InlineSkills,
+		InlineTraits:    o.InlineTraits,
+		InlineBehaviors: o.InlineBehaviors,
+		Tools:           o.Tools,
+	}
 }

api/api.go

@@ -59,5 +59,8 @@ func (a *API) RegisterRoutes(router forge.Router) error {
 	if err := a.registerMemoryRoutes(router); err != nil {
 		return err
 	}
-	return a.registerToolRoutes(router)
+	if err := a.registerToolRoutes(router); err != nil {
+		return err
+	}
+	return a.registerConfigRoutes(router)
 }

api/behavior_handler.go

@@ -12,7 +12,7 @@ import (
 )
 
 func (a *API) registerBehaviorRoutes(router forge.Router) error {
-	g := router.Group("/cortex", forge.WithGroupTags("behaviors"))
+	g := router.Group("", forge.WithGroupTags("behaviors"))
 
 	if err := g.POST("/behaviors", a.createBehavior,
 		forge.WithSummary("Create behavior"),
@@ -117,7 +117,7 @@ func (a *API) getBehavior(ctx forge.Context, _ *GetBehaviorRequest) (*behavior.B
 	return b, ctx.JSON(http.StatusOK, b)
 }
 
-func (a *API) listBehaviors(ctx forge.Context, req *ListBehaviorsRequest) ([]*behavior.Behavior, error) {
+func (a *API) listBehaviors(ctx forge.Context, req *ListBehaviorsRequest) (*ListBehaviorsResponse, error) {
 	behaviors, err := a.eng.ListBehaviors(ctx.Context(), &behavior.ListFilter{
 		AppID:  cortex.AppFromContext(ctx.Context()),
 		Limit:  defaultLimit(req.Limit),
@@ -126,7 +126,8 @@ func (a *API) listBehaviors(ctx forge.Context, req *ListBehaviorsRequest) ([]*be
 	if err != nil {
 		return nil, fmt.Errorf("list behaviors: %w", err)
 	}
-	return behaviors, ctx.JSON(http.StatusOK, behaviors)
+	resp := &ListBehaviorsResponse{Items: behaviors}
+	return resp, ctx.JSON(http.StatusOK, resp)
 }
 
 func (a *API) updateBehavior(ctx forge.Context, req *UpdateBehaviorRequest) (*behavior.Behavior, error) {

api/checkpoint_handler.go

@@ -11,7 +11,7 @@ import (
 )
 
 func (a *API) registerCheckpointRoutes(router forge.Router) error {
-	g := router.Group("/cortex", forge.WithGroupTags("checkpoints"))
+	g := router.Group("", forge.WithGroupTags("checkpoints"))
 
 	if err := g.GET("/checkpoints", a.listCheckpoints,
 		forge.WithSummary("List pending checkpoints"),
@@ -38,15 +38,16 @@ func (a *API) registerCheckpointRoutes(router forge.Router) error {
 	return nil
 }
 
-func (a *API) listCheckpoints(ctx forge.Context, req *ListCheckpointsRequest) ([]*checkpoint.Checkpoint, error) {
+func (a *API) listCheckpoints(ctx forge.Context, req *ListCheckpointsRequest) (*ListCheckpointsResponse, error) {
 	cps, err := a.eng.ListPendingCheckpoints(ctx.Context(), &checkpoint.ListFilter{
 		Limit:  defaultLimit(req.Limit),
 		Offset: req.Offset,
 	})
 	if err != nil {
 		return nil, fmt.Errorf("list checkpoints: %w", err)
 	}
-	return cps, ctx.JSON(http.StatusOK, cps)
+	resp := &ListCheckpointsResponse{Items: cps}
+	return resp, ctx.JSON(http.StatusOK, resp)
 }
 
 func (a *API) resolveCheckpoint(ctx forge.Context, req *ResolveCheckpointRequest) (*struct{}, error) {

api/config_handler.go

@@ -0,0 +1,64 @@
+package api
+
+import (
+	"fmt"
+	"net/http"
+
+	"github.com/xraph/forge"
+
+	"github.com/xraph/cortex"
+)
+
+// UpdateConfigRequest is the request body for updating engine configuration.
+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"`
+}
+
+func (a *API) registerConfigRoutes(router forge.Router) error {
+	g := router.Group("", forge.WithGroupTags("config"))
+
+	if err := g.GET("/config", a.getConfig,
+		forge.WithSummary("Get config"),
+		forge.WithDescription("Returns the current engine configuration."),
+		forge.WithOperationID("getConfig"),
+		forge.WithResponseSchema(http.StatusOK, "Engine configuration", &cortex.Config{}),
+		forge.WithErrorResponses(),
+	); err != nil {
+		return fmt.Errorf("register config routes: %w", err)
+	}
+
+	if err := g.PUT("/config", a.updateConfig,
+		forge.WithSummary("Update config"),
+		forge.WithDescription("Updates engine configuration at runtime. Changes are in-memory only."),
+		forge.WithOperationID("updateConfig"),
+		forge.WithRequestSchema(UpdateConfigRequest{}),
+		forge.WithResponseSchema(http.StatusOK, "Updated configuration", &cortex.Config{}),
+		forge.WithErrorResponses(),
+	); err != nil {
+		return fmt.Errorf("register config routes: %w", err)
+	}
+
+	return nil
+}
+
+func (a *API) getConfig(ctx forge.Context, _ *struct{}) (*cortex.Config, error) {
+	cfg := a.eng.Config()
+	return &cfg, ctx.JSON(http.StatusOK, cfg)
+}
+
+func (a *API) updateConfig(ctx forge.Context, req *UpdateConfigRequest) (*cortex.Config, error) {
+	update := cortex.Config{
+		DefaultModel:         req.DefaultModel,
+		DefaultMaxSteps:      req.DefaultMaxSteps,
+		DefaultMaxTokens:     req.DefaultMaxTokens,
+		DefaultTemperature:   req.DefaultTemperature,
+		DefaultReasoningLoop: req.DefaultReasoningLoop,
+	}
+
+	cfg := a.eng.UpdateConfig(update)
+	return &cfg, ctx.JSON(http.StatusOK, cfg)
+}

api/memory_handler.go

@@ -11,7 +11,7 @@ import (
 )
 
 func (a *API) registerMemoryRoutes(router forge.Router) error {
-	g := router.Group("/cortex", forge.WithGroupTags("memory"))
+	g := router.Group("", forge.WithGroupTags("memory"))
 
 	if err := g.GET("/agents/:name/memory", a.getConversation,
 		forge.WithSummary("Get conversation"),
@@ -37,7 +37,7 @@ func (a *API) registerMemoryRoutes(router forge.Router) error {
 	return nil
 }
 
-func (a *API) getConversation(ctx forge.Context, req *GetConversationRequest) ([]memory.Message, error) {
+func (a *API) getConversation(ctx forge.Context, req *GetConversationRequest) (*GetConversationResponse, error) {
 	appID := cortex.AppFromContext(ctx.Context())
 	cfg, err := a.eng.GetAgentByName(ctx.Context(), appID, ctx.Param("name"))
 	if err != nil {
@@ -51,7 +51,8 @@ func (a *API) getConversation(ctx forge.Context, req *GetConversationRequest) ([
 	if err != nil {
 		return nil, fmt.Errorf("load conversation: %w", err)
 	}
-	return messages, ctx.JSON(http.StatusOK, messages)
+	resp := &GetConversationResponse{Messages: messages}
+	return resp, ctx.JSON(http.StatusOK, resp)
 }
 
 func (a *API) clearConversation(ctx forge.Context, _ *ClearConversationRequest) (*struct{}, error) {