/**
 * Party/raid frames renderer — the host-neutral core of the subagent widget
 * (agent-frames-widget capability; design D1-D6 of the borderless redesign,
 * layered on the earlier D2, D3, D5, D9, D10 and subagent-ui-theming-and-style
 * decisions: approach-A style injection and running-record parent scoping).
 *
 * Takes tracker records + presentation options and returns styled lines.
 * Pure formatting/layout: no pi imports, no timers, no IO — unit-testable
 * without a host (ADR 0001; enforced by test/host-import-boundary.test.ts).
 * The pi adapter (`src/host/pi/agent-widget.ts`) owns observer wiring,
 * spinner ticks, `setWidget` calls, theme binding, and the visibility toggle.
 *
 * Layout model (hybrid, borderless):
 * - PARTY FRAMES: side-by-side BORDERLESS blocks (4 rows) for the K most
 *   interesting agents; K and the per-frame width are width-responsive
 *   between `partyFrameMinWidth`/`partyFrameMaxWidth` (cap 5, may be 0). No
 *   outer border, no title border, no spinner — line 0 is a plain
 *   left-aligned name; zones are delimited by background color and gaps
 *   alone. A 3-wide left column (top cell = role/sigil portrait tile, cells
 *   below = harness-color status panel) abuts three labeled bar lanes
 *   (health/mana/cast), each `<label> <bar> <right metric>`. Every lane is
 *   always present — a faded depletion track, a neutral muted track, or the
 *   stateless casting sweep (while a tool runs) / spawning pulse (while an
 *   agent has no session data yet) — never a blank gap.
 * - RAID CELLS: everyone beyond K as borderless 2-row × 4-column cells —
 *   health IS the top row (filling left-to-right), mana IS the bottom row
 *   (remaining budget, draining right-to-left) — filling left-to-right
 *   grid-style with 1-col gaps, wrapping, `+N` overflow cell past the row
 *   cap. No casting sweep at this scale; corner glyphs (harness sigil,
 *   spinner/tool-icon) are the only non-bar content.
 * - STACKING: party frames anchor to the widget's pi region; raid rows stack
 *   on the chat-facing side (aboveEditor → raid above party; belowEditor →
 *   party above raid).
 *
 * Color split (theming change): chrome (name row, neutral tracks) = theme
 * tokens; portrait tile = role color (default harness); status panel =
 * harness color; bars = fixed game colors (red health / blue mana / yellow
 * cast). Every bar's empty/unfilled portion defaults to a DERIVED faded
 * version of its own fill (`fadeHex`), not a fixed near-black; the mana
 * grace reserve is a DERIVED darker blue (same hue, `darkenHex`). Status is
 * carried by glyph, dimming, and the terminal-state overlay text.
 */
import { stripAnsi } from "#src/harness-colors";
import type { PendingEntry } from "#src/spawn-queue";
import type { SubagentRecord } from "#src/types";
import { type WidgetStyle } from "#src/widget-style";
/** Default MAXIMUM party frame width (the resting width). */
export declare const FRAME_WIDTH = 24;
/** Default MINIMUM party frame width — how tight a frame may pack. */
export declare const FRAME_MIN_WIDTH = 16;
/** Party frame height in lines: borderless — name row + 3 bar rows. */
export declare const FRAME_HEIGHT = 4;
/** Hard cap on party slots regardless of width (tui-frames-polish D5). */
export declare const MAX_PARTY_SLOTS = 5;
/** Default raid grid density (tui-frames-polish D5). */
export declare const DEFAULT_RAID_MAX_ROWS = 3;
export declare const DEFAULT_RAID_PER_ROW = 10;
/**
 * Grace-reserve darkening factor (design D3): the leftmost `graceTurns/total`
 * slice of the mana lane renders this fraction darker than the mana fill,
 * same hue — an at-rest reserve, not a red alarm. ~35% luminance drop reads
 * as clearly deeper without going black in either scheme.
 */
