@qilin-agent/client-ui-chat 0.0.0-stage → 3.1.3

package/lib/types/client/contract/slots.d.ts

@@ -0,0 +1,258 @@
+/** Chat-owned Slot declarations and composed component props. */
+import type { MessageId } from '@qilin-agent/llm/brand';
+import type { SessionId, SessionSeq } from '@qilin-agent/session/types';
+import type { CommandNode, CompactionSummaryNode, ConversationGroupData, ConversationLocationDataStore, ConversationTurnDataMap, GroupSnapshot, MessageImageLoader, MessageImagesOwnerProps, RenderMessageImages, TurnLocation } from '@qilin-agent/client-ui-conversation/client';
+import type { InjectFace, KeyedSnapshotSelectorHook, PropsLocale, PropsRenderSlots, PropsRuntime, PropsStore, SlotHookFactory, SnapshotSelectorHook } from '@qilin-agent/client-ui-slots';
+import type { MarkdownFileMentions } from '@qilin-agent/client-ui-primitives';
+import type { createChatStore } from '../stores.ts';
+import type { ToolCallId } from './store.ts';
+import type { ChatConversationViewNode, ChatNode, ChatNodeKind } from './chat-nodes.ts';
+import type { ChatNodeProcessSource, ChatNodeSource, ChatSnapshot, ChatTurnProcessPresentation } from './snapshot.ts';
+import type { TurnProcessSpec } from './turn-process.ts';
+import type { ObservableSnapshot } from '@qilin-agent/client-store';
+import type { ChatPresentationPolicy } from '../presentation-policy.ts';
+import type { PerformanceUsageMode } from '../../chat-settings.ts';
+/** Selector hook over the current Conversation binding's Chat target. */
+export type UseChat = SnapshotSelectorHook<ChatSnapshot>;
+/** Per-key selector hook over one Chat Node. */
+export type UseChatNode = KeyedSnapshotSelectorHook<ChatConversationViewNode | undefined>;
+/** Per-key selector hook over one Chat Node's Turn-process presentation. */
+export type UseChatNodeProcess = KeyedSnapshotSelectorHook<ChatTurnProcessPresentation | undefined>;
+/**
+ * Selector hook over the live presentation policy. Callers select one field or
+ * a derived conclusion, never the whole policy, so a mode change re-renders
+ * only components whose selected value changed.
+ */
+export type UsePresentation = SnapshotSelectorHook<ChatPresentationPolicy>;
+/** Where in a file an open should land. */
+export interface OpenFileOptions {
+    /** 1-based line to reveal; absent = the file's beginning. */
+    readonly line?: number;
+}
+/** Owner currency of the completed-Turn extension chain. */
+export interface TurnTailOwnerProps {
+    turn: TurnLocation;
+    seq: number;
+    openFile: (path: string) => void;
+}
+/** Owner currency of finalized-assistant actions. */
+export interface AssistantActionOwnerProps {
+    messageId: MessageId;
+}
+/** Optional prose file-mention provider consumed by Chat. */
+export interface ChatFileMentions {
+    /**
+     * Resolve prose links for one closing Turn.
+     * @param owner - closing-Turn identity and file opener.
+     * @param sessionId - viewed Session, including when history is inherited from a fork.
+     * @returns link resolver when available.
+     */
+    forClosing(owner: TurnTailOwnerProps, sessionId: SessionId): MarkdownFileMentions | undefined;
+}
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        /** Optional prose file-mention provider. */
+        chatFileMentions: ChatFileMentions;
+    }
+}
+/** Hook constrained to business data published on the current Chat Node's Turn. */
+export type UseChatNodeTurnData = <Key extends Extract<keyof ConversationTurnDataMap, string>>(key: Key) => Readonly<ConversationTurnDataMap[Key]> | undefined;
+/**
+ * Subscribe to enclosing-Turn resets and own one initially collapsed disclosure.
+ * Each invocation has independent open state; display-mode changes do not reset it.
+ * @returns the current open state, explicit setter, and toggle action.
+ */
+export type UseDisclosure = () => {
+    readonly expanded: boolean;
+    /** @param open - whether this disclosure is expanded. */
+    readonly setExpanded: (open: boolean) => void;
+    readonly toggle: () => void;
+};
+/** Stable sources bound to one rendered Chat Node. */
+export interface ChatNodeHookContext {
+    readonly turnData: ConversationLocationDataStore<ConversationTurnDataMap> | undefined;
+    readonly disclosureReset: ObservableSnapshot<number>;
+}
+/** Slot-level Hook factories for keyed Chat renderers. */
+export interface ChatNodeInjected {
+    hooks: {
+        turnData: SlotHookFactory<'conversation.chat.node', UseChatNodeTurnData>;
+        disclosure: SlotHookFactory<'conversation.chat.node', UseDisclosure>;
+    };
+}
+/** Stable owner currency delivered to a keyed Chat renderer. */
+export interface ChatNodeOwnerProps {
+    /** Renderer-owned Node portion selected by the grouping Definition. */
+    groupPart?: string;
+    cwd?: string | undefined;
+    /** Open the current source file of a skill referenced by a sent message. */
+    openSkill: (name: string) => void;
+    openFile: (path: string, options?: OpenFileOptions) => void;
+    inspectCall: ((callId: ToolCallId) => void) | undefined;
+    forkAt: (seq: number) => void;
+    /**
+     * Revise one sent user message: replace the composer draft with its text
+     * (the user edits the bubble and resends a new turn). User bubbles only;
+     * absent for owners that do not provide the wiring.
+     * @param text - the user message's plain text.
+     */
+    editUserMessage?: ((text: string) => void) | undefined;
+    /** Session-authorized image loader for the attachment presentation slot. */
+    loadImage: MessageImageLoader;
+    renderMessageImages: RenderMessageImages;
+    fileMentions: (owner: TurnTailOwnerProps) => MarkdownFileMentions | undefined;
+    /** Turn-process state when this Node belongs to a projected Turn. */
+    turnProcess?: TurnProcessOwnerProps | undefined;
+}
+/** Shared presentation state for one Turn-process answer generation. */
+export interface TurnProcessOwnerProps {
+    /** Process content eligible to share one Turn-level disclosure. */
+    readonly hasContent: boolean;
+    readonly spec: TurnProcessSpec;
+    readonly foldable: boolean;
+    readonly open: boolean;
+    setOpen(open: boolean): void;
+}
+/** Shared presentation-policy source for renderers that depend on the work-details mode. */
+export interface PresentationInjected {
+    hooks: {
+        /** Live presentation policy derived from the accepted work-details mode. */
+        presentation: ObservableSnapshot<ChatPresentationPolicy>;
+    };
+}
+/** Shared settings source for the performance row, composer statistics, and turn tail. */
+export interface PerformanceUsageInjected {
+    hooks: {
+        /** Accepted performance and usage detail preference. */
+        performanceUsage: ObservableSnapshot<PerformanceUsageMode>;
+    };
+}
+/** Full props of one keyed Chat renderer. */
+export type ChatNodeViewProps<Kind extends ChatNodeKind = ChatNodeKind> = PropsRuntime<'conversation.chat.node', Kind> & PropsLocale<'chat'>;
+/** Command-row owner share. */
+export interface CommandRowOwnerProps {
+    node: CommandNode;
+    compaction?: CompactionSummaryNode;
+}
+/** Full props of a registered command row. */
+export type CommandRowProps = PropsRuntime<'conversation.chat.commandview'>;
+/** Shared Chat store handle. */
+export type ChatStore = ReturnType<typeof createChatStore>;
+/** In-memory reader position resilient to transcript reflow. */
+export interface ChatScrollPosition {
+    readonly anchorKey: string;
+    readonly anchorTop: number;
+    readonly scrollTop: number;
+}
+/** Business callbacks injected into the Chat view. */
+export interface ChatViewInjected {
+    hooks: {
+        /** Live presentation policy derived from the accepted work-details mode. */
+        presentation: ObservableSnapshot<ChatPresentationPolicy>;
+    };
+    keyedHooks: {
+        /** Resolve the stable source for one Chat Node key. */
+        chatNode: (key: string) => ChatNodeSource;
+        /** Resolve the stable Turn-process source for one Chat Node key. */
+        chatNodeProcess: (key: string) => ChatNodeProcessSource;
+        /** Resolve one optional group without subscribing the root View to its data. */
+        chatGroup: (key: string) => ObservableSnapshot<GroupSnapshot<ConversationGroupData<'chat'>> | undefined> | undefined;
+    };
+    /** Open the current source file of a skill referenced by a sent message. */
+    openSkill: (name: string) => void;
+    /** Open one HTTP(S) message link at the selected destination, using an external tab if Sidebar Browser is unavailable. */
+    openExternalLink: (url: string) => void;
+    openFile: (path: string, options?: OpenFileOptions) => Promise<void>;
+    /** Open the right Sidebar's Trajectory tab focused on one tool call. */
+    openTrajectory: (callId: string) => void;
+    loadOlder: () => void;
+    /** Jump loader: page history back through seq; resolves when the window covers it. */
+    loadThrough: (seq: SessionSeq) => Promise<void>;
+    loadImage: MessageImageLoader;
+    chatScroll: {
+        save: (position: ChatScrollPosition | null) => void;
+        read: () => ChatScrollPosition | null;
+    };
+    forkAt: (seq: number) => void;
+    /**
+     * Revise one sent user message: replace the composer draft with its text.
+     * Implemented by the composition wiring over the conversation service.
+     * @param text - the user message's plain text.
+     */
+    editUserMessage?: ((text: string) => void) | undefined;
+    fileMentions: (owner: TurnTailOwnerProps) => MarkdownFileMentions | undefined;
+}
+/** Full Chat view props. */
+export type ChatViewSlotProps = PropsRuntime<'conversation.view'> & PropsRenderSlots<'conversation.chat.node' | 'conversation.message.images'> & PropsStore<ChatStore> & InjectFace<ChatViewInjected> & PropsLocale<'chat'>;
+/** Full props of the durable-message image renderer. */
+export type MessageImagesProps = PropsRuntime<'conversation.message.images'> & PropsLocale<'conversation'>;
+declare module '@qilin-agent/client-ui-slots' {
+    interface SessionStandardProps {
+        /** Selector hook over the current Conversation binding's Chat target. */
+        useChat: UseChat;
+    }
+    interface LocaleNamespaceMap {
+        /** Chat target, transcript node, statistics, and details copy. */
+        chat: import('../locale.ts').ChatKey;
+    }
+    interface SlotMap {
+        /**
+         * Final Chat node renderer, keyed by `ChatNodeKind`. The component receives
+         * the typed node, shared Chat actions, and Turn-data hook. Reusing a key
+         * replaces that node renderer; a kind with no occupant renders no row.
+         */
+        'conversation.chat.node': {
+            kind: 'keyed';
+            scope: 'session';
+            owner: ChatNodeOwnerProps;
+            keyProps: {
+                [Kind in ChatNodeKind]: {
+                    node: ChatNode<Kind>;
+                };
+            };
+            hookContext: ChatNodeHookContext;
+            inject: ChatNodeInjected;
+        };
+        /**
+         * Renderer for one consecutive group of durable message images. The owner
+         * supplies image references, an authorized loader, and alignment. A
+         * registration replaces the shipped gallery; without one, images are omitted.
+         */
+        'conversation.message.images': {
+            kind: 'single';
+            scope: 'session';
+            owner: MessageImagesOwnerProps;
+        };
+        /**
+         * Command row keyed by the command name. The component receives the folded
+         * command lifecycle and linked compaction when present. Reusing a key
+         * replaces that command renderer; an unoccupied key uses the generic card.
+         */
+        'conversation.chat.commandview': {
+            kind: 'keyed';
+            scope: 'session';
+            owner: CommandRowOwnerProps;
+        };
+        /**
+         * Ordered feature contributions before a completed Turn's action row. Each
+         * entry receives the Turn, closing sequence, and file opener. A fresh `id`
+         * adds an entry; entries without content return null.
+         */
+        'conversation.chat.turnTail': {
+            kind: 'list';
+            scope: 'session';
+            owner: TurnTailOwnerProps;
+        };
+        /**
+         * Ordered actions for one finalized assistant message. Each entry receives
+         * the durable message id; a fresh `id` adds an action and reusing one replaces
+         * that entry. With no entries, the standard action row remains unchanged.
+         */
+        'conversation.chat.assistant-actions': {
+            kind: 'list';
+            scope: 'session';
+            owner: AssistantActionOwnerProps;
+        };
+    }
+}
+//# sourceMappingURL=slots.d.ts.map

