/**
 * Task Assignment Service
 *
 * This service provides task assignment functionality for the orchestration system.
 * It manages the assignment of tasks to agents with orchestrator metadata tracking
 * including branch, worktree, and session associations.
 *
 * Key features:
 * - Assign tasks to agents with orchestrator metadata
 * - Query agent workload (tasks assigned to an agent)
 * - Query unassigned tasks
 * - Query tasks by assignment status
 * - Track branch, worktree, sessionId in task metadata
 *
 * @module
 */
import type { Task, ElementId, EntityId } from '@stoneforge/core';
import { TaskStatus } from '@stoneforge/core';
type TaskStatusValue = typeof TaskStatus[keyof typeof TaskStatus];
import type { QuarryAPI } from '@stoneforge/quarry';
import type { OrchestratorTaskMeta, MergeStatus } from '../types/index.js';
import type { MergeRequestProvider } from './merge-request-provider.js';
/**
 * Options for assigning a task to an agent
 */
export interface AssignTaskOptions {
    /** Git branch for the task (auto-generated if not provided) */
    branch?: string;
    /** Worktree path for the task (auto-generated if not provided) */
    worktree?: string;
    /** Claude Code session ID */
    sessionId?: string;
    /** Whether to mark the task as started immediately */
    markAsStarted?: boolean;
}
/**
 * Options for completing a task
 */
export interface CompleteTaskOptions {
    /** Summary of what was accomplished */
    summary?: string;
    /** Commit hash for the final commit */
    commitHash?: string;
    /** Whether to create a merge request (default: true if branch exists and provider is set) */
    createMergeRequest?: boolean;
    /** Custom merge request title (defaults to task title) */
    mergeRequestTitle?: string;
    /** Custom merge request body (defaults to task description + summary) */
    mergeRequestBody?: string;
    /** Base branch for merge request (defaults to 'main' or 'master') */
    baseBranch?: string;
}
/**
 * Options for handing off a task
 */
export interface HandoffTaskOptions {
    /** Session ID of the agent handing off */
    sessionId: string;
    /** Handoff message explaining why and providing context */
    message?: string;
    /** Override branch (defaults to current task branch) */
    branch?: string;
    /** Override worktree path (defaults to current task worktree) */
    worktree?: string;
}
/**
 * Result of a task completion with optional merge request info
 */
export interface TaskCompletionResult {
    /** The updated task */
    task: Task;
    /** URL of the created merge request, if applicable */
    mergeRequestUrl?: string;
    /** Merge request identifier, if applicable */
    mergeRequestId?: number;
}
/**
 * A task with its orchestrator metadata
 */
export interface TaskAssignment {
    /** The task ID */
    taskId: ElementId;
    /** The full task object */
    task: Task;
    /** Orchestrator-specific metadata */
    orchestratorMeta: OrchestratorTaskMeta | undefined;
}
/**
 * Filter for listing task assignments
 */
export interface AssignmentFilter {
    /** Filter by assigned agent */
    agentId?: EntityId;
    /** Filter by task status */
    taskStatus?: TaskStatusValue | TaskStatusValue[];
    /** Filter by assignment status */
    assignmentStatus?: AssignmentStatus | AssignmentStatus[];
    /** Filter by merge status */
    mergeStatus?: MergeStatus | MergeStatus[];
}
/**
 * Assignment status categories
 */
export type AssignmentStatus = 'unassigned' | 'assigned' | 'in_progress' | 'completed' | 'merged';
/**
 * All valid assignment status values
 */
export declare const AssignmentStatusValues: readonly ["unassigned", "assigned", "in_progress", "completed", "merged"];
/**
 * Summary of an agent's workload
 */
export interface AgentWorkloadSummary {
    /** Agent entity ID */
    agentId: EntityId;
    /** Total tasks assigned */
    totalTasks: number;
    /** Tasks by status */
    byStatus: Record<TaskStatusValue, number>;
    /** Tasks currently in progress */
    inProgressCount: number;
    /** Completed tasks awaiting merge */
    awaitingMergeCount: number;
}
/**
 * Task Assignment Service interface for managing task assignments in the orchestration system.
 *
 * The service provides methods for:
 * - Assigning tasks to agents with orchestrator metadata
 * - Querying agent workload
 * - Querying tasks by assignment status
 */