export declare const GRACE_RESERVE_DARKEN = 0.35;
/**
 * Raid cell dimensions (borderless redesign D6): two stacked one-line bars,
 * no border. Health is the top row, mana the bottom row.
 */
export declare const CELL_WIDTH = 5;
export declare const CELL_HEIGHT = 2;
/**
 * Casting sweep (design D4): one full stateless bounce cycle. A pure
 * function of `now` — no per-agent animation cursor is stored.
 */
export declare const SWEEP_PERIOD_MS = 1800;
/**
 * Startup window for the "spawning" pulse (widget-frame-fixes D1). The
 * spawning sweep is a TRANSIENT startup cue, not a permanent data-absence
 * state: a data-starved running agent only pulses while it is still within
 * this window of `startedAt`. Past it, a low-telemetry harness (e.g. cmd,
 * which emits no status file, no context tokens, and no per-turn tool events)
 * falls through to its neutral tracks instead of sweeping indefinitely.
 */
export declare const SPAWN_FLOOR_MS = 8000;
/**
 * Whether a record is still within its spawning startup window. A
 * missing/unparseable `startedAt` is treated as within the floor so nothing
 * regresses at t≈0 (the sweep is the safe default for a brand-new record).
 */
export declare function withinSpawnFloor(record: SubagentRecord, now: number): boolean;
/** Timed linger for completed/interrupted agents (design D5). */
export declare const LINGER_COMPLETED_MS = 15000;
/** TTL for the steered/nudged debuff. */
export declare const STEERED_DEBUFF_TTL_MS = 30000;
export declare const BUFF_GLYPH_THINKING = "\u03A8";
export declare const BUFF_GLYPH_WORKTREE = "\u2387";
export declare const BUFF_GLYPH_SANDBOX = "\u26E8";
export declare const DEBUFF_GLYPH_SANDBOX_DEGRADED = "\u26A0";
export declare const DEBUFF_GLYPH_GRACE = "\u25D4";
export declare const DEBUFF_GLYPH_STEERED = "\u27A4";
export declare const DEBUFF_GLYPH_STALE = "\u2026";
export declare const DEBUFF_GLYPH_RESUMED = "\u21BB";
export declare const DEBUFF_GLYPH_FAILED = "\u2717";
export declare const DEBUFF_GLYPH_CRASHED = "\u2620";
export declare const DEBUFF_GLYPH_INTERRUPTED = "\u23F8";
export type DisplayMode = "auto" | "party" | "raid";
/**
 * pi's real widget regions (design D6 rename): `aboveEditor` = between chat
 * and editor (the default), `belowEditor` = between editor and footer.
 */
