import type { AssetHealthIssue } from "./asset-health.js";
import type { ValidationResult } from "./asset-pack/validate.js";
import type { AgentAdapter, AgentContext, Blueprint, Domain, Profile, SchemaBundle } from "./schema.js";
import type { PtLogger } from "./log.js";
import type { ManualProgress } from "./manual-track.js";
/** activeProfile 的来源（session_start fallback 命中点）。 */
export type ProfileLoadSource = "flag" | "settings" | "session" | "auto" | "default" | "fallback" | null;
/** pt 注入到 Session Inject 的状态（自报，非检测 Pi）。
 *  - idle：未激活 / 无 segment
 *  - pending：Profile 已加载但还没轮到下一轮 before_agent_start
 *  - injected：本轮 before_agent_start 成功返回注入结果
 *  - failed：本轮 before_agent_start catch 异常 */
export type InjectionState = "idle" | "pending" | "injected" | "failed";
/** 当前追踪的 Manual 实例（LLM 调 pt_doc {action: start} 写入后触发）。
 *  进度（stepDone/stepTotal）不存 session——文件是 single source of truth，
 *  每次 widget 渲染时 parse 文件重新计算。 */
export interface ActiveManual {
    filePath: string;
    procedure: string;
    args: string;
    /** v16.x（P3）：manual 关联的 issue 名（可选）。单向引用——manual 自描述"为哪个 issue 服务"，
     *  不反向改 issue 文档。LLM 读 manual frontmatter 知道关联，用 bash/grep 查 issue 文件即可。
     *  未传时 undefined，frontmatter 无 issue 行（back-compat）。 */
    issue?: string;
    activatedAt: number;
}
/** Session 全量状态。 */
export interface SessionState {
    activeProfile: string | null;
    cachedSegment: string | null;
    cachedBundles: SchemaBundle[] | null;
    cachedAgentContext: AgentContext | null;
    cachedBlueprint: Blueprint | null;
    cachedDomains: Domain[];
    cachedProfile: Profile | null;
    lastCwd: string;
    lastBuiltPrompt: string | null;
    lastCacheHit: boolean;
    activeAdapter: AgentAdapter | null;
    /** v10.x：session 唯一短 id，8 hex（4.3B 组合空间，足够区分并发 pi 进程）。 */
    sessionId: string;
    /** v10.x：per-session 单例 logger（替代 per-transpile 实例化）。 */
    logger: PtLogger | null;
    /** v10.x：当前 activeProfile 的来源（可观测性）。null 表示未加载。 */
    loadedFrom: ProfileLoadSource;
    /** pt 注入到 Session Inject 的状态（footer 三态文字 + widget 依据）。 */
    injectionState: InjectionState;
    /** failed 时存错误消息（footer 追加）。其它状态 null。 */
    injectionError: string | null;
    /** 当前追踪的 Manual 实例（widget + footer 后缀 + 持久化恢复）。 */
    activeManual: ActiveManual | null;
    /** v18.x（issue pt-turncontext-llm-call-trigger 决策 6）：compaction 后重注入线索。
     *  引用指针（domain 名 + 文件路径），非内容缓存——Manual 文件在磁盘（compaction 不影响），
     *  TurnContext 内容靠 domain 名重新触发 pt_inject tool 获取。
     *  compaction 只裁 messages 不裁 extension state（sessionMap 不进 messages），自然存活。 */
    lastTurnRef: {
        turnInjectDomain: string;
        manualPath: string | null;
    } | null;
    /** v12.x：当前 manual widget 的 async parse 缓存（替代原 module-level `cachedManualProgress`）。 */
    cachedManualProgress: ManualProgress | null;
    /** P1：上次 setStatus("pt", ...) 写入的字符串（refreshInjectionFooter 字符串去重缓存）。
     *  进度/injection/profile 都未变时跳过 setStatus IPC，null 表示待首次写入或刚重置。 */
    lastFooterText: string | null;
    /** v14.x（issue pt-asset-migration-visibility Layer 2）：
     *  session_start 批量体检结果——footer 追加 ⚠ N issues + /pt status 暴露。
     *  null = 未扫描（用户加载内置 profile 后才扫描过项目 profile）。 */
    assetHealthIssues: AssetHealthIssue[] | null;
    /** v15.x PR1（§6.7.1）：session_start 一次性 pack 校验结果——/pt status 展示用。 */
    packValidation: ValidationResult[] | null;
    /** v15.x PR1（§6.7.3）：project pack 校验失败时标 true，transpileActive 强制回 guide。 */
    projectPackDegraded: boolean;
    /** issue pt-cold-start-warning-noise（§短期方案 1）：上次 health scan hash。
     *  session_start 体检时计算新 hash，与上次比较——变化才 notify，避免反复警告轰炸。
     *  null = 未扫过（首次启动 / cache miss 后第一次）。 */
    lastHealthHash: string | null;
    /** issue pt-cold-start-warning-noise（§短期方案 3）：pack validation 失败计数。
     *  key = pack 名（results[i].pack），value = 连续失败次数。
     *  跨 session_start 调用累计——同一 session 多次（reload / 切换 profile 触发重 validate）
     *  都增计数。超过阈值（默认 3）才 `ctx.ui.notify`，避免 transient race 噪音。
     *  validation 成功 → 清零该 key（连续失败终止）。 */
    transientValidationFailures: Map<string, number>;
}
/** 默认空 SessionState。 */
export declare function createSessionState(): SessionState;
/** 重置编译产物字段（catch 路径用）。
 *  v13.x（issue pt-no-agent-context-reset-session-state 修复）：
 *  - transpile/session_start/switchProfile 三处 catch 调用本函数
 *  - 避免 stale cachedAgentContext/cachedBlueprint/cachedDomains/cachedProfile/activeAdapter
 *    误导 /pt flows / /pt make-manual 返回旧 Profile 的手册列表（掩盖真实失败）
 *  - 不清 sessionId/logger/lastCwd/activeProfile/loadedFrom/activeManual（生命周期不同：
 *    session_id 标识当前会话、logger 持续写日志、lastCwd 是项目根、activeProfile 是用户意图、
 *    loadedFrom 是来源、activeManual 是手动追踪）
 */
export declare function resetSessionState(s: SessionState): void;
/** 取指定 sessionId 的 state（lazy create）。TUI 模式下只有一个 entry。 */
export declare function getSessionById(sessionId: string): SessionState;
/** 列表所有 session state（debug / 诊断用，如 /pt sessions 列表）。 */
export declare function listAllSessions(): SessionState[];
/** 清空指定 sessionId 的 state（session_shutdown 调用）。 */
export declare function clearSessionById(sessionId: string): void;
/** 清空所有 session state（仅测试 / 重启进程等需要）。 */
export declare function clearAllSessions(): void;
/** 测试 / 诊断：Map 的当前大小。 */
export declare function sessionCount(): number;