package/lib/types/client/contract/snapshot.d.ts

@@ -0,0 +1,105 @@
+import type { ConversationNode, ConversationTimelineSnapshot, PartialAssistant, RunningToolCall } from '@qilin-agent/client-ui-conversation/client';
+import type { ChatConversationViewNode, ChatNodeDataMap, ChatNodeKind } from './chat-nodes.ts';
+import type { ObservableSnapshot } from '@qilin-agent/client-store';
+import type { TurnProcessSpec } from './turn-process.ts';
+export type { AssistantBlock, AssistantMessageNode, AssistantProviderMetadataView, AssistantRequestConfig, AssistantTiming, CommandNode, CompactionSummaryNode, ContextMessageNode, ConversationNode, ModelRetryNode, PartialAssistant, PreparingToolCall, RunningToolCall, StartedToolCall, SteeringMessageNode, TodoItem, ToolArgs, ToolCallBlock, ToolResultNode, TurnErrorNode, TurnMaxTokensNode, UnknownSurfaceNode, UserMessageNode, } from '@qilin-agent/client-ui-conversation/client';
+/** Per-key observable used by one mounted Chat Node Seat. */
+export interface ChatNodeSource {
+    /** @returns the current Node for this source's stable key. */
+    readonly getSnapshot: () => ChatConversationViewNode | undefined;
+    /** @param listener - callback for changes to this key. @returns the unsubscribe function. */
+    readonly subscribe: (listener: () => void) => () => void;
+}
+/** Per-key observable for the Turn-process presentation surrounding one Chat Node. */
+export interface ChatNodeProcessSource {
+    /** @returns the current presentation, or absence outside a projected Turn process. */
+    readonly getSnapshot: () => ChatTurnProcessPresentation | undefined;
+    /** @param listener - callback for presentation changes. @returns the unsubscribe function. */
+    readonly subscribe: (listener: () => void) => () => void;
+}
+/** Stable live per-key reader for Chat nodes. */
+export interface ChatNodeStore {
+    /** @param key - stable Conversation Context key. @returns current Node, when visible or hidden. */
+    get(key: string): ChatConversationViewNode | undefined;
+    /** @param key - stable Conversation Context key. @returns its identity-stable observable source. */
+    source(key: string): ChatNodeSource;
+    /**
+     * Observe one Turn's data for a single Node kind, including hidden Nodes, in anchor order.
+     * Other Turns and kinds do not notify this source.
+     * @param turn - resolved owning Turn.
+     * @param kind - business Node kind.
+     * @returns an identity-stable source whose array changes only with its members.
+     */
+    turnDataSource<Kind extends ChatNodeKind>(turn: number, kind: Kind): ObservableSnapshot<readonly ChatNodeDataMap[Kind][]>;
+    /** @param key - stable Conversation Context key. @returns its Turn-process presentation source. */
+    processSource(key: string): ChatNodeProcessSource;
+    /** @returns all currently materialized Nodes without imposing render order. */
+    values(): readonly ChatConversationViewNode[];
+}
+/** One loaded Turn projected into the compact Chat navigation rail. */
+export interface TurnNavigationItem {
+    readonly turn: number;
+    /** Stable Conversation Context key the rail scrolls to. */
+    readonly anchorKey: string;
+    /** Bounded prompt preview; empty when the loaded window starts mid-Turn. */
+    readonly prompt: string;
+    /** Bounded assistant-response preview; empty until the Turn answers. */
+    readonly response: string;
+}
+/** Stable live navigation projection of the loaded Turns. */
+export interface ChatTurnNavigationIndex {
+    /**
+     * Loaded Turns that have a visible anchor, in timeline order. The array
+     * identity changes exactly when a Turn enters, leaves, or changes preview,
+     * so a renderer can select it directly as its change signal.
+     * @returns current navigation items.
+     */
+    items(): readonly TurnNavigationItem[];
+}
+/** Stable live Location index for Chat nodes. */
+export interface ChatLocationNodeIndex {
+    /** @param turn - owning turn. @returns ordered Chat Node keys in the turn. */
+    getTurn(turn: number): readonly string[];
+    /** @param turn - owning turn. @param step - owning step. @returns ordered Chat Node keys in the step. */
+    getStep(turn: number, step: number): readonly string[];
+}
+/** Cross-Node presentation facts derived for one Turn process. */
+export interface ChatTurnProcessPresentation {
+    readonly turn: number;
+    readonly spec: TurnProcessSpec;
+    /** Whether the loaded window contains this Turn's `turn/start`; folding is decided per Turn on this fact. */
+    readonly turnStarted: boolean;
+    readonly turnClosed: boolean;
+    readonly hasExternalProcess: boolean;
+    /** A visible input after process output prevents one disclosure from hiding its surrounding groups. */
+    readonly hasInterleavedInput: boolean;
+    readonly compactAnswer: boolean;
+}
+/** Compatibility projection backing the composer stats pills (StatsPills.tsx) and the legacy top-level snapshot fields. */
+export interface LegacyConversationSlice {
+    readonly nodes: readonly ConversationNode[];
+    readonly turnTimings: ReadonlyMap<number, {
+        readonly startTime: number;
+        readonly endTime?: number;
+    }>;
+    readonly turnEnds: ReadonlyMap<number, number>;
+    readonly partial: PartialAssistant | null;
+    readonly runningCalls: readonly RunningToolCall[];
+}
+/** Incremental Chat publication with immutable order and stable live keyed readers. */
+export interface ChatSnapshot {
+    readonly order: readonly string[];
+    readonly nodes: ChatNodeStore;
+    readonly locations: ChatLocationNodeIndex;
+    readonly navigation: ChatTurnNavigationIndex;
+    readonly timeline: ConversationTimelineSnapshot;
+    readonly legacy: LegacyConversationSlice;
+}
+declare module '@qilin-agent/client-ui-conversation/client' {
+    interface ConversationViewSnapshotMap {
+        chat: ChatSnapshot;
+    }
+}
+/** Empty Chat target used before a view builder is registered. */
+export declare const EMPTY_CHAT_SNAPSHOT: ChatSnapshot;
+//# sourceMappingURL=snapshot.d.ts.map

