kandev/apps/backend/internal/office/agents/handler.go

package agents

import (
	"errors"
	"net/http"
	"strings"

	"github.com/gin-gonic/gin"
	"github.com/kandev/kandev/internal/common/logger"
	"github.com/kandev/kandev/internal/office/models"
	"github.com/kandev/kandev/internal/office/routing"
	"github.com/kandev/kandev/internal/office/shared"

	"go.uber.org/zap"
)

const (
	ctxKeyAgentClaims = "agent_claims"
	ctxKeyAgentCaller = "agent_caller"
)

// Handler provides HTTP handlers for agent routes.
type Handler struct {
	svc    *AgentService
	logger *logger.Logger
}

// RegisterRoutes registers agent and instruction HTTP routes on the given router group.
func RegisterRoutes(group *gin.RouterGroup, svc *AgentService, log *logger.Logger) {
	h := &Handler{svc: svc, logger: log.WithFields(zap.String("component", "office-agents-handler"))}

	group.GET("/workspaces/:wsId/agents", h.listAgents)
	group.POST("/workspaces/:wsId/agents", h.createAgent)
	group.GET("/agents/:id", h.getAgent)
	group.PATCH("/agents/:id", h.updateAgent)
	group.PATCH("/agents/:id/status", h.updateAgentStatus)
	group.DELETE("/agents/:id", h.deleteAgent)

	group.GET("/agents/:id/instructions", h.listInstructions)
	group.GET("/agents/:id/instructions/:filename", h.getInstruction)
	group.PUT("/agents/:id/instructions/:filename", h.upsertInstruction)
	group.DELETE("/agents/:id/instructions/:filename", h.deleteInstruction)

	group.GET("/agents/:id/utilization", h.getAgentUtilization)

	group.GET("/agents/:id/memory", h.listMemory)
	group.PUT("/agents/:id/memory", h.upsertMemory)
	group.DELETE("/agents/:id/memory/all", h.deleteAllMemory)
	group.DELETE("/agents/:id/memory/:entryId", h.deleteMemory)
	group.GET("/agents/:id/memory/summary", h.memorySummary)
	group.GET("/agents/:id/memory/export", h.exportMemory)
}

// AgentAuthMiddleware returns a gin.HandlerFunc that extracts and validates agent JWTs.
// Requests without a JWT are treated as UI/admin requests and pass through.
func AgentAuthMiddleware(svc *AgentService) gin.HandlerFunc {
	return func(c *gin.Context) {
		auth := c.GetHeader("Authorization")
		if auth == "" || !strings.HasPrefix(auth, "Bearer ") {
			c.Next()
			return
		}
		token := strings.TrimPrefix(auth, "Bearer ")
		claims, err := svc.ValidateAgentJWT(token)
		if err != nil {
			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "invalid token"})
			return
		}
		agent, err := svc.GetAgentInstance(c.Request.Context(), claims.AgentProfileID)
		if err != nil {
			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "agent not found"})
			return
		}
		if wsID := c.Param("wsId"); wsID != "" && claims.WorkspaceID != wsID {
			c.AbortWithStatusJSON(http.StatusForbidden, gin.H{"error": "token workspace mismatch"})
			return
		}
		c.Set(ctxKeyAgentClaims, claims)
		c.Set(ctxKeyAgentCaller, agent)
		c.Next()
	}
}

// agentCallerFromCtx returns the authenticated agent or nil for UI requests.
func agentCallerFromCtx(c *gin.Context) *models.AgentInstance {
	val, ok := c.Get(ctxKeyAgentCaller)
	if !ok {
		return nil
	}
	agent, _ := val.(*models.AgentInstance)
	return agent
}

// CallerFromContext exposes the authenticated agent (or nil for UI
// requests) to other office packages that need to enforce agent-scoped
// authorization without depending on the agents package's internal
// context-key constants.
func CallerFromContext(c *gin.Context) *models.AgentInstance {
	return agentCallerFromCtx(c)
}