export type WidgetPlacementSide = "aboveEditor" | "belowEditor";
/** Ownership scope for running/pending records (design D5 scoping). */
export interface VisibilityScope {
    /**
     * Current parent session id. When set, running/pending records owned by a
     * DIFFERENT parent are hidden (undeterminable ownership → hidden too).
     * When absent, no ownership filtering applies (legacy behavior, tests).
     */
    currentParentSessionId?: string;
    /**
     * Registry-liveness predicate: is the agent actively driven by a live
     * controller in THIS session (spawned, resumed, or adopted here)? Live
     * agents count as owned regardless of their stored parentSessionId. Keys
     * on registry liveness, NOT the persisted `resumedAt` (which survives
     * across sessions and would wrongly re-surface old zombies).
     */
    isAgentLive?: (agentId: string) => boolean;
}
export interface FramesOptions {
    /** Viewport width in columns. */
    width: number;
    /** Current time (ms) — injected for testability. */
    now: number;
    /** Current spinner frame character for running agents. */
    spinnerFrame: string;
    /** Display mode (default "auto" = hybrid). */
    displayMode?: DisplayMode;
    /** Widget region — controls stacking order (default "aboveEditor"). */
    placement?: WidgetPlacementSide;
    /**
     * Session epoch (ms): terminal records that ended BEFORE this instant are
     * never shown. Linger — including linger-until-retrieved for failures — is
     * scoped to the session the parent can actually act in; a fresh session
     * starts with a clean widget even though tracker history persists.
     */
    sessionStartAt?: number;
    /**
     * Injected style (approach A — themed chrome via host tokens, fixed game
     * colors emitted host-neutrally). Absent → the static fallback palette.
     */
    style?: WidgetStyle;
    /** See {@link VisibilityScope.currentParentSessionId}. */
    currentParentSessionId?: string;
    /** See {@link VisibilityScope.isAgentLive}. */
    isAgentLive?: (agentId: string) => boolean;
    /**
     * Responsive party-frame width band (design D6). Party frames pack down
     * toward `partyFrameMinWidth` to admit one more member, and grow up to
     * `partyFrameMaxWidth` (never stretched past it). Invalid values, or
     * min > max, fall back to {@link FRAME_MIN_WIDTH}/{@link FRAME_WIDTH}.
     */
    partyFrameMinWidth?: number;
    partyFrameMaxWidth?: number;
    /**
     * Raid grid density (tui-frames-polish D5): the maximum number of raid rows
     * (default {@link DEFAULT_RAID_MAX_ROWS}) and the maximum raid cells per row
     * (default {@link DEFAULT_RAID_PER_ROW}; a narrow terminal may fit fewer).
     * The widget height budget derives from these. Invalid/non-positive values
     * fall back to the defaults.
     */
    raidMaxRows?: number;
    raidPerRow?: number;
}
/**
 * Ownership predicate for running/pending records (design D5 scoping):
 * owned = registry-live in this session OR `parentSessionId` matches
 * (legacy fallback: the `pilot-<parent>` / `_pi-sub-<parent>` prefix of
 * `recoveryId`). Undeterminable ownership → NOT owned (hidden).
 *
 * Shared by the widget's visibility selection AND the spawner's
 * concurrency-cap check, so the enforced cap and the displayed running
 * count can never disagree on what "owned" means.
 */
export declare function isOwnedRunningRecord(r: SubagentRecord, scope: VisibilityScope): boolean;
/**
 * Count the current parent's live running agents — the ONE running count,
 * used both for `maxConcurrentAgents` enforcement (spawner) and the widget's
 * status-bar count, so the two are computed identically.
 *
 * A record counts when it is `running`, owned per {@link isOwnedRunningRecord},
 * and live: registry-live agents (actively driven by a controller in this
 * session) are live by definition; for the rest, the optional `isWindowAlive`
 * callback (backed by `subagentWindowLiveness`) decides — a record whose
 * window is gone or unverifiable is a stale zombie and never consumes a cap
 * slot. Callers without a tmux reach (the widget's render path) omit the
 * callback; their owned records are registry-live in practice, and startup
 * reconciliation has already crashed-out anything with a dead window.
 */
export declare function countOwnedRunningAgents(records: SubagentRecord[], scope: VisibilityScope, isWindowAlive?: (r: SubagentRecord) => boolean): number;
/**
 * Select the records the widget should show right now (design D5):
 * - pending/running: when owned by the current parent session (or unscoped)
 * - completed/interrupted: within the 15s timed linger
 * - failed/crashed: until retrieved via get_subagent_result (then dropped
 *   on the next render tick)
 *
 * All terminal linger is scoped to the current session (`sessionStartAt`):
 * records that ended before it — persisted failures from earlier sessions,
 * and records the startup reconciler marks crashed before the UI attaches —
 * are never shown. Running/pending records are additionally scoped to the
 * current PARENT (`scope`): another (or a previous) parent session's
 * still-running agents never render here. The tracker keeps everything as
 * history for `get_subagent_result`; hidden records just aren't
 * actionable UI.
 */
export declare function selectVisibleAgents(records: SubagentRecord[], now: number, sessionStartAt?: number, scope?: VisibilityScope): SubagentRecord[];
/**
 * Interest ranking for party-slot assignment:
 * unacknowledged failure > newest terminal event > running.
 *
 * Stability rule (v1, per design): within the running class, order is pinned
 * by SPAWN ORDER (startedAt asc, id tiebreak) so frames don't churn as
 * activity fluctuates. Terminal classes order newest-first, which is stable
 * because completedAt never changes after the transition.
 */
