@qilin-agent/client-ui-trajectory 0.0.0-stage → 3.1.4

package/lib/index.js

@@ -0,0 +1,6 @@
+//#region lib/types/index.js
+/** Host loader entry for the browser-only trajectory plugin. */
+/** Provides no host-side behavior. */
+function apply() {}
+//#endregion
+export { apply };

package/lib/types/client/TrajectoryCell.d.ts

@@ -0,0 +1,13 @@
+import { formatElapsedSeconds, type TrajectoryCellProps } from './trajectory-record.ts';
+import type { TrajectoryTranslate } from './locales.ts';
+export { formatElapsedSeconds };
+export type { AssistantMetricDetail, TrajectoryCellKind, TrajectoryCellProps, } from './trajectory-record.ts';
+/**
+ * Render one trajectory step cell.
+ * @param props - index, kind, text, time, and optional Message metrics.
+ * @returns the cell element.
+ */
+export declare function TrajectoryCell({ t, index, kind, text, inputDetail: _inputDetail, promptDetail: _promptDetail, previousPromptDetail: _previousPromptDetail, outputDetail: _outputDetail, thinkingDetail: _thinkingDetail, sourceBlocks: _sourceBlocks, outputBlocks: _outputBlocks, schemaDetail: _schemaDetail, assistantMetrics: _assistantMetrics, result: _result, callId: _callId, toolName: _toolName, isError: _isError, timeSeconds, startedAt: _startedAt, input, output, think, selected, className, ...rest }: TrajectoryCellProps & {
+    t: TrajectoryTranslate;
+}): import("react").JSX.Element;
+//# sourceMappingURL=TrajectoryCell.d.ts.map

package/lib/types/client/TrajectoryGraphView.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Trajectory graph view: the ledger drawn as a live node and edge flow, with
+ * the ledger-order replay, record search, the edge-kind legend, canvas zoom
+ * and pan, and the structured record inspector.
+ *
+ * Motion is data-driven, not decorative: a record that is still moving pulses
+ * and every edge that delivers data into it carries a dashed flow, while the
+ * replay control walks the ledger in the order the events actually happened —
+ * pacing each hop by the recorded timestamps (clamped, so a 30-second tool
+ * call does not freeze the replay), dimming the records the cursor has not
+ * reached, and flying one packet per hop along the hop's real edge path
+ * (`<animateMotion path>`).
+ *
+ * The canvas adapts to its pane: a ResizeObserver feeds the measured canvas
+ * width into the layout, so the graph spreads its swimlanes across a wide pane
+ * and the canvas centers the sheet whenever it fits no more.
+ */
+import { type ReactNode } from 'react';
+import type { MessageImageLoader } from '@qilin-agent/client-ui-conversation/client';
+import type { InjectFace, PropsLocale, PropsRuntime } from '@qilin-agent/client-ui-slots';
+/** Session-bound image loader injected beside the trajectory locale seat. */
+export interface TrajectoryGraphViewInjected {
+    /** Session-authorized image URL loader with its synchronous cache read. */
+    loadImage: MessageImageLoader;
+    /** Reveal the ledger page this graph draws, in the same pane. */
+    openLedger: () => void;
+}
+/** The graph body's composed props: the Sidebar tab seat, its image loader, the ledger control, and the trajectory locale. */
+export type TrajectoryGraphViewProps = PropsRuntime<'sidebar.right.pane.tab'> & InjectFace<TrajectoryGraphViewInjected> & PropsLocale<'trajectory'>;
+/**
+ * Render one session's trajectory ledger as a node and edge graph.
+ * @param props - the Sidebar tab seat's runtime share, the authorized image
+ * loader, the ledger control, and the trajectory locale.
+ * @returns The graph body, or its empty and hint states.
+ */
+export declare function TrajectoryGraphView({ useTrajectory, loadImage, openLedger, t }: TrajectoryGraphViewProps): ReactNode;
+//# sourceMappingURL=TrajectoryGraphView.d.ts.map

package/lib/types/client/TrajectoryGroupHeader.d.ts

@@ -0,0 +1,13 @@
+export interface TrajectoryGroupHeaderProps {
+    /** Group title (`Message`, `Step 1`, …). */
+    title: string;
+    /** Secondary summary (`49 s`, `2.2 s skill`, …). */
+    description?: string;
+}
+/**
+ * Render a Message/Step group header inside a turn body.
+ * @param props - title and optional description.
+ * @returns the group header element.
+ */
+export declare function TrajectoryGroupHeader({ title, description }: TrajectoryGroupHeaderProps): import("react").JSX.Element;
+//# sourceMappingURL=TrajectoryGroupHeader.d.ts.map

