Add tool registry, policy evaluator, and inbox triage assistant

Implements the Application layer for AGT-02 (#337):
- IAgentPolicyEvaluator interface for tool-use policy checks
- TaskdeckToolRegistry: in-memory, thread-safe tool registry
- AgentPolicyEvaluator: allowlist enforcement, risk-level review
  gating, auto-apply OFF by default for all risk levels
- TaskdeckToolDefinition: concrete ITaskdeckTool record
- InboxTriageAssistant: bounded template that creates proposals
  from pending inbox items, never directly mutating board state

Author: Chris0Jeky

backend/src/Taskdeck.Application/Services/AgentPolicyEvaluator.cs

@@ -0,0 +1,167 @@
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+using Taskdeck.Application.Interfaces;
+using Taskdeck.Domain.Agents;
+using Taskdeck.Domain.Enums;
+using Taskdeck.Domain.Exceptions;
+
+namespace Taskdeck.Application.Services;
+
+/// <summary>
+/// Evaluates agent tool-use requests against the profile's policy configuration
+/// and the tool's risk level. Review-first is the default for all risk levels;
+/// low-risk auto-apply is OFF unless explicitly opted in via policy.
+/// </summary>
+public sealed class AgentPolicyEvaluator : IAgentPolicyEvaluator
+{
+    private readonly IUnitOfWork _unitOfWork;
+    private readonly ITaskdeckToolRegistry _toolRegistry;
+    private readonly ILogger<AgentPolicyEvaluator>? _logger;
+
+    public AgentPolicyEvaluator(
+        IUnitOfWork unitOfWork,
+        ITaskdeckToolRegistry toolRegistry,
+        ILogger<AgentPolicyEvaluator>? logger = null)
+    {
+        _unitOfWork = unitOfWork;
+        _toolRegistry = toolRegistry;
+        _logger = logger;
+    }
+
+    public async Task<PolicyDecision> EvaluateToolUseAsync(
+        Guid agentProfileId,
+        string toolKey,
+        IDictionary<string, string>? context = null,
+        CancellationToken cancellationToken = default)
+    {
+        if (agentProfileId == Guid.Empty)
+        {
+            _logger?.LogWarning("Policy evaluation denied: empty agent profile ID");
+            return PolicyDecision.Deny("Agent profile ID is required.");
+        }
+
+        if (string.IsNullOrWhiteSpace(toolKey))
+        {
+            _logger?.LogWarning("Policy evaluation denied: empty tool key");
+            return PolicyDecision.Deny("Tool key is required.");
+        }
+
+        // Look up the tool in the registry
+        var tool = _toolRegistry.GetTool(toolKey);
+        if (tool is null)
+        {
+            _logger?.LogWarning("Policy evaluation denied: tool '{ToolKey}' not found in registry", toolKey);
+            return PolicyDecision.Deny($"Tool '{toolKey}' is not registered.");
+        }
+
+        // Look up the agent profile
+        var profile = await _unitOfWork.AgentProfiles.GetByIdAsync(agentProfileId, cancellationToken);
+        if (profile is null)
+        {
+            _logger?.LogWarning("Policy evaluation denied: agent profile '{ProfileId}' not found", agentProfileId);
+            return PolicyDecision.Deny("Agent profile not found.");
+        }
+
+        if (!profile.IsEnabled)
+        {
+            _logger?.LogInformation(
+                "Policy evaluation denied: agent profile '{ProfileId}' is disabled", agentProfileId);
+            return PolicyDecision.Deny("Agent profile is disabled.");
+        }
+
+        // Parse the profile's policy JSON
+        var policy = ParsePolicy(profile.PolicyJson);
+
+        // Check tool allowlist: if a non-empty allowlist is defined, the tool must be in it
+        if (policy.AllowedTools.Count > 0 && !policy.AllowedTools.Contains(toolKey, StringComparer.OrdinalIgnoreCase))
+        {
+            _logger?.LogInformation(
+                "Policy evaluation denied: tool '{ToolKey}' not in allowlist for profile '{ProfileId}'",
+                toolKey, agentProfileId);
+            return PolicyDecision.Deny($"Tool '{toolKey}' is not in this agent's allowed tool list.");
+        }
+
+        // Enforce risk-level constraints
+        // High risk: always requires review, never auto-apply
+        if (tool.RiskLevel == ToolRiskLevel.High)
+        {
+            _logger?.LogInformation(
+                "Policy evaluation: tool '{ToolKey}' requires review (high risk) for profile '{ProfileId}'",
+                toolKey, agentProfileId);
+            return PolicyDecision.AllowWithReview($"High-risk tool '{tool.DisplayName}' requires review before execution.");
+        }
+
+        // Medium risk: always requires review
+        if (tool.RiskLevel == ToolRiskLevel.Medium)
+        {
+            _logger?.LogInformation(
+                "Policy evaluation: tool '{ToolKey}' requires review (medium risk) for profile '{ProfileId}'",
+                toolKey, agentProfileId);
+            return PolicyDecision.AllowWithReview($"Medium-risk tool '{tool.DisplayName}' requires review before execution.");
+        }
+
+        // Low risk: review-first by default; direct apply only if explicitly enabled
+        if (policy.AutoApplyLowRisk)
+        {
+            _logger?.LogInformation(
+                "Policy evaluation: tool '{ToolKey}' allowed direct (low risk, auto-apply enabled) for profile '{ProfileId}'",
+                toolKey, agentProfileId);
+            return PolicyDecision.AllowDirect($"Low-risk tool '{tool.DisplayName}' auto-applied per policy.");
+        }
+
+        _logger?.LogInformation(
+            "Policy evaluation: tool '{ToolKey}' requires review (low risk, auto-apply off) for profile '{ProfileId}'",
+            toolKey, agentProfileId);
+        return PolicyDecision.AllowWithReview($"Low-risk tool '{tool.DisplayName}' requires review (auto-apply is off).");
+    }
+
+    /// <summary>
+    /// Parse the profile's PolicyJson into a structured policy configuration.
+    /// Returns safe defaults if the JSON is missing or malformed.
+    /// </summary>
+    internal static AgentPolicyConfig ParsePolicy(string? policyJson)
+    {
+        if (string.IsNullOrWhiteSpace(policyJson) || policyJson == "{}")
+            return AgentPolicyConfig.Default;
+
+        try
+        {
+            var doc = JsonDocument.Parse(policyJson);
+            var root = doc.RootElement;
+
+            var allowedTools = new List<string>();
+            if (root.TryGetProperty("allowedTools", out var toolsElement) && toolsElement.ValueKind == JsonValueKind.Array)
+            {
+                foreach (var item in toolsElement.EnumerateArray())
+                {
+                    var value = item.GetString();
+                    if (!string.IsNullOrWhiteSpace(value))
+                        allowedTools.Add(value);
+                }
+            }
+
+            var autoApplyLowRisk = false;
+            if (root.TryGetProperty("autoApplyLowRisk", out var autoApplyElement)
+                && autoApplyElement.ValueKind == JsonValueKind.True)
+            {
+                autoApplyLowRisk = true;
+            }
+
+            return new AgentPolicyConfig(allowedTools, autoApplyLowRisk);
+        }
+        catch (JsonException)
+        {
+            return AgentPolicyConfig.Default;
+        }
+    }
+}
+
+/// <summary>
+/// Parsed representation of the agent profile's policy configuration.
+/// </summary>
+internal sealed record AgentPolicyConfig(
+    IReadOnlyList<string> AllowedTools,
+    bool AutoApplyLowRisk)
+{
+    public static AgentPolicyConfig Default { get; } = new(Array.Empty<string>(), false);
+}

backend/src/Taskdeck.Application/Services/IAgentPolicyEvaluator.cs

@@ -0,0 +1,25 @@
+using Taskdeck.Domain.Agents;
+
+namespace Taskdeck.Application.Services;
+
+/// <summary>
+/// Evaluates whether a given agent profile is allowed to use a specific tool,
+/// and under what constraints (review-first, direct apply, or deny).
+/// </summary>
+public interface IAgentPolicyEvaluator
+{
+    /// <summary>
+    /// Evaluate whether the agent profile identified by <paramref name="agentProfileId"/>
+    /// may invoke the tool identified by <paramref name="toolKey"/> in the given context.
+    /// </summary>
+    /// <param name="agentProfileId">The agent profile requesting tool use.</param>
+    /// <param name="toolKey">The tool registry key to evaluate.</param>
+    /// <param name="context">Optional contextual metadata (e.g. board ID, item count).</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>A <see cref="PolicyDecision"/> describing whether the action is allowed.</returns>
+    Task<PolicyDecision> EvaluateToolUseAsync(
+        Guid agentProfileId,
+        string toolKey,
+        IDictionary<string, string>? context = null,
+        CancellationToken cancellationToken = default);
+}

backend/src/Taskdeck.Application/Services/InboxTriageAssistant.cs

@@ -0,0 +1,197 @@
+using System.Text.Json;
+using Microsoft.Extensions.Logging;
+using Taskdeck.Application.DTOs;
+using Taskdeck.Application.Interfaces;
+using Taskdeck.Domain.Agents;
+using Taskdeck.Domain.Common;
+using Taskdeck.Domain.Entities;
+using Taskdeck.Domain.Enums;
+using Taskdeck.Domain.Exceptions;
+
+namespace Taskdeck.Application.Services;
+
+/// <summary>
+/// Bounded agent template that triages inbox items into proposals.
+/// Never directly mutates board state — all changes are routed through
+/// the proposal system and policy evaluator.
+/// </summary>
+public sealed class InboxTriageAssistant
+{
+    /// <summary>Tool key for the inbox triage tool registered in the tool registry.</summary>
+    public const string ToolKey = "inbox.triage";
+
+    /// <summary>Maximum number of inbox items to gather in a single triage run.</summary>
+    private const int MaxInboxItemsPerRun = 20;
+
+    private readonly IUnitOfWork _unitOfWork;
+    private readonly IAgentPolicyEvaluator _policyEvaluator;
+    private readonly IAutomationProposalService _proposalService;
+    private readonly ILogger<InboxTriageAssistant>? _logger;
+
+    public InboxTriageAssistant(
+        IUnitOfWork unitOfWork,
+        IAgentPolicyEvaluator policyEvaluator,
+        IAutomationProposalService proposalService,
+        ILogger<InboxTriageAssistant>? logger = null)
+    {
+        _unitOfWork = unitOfWork;
+        _policyEvaluator = policyEvaluator;
+        _proposalService = proposalService;
+        _logger = logger;
+    }
+
+    /// <summary>
+    /// Run the inbox triage template for a given agent profile and board.
+    /// Gathers pending inbox items, evaluates policy, and creates a proposal
+    /// for triage actions. Returns a failure result if policy denies the action
+    /// or if no actionable items are found.
+    /// </summary>
+    public async Task<Result<InboxTriageResultDto>> RunTriageAsync(
+        Guid agentProfileId,
+        Guid userId,
+        Guid boardId,
+        CancellationToken cancellationToken = default)
+    {
+        if (agentProfileId == Guid.Empty)
+            return Result.Failure<InboxTriageResultDto>(ErrorCodes.ValidationError, "Agent profile ID is required.");
+
+        if (userId == Guid.Empty)
+            return Result.Failure<InboxTriageResultDto>(ErrorCodes.ValidationError, "User ID is required.");
+
+        if (boardId == Guid.Empty)
+            return Result.Failure<InboxTriageResultDto>(ErrorCodes.ValidationError, "Board ID is required.");
+
+        // Evaluate policy before proceeding
+        var policyDecision = await _policyEvaluator.EvaluateToolUseAsync(
+            agentProfileId,
+            ToolKey,
+            new Dictionary<string, string> { ["boardId"] = boardId.ToString() },
+            cancellationToken);
+
+        if (!policyDecision.Allowed)
+        {
+            _logger?.LogInformation(
+                "Inbox triage denied by policy for profile '{ProfileId}': {Reason}",
+                agentProfileId, policyDecision.Reason);
+            return Result.Failure<InboxTriageResultDto>(ErrorCodes.Forbidden, policyDecision.Reason);
+        }
+
+        // Gather inbox context: recent pending items for this user
+        var pendingItems = (await _unitOfWork.LlmQueue.GetByUserAsync(userId, cancellationToken))
+            .Where(r => r.Status == RequestStatus.Pending)
+            .OrderBy(r => r.CreatedAt)
+            .Take(MaxInboxItemsPerRun)
+            .ToList();
+
+        if (pendingItems.Count == 0)
+        {
+            _logger?.LogInformation("Inbox triage found no pending items for user '{UserId}'", userId);
+            return Result.Failure<InboxTriageResultDto>(
+                ErrorCodes.NotFound, "No pending inbox items to triage.");
+        }
+
+        // Verify board exists
+        var board = await _unitOfWork.Boards.GetByIdAsync(boardId, cancellationToken);
+        if (board is null)
+        {
+            return Result.Failure<InboxTriageResultDto>(
+                ErrorCodes.NotFound, $"Board '{boardId}' not found.");
+        }
+
+        // Get the first column to use as the default target
+        var columns = (await _unitOfWork.Columns.GetByBoardIdAsync(boardId, cancellationToken))
+            .OrderBy(c => c.Position)
+            .ToList();
+
+        if (columns.Count == 0)
+        {
+            return Result.Failure<InboxTriageResultDto>(
+                ErrorCodes.NotFound, "Board has no columns to triage into.");
+        }
+
+        var defaultColumnId = columns[0].Id;
+
+        // Build proposal operations — one create-card per inbox item
+        var operations = pendingItems.Select((item, i) =>
+        {
+            var parameters = JsonSerializer.Serialize(new
+            {
+                title = TruncateTitle(item.Payload),
+                description = $"Triaged from inbox item {item.Id}",
+                columnId = defaultColumnId,
+                boardId
+            });
+
+            return new CreateProposalOperationDto(
+                Sequence: i,
+                ActionType: "create",
+                TargetType: "card",
+                Parameters: parameters,
+                IdempotencyKey: $"inbox-triage:{item.Id:N}:{boardId:N}");
+        }).ToList();
+
+        // Create the proposal — never directly mutating the board
+        var summary = pendingItems.Count == 1
+            ? $"Inbox triage: 1 item for board '{board.Name}'"
+            : $"Inbox triage: {pendingItems.Count} items for board '{board.Name}'";
+
+        var createResult = await _proposalService.CreateProposalAsync(
+            new CreateProposalDto(
+                SourceType: ProposalSourceType.Queue,
+                RequestedByUserId: userId,
+                Summary: summary,
+                RiskLevel: RiskLevel.Low,
+                CorrelationId: Guid.NewGuid().ToString(),
+                BoardId: boardId,
+                Operations: operations),
+            cancellationToken);
+
+        if (!createResult.IsSuccess)
+        {
+            _logger?.LogWarning(
+                "Inbox triage proposal creation failed for profile '{ProfileId}': {Error}",
+                agentProfileId, createResult.ErrorMessage);
+            return Result.Failure<InboxTriageResultDto>(createResult.ErrorCode, createResult.ErrorMessage);
+        }
+
+        _logger?.LogInformation(
+            "Inbox triage created proposal '{ProposalId}' with {Count} operations (review required: {Review})",
+            createResult.Value.Id, operations.Count, policyDecision.RequiresReview);
+
+        return Result.Success(new InboxTriageResultDto(
+            createResult.Value.Id,
+            operations.Count,
+            policyDecision.RequiresReview,
+            policyDecision.Reason));
+    }
+
+    private static string TruncateTitle(string input)
+    {
+        const int maxLength = 200;
+        var firstLine = input.Split('\n', StringSplitOptions.RemoveEmptyEntries).FirstOrDefault() ?? input;
+        var trimmed = firstLine.Trim();
+        return trimmed.Length > maxLength ? trimmed[..maxLength].TrimEnd() : trimmed;
+    }
+
+    /// <summary>
+    /// Returns the built-in tool definition for registration in the tool registry.
+    /// </summary>
+    public static ITaskdeckTool GetToolDefinition()
+    {
+        return new TaskdeckToolDefinition(
+            Key: ToolKey,
+            DisplayName: "Inbox Triage",
+            Description: "Triages pending inbox items into card proposals for a target board.",
+            Scope: ToolScope.Inbox,
+            RiskLevel: ToolRiskLevel.Medium);
+    }
+}
+
+/// <summary>
+/// Result DTO for an inbox triage run.
+/// </summary>
+public record InboxTriageResultDto(
+    Guid ProposalId,
+    int ItemsTriaged,
+    bool RequiresReview,
+    string PolicyReason);