package/lib/types/client/contract/store.d.ts

@@ -0,0 +1,13 @@
+/** Chat-owned per-Session view state. */
+/** Tool call identity as carried by Chat nodes. */
+export type ToolCallId = string;
+/** One manually expanded Turn answer generation. */
+export interface TurnProcessViewEntry {
+    readonly turn: number;
+    readonly answerStep: number;
+}
+/** Per-Session state shared only by the Chat view and details surface. */
+export interface ChatStoreState {
+    turnProcesses: TurnProcessViewEntry[];
+}
+//# sourceMappingURL=store.d.ts.map

package/lib/types/client/contract/turn-metrics.d.ts

@@ -0,0 +1,19 @@
+import type { AssistantMessageNode } from '@qilin-agent/client-ui-conversation/client';
+/** One assistant step's derivable latency facts; null marks an unrecorded part. */
+export interface StepReading {
+    /** step/start → first token delta, in ms. */
+    ttftMs: number | null;
+    /** First token delta → final message, in ms. */
+    decodeMs: number | null;
+    /** Provider-reported completion tokens. */
+    outputTokens: number | null;
+}
+type AssistantNode = AssistantMessageNode;
+/**
+ * Read one assistant node's TTFT, decode wall time, and output tokens.
+ * @param node - A settled assistant node.
+ * @returns Per-part readings with `null` for unrecorded values.
+ */
+export declare function assistantStepReading(node: AssistantNode): StepReading;
+export {};
+//# sourceMappingURL=turn-metrics.d.ts.map