export declare function rankAgents(records: SubagentRecord[]): SubagentRecord[];
/** Resolved party-frame width band: defaults on invalid input or min > max. */
export declare function resolvePartyWidthBand(minWidth?: number, maxWidth?: number): {
    min: number;
    max: number;
};
/**
 * Width-responsive party layout (design D6). The slot count is the largest
 * (≤ {@link MAX_PARTY_SLOTS}, ≤ `agentCount`) that fits at `minWidth`; the
 * per-frame width then grows to fill up to `maxWidth`:
 *
 *   maxFrames  = min(MAX_PARTY_SLOTS, floor((W + GAP) / (minWidth + GAP)))
 *   count      = min(maxFrames, agentCount)
 *   frameWidth = min(maxWidth, floor((W - (count-1)*GAP) / count))
 *
 * Frames sit at `maxWidth` when few agents / wide terminal, and pack down
 * toward `minWidth` to admit one more member into the party. Returns count 0
 * (no party) when the terminal can't fit one frame at `minWidth`.
 */
export declare function computePartyLayout(width: number, agentCount: number, minWidth?: number, maxWidth?: number): {
    count: number;
    frameWidth: number;
};
/** Static per-spawn buffs: thinking mode, worktree isolation, OS sandbox. */
export declare function buffGlyphs(record: SubagentRecord): string[];
/**
 * Dynamic lifecycle debuffs: grace turns, steered/nudged (TTL),
 * staleness-suspected (only when enabled for the role), resumed, and the
 * terminal-state debuffs that anchor linger-until-retrieved.
 */
export declare function debuffGlyphs(record: SubagentRecord, now: number): string[];
/** Single-width icon for a running tool name, or undefined if unrecognized. */
export declare function toolIcon(toolName: string | undefined): string | undefined;
/**
 * Stateless triangle-wave bounce position over `[0, width)`, a pure function
 * of `now` — the same `now` always yields the same column, so no per-agent
 * animation cursor is ever stored.
 */
export declare function sweepHeadIndex(now: number, width: number, periodMs?: number): number;
/** Auto-attack band period (design D4) — one L→R traversal of the lane. */
export declare const AUTO_ATTACK_PERIOD_MS = 1600;
/**
 * Unidirectional "thinking" band (design D4): a solid bright segment of
 * `AUTO_ATTACK_BAND_FRACTION` of the lane width that travels left→right and
 * wraps at the end (no bounce). Returns the set of column indices the band
 * currently covers — a pure function of `now`, sibling of {@link sweepHeadIndex}
 * with a different motion (advancing rather than triangle-wave).
 */
export declare function autoAttackBand(now: number, width: number, periodMs?: number): Set<number>;
/**
 * Truncate a STYLED string to a visible width, preserving ANSI sequences and
 * appending a reset so truncation never leaks styling. Safety net for narrow
 * viewports — the layout math should already fit.
 */
export declare function truncateVisible(text: string, width: number): string;
/**
 * Render the widget lines for the current tracker state.
 * Returns `[]` when nothing is visible (the adapter clears the region).
 * Every line's VISIBLE length is ≤ `opts.width` — the layout never overflows
 * horizontally (final truncation is a safety net for pathological widths).
 */
export declare function renderAgentFrames(records: SubagentRecord[], opts: FramesOptions): string[];
/**
 * Render the transient spawn queue as one host-neutral widget line. The queue
 * is additive to the frame height budget; callers append it after the normal
 * party/raid output. Entries use a role override only when it was explicitly
 * resolved at spawn; otherwise harness identity is the sole visual cue.
 */
export declare function renderSpawnQueueLine(entries: readonly PendingEntry[], width: number, style?: WidgetStyle): string | undefined;
export { stripAnsi };
//# sourceMappingURL=agent-frames.d.ts.map