/**
 * Session tracker type definitions.
 *
 * All field names use camelCase per REQ-ST-12. These interfaces define the
 * contracts for session knowledge capture files written under
 * `.hivemind/session-tracker/`.
 *
 * @module session-tracker/types
 */
import type { PendingNotification, CompactionCheckpointData, SessionLifecycleState } from "../../shared/types.js";
import type { DelegationRecoveryGuarantee, DelegationTerminalKind } from "../../coordination/delegation/types.js";
/** Configuration passed to the SessionTracker constructor. */
export interface SessionTrackerConfig {
    /** Absolute path to the project root directory. */
    projectRoot: string;
}
/** Reference to a child session from within the parent's `children` array. */
export interface ChildRef {
    /** The child session's unique identifier. */
    sessionID: string;
    /** The filename of the child session JSON file (e.g. "ses_abc.json"). */
    childFile: string;
}
import type { DelegationType } from "./delegation-types.js";
export type { DelegationLifecycleStatus, DelegationType, DelegationEventBase, SessionTrackerEvent, } from "./delegation-types.js";
export { DelegationTypeSchema } from "./delegation-types.js";
/**
 * Main session file frontmatter (YAML section of the `.md` knowledge file).
 * Mirrors the SPEC.md Section 5.1 format with camelCase field names.
 *
 * @example
 * ```typescript
 * const record: SessionRecord = {
 *   sessionID: "ses_1ed9df1adffe2hbJudz3sK60y3",
 *   title: "hm/governance/root/gsd-auditor/audit-phase23@0",
 *   created: "2026-05-10T21:54:36Z",
 *   updated: "2026-05-10T22:08:04Z",
 *   parentSessionID: null,
 *   delegationDepth: 0,
 *   children: [],
 *   continuityIndex: "session-continuity.json",
 *   status: "active",
 * }
 * ```
 */
export interface SessionRecord {
    /** Unique session identifier (e.g. "ses_1ed9df1adffe2hbJudz3sK60y3"). */
    sessionID: string;
    /** ISO 8601 timestamp of session creation. */
    created: string;
    /** ISO 8601 timestamp of last update. */
    updated: string;
    /** Parent session ID, or `null` for root sessions. */
    parentSessionID: string | null;
    /** Delegation depth: 0 = root, 1 = child, 2 = grandchild. */
    delegationDepth: number;
    /** Array of child session references. */
    children: ChildRef[];
    /** Path to the session-local continuity index file. */
    continuityIndex: string;
    /** Session status: active | idle | completed | error. */
    status: string;
    /** Machine-parsable session title in format {framework}/{workflow}/{classification}/{agent}/{purpose}@{depth}. Generated by the session naming service. */
    title?: string;
    /** Last assistant message content for context recovery. */
    lastMessage?: string;
}
/** Metadata about the agent that performed a delegation. */
export interface DelegatedBy {
    /** Name of the delegating agent (e.g. "Hm-L0-Orchestrator"). */
    agentName: string;
    /** Model identifier of the delegating agent (e.g. "DeepSeek V4 Pro"). */
    model: string;
    /** Tool used to delegate (typically "task"). */
    tool: string;
    /** Description of the delegated task. */
    description: string;
    /** The type of subagent dispatched (e.g. "hm-l2-investigator"). */
    subagentType: string;
}
/** Metadata about the primary agent running a child session. */
export interface MainAgent {
    /** Agent display name. */
    name: string;
    /** Model identifier (e.g. "DeepSeek V4 Pro"). */
    model: string;
}
/**
 * A single child entry in the hierarchy manifest (D-07).
 *
 * Each entry tracks a delegated child session and its current status.
 * The hierarchy-manifest.json is the authoritative source for the session
 * delegation tree, replacing ad-hoc gate decisions.
 */
export interface HierarchyManifestChild {
    /** Child session ID. */
    sessionID: string;
    /** Immediate parent session ID. */
    parentSessionID: string;
    /** Root main session ID (the directory owner). */
    rootMainSessionID: string;
    /** Delegation depth (1 = L1, 2 = L2, etc.). */
    delegationDepth: number;
    /** Who delegated this child (agent name). */
    delegatedBy: string;
    /** Subagent type dispatched (e.g. "hm-l2-researcher"). */
    subagentType: string;
    /** ISO 8601 timestamp of child session creation. */
    createdAt: string;
    /** ISO 8601 timestamp of last update. */
    updatedAt: string;
    /** Session status: active | idle | completed | error | aborted | cancelled. */
    status: string;
    /** Turn count for this child session. */
    turnCount: number;
    /** Filename of the child .json file. */
    childFile: string;
    /**
     * Optional discriminator identifying the delegation
     * mechanism that produced this child. See DelegationType in types.ts.
     * Set at WRITE time only (R7). Optional for backward compat (R1).
     */
    delegationType?: DelegationType;
}
/**
 * Hierarchy manifest — authoritative source for the session tree (D-07).
 *
 * Written as `hierarchy-manifest.json` in each root main session directory.
 * Provides a flattened, quickly-lookup-able list of all children for that
 * root main session. Coexists with session-continuity.json (which tracks
 * the hierarchical tree structure).
 */