// -- Agent handlers --

func (h *Handler) listAgents(c *gin.Context) {
	filter := AgentListFilter{
		Role:      c.Query("role"),
		Status:    c.Query("status"),
		ReportsTo: c.Query("reports_to"),
	}
	var (
		agents []*models.AgentInstance
		err    error
	)
	if filter.Role != "" || filter.Status != "" || filter.ReportsTo != "" {
		agents, err = h.svc.ListAgentInstancesFiltered(c.Request.Context(), c.Param("wsId"), filter)
	} else {
		agents, err = h.svc.ListAgentsFromConfig(c.Request.Context(), c.Param("wsId"))
	}
	if err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
		return
	}
	c.JSON(http.StatusOK, AgentListResponse{Agents: agents})
}

func (h *Handler) createAgent(c *gin.Context) {
	if err := checkAgentPermission(c, shared.PermCanCreateAgents); err != nil {
		return
	}
	var req CreateAgentRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	if err := checkNoEscalation(c, req.Permissions); err != nil {
		return
	}
	// The office agent gets a fresh row in agent_profiles. The repo's
	// CreateAgentInstance derives a default agent_id (CLI tool) from the
	// workspace's existing agents when AgentID is empty.
	agent := &models.AgentInstance{
		WorkspaceID:           c.Param("wsId"),
		Name:                  req.Name,
		Role:                  models.AgentRole(req.Role),
		Icon:                  req.Icon,
		Status:                models.AgentStatusIdle,
		ReportsTo:             req.ReportsTo,
		Permissions:           req.Permissions,
		BudgetMonthlyCents:    req.BudgetMonthlyCents,
		MaxConcurrentSessions: req.MaxConcurrentSessions,
		DesiredSkills:         req.DesiredSkills,
		ExecutorPreference:    req.ExecutorPreference,
	}
	if err := h.svc.CreateAgentInstanceWithCaller(c.Request.Context(), agent, agentCallerFromCtx(c), req.Reason); err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
		return
	}
	c.JSON(http.StatusCreated, AgentResponse{Agent: agent})
}

func (h *Handler) getAgent(c *gin.Context) {
	agent, err := h.svc.GetAgentFromConfig(c.Request.Context(), c.Param("id"))
	if err != nil {
		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
		return
	}
	c.JSON(http.StatusOK, AgentResponse{Agent: agent})
}

func (h *Handler) updateAgent(c *gin.Context) {
	ctx := c.Request.Context()
	targetID := c.Param("id")
	if caller := agentCallerFromCtx(c); caller != nil {
		if caller.ID != targetID && !isAdminRole(caller.Role) {
			c.JSON(http.StatusForbidden, gin.H{"error": "only CEO or admin can update other agents"})
			return
		}
	}
	agent, err := h.svc.GetAgentFromConfig(ctx, targetID)
	if err != nil {
		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
		return
	}
	var req UpdateAgentRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	if req.Permissions != nil {
		if err := checkNoEscalation(c, *req.Permissions); err != nil {
			return
		}
	}
	if req.Routing != nil {
		if err := h.applyRoutingOverride(c, agent, *req.Routing); err != nil {
			return
		}
	}
	applyAgentUpdates(agent, &req)
	if err := h.svc.UpdateAgentInstance(ctx, agent); err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
		return
	}
	c.JSON(http.StatusOK, AgentResponse{Agent: agent})
}