package/lib/types/client/contract/turn-process.d.ts

@@ -0,0 +1,40 @@
+import type { ChatNode } from './chat-nodes.ts';
+/** Current process range and finalized answer boundary derived from one Turn. */
+export interface TurnProcessSpec {
+    readonly turn: number;
+    /** Stable control-node anchor source, including currently ineligible evidence. */
+    readonly controlAnchorSeq: number;
+    readonly processStartSeq: number;
+    readonly answerAnchorSeq: number | null;
+    readonly answerStep: number | null;
+    readonly inlineReasoning: boolean;
+    /** Reply-bearing durable Assistant messages before the final answer. */
+    readonly messageCount: number;
+    /** Durable non-subagent Tool calls recorded by this Turn. */
+    readonly toolCallCount: number;
+    /** Tool calls whose configured name identifies a subagent delegation. */
+    readonly subagentCount: number;
+}
+/** Chat Node kinds that remain independent of a Turn's process disclosure. */
+export declare const TURN_PROCESS_INDEPENDENT_KINDS: ReadonlySet<string>;
+/**
+ * Compare immutable Turn-process specifications by their published fields.
+ * @param left - previous specification.
+ * @param right - next specification.
+ * @returns whether both values describe the same process presentation.
+ */
+export declare function sameTurnProcessSpec(left: TurnProcessSpec, right: TurnProcessSpec): boolean;
+/**
+ * Recognize the shipped subagent delegation name and its configured variants.
+ * Control tools use distinct names such as `send_message` and `list_agents`.
+ * @param name - durable Tool-call name.
+ * @returns whether the call creates or forks a subagent.
+ */
+export declare function isSubagentDelegationTool(name: string): boolean;
+/**
+ * Keep live, stopped, and failed Turns open.
+ * @param node - Node carrying the owning Turn.
+ * @returns whether whole-Turn collapse is unavailable.
+ */
+export declare function turnProcessAlwaysOpen(node: ChatNode | undefined): boolean;
+//# sourceMappingURL=turn-process.d.ts.map

