@toddzheng024/dscode-bundle 0.1.0

package/vendor/tui/types/render/projection.d.ts

@@ -0,0 +1,461 @@
+/**
+ * Pure session-event-to-view projection for the TUI transcript: one reducer
+ * over {@link SessionEvent}s producing the ordered entries the renderer draws.
+ * Rendering never reads the session directly — this module owns the view
+ * model, so tests drive it with plain event arrays.
+ *
+ * @module @deepseek-ai/dsh-tui/render/projection
+ */
+import { type ImageBlock, type MessageId, type StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { FileAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { TodoItem } from '@deepseek-ai/dsh-tool-todo';
+import { type ToolDetail } from './tool-detail.ts';
+/** One user prompt line. */
+export interface UserEntry {
+    kind: 'user';
+    /** Joined text blocks of the user message. */
+    text: string;
+    /** True for collapsed injected context (plugin/continuation notices), which
+     * the renderer marks with a dim ↳ instead of the user ❯ prompt. */
+    notice: boolean;
+    /** Durable image references carried by this prompt. */
+    images?: readonly ImageBlock['attachment'][];
+    /** Durable file references carried by this prompt (0.1.5 file blocks). */
+    files?: readonly FileAttachmentRef[];
+}
+/** One user message waiting in the agent inbox (the web's queued-message row). */
+export interface PendingEntry {
+    kind: 'pending';
+    /** Stable message identity shared with the durable `user/message` that retires it. */
+    messageId: MessageId;
+    /** Which inbox list holds the message: steering is consumed at the next step boundary. */
+    target: 'next-turn' | 'next-step';
+    /** Full message text — Codex PendingSteer renders queued prompts exactly like user rows. */
+    text: string;
+    /** Durable image references queued with this prompt. */
+    images?: readonly ImageBlock['attachment'][];
+    /** Durable file references queued with this prompt (0.1.5 file blocks). */
+    files?: readonly FileAttachmentRef[];
+}
+/** One authoritative assembled assistant reply. */
+export interface AssistantEntry {
+    kind: 'assistant';
+    /** Joined text blocks of the assistant message. */
+    text: string;
+    /** Joined reasoning blocks from the same assembled message. */
+    reasoning: string;
+    /** True when a cancelled stream's delivered prefix was finalized as this
+     * entry (rc.8 `assistant/message.interrupted`) — rendered with a marker. */
+    interrupted?: true;
+}
+/** One model-requested tool invocation and its settled state. */
+export interface ToolEntry {
+    kind: 'tool';
+    /** Correlation id shared with the matching `tool/result`. */
+    callId: string;
+    /**
+     * Global tool-call ordinal across the whole transcript (1, 2, 3…, never
+     * reset between turns). The tool-card badge and every error line that
+     * references the failed call share this number, so "call N" in an error
+     * always names the exact card the badge shows.
+     */
+    ordinal: number;
+    /** Tool name as the model addressed it. */
+    name: string;
+    /** Raw arguments JSON string exactly as the model produced it. */
+    arguments: string;
+    /** Bounded human-meaningful arguments preview for the tool card. */
+    preview: string;
+    /** Bounded delegation prompt (subagent cards' second row), '' when none. */
+    prompt: string;
+    /** Execution state; `running` until the paired result lands. */
+    state: 'running' | 'done' | 'error';
+    /** Bounded first text block of the result, empty until it lands. */
+    summary: string;
+    /**
+     * Bounded expansion payload for the verbose transcript (Ctrl+O), derived
+     * from the tool's persisted presentation metadata; undefined until the
+     * result lands and only when something renderable exists.
+     */
+    detail: ToolDetail | undefined;
+}
+/** One slash-command execution dispatched through `ctx.commands`. */
+export interface CommandEntry {
+    kind: 'command';
+    /** Pairing id shared with the matching `command/done`. */
+    commandId: string;
+    /** Lowercase command name without the leading slash. */
+    name: string;
+    /** Verbatim text following the command name. */
+    args: string;
+    /** Execution state; `running` until the paired lifecycle event lands. */
+    state: 'running' | 'done' | 'error';
+    /** Handler outcome text, empty until it lands. */
+    summary: string;
+}
+/** One turn-level failure surfaced from `turn/end`. */
+export interface ErrorEntry {
+    kind: 'error';
+    /** `code: message` of the failure. */
+    text: string;
+}
+/** One non-error turn outcome surfaced from `turn/end`. */
+export interface TurnMarkerEntry {
+    kind: 'turn-marker';
+    /** Human-readable outcome line, dim-rendered. */
+    text: string;
+}
+/** One completed compaction lifecycle surfaced from `compaction/end`. */
+export interface CompactionEntry {
+    kind: 'compaction';
+    /** True when the compaction completed, false when it failed. */
+    ok: boolean;
+    /** Heuristic tokens shadowed by the compaction (summary or prune price). */
+    tokens: number;
+    /** Failure text when `ok` is false, empty otherwise. */
+    error: string;
+}
+/** One provider-routed model-request retry (the `llm/retry` pair). */
+export interface RetryEntry {
+    kind: 'retry';
+    /** Correlation id shared with the matching `llm/retry-started`. */
+    retryId: string;
+    /** Retry policy mode from the event: `always` has no attempt cap. */
+    mode: 'normal' | 'always';
+    /** Attempt ordinal and its cap. */
+    attempt: number;
+    max: number;
+    /** Failure code that triggered the retry. */
+    code: string;
+    /** Backoff wait before the next attempt, in ms. */
+    delayMs: number;
+    /**
+     * `running` while the backoff waits, `done` once the attempt started — or
+     * when the turn ended first (the turn-end sweep finalizes orphans so they
+     * never pin the settled boundary).
+     */
+    state: 'running' | 'done';
+}
+/** Turn-tail deliverables: files mutated by the turn's diff-bearing tools. */
+export interface FilesEntry {
+    kind: 'files';
+    /** Unique mutated paths in call order, bounded. */
+    paths: readonly string[];
+}
+/** Ordered transcript items the renderer draws. */
+export type TranscriptEntry = UserEntry | PendingEntry | AssistantEntry | ToolEntry | CommandEntry | ErrorEntry | TurnMarkerEntry | CompactionEntry | RetryEntry | FilesEntry;
+/** The live goal the status line badges, folded from `goal/change`. */
+export interface GoalFold {
+    /** Human-requested completion objective. */
+    objective: string;
+    /** Durable lifecycle phase. */
+    phase: 'active' | 'paused' | 'blocked' | 'complete';
+    /** Highest admitted continuation round and its cap. */
+    rounds: number;
+    max: number;
+    /** Blocked explanation, empty outside the blocked phase. */
+    blocked: string;
+}
+/** Cumulative token accounting folded from `assistant/message` usage reports. */
+export interface UsageTotals {
+    /** Prompt-side billed tokens: `inputTokens` plus both cache buckets. */
+    inputTokens: number;
+    /** Completion-side tokens over the whole log. */
+    outputTokens: number;
+    /** Cache-read tokens over the whole log (0 when the adapter reports none). */
+    cacheReadTokens: number;
+}
+/**
+ * Estimated used tokens per context content type, folded from transcript
+ * events via {@link estimateTokens}. The segmented context bar's composition
+ * source: proportions across types are meaningful, absolute values are not
+ * (they never touch billing or the reported `lastPromptTokens`).
+ */
+export interface ContextSegments {
+    /** Rendered system-prompt text (latest `request/header`) plus injected-context notices. */
+    system: number;
+    /** Direct human prompts (durable `user/message` rows). */
+    prompt: number;
+    /** Assistant text blocks (visible replies). */
+    assistant: number;
+    /** Assistant reasoning blocks (hidden thinking). */
+    thinking: number;
+    /** Tool call arguments plus result text. */
+    tools: number;
+}
+/** Window-scoped figures the status line shows; timing uses event timestamps. */
+export interface TranscriptStats {
+    /** Durable turns opened (`turn/start` events). */
+    turns: number;
+    /** Model requests made (`step/start` events). */
+    steps: number;
+    /** Summed model wall time: `step/start` → `assistant/message`, in ms. */
+    llmMs: number;
+    /** Summed tool wall time: `tool/call` → `tool/result`, in ms. */
+    toolMs: number;
+    /** Cumulative token accounting; input stays 0 until a report lands. */
+    usage: UsageTotals;
+    /** Prompt-side size of the most recent reported request (context pressure). */
+    lastPromptTokens: number;
+    /** Newest advertised route capacity, 0 when no adapter ever advertised one. */
+    contextWindow: number;
+    /** Estimated used tokens per content type (the segmented bar's composition). */
+    contextSegments: ContextSegments;
+    /** Summed first-token waits: `step/start` → first non-empty chunk, in ms. */
+    ttftMs: number;
+    /** Steps that produced a first chunk (the TTFT average's denominator). */
+    ttftSteps: number;
+    /** Summed decode spans: first chunk → `assistant/message`, in ms. */
+    decodeMs: number;
+    /** Completion tokens over timed decode spans (the tok/s numerator). */
+    decodeTokens: number;
+    /**
+     * Adapter-owned reasoning effort of the latest `request/header` config —
+     * the EFFECTIVE effort the session actually uses (a materialized model
+     * default is included, exactly as the adapter resolved it). Empty when the
+     * header carried none (provider-default behavior). The status line appends
+     * it to the model segment as `provider/model@effort`.
+     */
+    reasoningEffort: string;
+}
+/** The complete TUI transcript view for one session. */
+export interface TranscriptView {
+    /** Settled entries in log order. */
+    entries: readonly TranscriptEntry[];
+    /** Bounded text tail accumulated from live stream frames since the last settlement. */
+    streaming: string;
+    /** Bounded thinking tail accumulated from reasoning deltas since the last flush. */
+    streamingReasoning: string;
+    /** Latest whole-list todo snapshot from `todo/write`, empty when none. */
+    todos: readonly TodoItem[];
+    /**
+     * Global tool-call ordinal counter: the number the NEXT `tool/call` lands
+     * with (1-based). Never reset, so the counter and the badges/error lines
+     * stay consistent across turns and resumed sessions.
+     */
+    toolCallOrdinal: number;
+    /** True while a durable turn is open (`turn/start` … `turn/end`). */
+    busy: boolean;
+    /** `turn/start` time of the open turn (0 while idle) — the web TurnStatus clock anchor. */
+    busySince: number;
+    /** Figures the status line renders. */
+    stats: TranscriptStats;
+    /**
+     * The `provider/model` pair of the last `request/header` snapshot — the
+     * session's own model record, which a resumed TUI prefers over the
+     * deployment default (mirrors the web host's resume selection order).
+     * Empty before the session's first request.
+     */
+    model: string;
+    /** Plan mode state folded from the last `plan/mode` event. */
+    plan: boolean;
+    /** Active permission preset folded from the last `permission/preset` event, empty before one. */
+    permission: string;
+    /** Latest session title folded from the last `session/title` event, empty before one. */
+    title: string;
+    /**
+     * Effective system prompt assembled from `system/message` surface nodes
+     * (v3): the head node's text joined with every later non-empty node, blank
+     * lines between. Empty before the first system node or when every node is
+     * empty ("no system prompt").
+     */
+    systemPrompt: string;
+    /** Sandbox-mode override folded from the last `sandbox/mode` event, empty when never switched. */
+    sandbox: string;
+    /** Current long-running goal folded from the last `goal/change`, undefined when cleared. */
+    goal: GoalFold | undefined;
+    /**
+     * Ordered live message ids per inbox target, mirrored from
+     * `agent/inbox/spliced` exactly like the upstream Inbox projection — the
+     * coordinates later removals resolve against.
+     */
+    pending: {
+        'next-turn': readonly string[];
+        'next-step': readonly string[];
+    };
+    /**
+     * Fold-internal timing anchors, never rendered: open step and tool-call
+     * start timestamps the next `assistant/message` / `tool/result` resolves
+     * against. Keyed `turn:step` and by call id. `turnSteps`/`turnTools`
+     * track which step/tool anchors still belong to the open turn so
+     * `turn/end` (and a superseding `step/start`) can sweep anchors an
+     * interruption left behind; `turnFiles` keys mutated paths by turn.
+     */
+    readonly anchors: {
+        stepStart: Map<string, number>;
+        toolStart: Map<string, number>;
+        firstChunkAt: Map<string, number>;
+        compactionTokens: Map<string, number>;
+        lastPruneTokens: number;
+        turnFiles: Map<number, Set<string>>;
+        turnSteps: Map<number, string>;
+        turnTools: Map<number, Set<string>>;
+        /** Live `system/message` surface nodes by event seq (empty string = an empty node). */
+        systemNodes: Map<number, string>;
+    };
+}
+/** Human-readable bounded image labels for transcript, inspector, and export surfaces. */
+export declare function imageLabels(images: readonly ImageBlock['attachment'][] | undefined): string;
+/** Human-readable bounded file labels for the same surfaces (0.1.5 file blocks). */
+export declare function fileLabels(files: readonly FileAttachmentRef[] | undefined): string;
+/** Prompt text with its durable image and file labels, without exposing local paths or bytes. */
+export declare function promptDisplayText(entry: Pick<UserEntry | PendingEntry, 'text' | 'images' | 'files'>): string;
+/** A fresh, empty transcript view. */
+export declare function createTranscriptView(): TranscriptView;
+/**
+ * Fold one session event into an updated view (copy-on-write).
+ * @param view - the view before the event.
+ * @param event - one durable session event from `session/event` or the log.
+ * @returns the view after the event; the input view is never mutated.
+ */
+export declare function projectEvent(view: TranscriptView, event: SessionEvent): TranscriptView;
+/**
+ * Mutable replay accumulator: folds a persisted log into the identical view
+ * `projectEvent` would produce, but in near-linear time. Where `projectEvent`
+ * is copy-on-write — every append/scan rebuilds the whole `entries` array, so
+ * folding a full log costs O(N²) — the accumulator appends by push, resolves
+ * id-keyed updates (tool/result, command/done, retry-started) through index
+ * maps, and tombstones retired pending rows, so the whole log folds in O(N)
+ * plus one compaction pass when tombstones exist.
+ *
+ * Index maps never delete: every appended row registers its index, so an id
+ * lookup miss provably means no matching row exists and the update is an O(1)
+ * no-op (a malicious/orphan-heavy log cannot force per-orphan full-array
+ * scans). Each id maps to ALL of its indices, so a duplicate id updates every
+ * matching row exactly like the copy-on-write reducer.
+ *
+ * @internal Exported only so tests can (a) prove replay ≡ sequential
+ * `projectEvent` folds and (b) assert the linear complexity deterministically
+ * via {@link ReplayAccumulator.ops}, which counts entry-level container work
+ * instead of relying on wall-clock thresholds. No public consumer.
+ */
+export interface ReplayAccumulator {
+    /** Working entry list; `undefined` marks a retired pending row (tombstone). */
+    entries: (TranscriptEntry | undefined)[];
+    /** callId → every index into `entries` holding a `tool` row with that id. */
+    toolIndex: Map<string, number[]>;
+    /** commandId → every index into `entries` holding a `command` row with that id. */
+    commandIndex: Map<string, number[]>;
+    /** retryId → every index into `entries` holding a `retry` row with that id. */
+    retryIndex: Map<string, number[]>;
+    /** messageId → every index into `entries` holding a `pending` row with that id. */
+    pendingIndex: Map<string, number[]>;
+    /** Tombstone count; zero means `entries` is already the final array. */
+    removedCount: number;
+    /** Mutable inbox id lists, mirroring `view.pending` order per target. */
+    pendingTurn: string[];
+    pendingStep: string[];
+    streaming: string;
+    streamingReasoning: string;
+    todos: readonly TodoItem[];
+    /** Global tool-call ordinal counter (see `TranscriptView.toolCallOrdinal`). */
+    toolCallOrdinal: number;
+    busy: boolean;
+    busySince: number;
+    model: string;
+    plan: boolean;
+    permission: string;
+    title: string;
+    systemPrompt: string;
+    sandbox: string;
+    goal: GoalFold | undefined;
+    stats: TranscriptStats;
+    stepStart: Map<string, number>;
+    toolStart: Map<string, number>;
+    firstChunkAt: Map<string, number>;
+    compactionTokens: Map<string, number>;
+    lastPruneTokens: number;
+    turnFiles: Map<number, Set<string>>;
+    turnSteps: Map<number, string>;
+    turnTools: Map<number, Set<string>>;
+    /** Live `system/message` surface nodes by event seq (empty string = an empty node). */
+    systemNodes: Map<number, string>;
+    /** Entry-level container operations performed so far (test instrumentation). */
+    ops: number;
+}
+/** @internal A fresh replay accumulator whose state mirrors `createTranscriptView()`. */
+export declare function createReplayAccumulator(): ReplayAccumulator;
+/**
+ * Fold one session event into a replay accumulator. This mirrors
+ * {@link projectEvent} case for case — same stats arithmetic, same anchor
+ * set/delete behavior, same entry shapes — so the finished view is identical
+ * to a sequential fold; only the `entries` container operations are mutable.
+ *
+ * @internal Test-instrumentation path; `projectEvents` is the public entry.
+ * @returns whether the event changed the accumulated state — the live store
+ * stays silent and keeps its snapshot identity for ignored events, exactly
+ * like the copy-on-write reducer returning its input view unchanged.
+ */
+export declare function replayProjectEvent(acc: ReplayAccumulator, event: SessionEvent): boolean;
+/**
+ * Materialize the accumulated fold as a `TranscriptView`, compacting any
+ * retired tombstones. The anchors maps are handed through as-is (their
+ * content is identical to a sequential fold's).
+ *
+ * @internal Test-instrumentation path; `projectEvents` is the public entry.
+ */
+export declare function finishReplay(acc: ReplayAccumulator): TranscriptView;
+/**
+ * Materialize the accumulated fold as a fresh immutable snapshot for the
+ * live store. Unlike {@link finishReplay} — the one-shot replay entry, which
+ * hands the accumulator's own arrays through because the accumulator is
+ * discarded — every array a renderer can hold is copied here, so later
+ * folds never mutate a snapshot already handed out. Same fields, same
+ * tombstone compaction.
+ *
+ * @internal Live-store path; `projectEvents` is the public entry.
+ */
+export declare function snapshotReplayView(acc: ReplayAccumulator): TranscriptView;
+/**
+ * Fold a replayed event history into one view.
+ *
+ * Folding is near-linear in the log size: the mutable replay accumulator
+ * appends in place and resolves id-keyed updates through index maps, so a
+ * long persisted session replays without the O(N²) copy-on-write rebuilds a
+ * naive sequential fold would incur. The result is identical to folding
+ * {@link projectEvent} per event in order.
+ * @param events - events in `seq` order.
+ * @returns the folded view.
+ */
+export declare function projectEvents(events: readonly SessionEvent[]): TranscriptView;
+/**
+ * Fold one process-local assistant-stream chunk frame (session-log v2+ keeps
+ * durable logs settlement-only; live typing rides the `agent/assistant-stream`
+ * agent event). Same first-token anchoring the durable `assistant/chunk` event
+ * used to carry: the first non-empty delta anchors the TTFT and empty
+ * keep-alive deltas do not count. The caller maps the frame's attempt to the
+ * `turn:step` key (the start frame owns turn/step; chunk frames do not).
+ * @param acc - the live replay accumulator.
+ * @param key - the `turn:step` key the attempt's start frame declared.
+ * @param time - the frame's safe-integer timestamp.
+ * @param chunk - the model chunk the frame carries.
+ * @returns whether the accumulator changed (the store stays silent otherwise).
+ */
+export declare function applyAssistantStreamChunk(acc: ReplayAccumulator, key: string, time: number, chunk: StreamChunk): boolean;
+/**
+ * Drop the live streaming tails without a settlement (an `agent/assistant-stream`
+ * end frame with an `abandoned` outcome, or a session switch). The next start
+ * frame rebuilds from scratch.
+ * @param acc - the live replay accumulator.
+ * @returns whether any tail text was discarded.
+ */
+export declare function clearAssistantStream(acc: ReplayAccumulator): boolean;
+/**
+ * The append-only flush boundary for a transcript view: the count of entries
+ * no later event can remove. Entries at or beyond this index are mutable and
+ * must stay in the live tree.
+ *
+ * `pending` rows are excluded even though they are not a running tool/retry:
+ * the inbox claims or cancels them durably (`agent/inbox/spliced` removals,
+ * `user/message` retirement), and an append-only `<Static>` flush cannot
+ * erase a row that vanishes from the view — the retired row would ghost on
+ * screen until the next source-backed replay. Running commands join the
+ * mutable boundary for the same reason in reverse: `command/done` mutates the
+ * row's state/summary, so a flushed row would keep its stale running mark
+ * until a resize-triggered replay. Everything else (including a completed
+ * tail) is final: later events only APPEND new rows.
+ * @param entries - the view's transcript entries in order.
+ * @returns the count of entries safe to flush (0 for an empty transcript).
+ */
+export declare function settledEntryCount(entries: readonly TranscriptEntry[]): number;

package/vendor/tui/types/render/status.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Status-bar composition for the TUI footer. Codex/Claude-Code-style split
+ * line: identity facts and session figures flow from the left, while the
+ * permission badge (the Codex "autonomous selection" anchor, with its
+ * shift+tab cycle hint) pins to the right edge. Every segment carries a tone
+ * the footer maps to a theme color, and layoutStatusBar degrades the line
+ * item by item so it always fits one physical row — truncation with an
+ * ellipsis happens only after every lesser group has already dropped out.
+ *
+ * @module @deepseek-ai/dsh-tui/render/status
+ */
+import type { TranscriptStats } from './projection.ts';
+/**
+ * Compact token count: 517 / 12.2K / 517K / 1.2M (one decimal under three
+ * digits), mirroring the web composer's StatsLine format.
+ * @param n - token count.
+ * @returns display string.
+ */
+export declare function formatTokens(n: number): string;
+/**
+ * Compact duration: 45.2s under a minute, 2m42s from there on.
+ * @param ms - duration in milliseconds.
+ * @returns display string.
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Cache-hit share of billed prompt-side input.
+ * @param usage - cumulative token totals.
+ * @returns percent rounded to one decimal place, or null when no input was billed.
+ */
+export declare function cacheHitPercent(usage: TranscriptStats['usage']): number | null;
+/**
+ * Presentation tones for status spans; the footer maps each to a theme color
+ * (Codex status-line accents: model/path/branch/state/usage categories).
+ */
+export type StatusTone = 'model' | 'live' | 'path' | 'branch' | 'value' | 'label' | 'meta' | 'accent' | 'success' | 'warn' | 'error' | 'ctxFill';
+/** One colored run inside the status bar. */
+export interface StatusSpan {
+    text: string;
+    tone: StatusTone;
+}
+/**
+ * One pipe-separated cluster on the leading side of the bar. Spans are the
+ * full visual sequence: junction separators ride along as their own dim
+ * 'label'-tone spans, so joining is a flat concat with no implicit glue.
+ */
+export interface StatusGroup {
+    spans: readonly StatusSpan[];
+}
+/** One physical row of the footer: leading clusters and trailing badges. */
+export interface StatusRow {
+    /** Leading clusters, pipe-separated in display order; index 0 is identity. */
+    left: readonly StatusGroup[];
+    /** Trailing spans pinned to the right edge, dot-separated in display order. */
+    right: readonly StatusSpan[];
+    /** Whether the shift+tab cycle hint rides after the permission badge. */
+    hint: boolean;
+}
+/**
+ * The footer layout: two stacked physical rows. Row 1 keeps the primary
+ * controls in model, cwd, mode, branch, context, permission order. Row 2
+ * carries every secondary session/run figure and degrades independently.
+ */
+export interface StatusLayout {
+    row1: StatusRow;
+    row2: StatusRow;
+}
+/** Separator between leading clusters. */
+export declare const STATUS_GROUP_SEPARATOR = " | ";
+/** Separator between trailing state spans. */
+export declare const STATUS_ITEM_SEPARATOR = " \u00B7 ";
+/** The Codex-style mode cycle hint appended to the permission badge. */
+export declare const STATUS_CYCLE_HINT = " (shift+tab to cycle)";
+/**
+ * Interior columns of the context bar. The layout starts every bar at this
+ * width so the drop ladder can pre-measure the group, then degrades the
+ * readout and shrinks the bar inside a tighter budget before dropping the
+ * group (see CONTEXT_MIN_WIDTH) rather than asking the layout for more room.
+ */
+export declare const CONTEXT_BAR_WIDTH = 24;
+/**
+ * Render context occupancy as ONE stepless proportional bar: a solid
+ * DeepSeek-blue fill run tracking the occupancy and a dim dotted free
+ * track for the rest. Nothing else lives inside the bar — the usage
+ * readout rides outside it (see contextGroupSpans) — so the geometry
+ * always reads as the true remaining share. A given occupancy always
+ * renders the identical bar.
+ * @param usedTokens - reported used tokens.
+ * @param contextWindow - route capacity.
+ * @param width - total bar columns.
+ * @returns tone-split spans for the footer to paint.
+ */
+export declare function contextBar(usedTokens: number, contextWindow: number, width: number): readonly StatusSpan[];
+/** How much usage detail the context group's readout carries. */
+export type ContextReadoutMode = 'full' | 'percent' | 'none';
+/**
+ * Compose the context group: the proportional bar plus the usage readout
+ * OUTSIDE the bar, so the dotted track keeps its proportional meaning no
+ * matter how wide the readout is. `full` reads `12.3K/1.0M 25%`; `percent`
+ * drops the absolute pair; `none` is the bare bar. The readout turns amber
+ * once occupancy reaches the warning threshold.
+ */
+export declare function contextGroupSpans(usedTokens: number, contextWindow: number, barWidth: number, readout: ContextReadoutMode): readonly StatusSpan[];
+/**
+ * One customizable status item (the Codex /statusline picker contract).
+ * 'left' items render as pipe-separated clusters after the identity dot;
+ * 'right' items pin to the right edge as dot-separated state badges.
+ */
+export type StatusItemId = 'model' | 'cwd' | 'branch' | 'plan' | 'mode' | 'turns' | 'durations' | 'cache' | 'context' | 'tokens' | 'title' | 'goal' | 'sandbox' | 'permission';
+/** Picker-facing metadata for one customizable item. */
+export interface StatusItemInfo {
+    id: StatusItemId;
+    /** Short picker label. */
+    label: string;
+    /** One-line picker description of what the item shows. */
+    description: string;
+    /** Which side of the split row the item renders on. */
+    side: 'left' | 'right';
+}
+/** The full item catalog in canonical order (the /statusline default). */
+export declare const STATUS_ITEMS: readonly StatusItemInfo[];
+/**
+ * Default order: the whole catalog (matches the pre-customization bar).
+ * The busy dot is not an item — it always leads the identity cluster.
+ */
+export declare const DEFAULT_STATUSLINE_ITEMS: readonly StatusItemId[];
+/**
+ * Parse a persisted statusline item list. The stored value is the ordered
+ * set of ENABLED items (the Codex /statusline contract): unknown ids and
+ * duplicates drop out, and a non-array value (missing or corrupt file)
+ * falls back to the full default set. An explicitly empty array is valid —
+ * the bar degrades to its busy dot alone.
+ * @param value - the raw parsed JSON value (expected string[]).
+ * @returns the normalized ordered item list.
+ */
+export declare function parseStatuslineItems(value: unknown): readonly StatusItemId[];
+/**
+ * Extra left padding on the secondary row so its content aligns with the
+ * model name's left edge on the primary row (padding 2 + busy dot 2). The
+ * layout subtracts it from row 2's budget so the indent can never wrap it.
+ */
+export declare const STATUS_ROW2_INDENT = 2;
+/** Identity facts the runner resolves once at mount; empty strings drop out. */
+export interface StatusFacts {
+    /** 'provider/model' selection serving this session. */
+    model: string;
+    /** Agent preset composing this session. */
+    mode?: string;
+    /** Working-directory basename the session serves. */
+    cwd: string;
+    /** Git branch name, empty outside a repository or on a detached HEAD file. */
+    branch: string;
+    /** Short session identifier (last dash-separated segment or tail). */
+    sessionId: string;
+    /** Latest session title (folded from 'session/title'); shown in place of the id. */
+    title: string;
+    /** Sandbox-mode override (folded from 'sandbox/mode'), empty when never switched. */
+    sandbox: string;
+    /** Live goal summary (folded from 'goal/change'), undefined when none. */
+    goal: {
+        phase: string;
+        rounds: number;
+        max: number;
+    } | undefined;
+    /** Whether plan mode is active (folded from 'plan/mode'). */
+    plan: boolean;
+    /** Active or pending permission preset; empty only when the service is unavailable. */
+    permission: string;
+}
+/**
+ * Traffic-light tone for a permission preset: read-only stays success green,
+ * full access reads error red, and every workspace-scoped middle ground
+ * (including unknown presets) reads warning amber.
+ * @param permission - active permission preset label.
+ * @returns tone for the badge span.
+ */
+export declare function permissionTone(permission: string): StatusTone;
+/**
+ * Compose the two-row footer layout under a column budget. Row 1 keeps model,
+ * cwd, mode, branch, context, then the right-pinned permission badge and cycle
+ * hint. It drops hint, context, and permission before ellipsizing identity.
+ * Row 2 fits all secondary figures and state within its own budget.
+ * @param facts - identity facts resolved by the runner.
+ * @param stats - session figures folded from the durable log.
+ * @param columns - usable columns for each row (before their left padding).
+ * @param options - 'busy' hides the cycle hint while a turn runs (Codex
+ * keeps mode hints idle-only); 'items' is the ordered enabled-item config
+ * from /statusline (defaults to the full catalog). Display order follows the
+ * config per side while the drop ladder keeps its fixed ranks.
+ * @returns the two rows to render; row1.left is never empty.
+ */
+export declare function layoutStatusBar(facts: StatusFacts, stats: TranscriptStats, columns: number, options?: {
+    busy?: boolean;
+    items?: readonly string[];
+    contextWidth?: number;
+}): StatusLayout;