// applyRoutingOverride validates the override blob and writes it onto
// the agent's Settings JSON. Writes a structured 400 with per-field
// details on validation failure (and returns the error so the caller
// skips the persistence step).
//
// In addition to the catalogue-only checks (known/dup/tier shape), the
// agent's chosen tier override is checked against the workspace routing
// config: rejecting a tier that no provider has mapped at save time
// prevents the silent "every launch immediately blocks" failure mode.
func (h *Handler) applyRoutingOverride(
	c *gin.Context, agent *models.AgentInstance, ov routing.AgentOverrides,
) error {
	known := h.svc.KnownProviders()
	cfg, err := h.svc.GetWorkspaceRouting(c.Request.Context(), agent.WorkspaceID)
	if err != nil {
		h.logger.Warn("workspace routing lookup failed; skipping cross-check",
			zap.String("workspace_id", agent.WorkspaceID), zap.Error(err))
		cfg = nil
	}
	if vErr := routing.ValidateAgentOverridesAgainstWorkspace(ov, known, cfg); vErr != nil {
		respondRoutingValidation(c, vErr)
		return vErr
	}
	merged, err := routing.WriteAgentOverrides(agent.Settings, ov)
	if err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
		return err
	}
	agent.Settings = merged
	return nil
}

// respondRoutingValidation translates a ValidationError into the same
// structured 400 shape the dashboard routing handler uses.
func respondRoutingValidation(c *gin.Context, err error) {
	var ve *routing.ValidationError
	if errors.As(err, &ve) {
		c.JSON(http.StatusBadRequest, gin.H{
			"error":   ve.Message,
			"field":   ve.Field,
			"details": ve.Details,
		})
		return
	}
	c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
}

func (h *Handler) deleteAgent(c *gin.Context) {
	if caller := agentCallerFromCtx(c); caller != nil {
		if !isAdminRole(caller.Role) {
			c.JSON(http.StatusForbidden, gin.H{"error": "only CEO or admin can delete agents"})
			return
		}
	}
	if err := h.svc.DeleteAgentInstance(c.Request.Context(), c.Param("id")); err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
		return
	}
	c.JSON(http.StatusOK, gin.H{"ok": true})
}

func (h *Handler) updateAgentStatus(c *gin.Context) {
	if caller := agentCallerFromCtx(c); caller != nil {
		targetID := c.Param("id")
		if targetID != caller.ID && !isAdminRole(caller.Role) {
			c.JSON(http.StatusForbidden, gin.H{"error": "only CEO or admin can change other agents' status"})
			return
		}
	}
	var req UpdateAgentStatusRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	agent, err := h.svc.UpdateAgentStatus(
		c.Request.Context(), c.Param("id"),
		models.AgentStatus(req.Status), req.PauseReason)
	if err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	c.JSON(http.StatusOK, AgentResponse{Agent: agent})
}

// -- Instruction handlers --

// isValidFilename checks that a filename does not contain path separators or traversals.
func isValidFilename(s string) bool {
	return s != "" && !strings.Contains(s, "/") && !strings.Contains(s, "\\") && !strings.Contains(s, "..")
}

func (h *Handler) listInstructions(c *gin.Context) {
	files, err := h.svc.ListInstructions(c.Request.Context(), c.Param("id"))
	if err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
		return
	}
	c.JSON(http.StatusOK, InstructionListResponse{Files: files})
}

func (h *Handler) getInstruction(c *gin.Context) {
	filename := c.Param("filename")
	if !isValidFilename(filename) {
		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid filename"})
		return
	}
	file, err := h.svc.GetInstruction(c.Request.Context(), c.Param("id"), filename)
	if err != nil {
		c.JSON(http.StatusNotFound, gin.H{"error": err.Error()})
		return
	}
	c.JSON(http.StatusOK, InstructionFileResponse{File: file})
}

func (h *Handler) upsertInstruction(c *gin.Context) {
	if caller := agentCallerFromCtx(c); caller != nil {
		if caller.ID != c.Param("id") && !isAdminRole(caller.Role) {
			c.JSON(http.StatusForbidden, gin.H{"error": "only CEO or admin can modify another agent's instructions"})
			return
		}
	}
	var req UpsertInstructionRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	agentID := c.Param("id")
	filename := c.Param("filename")
	if !isValidFilename(filename) {
		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid filename"})
		return
	}
	isEntry := filename == "AGENTS.md"
	if err := h.svc.UpsertInstruction(c.Request.Context(), agentID, filename, req.Content, isEntry); err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
		return
	}
	file, err := h.svc.GetInstruction(c.Request.Context(), agentID, filename)
	if err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
		return
	}
	c.JSON(http.StatusOK, InstructionFileResponse{File: file})
}