package/lib/types/client/conversation-nodes/assistant.d.ts

@@ -0,0 +1,36 @@
+import type { Context } from '@qilin-agent/kylin';
+import type { AssistantBlock, ConversationMatch, ConversationNodeDefinition } from '@qilin-agent/client-ui-conversation/client';
+import type { AssistantChatData } from '../contract/chat-nodes.ts';
+declare module '../contract/chat-nodes.ts' {
+    interface ChatNodeDataMap {
+        /** Streaming, settled, or interrupted Assistant step. */
+        'assistant-step': AssistantChatData;
+    }
+}
+declare module '@qilin-agent/client-ui-conversation/client' {
+    interface ConversationStepDataMap {
+        /** Streaming, settled, or interrupted Assistant material for this Step. */
+        'assistant-step': AssistantChatData;
+    }
+}
+interface AssistantState {
+    readonly turn: number;
+    readonly step: number;
+    readonly blocks: readonly (AssistantBlock | undefined)[];
+    readonly visibleBlocks: number;
+    readonly firstVisibleSeq: number | undefined;
+    readonly firstVisibleTime: number | undefined;
+    readonly firstTokenTime: number | undefined;
+    readonly hidden: boolean;
+    readonly final: ConversationMatch | undefined;
+    readonly usage: unknown;
+}
+/** Per-step Assistant streaming/final/interruption Definition. */
+export declare const assistantDefinition: ConversationNodeDefinition<AssistantState>;
+/**
+ * Register the Assistant lifecycle business contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export declare function registerAssistantConversationNode(ctx: Context): void;
+export {};
+//# sourceMappingURL=assistant.d.ts.map

package/lib/types/client/conversation-nodes/chat-snapshot-builder.d.ts

@@ -0,0 +1,103 @@
+import type { Context } from '@qilin-agent/kylin';
+import type { ConversationGroupInput, ConversationTimelineSnapshot, ConversationViewBuilder, ConversationViewDefinition } from '@qilin-agent/client-ui-conversation/client';
+import type { ChatConversationViewNode } from '../contract/chat-nodes.ts';
+import type { ChatNodeStore, ChatSnapshot } from '../contract/snapshot.ts';
+/**
+ * Order visible Chat Nodes without changing existing relative order as process
+ * eligibility changes. Opening input precedes process candidates, while
+ * each synthetic process control sits between them.
+ * @param nodes - currently materialized Chat Nodes.
+ * @returns visible Nodes in presentation order.
+ */
+export declare function orderedVisibleChatNodes(nodes: readonly ChatConversationViewNode[]): ChatConversationViewNode[];
+/**
+ * Attaches each direct message's step-loaded skill names to its Node.
+ *
+ * A step's `skill-invocation` injections follow the direct messages the host
+ * scanned for `/name` gestures and precede the step's first Node of any other
+ * kind, so every non-message, non-context Node closes a batch. Every ended
+ * Turn publishes its `turn-tail` Node on `turn/end` whatever the reason, so a
+ * batch never spans Turns, and `step/start` precedes the direct message in
+ * the log, so no boundary separates a message from its injections. Names
+ * attach to every direct message of the batch: the bubble decorates only the
+ * tokens its own text carries.
+ *
+ * The index holds only messages, skill injections, and boundaries, ordered by
+ * `anchorSeq`. An apply re-reads just the batches around the Nodes whose
+ * classification changed and never scans the store, so an assistant
+ * streaming frame costs nothing here (the append hot path never scans the
+ * Chat Nodes).
+ */
+export declare class SkillNameProjector {
+    private readonly entries;
+    /** Every indexed entry in `anchorSeq` order. */
+    private sorted;
+    /**
+     * Rebuild the index from a whole Node set and attach names to its messages.
+     * @param nodes - every materialized Chat Node, in any order.
+     * @returns the same Nodes, direct messages carrying their batch's names.
+     */
+    replace(nodes: readonly ChatConversationViewNode[]): readonly ChatConversationViewNode[];
+    /**
+     * Fold one incremental upsert set: re-read only the batches around the
+     * Nodes whose classification changed.
+     * @param upserts - the changed Nodes.
+     * @param store - the resident Nodes, read by key for the messages of an affected batch.
+     * @returns the upserts plus any resident message whose names changed.
+     */
+    apply(upserts: readonly ChatConversationViewNode[], store: ChatNodeStore): readonly ChatConversationViewNode[];
+    private insert;
+    private remove;
+    /** First index whose seq is at least `seq`. */
+    private lowerBound;
+    /** Last index of the boundary-free run containing `index`. */
+    private runEnd;
+    /** First index of the boundary-free run containing `index`. */
+    private runStart;
+    /** Record the names every message of the run `[start, end]` carries. */
+    private assignRun;
+    /**
+     * Re-read the run(s) around one changed seq: the run holding a message or
+     * skill entry, or — for a boundary, or a seq that left the index — the runs
+     * on both sides of that position.
+     */
+    private collectAround;
+}
+/** Incremental keyed Chat builder registered under the `chat` target. */
+export declare class ChatSnapshotBuilder implements ConversationViewBuilder<ChatConversationViewNode, ChatSnapshot> {
+    private readonly store;
+    private readonly locations;
+    private readonly navigation;
+    private readonly legacy;
+    private readonly referenceLabels;
+    private readonly skillNames;
+    private order;
+    private latestGroupInput;
+    private readonly readGroupNode;
+    private readonly readGroupTurn;
+    private readonly readGroupPosition;
+    /** Last published timeline: a Turn boundary can land without a new node. */
+    private timeline;
+    readonly empty: ChatSnapshot;
+    constructor();
+    replace(input: {
+        readonly nodes: readonly ChatConversationViewNode[];
+        readonly timeline: ConversationTimelineSnapshot;
+    }): ChatSnapshot;
+    apply(input: {
+        readonly upserts: readonly ChatConversationViewNode[];
+        readonly timeline: ConversationTimelineSnapshot;
+        readonly changedTurns?: readonly number[];
+    }): ChatSnapshot;
+    groupInput(): ConversationGroupInput<ChatConversationViewNode>;
+    publish(): void;
+    private snapshot;
+}
+/** Chat target factory contributed to the Conversation view registry. */
+export declare const chatViewDefinition: ConversationViewDefinition<ChatConversationViewNode, ChatSnapshot>;
+/**
+ * Register the incremental Chat target builder.
+ * @param ctx - owning UI Conversation context.
+ */
+export declare function registerChatConversationView(ctx: Context): void;
+//# sourceMappingURL=chat-snapshot-builder.d.ts.map

