/**
 * Session stacking intelligence — proactive session discovery and stacking recommendations.
 *
 * Provides intelligence for front-facing agents to prefer stacking onto existing
 * sessions (completed, failed, aborted, cancelled) instead of creating new ones.
 * The OpenCode SDK supports stacking via `task_id` / `parentSessionId` as long as
 * the session ID is valid — this works both within a delegation tree and across
 * independent sessions.
 *
 * Read-only (CQRS read-side). No mutation authority.
 * @module coordination/delegation/session-intelligence
 */
import type { Delegation, DelegationStatus } from "./types.js";
/**
 * A session that is available for stacking new work onto.
 * Terminal sessions (completed/error/timeout) are all stackable as long as
 * the session ID exists and is valid in the SDK.
 */
export interface StackableSession {
    /** The child session ID to stack onto. */
    childSessionId: string;
    /** The agent that ran in this session. */
    agent: string;
    /** Terminal status of the session. */
    status: DelegationStatus;
    /** When the session was created. */
    createdAt: number;
    /** When the session reached terminal state. */
    completedAt?: number;
    /** Original delegation ID. */
    delegationId: string;
    /** Ready-to-use command for the `task` tool. */
    taskCommand: string;
    /** Ready-to-use command for the `delegate-task` tool. */
    delegateTaskCommand: string;
    /** Human-readable reason why this session is stackable. */
    reason: string;
    /** Error message if the session failed — useful for retry context. */
    error?: string;
    /** Last known output excerpt. */
    finalMessageExcerpt?: string;
}
/**
 * A retry recommendation produced after a delegation fails.
 * Contains everything the calling agent needs to retry by stacking.
 */
export interface RetryRecommendation {
    /** The failed session to stack onto. */
    childSessionId: string;
    /** Agent to use for retry. */
    agent: string;
    /** Pre-formatted retry prompt that references the original task. */
    retryPrompt: string;
    /** Ready-to-use `task` tool invocation. */
    taskCommand: string;
    /** Ready-to-use `delegate-task` tool invocation. */
    delegateTaskCommand: string;
    /** Original error that caused the failure. */
    originalError?: string;
    /** Banner message for the agent. */
    guidance: string;
}
/**
 * Finds all sessions that are available for stacking new work onto.
 *
 * Scans delegation records for terminal sessions (completed, error, timeout)
 * and returns them ranked by recency (most recent first).
 *
 * @param delegations - All known delegation records (in-memory + persisted + session-tracker).
 * @param agentFilter - Optional agent name filter to match specific agents.
 * @param parentSessionFilter - Optional parent session filter for scoping.
 * @returns Ranked list of stackable sessions.
 */
export declare function findStackableSessions(delegations: Delegation[], agentFilter?: string, parentSessionFilter?: string): StackableSession[];
/**
 * Finds all sessions that are still active (dispatched/running) and can be resumed.
 *
 * @param delegations - All known delegation records.
 * @param parentSessionFilter - Optional parent session filter.
 * @returns Active sessions that can be resumed.
 */
export declare function findResumableSessions(delegations: Delegation[], parentSessionFilter?: string): StackableSession[];
/**
 * Builds a retry recommendation for a failed delegation.
 * Produces a structured recommendation with ready-to-use commands
 * that stack onto the failed session instead of creating a new one.
 *
 * @param delegation - The failed delegation record.
 * @param customRetryPrompt - Optional custom prompt for the retry. Defaults to continuation prompt.
 * @returns A complete retry recommendation, or null if the delegation isn't retryable.
 */
export declare function getRetryRecommendation(delegation: Delegation, customRetryPrompt?: string): RetryRecommendation | null;
/**
 * Builds the properly formatted context JSON for stacking onto a session
 * via the `delegate-task` tool's `context` parameter.
 *
 * @param sessionId - The session ID to stack onto.
 * @returns JSON string for the `context` parameter.
 */
export declare function buildStackOnContext(sessionId: string): string;
/**
 * Generates a stacking guidance banner for tool output.
 * Used by delegation-status list and find-stackable actions to proactively
 * inform agents about stackable sessions.
 *
 * @param stackableCount - Number of stackable sessions found.
 * @param resumableCount - Number of resumable sessions found.
 * @returns Human-readable guidance banner.
 */
export declare function buildStackingGuidanceBanner(stackableCount: number, resumableCount: number): string;
//# sourceMappingURL=session-intelligence.d.ts.map