func (h *Handler) deleteInstruction(c *gin.Context) {
	if caller := agentCallerFromCtx(c); caller != nil {
		if caller.ID != c.Param("id") && !isAdminRole(caller.Role) {
			c.JSON(http.StatusForbidden, gin.H{"error": "only CEO or admin can modify another agent's instructions"})
			return
		}
	}
	filename := c.Param("filename")
	if !isValidFilename(filename) {
		c.JSON(http.StatusBadRequest, gin.H{"error": "invalid filename"})
		return
	}
	if err := h.svc.DeleteInstruction(c.Request.Context(), c.Param("id"), filename); err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
		return
	}
	c.JSON(http.StatusOK, gin.H{"ok": true})
}

// -- Utilization handler --

func (h *Handler) getAgentUtilization(c *gin.Context) {
	usage, err := h.svc.GetAgentUtilization(c.Request.Context(), c.Param("id"))
	if err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
		return
	}
	if usage == nil {
		c.JSON(http.StatusOK, gin.H{"utilization": nil})
		return
	}
	c.JSON(http.StatusOK, gin.H{"utilization": usage})
}

// -- Memory handlers --

// checkAgentMemoryAccess returns an error and writes 403 when an agent
// caller attempts to access another agent's memory. UI callers (no agent
// JWT) pass through unchanged. The CEO/admin role is allowed cross-agent
// memory access to mirror the existing instruction-handler convention.
func checkAgentMemoryAccess(c *gin.Context) error {
	caller := agentCallerFromCtx(c)
	if caller == nil {
		return nil
	}
	if caller.ID == c.Param("id") || isAdminRole(caller.Role) {
		return nil
	}
	c.JSON(http.StatusForbidden, gin.H{"error": "agents may only access their own memory"})
	return shared.ErrForbidden
}

func (h *Handler) listMemory(c *gin.Context) {
	if err := checkAgentMemoryAccess(c); err != nil {
		return
	}
	layer := c.Query("layer")
	entries, err := h.svc.ListMemory(c.Request.Context(), c.Param("id"), layer)
	if err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
		return
	}
	c.JSON(http.StatusOK, MemoryListResponse{Memory: entries})
}

func (h *Handler) upsertMemory(c *gin.Context) {
	if err := checkAgentMemoryAccess(c); err != nil {
		return
	}
	var req UpsertMemoryRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		return
	}
	agentID := c.Param("id")
	for _, entry := range req.Entries {
		mem := &models.AgentMemory{
			AgentProfileID: agentID,
			Layer:          entry.Layer,
			Key:            entry.Key,
			Content:        entry.Content,
			Metadata:       entry.Metadata,
		}
		if err := h.svc.UpsertAgentMemory(c.Request.Context(), mem); err != nil {
			c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
			return
		}
	}
	c.JSON(http.StatusOK, gin.H{"ok": true})
}

func (h *Handler) deleteAllMemory(c *gin.Context) {
	if err := checkAgentMemoryAccess(c); err != nil {
		return
	}
	if err := h.svc.DeleteAllMemory(c.Request.Context(), c.Param("id")); err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
		return
	}
	c.JSON(http.StatusOK, gin.H{"ok": true})
}

func (h *Handler) deleteMemory(c *gin.Context) {
	agentID := c.Param("id")
	entryID := c.Param("entryId")
	if err := h.svc.DeleteAgentMemoryOwned(c.Request.Context(), agentID, entryID); err != nil {
		c.JSON(http.StatusNotFound, gin.H{"error": "memory entry not found"})
		return
	}
	c.JSON(http.StatusOK, gin.H{"ok": true})
}

