/**
 * Predecessor Query Service
 *
 * This service enables agents to consult previous sessions for context and guidance.
 * It implements the predecessor query pattern from the orchestration spec:
 *
 * 1. Find most recent session for a given role
 * 2. Resume that previous session using Claude Code's --resume flag
 * 3. Send a message to the predecessor
 * 4. Capture the response
 * 5. Suspend the predecessor session again
 * 6. Return the response to the current agent
 *
 * This allows collaborative problem-solving between agents by enabling new sessions
 * to query previous session holders for historical context.
 *
 * @module
 */
import { EventEmitter } from 'node:events';
import type { EntityId, Timestamp } from '@stoneforge/core';
import type { AgentRole } from '../types/agent.js';
import type { SessionManager } from './session-manager.js';
/**
 * Options for querying a predecessor
 */
export interface PredecessorQueryOptions {
    /** Maximum time to wait for a response in milliseconds (default: 60000) */
    readonly timeout?: number;
    /** Whether to suspend the predecessor after getting a response (default: true) */
    readonly suspendAfterResponse?: boolean;
    /** Additional context to provide to the predecessor */
    readonly context?: string;
    /** Working directory for the resumed session */
    readonly workingDirectory?: string;
}
/**
 * Result of a predecessor query
 */
export interface PredecessorQueryResult {
    /** Whether the query was successful */
    readonly success: boolean;
    /** The response message from the predecessor */
    readonly response?: string;
    /** The predecessor session information */
    readonly predecessor?: PredecessorInfo;
    /** Error message if the query failed */
    readonly error?: string;
    /** Timestamp when the query completed */
    readonly completedAt: Timestamp;
    /** Duration of the query in milliseconds */
    readonly durationMs: number;
}
/**
 * Information about the predecessor session
 */
export interface PredecessorInfo {
    /** The agent ID of the predecessor */
    readonly agentId: EntityId;
    /** The agent name */
    readonly agentName?: string;
    /** The role of the predecessor */
    readonly role: AgentRole;
    /** The provider session ID used for resume */
    readonly providerSessionId: string;
    /** The internal session ID */
    readonly sessionId: string;
    /** The working directory of the predecessor session */
    readonly workingDirectory: string;
    /** When the predecessor session was originally started */
    readonly originalStartedAt?: Timestamp;
    /** When the predecessor session was suspended */
    readonly suspendedAt?: Timestamp;
}
/**
 * Status of a predecessor query
 */
export type PredecessorQueryStatus = 'pending' | 'resuming' | 'waiting_response' | 'completed' | 'failed' | 'timed_out';
/**
 * Active predecessor query tracking
 */
export interface ActivePredecessorQuery {
    /** Unique query ID */
    readonly id: string;
    /** The requesting agent ID */
    readonly requestingAgentId: EntityId;
    /** The role being queried */
    readonly targetRole: AgentRole;
    /** The message sent to the predecessor */
    readonly message: string;
    /** Current status of the query */
    status: PredecessorQueryStatus;
    /** The predecessor session ID (once resumed) */
    predecessorSessionId?: string;
    /** Query started timestamp */
    readonly startedAt: Timestamp;
    /** Query completed timestamp */
    completedAt?: Timestamp;
    /** Accumulated response text */
    responseAccumulator: string;
    /** Event emitter for query events */
    readonly events: EventEmitter;
}
/**
 * Predecessor Query Service interface.
 *
 * This service enables agents to consult previous sessions of a given role
 * for context, guidance, or to understand historical decisions.
 */
export interface PredecessorQueryService {
    /**
     * Queries a predecessor session of a given role.
     *
     * This method:
     * 1. Finds the most recent suspended/terminated session for the role
     * 2. Resumes that session using Claude Code's --resume flag
     * 3. Sends the provided message to the predecessor
     * 4. Waits for and captures the response
     * 5. Suspends the predecessor session again
     * 6. Returns the response
     *
     * @param requestingAgentId - The agent making the query
     * @param role - The role to query (e.g., 'director', 'worker')
     * @param message - The message/question to send to the predecessor
     * @param options - Query options
     * @returns The query result with the predecessor's response
     */
    consultPredecessor(requestingAgentId: EntityId, role: AgentRole, message: string, options?: PredecessorQueryOptions): Promise<PredecessorQueryResult>;
    /**
     * Gets information about the most recent predecessor for a role.
     *
     * This is useful for checking if a predecessor exists before querying,
     * or for getting context about who held the role previously.
     *
     * @param role - The role to find the predecessor for
     * @returns The predecessor info or undefined if none exists
     */
    getPredecessorInfo(role: AgentRole): Promise<PredecessorInfo | undefined>;
    /**
     * Checks if a predecessor exists and can be queried for a given role.
     *
     * A predecessor is queryable if:
     * - A previous session exists for the role
     * - The session was suspended (not terminated) OR has a Claude session ID
     *
     * @param role - The role to check
     * @returns True if a queryable predecessor exists
     */
    hasPredecessor(role: AgentRole): Promise<boolean>;
    /**
     * Gets the status of an active predecessor query.
     *
     * @param queryId - The query ID
     * @returns The active query or undefined if not found
     */
    getActiveQuery(queryId: string): ActivePredecessorQuery | undefined;
    /**
     * Lists all active predecessor queries.
     *
     * @returns Array of active queries
     */
    listActiveQueries(): ActivePredecessorQuery[];
    /**
     * Cancels an active predecessor query.
     *
     * This will attempt to gracefully stop the resumed predecessor session
     * and clean up resources.
     *
     * @param queryId - The query ID to cancel
     */
    cancelQuery(queryId: string): Promise<void>;
}
/** Default timeout for predecessor queries (60 seconds) */
export declare const DEFAULT_QUERY_TIMEOUT_MS = 60000;
/** Minimum timeout for predecessor queries (10 seconds) */
export declare const MIN_QUERY_TIMEOUT_MS = 10000;
/** Maximum timeout for predecessor queries (5 minutes) */
export declare const MAX_QUERY_TIMEOUT_MS = 300000;
/**
 * Implementation of the Predecessor Query Service.
 */
export declare class PredecessorQueryServiceImpl implements PredecessorQueryService {
    private readonly sessionManager;
    private readonly activeQueries;
    private queryCounter;
    constructor(sessionManager: SessionManager);
    consultPredecessor(requestingAgentId: EntityId, role: AgentRole, message: string, options?: PredecessorQueryOptions): Promise<PredecessorQueryResult>;
    getPredecessorInfo(role: AgentRole): Promise<PredecessorInfo | undefined>;
    hasPredecessor(role: AgentRole): Promise<boolean>;
    getActiveQuery(queryId: string): ActivePredecessorQuery | undefined;
    listActiveQueries(): ActivePredecessorQuery[];
    cancelQuery(queryId: string): Promise<void>;
    private generateQueryId;
    private normalizeTimeout;
    private captureResponse;
}
/**
 * Error thrown when a predecessor query times out
 */
export declare class TimeoutError extends Error {
    constructor(message: string);
}
/**
 * Error thrown when no predecessor is found for a role
 */
export declare class NoPredecessorError extends Error {
    constructor(role: AgentRole);
}
/**
 * Creates a PredecessorQueryService instance
 */
export declare function createPredecessorQueryService(sessionManager: SessionManager): PredecessorQueryService;
//# sourceMappingURL=predecessor-query.d.ts.map