package/lib/types/client/conversation-nodes/command.d.ts

@@ -0,0 +1,53 @@
+import type { Context } from '@qilin-agent/kylin';
+import type { CommandNode, CompactionSummaryNode, ConversationMatch, ConversationNodeDefinition } from '@qilin-agent/client-ui-conversation/client';
+declare module '../contract/chat-nodes.ts' {
+    interface ChatNodeDataMap {
+        /** Ordinary slash-command lifecycle. */
+        command: CommandNode;
+        /** Manual compact command combined with its compaction transaction. */
+        'manual-compaction': ManualCompactionChatData;
+    }
+}
+type CommandId = CommandNode['commandId'];
+interface CommandState {
+    readonly command: CommandNode;
+    readonly summary?: ConversationMatch;
+    readonly checkpoint?: ConversationMatch;
+}
+interface CompactionEvidence {
+    readonly summary?: ConversationMatch;
+    readonly checkpoint?: ConversationMatch;
+}
+/**
+ * Read correlation identity from a compaction replacement checkpoint.
+ * @param event - candidate Session event.
+ * @returns correlated compaction and optional command identity.
+ */
+declare function compactSource(event: Parameters<ConversationNodeDefinition['match']>[0]): {
+    compactionId: string;
+    sourceCommandId?: CommandId;
+} | undefined;
+/**
+ * Build the visible summary marker from optional lifecycle evidence.
+ * @param match - compaction/summary Match, when loaded.
+ * @param checkpoint - replacement checkpoint Match.
+ * @returns final compaction summary Node data.
+ */
+declare function compactSummary(match: ConversationMatch | undefined, checkpoint: ConversationMatch): CompactionSummaryNode;
+/**
+ * Fold shared compaction evidence into a Definition-owned State.
+ * @param state - current business State carrying optional compaction evidence.
+ * @param match - next compaction lifecycle Match.
+ * @returns adopted State, preserving reference identity when the Match adds no evidence.
+ */
+export declare function updateCompactionState<State extends CompactionEvidence>(state: State, match: ConversationMatch): State;
+/** Slash-command lifecycle, including integrated manual compaction, Definition. */
+export declare const commandDefinition: ConversationNodeDefinition<CommandState>;
+/**
+ * Register the command lifecycle business contribution.
+ * @param ctx - owning UI Conversation context.
+ */
+export declare function registerCommandConversationNode(ctx: Context): void;
+/** Shared structural checkpoint recognizer for automatic compaction. */
+export { compactSource, compactSummary };
+//# sourceMappingURL=command.d.ts.map