export interface HierarchyManifest {
    /** Schema version. */
    version: string;
    /** Root main session ID that owns this manifest. */
    rootMainSessionID: string;
    /** ISO 8601 timestamp of last manifest update. */
    lastUpdated: string;
    /** Flattened map of all children (L1, L2, ...) keyed by sessionID. */
    children: Record<string, HierarchyManifestChild>;
    /** Total number of child sessions. */
    totalChildren: number;
    /** Maximum delegation depth observed. */
    maxDepth: number;
}
/** A single tool invocation record within a turn. */
export interface ToolRecord {
    /** Name of the tool invoked (e.g. "skill", "read", "task"). */
    tool: string;
    /** Tool input arguments (pruned to metadata for captured tools). */
    input: unknown;
    /** Pruned/pruned output if applicable, or `undefined` if not captured. */
    outputPruned?: string;
    /** Execution status: "success" | "error" | undefined if unknown. */
    status?: string;
}
/** A single turn (exchange) within a session. */
export interface Turn {
    /** One-based turn number within the session. */
    turn: number;
    /** Actor designation (e.g. "main_l0_agent", "user"). */
    actor: string;
    /** Original actor type before transformation, if applicable. */
    actorTransformedFrom?: string;
    /** Message content text. */
    content: string;
    /** Tool invocations that occurred during this turn. */
    tools: ToolRecord[];
    /** Optional role (e.g., "user", "assistant") to precisely classify the turn. */
    role?: string;
}
/**
 * Child session file contents (SPEC.md Section 5.2).
 * Stored as `.json` under the parent session's subdirectory.
 *
 * @example
 * ```typescript
 * const child: ChildSessionRecord = {
 *   sessionID: "ses_1ed9c5c20ffePWOXce5JQpS5Yk",
 *   parentSessionID: "ses_1ed9df1adffe2hbJudz3sK60y3",
 *   delegationDepth: 1,
 *   delegatedBy: {
 *     agentName: "Hm-L0-Orchestrator",
 *     tool: "task",
 *     description: "Investigate event tracker bugs",
 *     subagentType: "hm-l2-investigator",
 *   },
 *   created: "2026-05-10T21:56:44Z",
 *   updated: "2026-05-10T22:04:47Z",
 *   status: "completed",
 *   mainAgent: { name: "Hm-L2-Investigator", model: "DeepSeek V4 Pro" },
 *   turns: [],
 *   children: [],
 * }
 * ```
 */
export interface ChildSessionRecord {
    /** Unique child session identifier. */
    sessionID: string;
    /** Parent session's unique identifier. */
    parentSessionID: string;
    /** Delegation depth (1 = direct child, 2 = grandchild, etc.). */
    delegationDepth: number;
    /** Metadata about the agent that delegated this child session. */
    delegatedBy: DelegatedBy;
    /** ISO 8601 timestamp of child session creation. */
    created: string;
    /** ISO 8601 timestamp of last update. */
    updated: string;
    /** Session status: active | completed | error. */
    status: string;
    /** Metadata about the agent running this child session. */
    mainAgent: MainAgent;
    /** Ordered array of turns within this child session. */
    turns: Turn[];
    /** Nested child sessions of this child (grandchildren). */
    children: string[];
    /** Last non-user message content, preserved in full for resumption context (RC-4). */
    lastMessage?: string;
    /** Journey array — records tool calls, results, and assistant messages. CP-ST-05-01. */
    journey?: JourneyEntry[];
    /** Pending notifications for this session (from continuity store). REF: REQ-P41B-01 */
    pendingNotifications?: PendingNotification[];
    /** Queue key for slot-managed delegation (from delegation record). REF: REQ-P41B-02 */
    queueKey?: string;
    /** How the delegation terminated (from delegation record). REF: REQ-P41B-02 */
    terminalKind?: DelegationTerminalKind;
    /** Recovery guarantee level (from delegation record). REF: REQ-P41B-02 */
    recoveryGuarantee?: DelegationRecoveryGuarantee;
    /** How the child session was dispatched (from delegation record). REF: REQ-P41B-02 */
    executionMode?: "sdk" | "pty" | "headless";
    /** Compaction checkpoint data (from continuity store). REF: REQ-P41B-02 */
    compactionCheckpoint?: CompactionCheckpointData;
    /** Session lifecycle state (from continuity store). REF: REQ-P41B-02 */
    lifecycle?: SessionLifecycleState;
    /**
     * Optional discriminator identifying the delegation
     * mechanism that produced this child. See DelegationType in types.ts.
     * Mirrored on both ChildSessionRecord AND HierarchyManifestChild to
     * prevent regeneration drift (R9 mitigation). Set at WRITE time only.
     */
    delegationType?: DelegationType;
}
/**
 * A single entry in the session journey log.
 * Records tool calls, results, and assistant messages for audit and recovery.
 * CP-ST-05-01 addition.
 */
