/**
 * Orchestrator API Implementation
 *
 * This module provides the OrchestratorAPI class that extends QuarryAPI
 * with orchestration-specific functionality for managing AI agents, their
 * sessions, and task assignments.
 *
 * The OrchestratorAPI wraps an existing QuarryAPI instance and adds:
 * - Agent registration and management
 * - Session tracking
 * - Orchestrator-specific task metadata
 */
import type { StorageBackend } from '@stoneforge/storage';
import { type Entity, type EntityId, type Task, type ChannelId, type ElementId } from '@stoneforge/core';
import { type QuarryAPI, QuarryAPIImpl } from '@stoneforge/quarry';
import type { AgentRole, AgentMetadata, RegisterDirectorInput, RegisterWorkerInput, RegisterStewardInput, AgentFilter, OrchestratorTaskMeta } from '../types/index.js';
/**
 * An Entity that represents an agent with orchestrator metadata.
 * The agent-specific metadata is stored under `entity.metadata.agent`
 */
export interface AgentEntity extends Entity {
    metadata: {
        agent: AgentMetadata;
        [key: string]: unknown;
    };
}
/**
 * Type guard to check if an entity is an agent entity
 */
export declare function isAgentEntity(entity: Entity): entity is AgentEntity;
/**
 * Gets the agent metadata from an entity
 */
export declare function getAgentMetadata(entity: Entity): AgentMetadata | undefined;
/**
 * Extended API interface for orchestration operations
 */
export interface OrchestratorAPI extends QuarryAPI {
    /**
     * Registers a Director agent
     */
    registerDirector(input: RegisterDirectorInput): Promise<AgentEntity>;
    /**
     * Registers a Worker agent
     */
    registerWorker(input: RegisterWorkerInput): Promise<AgentEntity>;
    /**
     * Registers a Steward agent
     */
    registerSteward(input: RegisterStewardInput): Promise<AgentEntity>;
    /**
     * Gets an agent by ID
     */
    getAgent(entityId: EntityId): Promise<AgentEntity | undefined>;
    /**
     * Gets an agent by name
     */
    getAgentByName(name: string): Promise<AgentEntity | undefined>;
    /**
     * Lists agents matching the filter
     */
    listAgents(filter?: AgentFilter): Promise<AgentEntity[]>;
    /**
     * Gets all agents with a specific role
     */
    getAgentsByRole(role: AgentRole): Promise<AgentEntity[]>;
    /**
     * Gets available workers (idle or running but accepting tasks)
     */
    getAvailableWorkers(): Promise<AgentEntity[]>;
    /**
     * Gets all stewards
     */
    getStewards(): Promise<AgentEntity[]>;
    /**
     * Gets the Director agent (there should be only one per workspace)
     */
    getDirector(): Promise<AgentEntity | undefined>;
    /**
     * Updates an agent's session status
     */
    updateAgentSession(entityId: EntityId, sessionId: string | undefined, status: 'idle' | 'running' | 'suspended' | 'terminated'): Promise<AgentEntity>;
    /**
     * Gets the agent's channel for receiving messages
     */
    getAgentChannel(entityId: EntityId): Promise<ChannelId | undefined>;
    /**
     * Sets orchestrator metadata on a task
     */
    setTaskOrchestratorMeta(taskId: ElementId, meta: OrchestratorTaskMeta): Promise<Task>;
    /**
     * Updates orchestrator metadata on a task
     */
    updateTaskOrchestratorMeta(taskId: ElementId, updates: Partial<OrchestratorTaskMeta>): Promise<Task>;
    /**
     * Gets orchestrator metadata from a task
     */
    getTaskOrchestratorMeta(taskId: ElementId): Promise<OrchestratorTaskMeta | undefined>;
    /**
     * Assigns a task to an agent (sets orchestrator metadata)
     */
    assignTaskToAgent(taskId: ElementId, agentId: EntityId, options?: {
        branch?: string;
        worktree?: string;
        sessionId?: string;
        markAsStarted?: boolean;
    }): Promise<Task>;
}
/**
 * OrchestratorAPI implementation that extends QuarryAPIImpl
 */
export declare class OrchestratorAPIImpl extends QuarryAPIImpl implements OrchestratorAPI {
    constructor(backend: StorageBackend);
    registerDirector(input: RegisterDirectorInput): Promise<AgentEntity>;
    registerWorker(input: RegisterWorkerInput): Promise<AgentEntity>;
    registerSteward(input: RegisterStewardInput): Promise<AgentEntity>;
    getAgent(entityId: EntityId): Promise<AgentEntity | undefined>;
    getAgentByName(name: string): Promise<AgentEntity | undefined>;
    listAgents(filter?: AgentFilter): Promise<AgentEntity[]>;
    getAgentsByRole(role: AgentRole): Promise<AgentEntity[]>;
    getAvailableWorkers(): Promise<AgentEntity[]>;
    getStewards(): Promise<AgentEntity[]>;
    getDirector(): Promise<AgentEntity | undefined>;
    updateAgentSession(entityId: EntityId, sessionId: string | undefined, status: 'idle' | 'running' | 'suspended' | 'terminated'): Promise<AgentEntity>;
    getAgentChannel(entityId: EntityId): Promise<ChannelId | undefined>;
    setTaskOrchestratorMeta(taskId: ElementId, meta: OrchestratorTaskMeta): Promise<Task>;
    updateTaskOrchestratorMeta(taskId: ElementId, updates: Partial<OrchestratorTaskMeta>): Promise<Task>;
    getTaskOrchestratorMeta(taskId: ElementId): Promise<OrchestratorTaskMeta | undefined>;
    assignTaskToAgent(taskId: ElementId, agentId: EntityId, options?: {
        branch?: string;
        worktree?: string;
        sessionId?: string;
        markAsStarted?: boolean;
    }): Promise<Task>;
    /**
     * Creates a dedicated channel for an agent
     *
     * @param agentName - The name of the agent (used for channel naming)
     * @param agentId - The ID of the agent entity (used for membership)
     * @param createdBy - The entity that created the agent (will be a channel member)
     * @returns The created channel
     */
    private createAgentChannel;
    /**
     * Updates an agent's metadata
     */
    private updateAgentMetadata;
}
/**
 * Creates an OrchestratorAPI instance
 */
export declare function createOrchestratorAPI(backend: StorageBackend): OrchestratorAPI;
//# sourceMappingURL=orchestrator-api.d.ts.map