/**
 * Session Engine Operations — business logic layer.
 *
 * Contains all session domain logic migrated from
 * `packages/cleo/src/dispatch/engines/session-engine.ts` (ENG-MIG-6 / T1573).
 *
 * Each exported function returns `EngineResult` and is importable from
 * `@cleocode/core/internal` so the CLI dispatch layer can call them without
 * any intermediate engine file.
 *
 * @task T1573 — ENG-MIG-6
 * @epic T1566
 */
import type { Session, SessionSummaryInput, TaskWorkState } from '@cleocode/contracts';
import { type EngineResult } from '../engine-result.js';
import { type ContextInjectionData } from '../sessions/context-inject.js';
import { type DebriefData, type DecisionRecord, type FindSessionsParams, type HandoffData, type MinimalSessionRecord, type SessionBriefing } from '../sessions/index.js';
import { type TaskWorkHistoryEntry } from '../task-work/index.js';
/**
 * Get current session status.
 *
 * Returns whether there is an active session, along with the session record,
 * current task work state, and the running CLEO_OWNER_OVERRIDE count for
 * the active session (T1501 / P0-5).
 *
 * @param projectRoot - Absolute path to the project root
 * @returns EngineResult with active session flag, session record, task work
 *   state, and `overrideCount` for the active session.
 *
 * @task T1573
 */
export declare function sessionStatus(projectRoot: string): Promise<EngineResult<{
    hasActiveSession: boolean;
    session?: Session | null;
    taskWork?: TaskWorkState | null;
    /** Running CLEO_OWNER_OVERRIDE count for the active session. */
    overrideCount: number;
}>>;
/**
 * Rebind the calling shell's env to a specific session (T9975).
 *
 * Returns a shell export command that the caller should eval in its shell.
 * This is the recommended approach for multi-agent handoffs: agent B calls
 * `cleo session adopt <id>` to start working in the context of agent A's
 * session without restarting it.
 *
 * The session must exist and be active. The caller is responsible for
 * printing and evaluating the returned `exportCommand`.
 *
 * @param projectRoot - Absolute path to the project root
 * @param sessionId - Session ID to adopt
 * @returns EngineResult with exportCommand and sessionId
 *
 * @task T9975
 */
export declare function sessionAdopt(projectRoot: string, sessionId: string): Promise<EngineResult<{
    sessionId: string;
    exportCommand: string;
    envVar: 'CLEO_SESSION_ID';
}>>;
/**
 * List sessions with budget enforcement.
 *
 * Defaults to 10 results when no explicit limit is provided to protect
 * agent context budgets. Includes `_meta.truncated` and `_meta.total`
 * so agents know when the result set was capped.
 *
 * @param projectRoot - Absolute path to the project root
 * @param params - Optional filter and pagination parameters
 * @returns EngineResult with sessions array, total, filtered count, and truncation metadata
 *
 * @task T1573
 */
export declare function sessionList(projectRoot: string, params?: {
    active?: boolean;
    status?: string;
    limit?: number;
    offset?: number;
    all?: boolean;
}): Promise<EngineResult<{
    sessions: Session[];
    total: number;
    filtered: number;
    _meta: {
        truncated: boolean;
        total: number;
    };
}>>;
/**
 * Lightweight session discovery — returns minimal session records.
 *
 * Optimized for low context cost. Returns only essential fields (ID, status,
 * scope, timestamps) without full session details.
 *
 * @param projectRoot - Absolute path to the project root
 * @param params - Optional search parameters
 * @returns EngineResult with array of minimal session records
 *
 * @task T1573
 */
export declare function sessionFind(projectRoot: string, params?: FindSessionsParams): Promise<EngineResult<MinimalSessionRecord[]>>;
/**
 * Show a specific session by ID.
 *
 * @param projectRoot - Absolute path to the project root
 * @param sessionId - Session identifier to look up
 * @returns EngineResult with the full Session record
 *
 * @task T1573
 */
export declare function sessionShow(projectRoot: string, sessionId: string): Promise<EngineResult<Session>>;
/**
 * Get current task being worked on.
 *
 * @param projectRoot - Absolute path to the project root
 * @returns EngineResult with currentTask and currentPhase
 *
 * @task T1573
 */