export interface TaskAssignmentService {
    /**
     * Assigns a task to an agent with orchestrator metadata.
     *
     * This method:
     * 1. Validates the task and agent exist
     * 2. Sets the task's assignee field
     * 3. Sets orchestrator metadata (branch, worktree, sessionId, etc.)
     * 4. Optionally marks the task as started
     *
     * @param taskId - The task to assign
     * @param agentId - The agent to assign to
     * @param options - Optional assignment options
     * @returns The updated task
     */
    assignToAgent(taskId: ElementId, agentId: EntityId, options?: AssignTaskOptions): Promise<Task>;
    /**
     * Unassigns a task from its current agent.
     *
     * This clears the assignee field and removes agent-specific orchestrator metadata,
     * but preserves branch information for potential reassignment.
     *
     * @param taskId - The task to unassign
     * @returns The updated task
     */
    unassignTask(taskId: ElementId): Promise<Task>;
    /**
     * Marks a task as started by the assigned agent.
     *
     * Sets the task status to IN_PROGRESS and records the start time.
     *
     * @param taskId - The task to start
     * @param sessionId - Optional session ID to associate
     * @returns The updated task
     */
    startTask(taskId: ElementId, sessionId?: string): Promise<Task>;
    /**
     * Marks a task as completed by the assigned agent.
     *
     * Sets the task status to REVIEW (awaiting merge) and records completion time.
     * The merge steward will later set CLOSED after successfully merging the branch.
     * Optionally creates a merge request for the task branch (when a provider is configured).
     *
     * @param taskId - The task to complete
     * @param options - Optional completion options
     * @returns The updated task and optional merge request info
     */
    completeTask(taskId: ElementId, options?: CompleteTaskOptions): Promise<TaskCompletionResult>;
    /**
     * Hands off a task to be picked up by another agent.
     *
     * This method:
     * 1. Preserves branch/worktree reference in task metadata
     * 2. Appends a handoff note to the task description
     * 3. Unassigns the task so it returns to the pool
     *
     * The next agent assigned to this task can continue from the
     * existing branch/worktree state.
     *
     * @param taskId - The task to hand off
     * @param options - Handoff options including session ID and message
     * @returns The updated task
     */
    handoffTask(taskId: ElementId, options: HandoffTaskOptions): Promise<Task>;
    /**
     * Updates the session ID for a task.
     *
     * @param taskId - The task to update
     * @param sessionId - The new session ID
     * @returns The updated task
     */
    updateSessionId(taskId: ElementId, sessionId: string): Promise<Task>;
    /**
     * Gets all tasks assigned to a specific agent.
     *
     * @param agentId - The agent to query
     * @param filter - Optional filter for task status, etc.
     * @returns Array of task assignments
     */
    getAgentTasks(agentId: EntityId, filter?: Omit<AssignmentFilter, 'agentId'>): Promise<TaskAssignment[]>;
    /**
     * Gets a summary of an agent's workload.
     *
     * @param agentId - The agent to query
     * @returns Workload summary with counts by status
     */
    getAgentWorkload(agentId: EntityId): Promise<AgentWorkloadSummary>;
    /**
     * Checks if an agent has capacity for more tasks.
     *
     * @param agentId - The agent to check
     * @returns true if the agent can accept more tasks
     */
    agentHasCapacity(agentId: EntityId): Promise<boolean>;
    /**
     * Gets all unassigned tasks (tasks without an agent assigned).
     *
     * @param filter - Optional filter for task status, etc.
     * @returns Array of unassigned tasks
     */
    getUnassignedTasks(filter?: Omit<AssignmentFilter, 'agentId' | 'assignmentStatus'>): Promise<Task[]>;
    /**
     * Gets tasks by assignment status.
     *
     * @param status - Assignment status to filter by
     * @param filter - Optional additional filters
     * @returns Array of matching task assignments
     */
    getTasksByAssignmentStatus(status: AssignmentStatus, filter?: Omit<AssignmentFilter, 'assignmentStatus'>): Promise<TaskAssignment[]>;
    /**
     * Lists task assignments with flexible filtering.
     *
     * @param filter - Filter options
     * @returns Array of matching task assignments
     */
    listAssignments(filter?: AssignmentFilter): Promise<TaskAssignment[]>;
    /**
     * Gets tasks that are completed and awaiting merge.
     *
     * @returns Array of tasks ready for merge
     */
    getTasksAwaitingMerge(): Promise<TaskAssignment[]>;
}
/**
 * Implementation of the Task Assignment Service.
 *
 * This implementation uses the QuarryAPI for storage operations.
 */
export declare class TaskAssignmentServiceImpl implements TaskAssignmentService {
    private readonly api;
    private readonly mergeRequestProvider?;
    constructor(api: QuarryAPI, mergeRequestProvider?: MergeRequestProvider);
    assignToAgent(taskId: ElementId, agentId: EntityId, options?: AssignTaskOptions): Promise<Task>;
    unassignTask(taskId: ElementId): Promise<Task>;
    startTask(taskId: ElementId, sessionId?: string): Promise<Task>;
    completeTask(taskId: ElementId, options?: CompleteTaskOptions): Promise<TaskCompletionResult>;
    handoffTask(taskId: ElementId, options: HandoffTaskOptions): Promise<Task>;
    updateSessionId(taskId: ElementId, sessionId: string): Promise<Task>;
    getAgentTasks(agentId: EntityId, filter?: Omit<AssignmentFilter, 'agentId'>): Promise<TaskAssignment[]>;
    getAgentWorkload(agentId: EntityId): Promise<AgentWorkloadSummary>;
    agentHasCapacity(agentId: EntityId): Promise<boolean>;
    getUnassignedTasks(filter?: Omit<AssignmentFilter, 'agentId' | 'assignmentStatus'>): Promise<Task[]>;
    getTasksByAssignmentStatus(status: AssignmentStatus, filter?: Omit<AssignmentFilter, 'assignmentStatus'>): Promise<TaskAssignment[]>;
    listAssignments(filter?: AssignmentFilter): Promise<TaskAssignment[]>;
    getTasksAwaitingMerge(): Promise<TaskAssignment[]>;
    /**
     * Determines the assignment status of a task
     */
    private determineAssignmentStatus;
}
/**
 * Creates a TaskAssignmentService instance
 *
 * @param api - The QuarryAPI instance
 * @param mergeRequestProvider - Optional provider for creating merge requests.
 *   When omitted, merge request creation is silently skipped.
 */
export declare function createTaskAssignmentService(api: QuarryAPI, mergeRequestProvider?: MergeRequestProvider): TaskAssignmentService;
export {};
//# sourceMappingURL=task-assignment-service.d.ts.map