@oh-my-pi/pi-tui 18.2.4 → 18.2.6

package/dist/types/overlays/advisor-config.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Fullscreen `/advisor configure` overlay: a mouse- and keyboard-driven editor
+ * for the `WATCHDOG.yml` advisor roster at project or user level.
+ *
+ * It paints the entire alternate screen from row 0 (so SGR mouse rows index
+ * directly into the rendered frame) using the shared {@link ./overlay-box} chrome.
+ * The list screen is a two-pane split (the `/extensions` idiom): a clickable
+ * advisor/action sidebar on the left, and a scrollable preview of the highlighted
+ * advisor's model / tools / instructions on the right, filling the free space.
+ *
+ * Each screen is backed by a proven primitive — {@link SelectList} (list / detail
+ * / tools / thinking), {@link Input} (name), {@link ModelSelectorComponent} (the
+ * same rich `/model` picker, in direct-select mode), and {@link HookEditorComponent}
+ * (multiline instructions; Ctrl+G opens `$EDITOR`). The overlay edits an in-memory
+ * {@link WatchdogConfigDoc} and only touches disk + the live advisors via the host
+ * `save` callback.
+ */
+import type { ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import { type Model, type UsageLimit, type UsageReport } from "@oh-my-pi/pi-ai";
+import { type Component, type TUI } from "../index.js";
+import { type ModelBrowserSource } from "./model-browser.js";
+/** One advisor declared in `WATCHDOG.yml`; its instructions specialize the shared baseline. */
+export interface AdvisorConfig {
+    name: string;
+    /** Model selector with an optional `:level` thinking suffix, resolved like any other model override. */
+    model?: string;
+    /** Built-in tool names, including mutating tools; omitted uses read/grep/glob plus available recall, empty grants none. */
+    tools?: string[];
+    instructions?: string;
+    /** Defaults to true; false retains the advisor in the roster and status displays without building its runtime. */
+    enabled?: boolean;
+    /** Maximum non-blocker notes per advisor prompt update (default 4); blockers are exempt. */
+    maxNotesPerUpdate?: number;
+}
+/** Which level a `WATCHDOG.yml` lives at: the project root or the user agent dir. */
+export type AdvisorConfigScope = "project" | "user";
+/** Editable raw contents of one `WATCHDOG.yml`, without cross-level merging or `@import` expansion, for exact round trips. */
+export interface WatchdogConfigDoc {
+    instructions?: string;
+    maxNotesPerUpdate?: number;
+    advisors: AdvisorConfig[];
+    /** Per-entry problems found while loading (dropped entries). Shown when the file becomes active in the editor. */
+    warnings?: string[];
+}
+export interface AdvisorConfigStat {
+    name: string;
+    sessionId?: string;
+    status: string;
+    model?: {
+        provider: string;
+    };
+    tokens: {
+        input: number;
+        output: number;
+        cacheRead: number;
+    };
+    cost: number;
+    contextWindow: number;
+    contextTokens: number;
+}
+/** Host callbacks: all disk + live-runtime effects flow through these. */
+export interface AdvisorConfigCallbacks {
+    /** Load a scope's `WATCHDOG.yml` into an editable doc (empty when absent). */
+    loadDoc: (scope: AdvisorConfigScope) => Promise<WatchdogConfigDoc>;
+    /** Persist the doc to the scope's file and rebuild the live advisors. */
+    save: (scope: AdvisorConfigScope, doc: WatchdogConfigDoc) => Promise<void>;
+    /** Tear down the overlay and restore the editor. */
+    close: () => void;
+    requestRender: () => void;
+    /** Surface a transient status/warning line to the user. */
+    notify: (message: string) => void;
+    /**
+     * Surface a sticky warning (e.g. malformed entries in the file just made
+     * active by a scope switch). Falls back to `notify` when omitted.
+     */
+    warn?: (message: string) => void;
+    /** Live advisor usage stats; lets the preview show tokens/cost per advisor. */
+    getAdvisorStats?: () => AdvisorConfigStat[];
+    /** Reports normalized by the host to collapse shared credential pools. */
+    getUsageReports?: () => Promise<UsageReport[] | null>;
+    /** Filter to the advisor's active credential; absent identity includes every limit. */
+    getQuotaLimitFilter?: (provider: string, sessionId: string | undefined) => ((report: UsageReport, limit: UsageLimit) => boolean) | undefined;
+}
+export interface AdvisorConfigDeps {
+    getAvailableModels: () => Model[];
+    browserSource: ModelBrowserSource;
+    defaultToolNames: ReadonlySet<string>;
+    externalEditor?: (text: string) => Promise<string | null>;
+    scopedModels: ReadonlyArray<{
+        model: Model;
+        thinkingLevel?: ThinkingLevel;
+    }>;
+    availableToolNames: string[];
+    /** Formatted advisor-role model shown on the seeded default row (e.g. "anthropic/claude-..."). */
+    defaultModelLabel?: string;
+}
+/**
+ * One-line provider quota display. The host supplies normalized usage reports
+ * and an optional credential filter; the overlay owns only presentation.
+ */
+export declare function formatCompactQuota(provider: string, reports: UsageReport[], nowMs: number, includeLimit?: (report: UsageReport, limit: UsageLimit) => boolean): string | null;
+/**
+ * Fullscreen advisor-configuration overlay. Implements {@link Component} directly
+ * (rather than extending Container) so it owns the whole frame and the mouse
+ * geometry needed to make every row clickable.
+ */
+export declare class AdvisorConfigOverlayComponent implements Component {
+    #private;
+    constructor(tui: TUI, deps: AdvisorConfigDeps, scope: AdvisorConfigScope, doc: WatchdogConfigDoc, callbacks: AdvisorConfigCallbacks);
+    render(width: number): readonly string[];
+    handleInput(data: string): void;
+    /** Forward enhanced-paste transports into a multiline instructions editor. */
+    pasteText(text: string): void;
+}

package/dist/types/overlays/agent-activity.d.ts

@@ -0,0 +1,41 @@
+import type { AgentProgress } from "../tools/task.js";
+export type AgentActivityKind = "response" | "tool" | "irc" | "lifecycle";
+export type AgentActivityStatus = "pending" | "success" | "error" | "aborted";
+export interface AgentActivityRow {
+    id: string;
+    agentId: string;
+    timestamp: number;
+    kind: AgentActivityKind;
+    title: string;
+    summary: string;
+    status?: AgentActivityStatus;
+    entryId?: string;
+    toolCallId?: string;
+    toolName?: string;
+    from?: string;
+    to?: string;
+    replyTo?: string;
+    source: "live" | "transcript" | "irc";
+}
+export interface AgentActivityQuery {
+    agentIds?: ReadonlySet<string>;
+    kinds?: ReadonlySet<AgentActivityKind>;
+    search?: string;
+    before?: {
+        timestamp: number;
+        id: string;
+    };
+    limit?: number;
+}
+/** Activity index surface rendered by the agent hub. */
+export interface AgentActivitySource {
+    setLive(agentId: string, rows: AgentActivityRow[]): void;
+    sync(agentId: string, sessionFile: string | null): Promise<void>;
+    query(query: AgentActivityQuery): AgentActivityRow[];
+    recent(agentId: string, limit: number): AgentActivityRow[];
+}
+/** Collapse an activity label to one readable terminal line. */
+export declare function activityOneLine(value: string): string;
+/** Stable timestamp ordering for merged activity rows. */
+export declare function compareActivityRows(a: AgentActivityRow, b: AgentActivityRow): number;
+export declare function activityRowsFromProgress(progress: AgentProgress, lastUpdate?: number): AgentActivityRow[];

package/dist/types/overlays/agent-hub-projection.d.ts

@@ -0,0 +1,33 @@
+import type { AgentMetricsSummary, AgentRecordLike, AgentStatus } from "./agent-hub-types.js";
+import type { ObservableSession } from "./session-observer-registry.js";
+export type AgentMetrics = AgentMetricsSummary;
+export interface AggregateMetrics extends AgentMetrics {
+    reportedAgents: number;
+    /** Rows whose duration is an observer-measured active runtime. */
+    activeDurationAgents: number;
+}
+interface AgentTreeProjection<TRecord extends AgentRecordLike> {
+    rows: TRecord[];
+    depthById: Map<string, number>;
+    parentById: Map<string, string>;
+    lastSiblingById: Map<string, boolean>;
+}
+export declare const STATUS_ORDER: Record<AgentStatus, number>;
+/** Exact observer usage for one roster entry. */
+export declare function progressMetrics(observed: ObservableSession | undefined): AgentMetrics | undefined;
+export declare function aggregateMetrics<TRecord extends AgentRecordLike>(args: {
+    rows: readonly TRecord[];
+    observedById: ReadonlyMap<string, ObservableSession>;
+    metricsFor: (ref: TRecord, observed: ObservableSession | undefined) => AgentMetrics | undefined;
+    fallbackStatsSession: (ref: TRecord, observed: ObservableSession | undefined) => NonNullable<AgentRecordLike["session"]> | undefined;
+    sessionMetrics: WeakMap<object, {
+        metrics: AgentMetrics | undefined;
+    }>;
+    refreshFallback: boolean;
+}): {
+    metrics: AggregateMetrics;
+    hasFallbackLiveSessions: boolean;
+};
+/** Parent-before-child projection preserving the roster's stable sibling order. */
+export declare function projectAgentTree<TRecord extends AgentRecordLike>(refs: readonly TRecord[]): AgentTreeProjection<TRecord>;
+export {};

package/dist/types/overlays/agent-hub-renderer.d.ts

@@ -0,0 +1,53 @@
+import type { ThemeColor } from "../theme/theme.js";
+import { type AgentRecordLike } from "./agent-hub-types.js";
+import type { ObservableSession } from "./session-observer-registry.js";
+import type { AgentMetrics } from "./agent-hub-projection.js";
+export interface RosterRender {
+    lines: string[];
+    hitRows: Array<number | undefined>;
+}
+/** Compute the max content width for the current terminal, accounting for chrome. */
+export declare function contentWidth(): number;
+/** Sanitize a line for TUI display and truncate it to the viewport width. */
+export declare function sanitizeLine(text: string, maxWidth?: number): string;
+export declare function clampHubLine(line: string, width: number): string;
+/** Status glyph, colored per theme status conventions. The title-line counts spell out the words. */
+export declare function statusGlyph(status: AgentRecordLike["status"]): string;
+export declare function statusText(status: AgentRecordLike["status"], text: string): string;
+/** Host-resolved model-role label and color. */
+export interface AgentRoleDisplay {
+    color?: ThemeColor;
+    tag?: string;
+    name?: string;
+}
+/** Textual model-role tag; color reinforces (but never replaces) the label. */
+export declare function formatRoleBadge(role: string, info: AgentRoleDisplay): string;
+/**
+ * Resolved model + reasoning level for a hub row. Exact executor progress is
+ * authoritative (and survives completion); direct live sessions are the
+ * fallback for agents without an observer snapshot — the main session has no
+ * snapshot at all, so its row is read straight off the live session.
+ *
+ * Every source reports the model that produced the row's work, never the one
+ * the session merely points at: an armed fallback that has not served yet stays
+ * attributed to whichever model last actually spoke.
+ */
+export declare function modelBadge(ref: AgentRecordLike, observed: ObservableSession | undefined): string | undefined;
+export declare function formatMetricDuration(metrics: AgentMetrics): string | undefined;
+export declare function formatCost(cost: number): string;
+export declare function formatMetrics(metrics: AgentMetrics): string;
+/** Row-grid variant of {@link formatMetrics}: fixed-width cells so every agent's metadata
+ * line shares one column layout instead of flowing after wrapped text. Cost is left-aligned
+ * so the line starts flush; the numeric cells are right-aligned so units line up. */
+export declare function formatMetricColumns(metrics: AgentMetrics, age: string): string;
+export declare function contextGauge(tokens: number, window: number): string;
+/** Fit a child-id preview without joining an arbitrarily large child set. */
+export declare function formatChildIds(children: readonly AgentRecordLike[], width: number): string;
+/** Bash `tree`-style branch for an agent's identity row. */
+export declare function treeBranch(ref: AgentRecordLike, maxWidth: number, depthById: ReadonlyMap<string, number>, parentById: ReadonlyMap<string, string>, lastSiblingById: ReadonlyMap<string, boolean>): string;
+/** Ancestry rails for the task and metrics rows beneath an agent identity. */
+export declare function treeContinuation(ref: AgentRecordLike, maxWidth: number, depthById: ReadonlyMap<string, number>, parentById: ReadonlyMap<string, string>, lastSiblingById: ReadonlyMap<string, boolean>): string;
+/** One roster-wide origin for metric columns, independent of tree depth. */
+export declare function treeMetadataIndent(maxWidth: number, maxDepth: number): number;
+/** Right-align `text` inside a fixed-width cell, truncating overflow. */
+export declare function alignRightCell(text: string, width: number): string;

package/dist/types/overlays/agent-hub-types.d.ts

@@ -0,0 +1,99 @@
+import type { AgentMessage, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { Model } from "@oh-my-pi/pi-ai";
+/** Identity of the ambient main session in the agent roster. */
+export declare const MAIN_AGENT_ID = "Main";
+/** Lifecycle state shown in the roster. */
+export type AgentStatus = "running" | "idle" | "parked" | "aborted";
+/** Usage summary consumed by the roster and inspector. */
+export interface AgentMetricsSummary {
+    tokens: number;
+    requests: number;
+    tools: number;
+    cost: number;
+    durationMs: number;
+    durationKind?: "active" | "span" | "unknown";
+    contextTokens?: number;
+    contextWindow?: number;
+}
+/** Live session data and actions used by the agent hub. */
+export interface AgentHubSession {
+    readonly thinkingLevel: ThinkingLevel | undefined;
+    readonly model: Model | undefined;
+    readonly servingModel?: {
+        selector: string;
+        isFallback: boolean;
+    };
+    readonly agent?: {
+        state: {
+            messages: AgentMessage[];
+        };
+    };
+    getSessionStats(): {
+        tokens: {
+            input: number;
+            output: number;
+            cacheWrite: number;
+        };
+        assistantMessages: number;
+        toolCalls: number;
+        cost: number;
+        contextUsage?: {
+            tokens: number;
+            contextWindow: number;
+        } | null;
+    };
+    abort(options?: {
+        reason?: string;
+    }): Promise<void>;
+}
+/** Structural view of an agent-registry record. */
+export interface AgentRecordLike {
+    id: string;
+    displayName: string;
+    kind: "main" | "sub" | "advisor";
+    parentId?: string;
+    status: AgentStatus;
+    session: AgentHubSession | null;
+    sessionFile: string | null;
+    createdAt: number;
+    lastActivity: number;
+    activity?: string;
+    history?: {
+        agent?: string;
+        modelRole?: string;
+        resolvedModel?: string;
+        resolvedModelIsFallback?: boolean;
+        metrics?: AgentMetricsSummary;
+        readOnly?: boolean;
+        outputPath?: string;
+        patchPath?: string;
+        branchName?: string;
+        nestedPatchPaths?: string[];
+    };
+    lifecycle?: {
+        responseAt?: number;
+        acceptedAt?: number;
+        terminalAt?: number;
+    };
+}
+/** Registry operations needed to display a live roster. */
+export interface AgentHubRegistry<TRecord extends AgentRecordLike = AgentRecordLike> {
+    list(): TRecord[];
+    get(id: string): TRecord | undefined;
+    onChange(listener: () => void): () => void;
+}
+/** Lifecycle actions exposed by the host. */
+export interface AgentLifecycleLike<TRecord extends AgentRecordLike = AgentRecordLike> {
+    ensureLive(id: string): Promise<{
+        prompt(text: string, options: {
+            streamingBehavior: "steer";
+        }): Promise<unknown>;
+    }>;
+    release(id: string, expected: TRecord, options: {
+        tombstone: true;
+    }): Promise<boolean>;
+}
+/** Unread-message counts supplied by the host IRC bus. */
+export interface IrcBusLike {
+    unreadCount(id: string): number;
+}

package/dist/types/overlays/agent-hub.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Agent Hub overlay component.
+ *
+ * One overlay, two views:
+ * - Table view: every registered agent except Main (Main IS the ambient
+ *   chat), live from the global AgentHubRegistry — status, unread irc count,
+ *   current/last task, last activity. Navigate with keys, wheel, hover, and
+ *   click; `r` revives a parked agent, `x` aborts + releases one.
+ * - Chat view: per-agent transcript (incremental session-file tail, absorbed
+ *   from the old session observer overlay) plus an input line. Submitting
+ *   revives a parked agent, then prompts/steers it; the message lands in the
+ *   agent's persisted history via the normal prompt path.
+ *
+ * Replaces the old SessionObserverOverlayComponent (ctrl+s observer).
+ */
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import { Container, type TUI } from "../tui.js";
+import { type SelectListMouseTarget } from "../mouse.js";
+import { type AgentActivitySource } from "./agent-activity.js";
+import type { KeyId } from "../app-keybindings.js";
+import type { MessageRenderer } from "../chat/extension-types.js";
+import type { AgentLifecycleLike, IrcBusLike } from "./agent-hub-types.js";
+import { type AgentRecordLike, type AgentHubRegistry } from "./agent-hub-types.js";
+import type { SessionObserverRegistry } from "./session-observer-registry.js";
+import { type AgentTranscriptSource } from "./agent-transcript-viewer.js";
+import type { AgentRoleDisplay } from "./agent-hub-renderer.js";
+export type AgentHubSection = "agents" | "activity";
+/** Result of one host-backed transcript read for the Agent Hub viewer. */
+export interface AgentHubRemoteTranscript {
+    text: string;
+    newSize: number;
+    /** Terminal read failure reported by the host; guests should surface it instead of retrying hot. */
+    error?: string;
+}
+/** Guest-side proxy for hub actions executed on the collab host. */
+export interface AgentHubRemote {
+    chat(id: string, text: string): void;
+    kill(id: string): void;
+    revive(id: string): void;
+    /** Mirrors readFileIncremental: text from fromByte (complete JSONL lines), newSize = next fromByte base; null = temporarily unavailable. */
+    readTranscript(id: string, fromByte: number): Promise<AgentHubRemoteTranscript | null>;
+}
+export interface AgentHubDeps<TRecord extends AgentRecordLike = AgentRecordLike> {
+    /** Progress/status snapshot source (task lifecycle + progress channels). */
+    observers: SessionObserverRegistry;
+    /** Resolve the current display metadata for a model role. */
+    getRoleInfo?: (role: string) => AgentRoleDisplay;
+    /** Host-backed transcript parsing and local reads. */
+    transcript: AgentTranscriptSource;
+    /** Register persisted roster entries while the overlay remains alive. */
+    loadPersisted: (shouldContinue: () => boolean) => Promise<void>;
+    /** Keys that toggle the hub closed from inside (app.agents.hub + app.session.observe). */
+    hubKeys: KeyId[];
+    onDone: () => void;
+    requestRender: () => void;
+    /** Registry supplying the roster. */
+    registry: AgentHubRegistry<TRecord>;
+    /** Resolve lifecycle actions lazily when a local action needs them. */
+    lifecycle: () => AgentLifecycleLike<TRecord>;
+    /** Host message bus supplying unread counts. */
+    irc: IrcBusLike;
+    /** TUI handle for transcript components; tests omit it and get a render-only stub. */
+    ui?: TUI;
+    /** Tool lookup for transcript renderers (labels, custom render functions). */
+    getTool?: (name: string) => AgentTool | undefined;
+    /** Whether the active registry entry came from a built-in factory. */
+    isBuiltInTool?: (name: string) => boolean;
+    /** Extension message renderers for custom messages in the transcript. */
+    getMessageRenderer?: (customType: string) => MessageRenderer | undefined;
+    /** Cwd used by tool renderers for path shortening; defaults to the project dir. */
+    cwd?: string;
+    /** Mirrors the main transcript's thinking-block visibility. */
+    hideThinkingBlock?: () => boolean;
+    proseOnlyThinking?: () => boolean;
+    /** Keys toggling tool output expansion (app.tools.expand). */
+    expandKeys?: KeyId[];
+    /** Focus the main view on this agent's live session (ctx.focusAgentSession). When absent (collab guest, tests), Enter opens the in-hub chat view instead. */
+    focusAgent?: (id: string) => Promise<void>;
+    /** Current main session file; used to seed parked historical subagents after restart. */
+    sessionFile?: string | null;
+    /** Initial top-level projection; slash commands deep-link into this surface. */
+    initialSection?: AgentHubSection;
+    /** Unified local or remote activity source. */
+    activity: AgentActivitySource;
+    /** Whether observer progress should update live activity rows. */
+    manageActivityLive?: boolean;
+    /** Collab guest: route actions/transcripts to the host instead of local sessions. */
+    remote?: AgentHubRemote;
+}
+export declare class AgentHubOverlayComponent<TRecord extends AgentRecordLike = AgentRecordLike> extends Container implements SelectListMouseTarget {
+    #private;
+    /** Resolves after persisted historical subagents have been registered and rows refreshed. */
+    readonly persistedSubagentsReady: Promise<void>;
+    constructor(deps: AgentHubDeps<TRecord>);
+    /**
+     * Whether the current table view has no agents to show (every registered agent
+     * except Main). Persisted historical rows may arrive later; callers that need
+     * those included must wait for {@link persistedSubagentsReady} first.
+     */
+    get isEmpty(): boolean;
+    /** Tear down every subscription and timer. Called by the overlay owner on close. */
+    dispose(): void;
+    render(width: number): readonly string[];
+    handleInput(keyData: string): void;
+    /**
+     * Seed the table's left-left close detector with the current time so a single
+     * subsequent `←` (within {@link LEFT_TAP_WINDOW_MS}) dismisses the hub.
+     *
+     * The editor's own double-tap detector consumes the `←←` that opens the hub,
+     * leaving this detector at its fresh `0` — without this handoff the user would
+     * have to press `←←` a second time to escape. Called by the opener when the hub
+     * was raised by that gesture.
+     */
+    armCloseTap(): void;
+    /**
+     * Open the fullscreen transcript viewer for an agent id (public for table Enter
+     * and tests). Mounts {@link AgentTranscriptViewer} as a `fullscreen` overlay so it
+     * owns the alternate screen; the hub table stays mounted underneath and is
+     * restored when the viewer closes. No-op without a real TUI (render-only test stub).
+     */
+    openChat(id: string, entryId?: string): void;
+    handleWheel(delta: -1 | 1): void;
+    hitTest(line: number): number | undefined;
+    setHoverIndex(index: number | null): void;
+    clickItem(index: number): void;
+}

package/dist/types/overlays/agent-transcript-viewer.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Fullscreen transcript viewer.
+ *
+ * `AgentHubOverlayComponent.openChat` mounts this as a `fullscreen` overlay
+ * (`ui.showOverlay(..., { fullscreen: true })`), so it borrows the terminal's
+ * alternate screen buffer (the vim/less idiom) and paints the whole screen — no
+ * compositing into the live transcript's scrollback. It renders a parked
+ * subagent / advisor / collab-guest transcript that has no live in-view session.
+ *
+ * Local transcripts tail append-only growth: unchanged file identity plus stable
+ * sentinels means only newly appended JSONL is parsed and rendered. Rewrites,
+ * truncation, rotation, or sentinel drift fall back to a full rebuild so changed
+ * historical entries cannot leave stale components behind. Collab guests use the
+ * same append path over the host's byte-capped transcript reads.
+ */
+import type * as fs from "node:fs";
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import type { Component, TUI } from "../tui.js";
+import type { KeyId } from "../app-keybindings.js";
+import type { MessageRenderer } from "../chat/extension-types.js";
+import type { AgentLifecycleLike } from "./agent-hub-types.js";
+import type { AgentHubRegistry } from "./agent-hub-types.js";
+import type { SessionMessageEntryLike } from "../chat/transcript-entry.js";
+import type { SessionObserverRegistry } from "./session-observer-registry.js";
+import type { AgentHubRemote } from "./agent-hub.js";
+/** Parsed message and model metadata relevant to a transcript viewer. */
+export type AgentTranscriptEntry = SessionMessageEntryLike | {
+    type: "model_change";
+    model: string;
+};
+/** Local filesystem and session parsing capabilities supplied by the host. */
+export interface AgentTranscriptSource {
+    fs: Pick<typeof fs, "openSync" | "closeSync" | "readSync" | "readFileSync" | "statSync">;
+    parseEntries(text: string): AgentTranscriptEntry[];
+}
+export interface AgentTranscriptViewerDeps {
+    agentId: string;
+    transcript: AgentTranscriptSource;
+    /** Persisted entry to reveal on first paint when opened from an activity row. */
+    initialEntryId?: string;
+    registry: AgentHubRegistry;
+    /** Collab guest: read transcript from the host instead of a local file. */
+    remote?: AgentHubRemote;
+    /** Progress/cost snapshot source for the stats line. */
+    observers?: SessionObserverRegistry;
+    /** Revive+prompt path for messageable local agents. Lazy to avoid touching the global. */
+    lifecycle?: () => AgentLifecycleLike;
+    ui: TUI;
+    getTool?: (name: string) => AgentTool | undefined;
+    /** Whether the active registry entry came from a built-in factory. */
+    isBuiltInTool?: (name: string) => boolean;
+    getMessageRenderer?: (customType: string) => MessageRenderer | undefined;
+    cwd: string;
+    hideThinkingBlock?: () => boolean;
+    proseOnlyThinking?: () => boolean;
+    expandKeys: KeyId[];
+    /** Keys that toggle the whole hub closed (app.agents.hub + app.session.observe). */
+    hubKeys: KeyId[];
+    requestRender: () => void;
+    /** Close just this viewer (Esc), returning to the hub table. */
+    onClose: () => void;
+    /** Close this viewer AND the hub (hub-toggle keys). */
+    onHubClose: () => void;
+}
+export declare class AgentTranscriptViewer implements Component {
+    #private;
+    constructor(deps: AgentTranscriptViewerDeps);
+    dispose(): void;
+    handleInput(data: string): void;
+    render(width: number): readonly string[];
+}

package/dist/types/overlays/agents-hub.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Fullscreen /agents hub, shown on the alternate screen like /models.
+ *
+ * Layout mirrors the model hub: a sidebar of scopes (All agents, per-source
+ * groups, "+ New agent"), a body listing agents with type-to-filter search,
+ * and a footer that turns into a chip strip while configuring. Enter on an
+ * agent opens its property strip (enabled / model / prewalk / advisor); a
+ * property opens a value strip whose "pick model…" chip dives into the real
+ * ModelBrowser and whose "pattern…" chip opens an inline pattern input, so
+ * every per-agent knob is picked instead of memorized.
+ */
+import type { Model } from "@oh-my-pi/pi-ai";
+import { type Component, type TUI } from "../index.js";
+import type { AgentSource } from "../tools/task.js";
+import { type ModelBrowserSource } from "./model-browser.js";
+/** One agent with its per-agent settings overrides resolved for display. */
+export interface HubAgent {
+    name: string;
+    description: string;
+    systemPrompt: string;
+    source: AgentSource;
+    filePath?: string;
+    model?: string[];
+    prewalk?: boolean | string;
+    advisor?: boolean | string;
+    disabled: boolean;
+    /** `task.agentModelOverrides[name]` as a comma-joined pattern list. */
+    overrideModel?: string;
+    /** `task.agentPrewalk[name]`: "on", "off", or a model pattern. */
+    prewalkOverride?: string;
+    /** `task.agentAdvisor[name]`: "on", "off", or a model pattern. */
+    advisorOverride?: string;
+}
+/** The per-agent knob a strip or the model browser is editing. */
+type PropertyKind = "model" | "prewalk" | "advisor";
+export interface GeneratedAgentSpec {
+    identifier: string;
+    whenToUse: string;
+    systemPrompt: string;
+}
+/** Runtime-owned discovery, settings, generation and persistence. */
+export interface AgentsHubDeps {
+    browserSource: ModelBrowserSource;
+    loadAgents: () => Promise<HubAgent[]>;
+    getAvailableModels: () => Model[];
+    effectiveModelPatterns: (agent: HubAgent) => string[];
+    resolvePatterns: (patterns: string[]) => string | undefined;
+    effectivePrewalkPattern: (agent: HubAgent) => string | undefined;
+    effectiveAdvisorPattern: (agent: HubAgent) => string | undefined;
+    setDisabledAgents: (names: string[]) => void;
+    setOverrides: (property: PropertyKind, overrides: Record<string, string>) => void;
+    generateAgent: (description: string, onText: (text: string) => void) => Promise<string>;
+    saveAgent: (scope: "project" | "user", spec: GeneratedAgentSpec) => Promise<string>;
+}
+export interface AgentsHubCallbacks {
+    onCancel: () => void;
+}
+/**
+ * The fullscreen agents hub component. Hosted via
+ * `ui.showOverlay(..., { fullscreen: true })`; the host must call
+ * {@link AgentsHubComponent.dispose} when the overlay closes.
+ */
+export declare class AgentsHubComponent implements Component {
+    #private;
+    private constructor();
+    static create(tui: TUI, deps: AgentsHubDeps, callbacks?: AgentsHubCallbacks): Promise<AgentsHubComponent>;
+    dispose(): void;
+    invalidate(): void;
+    handleInput(data: string): void;
+    render(width: number): readonly string[];
+}
+export {};