export interface JourneyEntry {
    /** ISO 8601 timestamp of the event. */
    timestamp: string;
    /** Type of journey entry: tool_call, tool_result, assistant_message, session_compacted. */
    type: "tool_call" | "tool_result" | "assistant_message" | "session_compacted" | "tool_intelligence_decision";
    /** Content or description of the event. */
    content: string;
    /** Optional metadata (tool name, status, etc.). */
    metadata?: Record<string, unknown>;
}
/** A child entry within the session-local hierarchy tree. */
export interface ChildHierarchyEntry {
    /** Filename of the child session file. */
    file: string;
    /** Delegation depth of this child. */
    depth: number;
    /** Current status of the child session. */
    status: string;
    /** Who delegated this child (agent name or "main_l0_agent"). */
    delegatedBy: string;
    /** Subagent type dispatched (e.g. "hm-l2-researcher"). Optional for backward compat. */
    subagentType?: string;
    /** Nested children map, keyed by child session ID. */
    children: Record<string, ChildHierarchyEntry>;
    /**
     * Optional discriminator identifying the
     * delegation mechanism. Type-erased `string` (not `DelegationType`) because
     * the tree regeneration pass at hierarchy-manifest.ts:285-297 is type-agnostic.
     * Set at WRITE time only. Optional for backward compat (R1).
     */
    delegationType?: string;
}
/**
 * Session-local continuity index (SPEC.md Section 5.3).
 * Lives at `.hivemind/session-tracker/{sessionID}/session-continuity.json`.
 * Tracks the parent-child hierarchy within a single main session.
 */
export interface SessionContinuityIndex {
    /** Schema version (currently "2.0"). */
    version: string;
    /** The main session ID this index belongs to. */
    sessionID: string;
    /** ISO 8601 timestamp of last index update. */
    lastUpdated: string;
    /** Hierarchy tree for this session. */
    hierarchy: {
        /** Root session ID. */
        root: string;
        /** Map of child session IDs to hierarchy entries. */
        children: Record<string, ChildHierarchyEntry>;
    };
    /** Total number of turns recorded. */
    turnCount: number;
    /** Summary of tool invocations by tool name. */
    toolSummary: Record<string, number>;
}
/**
 * Metadata about a main session in the project-level index.
 * Used as values in the `sessions` map of ProjectContinuityIndex.
 */
export interface ProjectSessionEntry {
    /** Relative directory path for this session's files. */
    dir: string;
    /** Filename of the main session .md file. */
    mainFile: string;
    /** Relative path to the session-local continuity index. */
    continuityIndex: string;
    /** ISO 8601 timestamp of session creation. */
    created: string;
    /** ISO 8601 timestamp of last session update. */
    updated: string;
    /** Session status: active | completed | error. */
    status: string;
    /** Number of child sessions. */
    childCount: number;
    /** Maximum delegation depth reached. */
    totalDelegationDepth: number;
}
/**
 * Project-level continuity index (SPEC.md Section 5.4).
 * Lives at `.hivemind/session-tracker/project-continuity.json`.
 * Connects all main sessions across the project.
 */
export interface ProjectContinuityIndex {
    /** Schema version (currently "2.0"). */
    version: string;
    /** Absolute path to the project root directory. */
    projectRoot: string;
    /** ISO 8601 timestamp of last index update. */
    lastUpdated: string;
    /** Map of session IDs to their project-level metadata. */
    sessions: Record<string, ProjectSessionEntry>;
    /** Session IDs in chronological order (oldest first). */
    chronologicalOrder: string[];
}
/**
 * Validates whether a value is a well-formed session ID string.
 *
 * Session IDs must not contain path traversal characters ("/", "\\", "..").
 * Path safety is enforced by sanitizeSessionID and safeSessionPath in
 * atomic-write.ts. This validation rejects only path-injection characters
 * (DEFECT-14).
 *
 * @param id - The value to check.
 * @returns `true` if `id` is a valid session ID string.
 *
 * @example
 * ```typescript
 * isValidSessionID("ses_1ed9df1adffe2hbJudz3sK60y3") // true
 * isValidSessionID("../etc/passwd")   // false
 * isValidSessionID(null)   // false
 * ```
 */
export declare function isValidSessionID(id: unknown): id is string;
/**
 * Minimal validation that a hook payload object contains a valid sessionID.
 * Does not validate the full payload shape — only confirms the object exists
 * and carries a parseable session identifier.
 *
 * @param payload - The hook payload to check.
 * @returns `true` if `payload` is an object with a valid `sessionID` field.
 */
export declare function isValidHookPayload(payload: unknown): boolean;
//# sourceMappingURL=types.d.ts.map