/**
 * Spawn Backend Abstraction (Issue #1377)
 *
 * Defines a thin `SpawnBackend` interface with two implementations:
 * - `TaskSpawnBackend` — spawns agents via `task` tool (CLI / VS Code)
 * - `SessionSpawnBackend` — spawns agents as sub-sessions via `create_session` (Copilot App)
 *
 * The coordinator detects which backend to use at startup via `detectSpawnBackend()`.
 * If App backend fails, it gracefully degrades to the task backend (fallback).
 */
/** Platform environment for spawn dispatch */
export type SpawnPlatform = 'cli' | 'app' | 'vscode';
/** Configuration for spawning an agent */
export interface SpawnRequest {
    /** Agent name (lowercase cast name) */
    agentName: string;
    /** Full prompt to send to the spawned agent */
    prompt: string;
    /** Human-readable description (e.g., "🔧 EECOM: Refactoring auth module") */
    description: string;
    /** Short name for UI display (lowercase cast name) */
    name: string;
    /** Model to use */
    model?: string;
    /** Reasoning effort override */
    reasoningEffort?: string;
    /** Context tier override (context window size) */
    contextTier?: string;
    /** Whether the spawned work produces commits (sub-session only) */
    producesCommits?: boolean;
    /** Whether to run in background */
    background?: boolean;
}
/** Handle to a spawned agent — allows result collection and status checks */
export interface SpawnHandle {
    /** Unique identifier for the spawned agent/session */
    id: string;
    /** Agent name */
    agentName: string;
    /** Which backend was used */
    platform: SpawnPlatform;
    /** Whether the spawn succeeded */
    success: boolean;
    /** Error message if spawn failed */
    error?: string;
}
/** Session object returned by the injected session factory */
export interface SpawnedSession {
    /** Unique session identifier */
    sessionId: string;
    /** Send the initial message when kickoff is not handled by session creation */
    sendMessage: (opts: {
        prompt: string;
        mode?: 'enqueue' | 'immediate';
    }) => Promise<void>;
}
/** Session creation callback injected by SDK callers */
export type CreateSessionFn = (config: any) => Promise<SpawnedSession>;
/**
 * Default timeout (ms) applied to an injected `createSession` call so a hung
 * factory cannot hold a concurrency slot / pending-spawn counter forever.
 */
export declare const DEFAULT_CREATE_SESSION_TIMEOUT_MS = 60000;
/** Error thrown when an injected createSession call exceeds its timeout. */
export declare class SpawnTimeoutError extends Error {
    constructor(ms: number);
}
/** Options shared by all spawn backends. */
export interface SpawnBackendOptions {
    /**
     * Timeout (ms) for the injected `createSession` call.
     * Defaults to {@link DEFAULT_CREATE_SESSION_TIMEOUT_MS}; set to 0 to disable.
     */
    createSessionTimeoutMs?: number;
    /**
     * Optional availability predicate. When provided, `isAvailable()` delegates
     * to it instead of the default heuristic — letting callers gate a backend on
     * real environment signals (e.g., tool-registry membership).
     */
    availabilityCheck?: () => boolean;
}
/** Options for sub-session creation (App mode) */
export interface SessionSpawnOptions extends SpawnBackendOptions {
    /** Project ID for session creation */
    projectId?: string;
    /** Whether to coordinate with creator session */
    coordinateWithCreator?: boolean;
    /** Notification preference when session goes idle */
    notifyOnIdle?: 'once' | 'always';
    /** Maximum concurrent sub-sessions (default: 5) */
    maxConcurrent?: number;
    /** Session mode */
    mode?: 'plan' | 'interactive' | 'autopilot';
}
/**
 * Abstract interface for agent spawn dispatch.
 * Implementations handle platform-specific spawn mechanics.
 */
export interface SpawnBackend {
    /** Platform this backend targets */
    readonly platform: SpawnPlatform;
    /**
     * Spawn an agent with the given request.
     * Returns a handle for tracking the spawned agent.
     */
    spawn(request: SpawnRequest): Promise<SpawnHandle>;
    /**
     * Release a previously spawned handle once the caller observes completion.
     * Backends that enforce concurrency caps must decrement their tracking here.
     */
    release(handle: SpawnHandle): void;
    /**
     * Check if this backend is available in the current environment.
     * Used by detectSpawnBackend() to pick the right implementation.
     */
    isAvailable(): boolean;
}
/**
 * Spawns agents via the injected session factory for CLI / VS Code contexts.
 * In prompt-only tool contexts, the coordinator LLM maps this abstraction to the `task` tool.
 */
export declare class TaskSpawnBackend implements SpawnBackend {
    private readonly createSession;
    readonly platform: SpawnPlatform;
    private options;
    constructor(createSession: CreateSessionFn, options?: SpawnBackendOptions);
    isAvailable(): boolean;
    spawn(request: SpawnRequest): Promise<SpawnHandle>;
    release(_handle: SpawnHandle): void;
}
/**
 * Spawns agents as sub-sessions via the injected session factory for Copilot App contexts.
 * Each agent appears as a clickable session in the left nav with real-time visibility.
 *
 * Design constraints:
 * - Max depth: 1 (no sub-sub-sessions)
 * - Concurrency cap: configurable, default 5
 * - Only for commit-producing work; pure analysis uses task backend
 * - Naming: "{Name} {verb}ing {noun}" (40-char max, sentence case)
 */
export declare class SessionSpawnBackend implements SpawnBackend {
    private readonly createSession;
    readonly platform: SpawnPlatform;
    private options;
    private activeSessionIds;
    private pendingSpawnCount;
    constructor(createSession: CreateSessionFn, options?: SessionSpawnOptions);
    isAvailable(): boolean;
    spawn(request: SpawnRequest): Promise<SpawnHandle>;
    release(handle: SpawnHandle): void;
    /** Get current active session count */
    getActiveCount(): number;
}
/**
 * Detect which spawn backend to use based on available tools.
 *
 * Detection order:
 * 1. `create_session` tool available → App mode (SessionSpawnBackend)
 * 2. `task` tool available → CLI mode (TaskSpawnBackend)
 * 3. Neither → fallback to TaskSpawnBackend
 *
 * @param availableTools - Set of tool names available in the current environment
 * @param createSession - Injected session creation callback used by the selected backend
 * @param options - Options for SessionSpawnBackend if App mode is detected
 */
export declare function detectSpawnBackend(availableTools: ReadonlySet<string> | string[], createSession: CreateSessionFn, options?: SessionSpawnOptions): SpawnBackend;
/**
 * Detect spawn platform from available tools (returns platform type only).
 *
 * @param availableTools - Set of tool names available in the current environment
 */
export declare function detectSpawnPlatform(availableTools: ReadonlySet<string> | string[]): SpawnPlatform;
/**
 * Truncate a session name to 40 characters (Copilot App limit).
 * Prefers cutting at a word boundary.
 */
export declare function truncateSessionName(name: string): string;
/**
 * Build a session name following the convention: "{Name} {verb}ing {noun}"
 * Example: "Flight reviewing arch", "EECOM refactoring auth"
 */
export declare function buildSessionName(agentName: string, taskVerb: string, taskNoun: string): string;
//# sourceMappingURL=spawn-backend.d.ts.map