package/lib/types/client/TrajectoryTable.d.ts

@@ -0,0 +1,111 @@
+/** Turn-aware trajectory event ledger with a local record inspector. */
+import type { JsonTreeProps } from '@qilin-agent/client-ui-primitives';
+import type { AssistantRequestConfig, RenderMessageImages } from '@qilin-agent/client-ui-conversation/client';
+import type { TrajectoryCellProps } from './trajectory-record.ts';
+import type { TrajectoryTurnModel } from './layout.ts';
+import type { TrajectoryTranslate } from './locales.ts';
+/** Props for the trajectory ledger. */
+export interface TrajectoryTableProps {
+    /** Wrapping control shared by all JSON inspectors. */
+    stringWrapping?: JsonTreeProps['stringWrapping'];
+    /** Trajectory locale seat. */
+    t: TrajectoryTranslate;
+    /** Slot-backed durable image renderer shared with the Chat gallery. */
+    renderImages: RenderMessageImages;
+    /** Session-global request numbers for the request groups visible in this context. */
+    requestNumbers?: readonly TrajectoryRequestNumber[];
+    /** Grouped records in display order. */
+    turns: readonly TrajectoryTurnModel[];
+    /** In-flight cells whose content replaces the matching structural record index. */
+    streamingCells?: readonly TrajectoryCellProps[];
+    /** Record indexes emphasized by the active timeline focus. */
+    timelineFocusIndexes?: ReadonlySet<number> | null;
+    /** Record indexes retained by the active live search, or null without a query. */
+    searchMatchIndexes?: ReadonlySet<number> | null;
+    /** Report the record currently selected in the local inspector. */
+    onSelectedIndexChange?: (index: number | null) => void;
+    /** Report a direct user selection from a ledger row. */
+    onRecordSelect?: (index: number) => void;
+    /** One externally requested record selection; a new object repeats the request. */
+    recordSelection?: {
+        readonly index: number;
+    } | null;
+    /** One externally requested record focus without changing inspector selection. */
+    recordFocus?: {
+        readonly index: number;
+    } | null;
+    /** Whether the initial history tail is still loading. */
+    historyLoading?: boolean;
+    /** Whether one older history page request is pending anywhere. */
+    olderHistoryLoading?: boolean;
+    /** First loaded raw event, used to preserve scroll position after prepending a page. */
+    historyStartSeq?: number | undefined;
+    /** Whether one older history page can be requested. */
+    hasOlderRecords?: boolean;
+    /** Load one older history page. */
+    onLoadOlder?: () => Promise<boolean>;
+    /** Clear selection state owned by the ledger host. */
+    onClearSelection?: () => void;
+    /** Turn ids whose rows after the first are folded into a summary. */
+    collapsedTurns: ReadonlySet<number>;
+    /** Toggle one turn between folded and expanded. */
+    onToggleTurn: (turn: number) => void;
+    /** Stable Assistant record ids whose tool calls are folded. */
+    collapsedAssistants: ReadonlySet<string>;
+    /** Toggle tool calls under one assistant record. */
+    onToggleAssistant: (id: string) => void;
+    /** One-shot cross-view inspect: open and scroll to this call's record. */
+    inspectCallId?: string | null;
+    /** Acknowledge a consumed (or unresolvable) inspect request. */
+    onInspectApplied?: (() => void) | undefined;
+}
+/** Request-inspector fields shared by ordinary generation and compaction. */
+interface TrajectoryRequestNumberBase {
+    group: string;
+    number: number;
+    status?: 'complete' | 'running' | 'error';
+    startedAt?: number;
+    completedAt?: number | null;
+    error?: string;
+    errorCode?: string;
+    retry?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    resultSeq?: number;
+    provider?: string;
+    model?: string;
+    requestConfig?: AssistantRequestConfig;
+    usage?: TrajectoryUsage;
+    cumulativeUsage?: TrajectoryUsage;
+}
+/** One purpose-discriminated request identity paired with its session-global number. */
+export type TrajectoryRequestNumber = TrajectoryRequestNumberBase & ({
+    purpose?: 'assistant';
+    /** Request anchor event sequence; absent for the currently streaming request. */
+    seq?: number;
+    turn: number;
+    step: number;
+} | {
+    purpose: 'compaction';
+    /** Request anchor event sequence and stable compaction identity. */
+    seq: number;
+    turn: number | null;
+    step: 0;
+});
+/** Disjoint provider token buckets for one request or a session prefix. */
+export interface TrajectoryUsage {
+    input?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    output?: number;
+    reasoning?: number;
+}
+/**
+ * Render trajectory events as a dense ledger with turn and step separators.
+ * Clicking ledger whitespace clears the active record or request selection.
+ * @param props - Grouped trajectory data and whole-ledger fold state.
+ * @returns The ledger and an optional local record inspector.
+ */
+export declare function TrajectoryTable({ t, stringWrapping, renderImages, requestNumbers: sessionRequestNumbers, turns, streamingCells, timelineFocusIndexes, searchMatchIndexes, onSelectedIndexChange, onRecordSelect, recordSelection, recordFocus, historyLoading, olderHistoryLoading, historyStartSeq, hasOlderRecords, onLoadOlder, onClearSelection, collapsedTurns, onToggleTurn, collapsedAssistants, onToggleAssistant, inspectCallId, onInspectApplied, }: TrajectoryTableProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=TrajectoryTable.d.ts.map

package/lib/types/client/TrajectoryTimeline.d.ts

@@ -0,0 +1,26 @@
+/** Chrome-Network-style overview timeline for focusing the trajectory ledger. */
+import type { TrajectoryTurnModel } from './layout.ts';
+import type { TrajectoryTranslate } from './locales.ts';
+import { type TrajectoryTimelineMode, type TrajectoryTimeRange } from './timeline.ts';
+/** Props for the fixed full-domain overview above the trajectory ledger. */
+export interface TrajectoryTimelineProps {
+    t: TrajectoryTranslate;
+    turns: readonly TrajectoryTurnModel[];
+    mode: TrajectoryTimelineMode;
+    range: TrajectoryTimeRange | null;
+    /** Whether the loaded timeline omits an earlier history prefix. */
+    hasEarlierRecords?: boolean;
+    /** Load one earlier history page from the truncation control. */
+    onLoadEarlier?: () => Promise<boolean>;
+    selectedIndex?: number | null;
+    /** Record indexes matching the active ledger search, or null without a query. */
+    searchMatchIndexes?: ReadonlySet<number> | null;
+    onRangeChange: (range: TrajectoryTimeRange | null) => void;
+    /** Select a directly clicked timeline block. */
+    onRecordSelect?: (index: number) => void;
+    /** Bring the nearest record into view after clicking timeline whitespace. */
+    onRecordFocus?: (index: number) => void;
+}
+/** Overview renderer with drag ranges, click-sized focus, and Escape reset. */
+export declare const TrajectoryTimeline: import("react").MemoExoticComponent<({ t, turns, mode, range, hasEarlierRecords, onLoadEarlier, selectedIndex, searchMatchIndexes, onRangeChange, onRecordSelect, onRecordFocus, }: TrajectoryTimelineProps) => import("react").JSX.Element>;
+//# sourceMappingURL=TrajectoryTimeline.d.ts.map

package/lib/types/client/TrajectoryToolbar.d.ts

@@ -0,0 +1,34 @@
+/** Trajectory toolbar: timeline and ledger fold controls. */
+import type { TranslateNS } from '@qilin-agent/client-ui-slots';
+import type { NS } from './locales.ts';
+export interface TrajectoryToolbarProps {
+    /** Whether timeline blocks use recorded durations instead of equal widths. */
+    actualDuration: boolean;
+    /** Select recorded-duration or equal-width blocks. */
+    onActualDurationChange: (actualDuration: boolean) => void;
+    /** Whether recorded timing retains idle gaps between operations. */
+    actualTime: boolean;
+    /** Select complete wall-clock timing or idle-compressed timing. */
+    onActualTimeChange: (actualTime: boolean) => void;
+    /** Whether every collapsible turn is currently folded. */
+    allTurnsCollapsed: boolean;
+    /** Fold or expand every collapsible turn. */
+    onToggleAllTurns: () => void;
+    /** Whether every collapsible assistant's tool calls are currently folded. */
+    allAssistantsCollapsed: boolean;
+    /** Fold or expand tool calls under every collapsible assistant. */
+    onToggleAllAssistants: () => void;
+    /** Current live ledger search query. */
+    searchQuery: string;
+    /** Update the live ledger search query. */
+    onSearchQueryChange: (query: string) => void;
+    /** Translate a toolbar dictionary key. */
+    t: TranslateNS<typeof NS>;
+}
+/**
+ * Render the sticky trajectory toolbar.
+ * @param props - rendered counts and whole-list fold state.
+ * @returns the toolbar element.
+ */
+export declare function TrajectoryToolbar({ actualDuration, onActualDurationChange, actualTime, onActualTimeChange, allTurnsCollapsed, onToggleAllTurns, allAssistantsCollapsed, onToggleAllAssistants, searchQuery, onSearchQueryChange, t, }: TrajectoryToolbarProps): import("react").JSX.Element;
+//# sourceMappingURL=TrajectoryToolbar.d.ts.map

package/lib/types/client/TrajectoryTurn.d.ts

@@ -0,0 +1,17 @@
+import type { ReactNode } from 'react';
+import type { TrajectoryTranslate } from './locales.ts';
+export interface TrajectoryTurnProps {
+    /** 1-based turn index for the sticky header. */
+    turn: number;
+    /** Message / Step headers and TrajectoryCell rows. */
+    children?: ReactNode;
+    /** Trajectory locale seat. */
+    t: TrajectoryTranslate;
+}
+/**
+ * Render one turn section (sticky header + body).
+ * @param props - turn index and body children.
+ * @returns the turn section element.
+ */
+export declare function TrajectoryTurn({ turn, children, t }: TrajectoryTurnProps): import("react").JSX.Element;
+//# sourceMappingURL=TrajectoryTurn.d.ts.map

package/lib/types/client/TrajectoryTurnHeader.d.ts

@@ -0,0 +1,14 @@
+import type { TrajectoryTranslate } from './locales.ts';
+export interface TrajectoryTurnHeaderProps {
+    /** 1-based turn index shown as `Turn N`. */
+    turn: number;
+    /** Trajectory locale seat. */
+    t: TrajectoryTranslate;
+}
+/**
+ * Render the sticky turn header row.
+ * @param props.turn - turn index.
+ * @returns the sticky header element.
+ */
+export declare function TrajectoryTurnHeader({ turn, t }: TrajectoryTurnHeaderProps): import("react").JSX.Element;
+//# sourceMappingURL=TrajectoryTurnHeader.d.ts.map

package/lib/types/client/TrajectoryView.d.ts

@@ -0,0 +1,20 @@
+/** Trajectory view: compact summary over a turn-aware event ledger. */
+import type { MessageImageLoader } from '@qilin-agent/client-ui-conversation/client';
+import type { InjectFace, PropsLocale, PropsRenderSlots, PropsRuntime } from '@qilin-agent/client-ui-slots';
+import type { SnapshotStore } from '@qilin-agent/client-store';
+import type { JsonTreeProps } from '@qilin-agent/client-ui-primitives';
+/** Session-bound controls not already supplied by the Sidebar tab seat. */
+export interface TrajectoryViewInjected {
+    /** Shared wrapping preference read by expansion handlers. */
+    jsonStringWrapping?: Omit<NonNullable<JsonTreeProps['stringWrapping']>, 'label'>;
+    hooks: {
+        duration: SnapshotStore<boolean>;
+    };
+    loadOlder: () => Promise<boolean>;
+    loadImage: MessageImageLoader;
+    setActualDuration: (actualDuration: boolean) => void;
+}
+/** The ledger body's composed props: the Sidebar tab seat, its images child, and its controls. */
+export type TrajectoryViewProps = PropsRuntime<'sidebar.right.pane.tab'> & PropsRenderSlots<'conversation.trajectory.images'> & InjectFace<TrajectoryViewInjected> & PropsLocale<'trajectory'>;
+export declare function TrajectoryView({ useSession, useTrajectory, useDuration, useTabInfo, loadOlder, loadImage, setActualDuration, renderSlot, t, jsonStringWrapping, }: TrajectoryViewProps): import("react").JSX.Element;
+//# sourceMappingURL=TrajectoryView.d.ts.map

package/lib/types/client/code-program.d.ts

@@ -0,0 +1,19 @@
+/** Read replayable PTC source and language hints from recorded tool arguments and schemas. */
+import type { TrajectoryCellProps } from './trajectory-record.ts';
+/** Recorded name of the programmatic tool-calling entry point. */
+export declare const PTC_TOOL_NAME = "run_code";
+/** Validated source and original arguments for one recorded run_code call. */
+export interface CodeProgram {
+    rawInput: string;
+    source: string;
+    description: string;
+    arguments: Record<string, unknown>;
+    language: 'typescript' | 'python' | undefined;
+}
+/**
+ * Resolve a PTC program without guessing its language from source or current runtime settings.
+ * @param cell - Recorded tool arguments and the schema visible at call time.
+ * @returns The program, or undefined for another tool or unsupported arguments.
+ */
+export declare function codeProgram(cell: TrajectoryCellProps): CodeProgram | undefined;
+//# sourceMappingURL=code-program.d.ts.map

package/lib/types/client/copy-codes.d.ts

@@ -0,0 +1,4 @@
+/** Stable non-display markers for client-synthesized trajectory copy. */
+/** Error marker localized only when the trajectory renders it. */
+export declare const COMPACTION_INTERRUPTED_ERROR = "trajectory.compaction-interrupted";
+//# sourceMappingURL=copy-codes.d.ts.map

package/lib/types/client/duration-store.d.ts

@@ -0,0 +1,7 @@
+import { type SnapshotStore } from '@qilin-agent/client-store';
+/**
+ * Create the browser-wide trajectory duration preference source.
+ * @returns a persisted source shared by every session view in one plugin lifecycle.
+ */
+export declare function createTrajectoryDurationStore(): SnapshotStore<boolean>;
+//# sourceMappingURL=duration-store.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Browser trajectory plugin: two right-Sidebar page types over the same
+ * Trajectory target — the event ledger, and the graph view that draws it as a
+ * node and edge flow — without defining a service.
+ */
+import type { Context } from '@qilin-agent/kylin';
+export type { TrajectoryKey } from './locales.ts';
+export type { TrajectoryContribution, TrajectoryConversationViewNode, TrajectoryRequestHeaderState, TrajectorySnapshot, UseTrajectory, } from './trajectory-contract.ts';
+export type { TrajectoryTabParams } from './trajectory-tab-definition.ts';
+export { TRAJECTORY_ID, TRAJECTORY_KIND } from './trajectory-tab-definition.ts';
+/** Required services: the Sidebar controller and tab registry, the slot registry, Session paging, and the locale service. */
+export declare const inject: string[];
+/**
+ * Client plugin body: register the Sidebar tab type, its body, and its data
+ * contributions. Each registration rides an effect wrapper, so plugin unload
+ * removes the type and its seats together.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/layout.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Trajectory list fold: expand assistant blocks, attach usage to Message,
+ * own-duration times, in-flight partial/runningCalls, and group descriptions.
+ */
+import type { ConversationLocation, RequestInspectionSnapshot, RequestView } from '@qilin-agent/client-ui-conversation/client';
+import type { TrajectoryCellProps } from './trajectory-record.ts';
+import type { TrajectorySnapshot } from './trajectory-contract.ts';
+import type { TrajectoryTranslate } from './locales.ts';
+/** One Message or Step group inside a turn. */
+export interface TrajectoryGroupModel {
+    title: string;
+    description?: string;
+    cells: readonly TrajectoryCellProps[];
+}
+/** One sticky turn, or a standalone compaction section between turns. */
+export interface TrajectoryTurnModel {
+    turn: number | null;
+    groups: readonly TrajectoryGroupModel[];
+}
+/** Snapshot slice the trajectory view folds. */
+export interface TrajectoryLayoutInput {
+    systemPrompts?: TrajectorySnapshot['systemPrompts'];
+    nodes: TrajectorySnapshot['eventNodes'];
+    eventLocations?: ReadonlyMap<number, ConversationLocation>;
+    partial: TrajectorySnapshot['partial'];
+    runningCalls: TrajectorySnapshot['runningCalls'];
+    requests?: readonly RequestView[];
+    callSchemas?: RequestInspectionSnapshot['callSchemas'];
+}
+/**
+ * Fold a snapshot into turn → Message/Step groups with expanded cells.
+ * @param input - nodes plus in-flight partial/runningCalls.
+ * @param t - Trajectory locale translator.
+ * @returns turns ordered by first appearance.
+ */
+export declare function deriveTrajectoryLayout(input: TrajectoryLayoutInput, t: TrajectoryTranslate): readonly TrajectoryTurnModel[];
+/**
+ * Append the changing in-flight assistant cells to a stable finalized layout.
+ * @param turns - Finalized layout derived with an empty-block partial anchor.
+ * @param partial - Current in-flight assistant projection.
+ * @param lastIndex - Highest cell index in the finalized layout.
+ * @param t - Trajectory locale translator.
+ * @returns The original layout without a partial, otherwise a layout sharing every unaffected turn.
+ */
+export declare function appendTrajectoryPartialLayout(turns: readonly TrajectoryTurnModel[], partial: TrajectorySnapshot['partial'], lastIndex: number, t: TrajectoryTranslate): readonly TrajectoryTurnModel[];
+//# sourceMappingURL=layout.d.ts.map