export declare function taskCurrentGet(projectRoot: string): Promise<EngineResult<{
    currentTask: string | null;
    currentPhase: string | null;
}>>;
/**
 * Start working on a specific task.
 *
 * @param projectRoot - Absolute path to the project root
 * @param taskId - Task ID to start working on
 * @returns EngineResult with taskId and previousTask
 *
 * @task T1573
 */
export declare function taskStart(projectRoot: string, taskId: string): Promise<EngineResult<{
    taskId: string;
    previousTask: string | null;
}>>;
/**
 * Stop working on the current task.
 *
 * @param projectRoot - Absolute path to the project root
 * @returns EngineResult with cleared flag and previousTask
 *
 * @task T1573
 */
export declare function taskStop(projectRoot: string): Promise<EngineResult<{
    cleared: boolean;
    previousTask: string | null;
}>>;
/**
 * Get task work history from session notes.
 *
 * @param projectRoot - Absolute path to the project root
 * @returns EngineResult with history entries and count
 *
 * @task T1573
 */
export declare function taskWorkHistory(projectRoot: string): Promise<EngineResult<{
    history: TaskWorkHistoryEntry[];
    count: number;
}>>;
/**
 * Start a new session.
 *
 * Validates scope, guards against active session conflicts, chains session
 * links, computes auto-briefing, and appends a session_start journal entry.
 *
 * @param projectRoot - Absolute path to the project root
 * @param params - Session start parameters including scope, name, and options
 * @returns EngineResult with the newly created Session (enriched with briefing)
 *
 * @task T1573
 */
export declare function sessionStart(projectRoot: string, params: {
    scope: string;
    name?: string;
    autoStart?: boolean;
    startTask?: string;
    /** Enable full query+mutation audit logging for behavioral grading. */
    grade?: boolean;
    /**
     * Human-readable agent handle for multi-agent isolation (T9975).
     *
     * When provided, the conflict check is scoped to sessions sharing the same
     * agent handle: a new session is allowed if no active session with this
     * exact handle exists. This enables N concurrent agents to run in parallel
     * without briefing surface collisions.
     */
    agentHandle?: string;
}): Promise<EngineResult<Session>>;
/**
 * End the caller's session, scoped env-first (T11346 · Epic T11284).
 *
 * Clears the per-session focus state, updates session status, optionally builds
 * a summarization prompt, and appends a session_end journal entry.
 *
 * T11346 — the target session is resolved env-first (the CALLER's session via
 * `resolveCurrentSession`), NOT `getActiveSession()` (most-recent active row).
 * An explicit `params.sessionId` overrides env/active resolution. This means
 * one agent calling `cleo session end` can no longer end a different
 * concurrently-active agent's session — it ends ITS own, or no-ops with
 * `E_SESSION_NOT_FOUND` for a session it does not own.
 *
 * @param projectRoot - Absolute path to the project root
 * @param notes - Optional notes to record
 * @param params - Optional session summary input + explicit target session id
 * @returns EngineResult with sessionId, ended flag, and optional memoryPrompt
 *
 * @task T1573
 * @task T11346
 */
export declare function sessionEnd(projectRoot: string, notes?: string, params?: {
    sessionSummary?: SessionSummaryInput;
    sessionId?: string;
}): Promise<EngineResult<{
    sessionId: string;
    ended: boolean;
    memoryPrompt?: string;
}>>;
/**
 * Resume an ended or suspended session.
 *
 * @param projectRoot - Absolute path to the project root
 * @param sessionId - Session ID to resume
 * @returns EngineResult with the resumed Session
 *
 * @task T1573
 */
export declare function sessionResume(projectRoot: string, sessionId: string): Promise<EngineResult<Session>>;
/**
 * Garbage collect old sessions.
 *
 * @param projectRoot - Absolute path to the project root
 * @param maxAgeDays - Maximum age in days before marking active sessions orphaned
 * @returns EngineResult with orphaned and removed session IDs
 *
 * @task T1573
 */
export declare function sessionGc(projectRoot: string, maxAgeDays?: number): Promise<EngineResult<{
    orphaned: string[];
    removed: string[];
}>>;
/**
 * Suspend an active session.
 *
 * @param projectRoot - Absolute path to the project root
 * @param sessionId - Session ID to suspend
 * @param reason - Optional suspension reason
 * @returns EngineResult with the suspended Session
 *
 * @task T1573
 */