func (h *Handler) memorySummary(c *gin.Context) {
	if err := checkAgentMemoryAccess(c); err != nil {
		return
	}
	entries, err := h.svc.GetMemorySummary(c.Request.Context(), c.Param("id"))
	if err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
		return
	}
	c.JSON(http.StatusOK, gin.H{"count": len(entries), "memory": entries})
}

func (h *Handler) exportMemory(c *gin.Context) {
	if err := checkAgentMemoryAccess(c); err != nil {
		return
	}
	entries, err := h.svc.ExportMemory(c.Request.Context(), c.Param("id"))
	if err != nil {
		c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
		return
	}
	c.JSON(http.StatusOK, MemoryListResponse{Memory: entries})
}

// -- Permission helpers --

// checkAgentPermission returns nil and does nothing for UI requests.
// For agent callers, it checks the specified permission and returns 403 if denied.
func checkAgentPermission(c *gin.Context, permKey string) error {
	caller := agentCallerFromCtx(c)
	if caller == nil {
		return nil
	}
	perms := shared.ResolvePermissions(shared.AgentRole(caller.Role), caller.Permissions)
	if !shared.HasPermission(perms, permKey) {
		c.JSON(http.StatusForbidden, gin.H{"error": "forbidden: missing " + permKey})
		return shared.ErrForbidden
	}
	return nil
}

// checkNoEscalation verifies an agent caller is not granting permissions it
// does not itself hold. No-op for UI requests or empty permission strings.
func checkNoEscalation(c *gin.Context, permsJSON string) error {
	caller := agentCallerFromCtx(c)
	if caller == nil || permsJSON == "" || permsJSON == "{}" {
		return nil
	}
	callerPerms := shared.ResolvePermissions(shared.AgentRole(caller.Role), caller.Permissions)
	if err := shared.ValidateNoEscalation(callerPerms, permsJSON); err != nil {
		c.JSON(http.StatusForbidden, gin.H{"error": err.Error()})
		return err
	}
	return nil
}

// isAdminRole returns true for roles that have administrative privileges.
func isAdminRole(role models.AgentRole) bool {
	return role == models.AgentRoleCEO
}

func applyAgentUpdates(agent *models.AgentInstance, req *UpdateAgentRequest) {
	if req.Name != nil {
		agent.Name = *req.Name
	}
	// Wave G: AgentInstance.ID is the agent_profiles row id; the legacy
	// AgentProfileID request field is now a no-op for updates (the row's id
	// cannot change after creation). Accepting the field keeps existing
	// clients valid; the value is intentionally ignored.
	if req.Role != nil {
		agent.Role = models.AgentRole(*req.Role)
	}
	if req.Icon != nil {
		agent.Icon = *req.Icon
	}
	if req.Status != nil {
		agent.Status = models.AgentStatus(*req.Status)
	}
	if req.ReportsTo != nil {
		agent.ReportsTo = *req.ReportsTo
	}
	if req.Permissions != nil {
		agent.Permissions = *req.Permissions
	}
	if req.BudgetMonthlyCents != nil {
		agent.BudgetMonthlyCents = *req.BudgetMonthlyCents
	}
	if req.MaxConcurrentSessions != nil {
		agent.MaxConcurrentSessions = *req.MaxConcurrentSessions
	}
	if req.DesiredSkills != nil {
		agent.DesiredSkills = *req.DesiredSkills
	}
	if req.SkillIDs != nil {
		agent.SkillIDs = *req.SkillIDs
	}
	if req.ExecutorPreference != nil {
		agent.ExecutorPreference = *req.ExecutorPreference
	}
	if req.PauseReason != nil {
		agent.PauseReason = *req.PauseReason
	}
	if req.AutoApprove != nil {
		agent.AutoApprove = *req.AutoApprove
	}
	if req.AllowIndexing != nil {
		agent.AllowIndexing = *req.AllowIndexing
	}
	if req.CLIPassthrough != nil {
		agent.CLIPassthrough = *req.CLIPassthrough
	}
}