/**
 * CleoOS CANT bridge — Wave 2 + Wave 5 Pi extension.
 *
 * CANONICAL LOCATION: `packages/cleo-os/extensions/cleo-cant-bridge.ts`
 *
 * This file was copied from
 * `packages/cleo/templates/cleoos-hub/pi-extensions/cleo-cant-bridge.ts`
 * (T393). The template path is kept for reference but this file is the
 * authoritative source. A future cleanup wave (post-T381) should remove
 * the template copy once all consumers have migrated.
 *
 * Installed to: $XDG_DATA_HOME/cleo/extensions/cleo-cant-bridge.js
 * Loaded by:    Pi via `--extension <path>` injected by CleoOS cli.ts
 *
 * This bridge discovers `.cant` files across the 3-tier hierarchy at
 * session start, compiles them via `@cleocode/cant`'s `compileBundle()`,
 * and appends the compiled declarations to Pi's system prompt on
 * `before_agent_start`. This gives the LLM awareness of all declared
 * agents, teams, and tools without hand-authored protocol text.
 *
 * 3-tier resolution (T438, ULTRAPLAN Section 2.4):
 *   - Global:  `~/.local/share/cleo/cant/` (lowest precedence)
 *   - User:    `~/.config/cleo/cant/`
 *   - Project: `<cwd>/.cleo/cant/` (highest precedence)
 *   - Override semantics: project > user > global, matched by basename
 *   - Prompt strategy: APPEND (per ULTRAPLAN L6, never replace)
 *
 * Wave 8 additions (T420):
 *   - validate-on-load mental-model injection
 *   - When the spawned agent's CANT definition has a `mentalModel` block,
 *     fetches prior mental-model observations via memoryFind and injects
 *     them into the Pi system prompt with VALIDATE_ON_LOAD_PREAMBLE.
 *   - Exports `VALIDATE_ON_LOAD_PREAMBLE` and `buildMentalModelInjection`
 *     for testability (T421).
 *
 * Requirements:
 *   - `@cleocode/cant` must be installed (provides `compileBundle`)
 *   - Pi coding agent runtime (`@mariozechner/pi-coding-agent`)
 *
 * Guardrails:
 *   - Best-effort: if `@cleocode/cant` is not installed or `.cleo/cant`
 *     does not exist, the bridge is a no-op. NEVER crash Pi.
 *   - NO top-level await; all work happens inside event handlers.
 *   - APPEND to system prompt, never replace.
 *
 * @packageDocumentation
 */
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
/**
 * Preamble text injected into the Pi system prompt when an agent has a
 * `mental_model:` CANT block. The agent MUST re-evaluate each observation
 * against the current project state before acting.
 *
 * Exported so empirical tests (T421) can assert on its presence.
 */
export declare const VALIDATE_ON_LOAD_PREAMBLE: string;
/** Minimal observation shape returned by memoryFind / searchBrainCompact. */
export interface MentalModelObservation {
    id: string;
    type: string;
    title: string;
    date?: string;
}
/**
 * Build the validate-on-load mental-model injection string.
 *
 * Pure function — no I/O, safe to call in tests without a real DB.
 *
 * @param agentName - Name of the spawned agent (used in the header line).
 * @param observations - Prior mental-model observations to list.
 * @returns System-prompt block containing the preamble and numbered observations,
 *          or an empty string when `observations` is empty.
 */
export declare function buildMentalModelInjection(agentName: string, observations: MentalModelObservation[]): string;
/**
 * Cached bundle counts from the last session_start compilation.
 * Used by the banner and status bar entries.
 */
export interface BundleCounts {
    /** Number of agents declared in the CANT bundle. */
    agents: number;
    /** Number of teams declared in the CANT bundle. */
    teams: number;
    /** Number of tools declared in the CANT bundle. */
    tools: number;
    /** Name of the first team in the bundle, or "none" if no teams. */
    teamName: string;
}
/**
 * Build the CleoOS branded session banner lines.
 *
 * Renders a box-drawing banner with the forge aesthetic using purple
 * ANSI accents and the compiled CANT bundle counts.
 *
 * @param counts - Agent, team, and tool counts from the CANT bundle.
 * @param sessionId - The current session ID, if available.
 * @returns An array of pre-formatted ANSI lines for the widget.
 */
export declare function buildSessionBanner(counts: BundleCounts, sessionId: string): string[];
/**
 * Build the memory-bridge system-prompt block appended to every agent.
 *
 * Wraps the raw memory-bridge.md content in a clearly labeled section
 * so the agent knows this is the CLEO project memory context.
 *
 * @param content - The raw memory-bridge.md content.
 * @returns The formatted memory-bridge block for system prompt injection.
 */
export declare function buildMemoryBridgeInjection(content: string): string;
/**
 * The slice of `@cleocode/paths` this extension resolves CLEO dirs through.
 * Loaded at runtime via {@link importCleoModule} (see the module-resolution
 * note at the top of this file).
 */
export interface CleoPathsModule {
    getCleoHome: () => string;
    getCleoPlatformPaths: () => {
        config: string;
    };
}
/**
 * Load `@cleocode/paths`, the SSoT for CLEO's platform dirs.
 *
 * Returns `null` when it cannot be resolved. Callers then skip the global
 * tiers rather than guess a Linux-only `~/.local/share` path that is wrong
 * on macOS and Windows. The first `null` of the process is reported through
 * `warn`, so the skipped tiers are visible without repeating every turn.
 *
 * @param warn - Receives the one-time warning (e.g. `ctx.ui.notify`).
 * @returns The paths module, or null when it cannot be loaded.
 */
export declare function loadCleoPaths(warn?: (message: string) => void): Promise<CleoPathsModule | null>;
/**
 * Reset the one-time warning latch of {@link loadCleoPaths}.
 *
 * @internal Test-only.
 */
export declare function _resetCleoPathsWarningForTests(): void;
/**
 * Resolve the paths for the 3-tier CANT hierarchy.
 *
 * The global tier is `<getCleoHome()>/cant` and the user tier is
 * `<CLEO config dir>/cant`, both from `@cleocode/paths`. When that module is
 * unavailable only the project tier is returned.
 *
 * @param projectDir - The project root directory (for the project tier).
 * @param cleoPaths - The loaded `@cleocode/paths` module, or null.
 * @returns An object with `global`, `user`, and `project` CANT directory paths.
 */
export declare function resolveThreeTierPaths(projectDir: string, cleoPaths: CleoPathsModule | null): {
    global: string | null;
    user: string | null;
    project: string;
};
/**
 * Pi extension factory for the CleoOS CANT bridge.
 *
 * Registers event handlers for `session_start` (compile `.cant` files)
 * and `before_agent_start` (append compiled bundle + mental-model injection
 * to system prompt). Also registers a `/cant:bundle-info` command for
 * introspection.
 *
 * @param pi - The Pi extension API instance.
 */
export default function (pi: ExtensionAPI): void;
//# sourceMappingURL=cleo-cant-bridge.d.ts.map