export declare function sessionSuspend(projectRoot: string, sessionId: string, reason?: string): Promise<EngineResult<Session>>;
/**
 * List session history with focus changes and completed tasks.
 *
 * @param projectRoot - Absolute path to the project root
 * @param params - Optional filter parameters
 * @returns EngineResult with session history entries
 *
 * @task T1573
 */
export declare function sessionHistory(projectRoot: string, params?: {
    sessionId?: string;
    limit?: number;
}): Promise<EngineResult<{
    sessions: Array<{
        id: string;
        name?: string;
        status: string;
        startedAt: string;
        endedAt?: string | null;
        tasksCompleted: number;
        focusChanges: number;
        focusHistory: Array<{
            taskId: string;
            timestamp: string;
        }>;
    }>;
}>>;
/**
 * Remove orphaned sessions and clean up stale data.
 *
 * @param projectRoot - Absolute path to the project root
 * @returns EngineResult with removed, autoEnded, and cleaned status
 *
 * @task T1573
 */
export declare function sessionCleanup(projectRoot: string): Promise<EngineResult<{
    removed: string[];
    autoEnded: string[];
    cleaned: boolean;
}>>;
/**
 * Record a decision to the audit trail.
 *
 * When `sessionId` is omitted, resolves to the active session.
 *
 * @param projectRoot - Absolute path to the project root
 * @param params - Decision recording parameters
 * @returns EngineResult with the recorded DecisionRecord
 *
 * @task T1573
 */
export declare function sessionRecordDecision(projectRoot: string, params: {
    sessionId?: string;
    taskId: string;
    decision: string;
    rationale: string;
    alternatives?: string[];
}): Promise<EngineResult<DecisionRecord>>;
/**
 * Read the decision log, optionally filtered by sessionId and/or taskId.
 *
 * @param projectRoot - Absolute path to the project root
 * @param params - Optional filter parameters
 * @returns EngineResult with array of DecisionRecord entries
 *
 * @task T1573
 */
export declare function sessionDecisionLog(projectRoot: string, params?: {
    sessionId?: string;
    taskId?: string;
}): Promise<EngineResult<DecisionRecord[]>>;
/**
 * Compute context drift score for the current session.
 *
 * @param projectRoot - Absolute path to the project root
 * @param params - Optional session filter
 * @returns EngineResult with drift score, factors, and scope counts
 *
 * @task T1573
 */
export declare function sessionContextDrift(projectRoot: string, params?: {
    sessionId?: string;
}): Promise<EngineResult<{
    score: number;
    factors: string[];
    completedInScope: number;
    totalInScope: number;
    outOfScope: number;
}>>;
/**
 * Record an assumption made during a session.
 *
 * @param projectRoot - Absolute path to the project root
 * @param params - Assumption recording parameters
 * @returns EngineResult with the recorded assumption
 *
 * @task T1573
 */
export declare function sessionRecordAssumption(projectRoot: string, params: {
    sessionId?: string;
    taskId?: string;
    assumption: string;
    confidence: 'high' | 'medium' | 'low';
}): Promise<EngineResult<{
    id: string;
    sessionId: string;
    taskId: string | null;
    assumption: string;
    confidence: string;
    timestamp: string;
}>>;
/**
 * Compute session statistics, optionally for a specific session.
 *
 * @param projectRoot - Absolute path to the project root
 * @param sessionId - Optional session ID to filter
 * @returns EngineResult with aggregate statistics
 *
 * @task T1573
 */
export declare function sessionStats(projectRoot: string, sessionId?: string): Promise<EngineResult<{
    totalSessions: number;
    activeSessions: number;
    suspendedSessions: number;
    endedSessions: number;
    archivedSessions: number;
    totalTasksCompleted: number;
    totalFocusChanges: number;
    averageResumeCount: number;
    session?: {
        id: string;
        status: string;
        tasksCompleted: number;
        focusChanges: number;
        resumeCount: number;
        durationMinutes: number;
    };
}>>;
/**
 * Switch to a different session.
 *
 * @param projectRoot - Absolute path to the project root
 * @param sessionId - Session ID to switch to
 * @returns EngineResult with the switched Session
 *
 * @task T1573
 */
