/**
 * Handoff Service (TB-O10e, TB-O10f)
 *
 * This service enables agent session handoffs for context preservation:
 *
 * - **Self-Handoff (TB-O10e)**: Agent hands off to fresh instance of itself
 *   - Creates handoff message with context summary
 *   - Suspends current session (available for predecessor query)
 *   - New session finds handoff note in inbox
 *
 * - **Agent-Agent Handoff (TB-O10f)**: Agent hands off to another agent
 *   - Sends handoff message to target agent's channel
 *   - Optionally transfers tasks to target agent
 *   - Triggers target agent to process handoff
 *
 * Key design decisions:
 * - Handoff is manual-only (agent decides when to hand off)
 * - Handoff messages stored as Documents for persistence
 * - Uses existing inbox/channel system for delivery
 *
 * @module
 */
import type { EntityId, DocumentId, MessageId, Timestamp } from '@stoneforge/core';
import type { QuarryAPI } from '@stoneforge/quarry';
import type { SessionManager, SessionRecord } from './session-manager.js';
import type { AgentRegistry } from '../services/agent-registry.js';
/**
 * Handoff message content structure
 */
export interface HandoffContent {
    /** Type identifier for handoff messages */
    readonly type: 'handoff';
    /** Agent ID of the source (handing off) */
    readonly fromAgentId: EntityId;
    /** Agent ID of the target (receiving handoff), undefined for self-handoff */
    readonly toAgentId?: EntityId;
    /** Summary of the current context/state */
    readonly contextSummary: string;
    /** Recommended next steps */
    readonly nextSteps?: string;
    /** Reason for the handoff */
    readonly reason?: string;
    /** Task IDs being transferred (for agent-agent handoff) */
    readonly taskIds?: string[];
    /** Provider session ID for predecessor queries */
    readonly providerSessionId?: string;
    /** Timestamp when handoff was initiated */
    readonly initiatedAt: Timestamp;
}
/**
 * Options for self-handoff
 */
export interface SelfHandoffOptions {
    /** Summary of current context to preserve */
    readonly contextSummary: string;
    /** Recommended next steps for the new session */
    readonly nextSteps?: string;
    /** Reason for triggering handoff */
    readonly reason?: string;
    /** Additional metadata to include */
    readonly metadata?: Record<string, unknown>;
}
/**
 * Result of a self-handoff operation
 */
export interface SelfHandoffResult {
    /** Whether the handoff was successful */
    readonly success: boolean;
    /** The handoff document ID */
    readonly handoffDocumentId?: DocumentId;
    /** The message ID sent to the agent's channel */
    readonly messageId?: MessageId;
    /** The suspended session record */
    readonly suspendedSession?: SessionRecord;
    /** Error message if failed */
    readonly error?: string;
    /** Timestamp when handoff completed */
    readonly completedAt: Timestamp;
}
/**
 * Options for agent-to-agent handoff
 */
export interface AgentHandoffOptions {
    /** Summary of current context to preserve */
    readonly contextSummary: string;
    /** Recommended next steps for the target agent */
    readonly nextSteps?: string;
    /** Reason for triggering handoff */
    readonly reason?: string;
    /** Task IDs to transfer to the target agent */
    readonly taskIds?: string[];
    /** Additional metadata to include */
    readonly metadata?: Record<string, unknown>;
    /** Whether to trigger the target agent to wake up (default: true) */
    readonly triggerTarget?: boolean;
}
/**
 * Result of an agent-to-agent handoff operation
 */
export interface AgentHandoffResult {
    /** Whether the handoff was successful */
    readonly success: boolean;
    /** The handoff document ID */
    readonly handoffDocumentId?: DocumentId;
    /** The message ID sent to the target agent's channel */
    readonly messageId?: MessageId;
    /** The suspended session record of the source agent */
    readonly suspendedSession?: SessionRecord;
    /** The target agent ID */
    readonly targetAgentId?: EntityId;
    /** Error message if failed */
    readonly error?: string;
    /** Timestamp when handoff completed */
    readonly completedAt: Timestamp;
}
/**
 * Handoff Service interface for agent session handoffs.
 *
 * The service provides methods for:
 * - Self-handoff: Agent hands off to fresh instance of itself
 * - Agent-agent handoff: Agent hands off to another agent (TB-O10f)
 */
export interface HandoffService {
    /**
     * Performs a self-handoff for an agent.
     *
     * This operation:
     * 1. Creates a handoff document with context summary
     * 2. Sends a handoff message to the agent's own channel
     * 3. Suspends the current session (preserving provider session ID)
     * 4. Terminates the process gracefully
     *
     * The new session can find the handoff note in its inbox and
     * optionally query the suspended predecessor for more context.
     *
     * @param agentId - The agent performing the handoff
     * @param sessionId - The current session ID
     * @param options - Handoff options
     * @returns Result of the handoff operation
     */
    selfHandoff(agentId: EntityId, sessionId: string, options: SelfHandoffOptions): Promise<SelfHandoffResult>;
    /**
     * Performs a handoff from one agent to another.
     *
     * This operation:
     * 1. Creates a handoff document with context summary
     * 2. Sends a handoff message to the target agent's channel
     * 3. Optionally transfers task assignments to the target
     * 4. Suspends the source session
     * 5. Optionally triggers the target agent to wake up
     *
     * @param fromAgentId - The agent initiating the handoff
     * @param toAgentId - The target agent receiving the handoff
     * @param sessionId - The current session ID of the source agent
     * @param options - Handoff options
     * @returns Result of the handoff operation
     */
    handoffToAgent(fromAgentId: EntityId, toAgentId: EntityId, sessionId: string, options: AgentHandoffOptions): Promise<AgentHandoffResult>;
    /**
     * Gets the most recent handoff message for an agent.
     *
     * @param agentId - The agent to check for handoff messages
     * @returns The most recent handoff content, or undefined if none
     */
    getLastHandoff(agentId: EntityId): Promise<HandoffContent | undefined>;
    /**
     * Checks if an agent has a pending handoff message.
     *
     * @param agentId - The agent to check
     * @returns True if a handoff message is pending
     */
    hasPendingHandoff(agentId: EntityId): Promise<boolean>;
}
/** Tag used to identify handoff documents */
export declare const HANDOFF_DOCUMENT_TAG = "handoff";
/** Message type for handoff messages */
export declare const HANDOFF_MESSAGE_TYPE = "handoff";
/**
 * Implementation of the Handoff Service.
 */
export declare class HandoffServiceImpl implements HandoffService {
    private readonly sessionManager;
    private readonly registry;
    private readonly api;
    constructor(sessionManager: SessionManager, registry: AgentRegistry, api: QuarryAPI);
    selfHandoff(agentId: EntityId, sessionId: string, options: SelfHandoffOptions): Promise<SelfHandoffResult>;
    handoffToAgent(fromAgentId: EntityId, toAgentId: EntityId, sessionId: string, options: AgentHandoffOptions): Promise<AgentHandoffResult>;
    getLastHandoff(agentId: EntityId): Promise<HandoffContent | undefined>;
    hasPendingHandoff(agentId: EntityId): Promise<boolean>;
}
/**
 * Creates a HandoffService instance
 */
export declare function createHandoffService(sessionManager: SessionManager, registry: AgentRegistry, api: QuarryAPI): HandoffService;
//# sourceMappingURL=handoff.d.ts.map