export declare function sessionSwitch(projectRoot: string, sessionId: string): Promise<EngineResult<Session>>;
/**
 * Archive old/ended sessions.
 *
 * @param projectRoot - Absolute path to the project root
 * @param olderThan - Optional ISO date string; sessions older than this are archived
 * @returns EngineResult with archived session IDs and count
 *
 * @task T1573
 */
export declare function sessionArchive(projectRoot: string, olderThan?: string): Promise<EngineResult<{
    archived: string[];
    count: number;
}>>;
/**
 * Get handoff data for the most recent ended session.
 *
 * @param projectRoot - Absolute path to the project root
 * @param scope - Optional scope filter
 * @returns EngineResult with handoff data or null
 *
 * @task T1573
 */
export declare function sessionHandoff(projectRoot: string, scope?: {
    type: string;
    epicId?: string;
}): Promise<EngineResult<{
    sessionId: string;
    handoff: HandoffData;
} | null>>;
/**
 * Compute and persist handoff data for a session.
 *
 * @param projectRoot - Absolute path to the project root
 * @param sessionId - Session ID to compute handoff for
 * @param options - Optional note and nextAction
 * @returns EngineResult with computed HandoffData
 *
 * @task T1573
 */
export declare function sessionComputeHandoff(projectRoot: string, sessionId: string, options?: {
    note?: string;
    nextAction?: string;
}): Promise<EngineResult<HandoffData>>;
/**
 * Compute session briefing — composite view for session start.
 *
 * Aggregates data from handoff, current focus, next tasks, bugs, blockers, and epics.
 *
 * @param projectRoot - Absolute path to the project root
 * @param options - Optional briefing configuration
 * @returns EngineResult with SessionBriefing data
 *
 * @task T1573
 */
export declare function sessionBriefing(projectRoot: string, options?: {
    maxNextTasks?: number;
    maxBugs?: number;
    maxBlocked?: number;
    maxEpics?: number;
    scope?: string;
    /**
     * Explicit session ID to scope the briefing to (T9975).
     *
     * When provided, the briefing is scoped to this specific session
     * rather than the most-recent active session. Used by agents that
     * have their own `CLEO_SESSION_ID` env var set.
     */
    sessionId?: string;
}): Promise<EngineResult<SessionBriefing>>;
/**
 * Compute and persist rich debrief data for a session.
 *
 * Persists as both handoffJson (backward compat) and debriefJson (rich data).
 *
 * @param projectRoot - Absolute path to the project root
 * @param sessionId - Session ID to compute debrief for
 * @param options - Optional note and nextAction
 * @returns EngineResult with computed DebriefData
 *
 * @epic T4959
 * @task T1573
 */
export declare function sessionComputeDebrief(projectRoot: string, sessionId: string, options?: {
    note?: string;
    nextAction?: string;
}): Promise<EngineResult<DebriefData>>;
/**
 * Read a session's debrief data.
 *
 * Falls back to handoff data if no debrief is available.
 *
 * @param projectRoot - Absolute path to the project root
 * @param sessionId - Session ID to retrieve debrief for
 * @returns EngineResult with DebriefData, fallback handoff, or null
 *
 * @epic T4959
 * @task T1573
 */
export declare function sessionDebriefShow(projectRoot: string, sessionId: string): Promise<EngineResult<DebriefData | {
    handoff: unknown;
    fallback: true;
} | null>>;
/**
 * Show the session chain for a given session.
 *
 * Returns ordered list of sessions linked via previousSessionId/nextSessionId.
 *
 * @param projectRoot - Absolute path to the project root
 * @param sessionId - Anchor session ID
 * @returns EngineResult with ordered chain entries
 *
 * @epic T4959
 * @task T1573
 */
export declare function sessionChainShow(projectRoot: string, sessionId: string): Promise<EngineResult<Array<{
    id: string;
    status: string;
    startedAt: string;
    endedAt: string | null;
    agentIdentifier: string | null;
    position: number;
}>>>;
/**
 * Inject context protocol content.
 *
 * @param protocolType - The protocol type to inject
 * @param params - Optional taskId and variant
 * @param projectRoot - Optional project root
 * @returns EngineResult with injected context data
 *
 * @task T1573
 */
export declare function sessionContextInject(protocolType: string, params?: {
    taskId?: string;
    variant?: string;
}, projectRoot?: string): EngineResult<ContextInjectionData>;
//# sourceMappingURL=engine-ops.d.ts.map