@huanlin/dsh-focus-chat 0.1.23

package/lib/types/client/model/feedback-controller.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Browser-local object layer over one Session's durable message-feedback
+ * sidecar. The Host owns per-item compare-and-set: every mutation carries the
+ * version this controller last observed, and a `version-conflict` reply carries
+ * the authoritative item, so a lost race reconciles from the reply itself
+ * instead of refetching the whole Session.
+ * @module @deepseek-ai/dsh-client-ui-message-feedback/client/controller
+ */
+import type { RemoteResult } from '@deepseek-ai/dsh-typert-protocol';
+import type { HostObservable } from '@deepseek-ai/dsh-client-ui-slots';
+import type { MessageId, SessionId } from '@deepseek-ai/dsh-client-connection/client';
+import type { MessageFeedbackDeleteResult, MessageFeedbackItem, MessageFeedbackListResult, MessageFeedbackPutResult, MessageFeedbackRating } from '@deepseek-ai/dsh-message-feedback/types';
+/**
+ * The three Remote calls this controller needs. The generated face wraps every
+ * business result in {@link RemoteResult}: a carrier failure arrives as the
+ * `ok: false` branch rather than a rejection, so this controller reads one
+ * envelope and never wraps a call to recover a transport error.
+ */
+export interface MessageFeedbackRemote {
+    list: (request: {
+        sessionId: SessionId;
+    }) => Promise<RemoteResult<MessageFeedbackListResult>>;
+    put: (request: {
+        sessionId: SessionId;
+        messageId: MessageId;
+        rating: MessageFeedbackRating;
+        note?: string;
+        ifVersion: MessageFeedbackItem['version'] | null;
+    }) => Promise<RemoteResult<MessageFeedbackPutResult>>;
+    delete: (request: {
+        sessionId: SessionId;
+        messageId: MessageId;
+        ifVersion: MessageFeedbackItem['version'];
+    }) => Promise<RemoteResult<MessageFeedbackDeleteResult>>;
+}
+/** Load state of the one list read that seeds every per-message control. */
+export type MessageFeedbackStatus = 'cold' | 'loading' | 'ready' | 'error';
+/** Immutable view published to every per-message control in one Session. */
+export interface MessageFeedbackView {
+    status: MessageFeedbackStatus;
+    /** Current item per message, keyed by the addressed message id. */
+    items: ReadonlyMap<MessageId, MessageFeedbackItem>;
+    /** Reason the last load failed, cleared by the next successful load. */
+    error: string | null;
+}
+/** Settled action shape rendered by the message-level controls. */
+export type MessageFeedbackActionResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/**
+ * Per-session feedback object layer. One instance backs every per-message
+ * control in that Session, so a single list read seeds them all.
+ */
+export declare class MessageFeedbackController implements HostObservable<MessageFeedbackView> {
+    private readonly remote;
+    private readonly sessionId;
+    private view;
+    private readonly listeners;
+    private loadPromise;
+    private operationTail;
+    private disposed;
+    /**
+     * @param remote - the messageFeedback Remote namespace.
+     * @param sessionId - Session owning every addressed assistant message.
+     */
+    constructor(remote: MessageFeedbackRemote, sessionId: SessionId);
+    /** Return the cached immutable view. */
+    getSnapshot: () => MessageFeedbackView;
+    /** Subscribe to view replacement. */
+    subscribe: (listener: () => void) => (() => void);
+    /**
+     * Load once; a failed load stays retryable.
+     * @returns the settled load result, shared by concurrent callers.
+     */
+    ensure(): Promise<MessageFeedbackActionResult>;
+    /**
+     * Re-read the authoritative list, collapsing concurrent callers onto one
+     * in-flight read.
+     *
+     * This is the unserialized read used to seed a cold controller, where no
+     * mutation can be in flight yet. A reconnect must use {@link resync} instead:
+     * an unserialized list response can otherwise arrive after a newer mutation's
+     * reply and overwrite the version that mutation just committed.
+     * @returns the settled reload result.
+     */
+    refresh(): Promise<MessageFeedbackActionResult>;
+    /**
+     * Re-read the list behind this Session's queued mutations, so a reconnect
+     * cannot resurrect a version an in-flight mutation already replaced.
+     * @returns the settled reload result.
+     */
+    resync(): Promise<MessageFeedbackActionResult>;
+    /**
+     * Create or replace feedback for one message, comparing against the version
+     * this controller last observed.
+     *
+     * The note is resolved here rather than by the caller: `mutate` awaits the
+     * one list read first, so this body always sees the committed item, while a
+     * control that rendered before that read completed would still be holding
+     * `undefined`. Omitting `note` therefore keeps whatever is stored; only
+     * {@link clearNote} removes one.
+     * @param messageId - target assistant message.
+     * @param rating - desired judgment.
+     * @param note - replacement explanation; omitted keeps the stored note.
+     * @returns the settled mutation result.
+     */
+    rate(messageId: MessageId, rating: MessageFeedbackRating, note?: string): Promise<MessageFeedbackActionResult>;
+    /**
+     * Replace one message's rating with the opposite judgment, or retract it when
+     * the committed rating already matches. The decision reads the committed item
+     * inside the serialized mutation, so a click that lands before the first list
+     * read still toggles against the stored value rather than the empty view a
+     * cold control rendered.
+     * @param messageId - target assistant message.
+     * @param rating - the judgment the human asked for.
+     * @returns the settled mutation result.
+     */
+    toggle(messageId: MessageId, rating: MessageFeedbackRating): Promise<MessageFeedbackActionResult>;
+    /**
+     * Drop the note while keeping the rating. Absent feedback needs no call.
+     * @param messageId - target assistant message.
+     * @returns the settled mutation result.
+     */
+    clearNote(messageId: MessageId): Promise<MessageFeedbackActionResult>;
+    /**
+     * Remove feedback for one message. A message with no known item is already
+     * in the requested state, so no call is made.
+     * @param messageId - target assistant message.
+     * @returns the settled mutation result.
+     */
+    clear(messageId: MessageId): Promise<MessageFeedbackActionResult>;
+    /** Commit one put against the observed version and reconcile a conflict. */
+    private putCommitted;
+    /** Commit one delete against the observed version and reconcile a conflict. */
+    private deleteCommitted;
+    /** Drop subscribers and refuse further work when the owning fiber unloads. */
+    dispose(): void;
+    /** Fetch the whole sidecar and publish it as the seeded view. */
+    private load;
+    /**
+     * Serialize one mutation behind this Session's prior mutation so queued
+     * operations always compare against the committed version, and translate a
+     * transport throw into the same settled shape the controls already render.
+     */
+    private mutate;
+    /**
+     * Replace one message's entry, keeping every other entry's identity. Only a
+     * `mutate` operation reaches this, and `mutate` refuses admission once the
+     * controller is disposed, so no disposal guard belongs here; `publish` is
+     * the single place that stops notifying after listeners are dropped.
+     */
+    private commit;
+    /** Replace the view and contain subscriber failures at the observable boundary. */
+    private publish;
+}

package/lib/types/client/model/flow.d.ts

@@ -0,0 +1,76 @@
+import type { ChatConversationViewNode, ToolCallBlock } from '@deepseek-ai/dsh-client-ui-chat/client';
+import { type ToolRowModelCache } from './tools.ts';
+import type { FocusFlowItem } from './types.ts';
+/**
+ * One derived flow item plus the identity facts it was derived from. The
+ * signature holds node/data references only — O(1) per node per rebuild —
+ * so an unchanged node reuses its previous item object and memoized rows
+ * never re-render while the rest of the conversation streams.
+ */
+interface CachedFlowItem {
+    readonly signature: unknown;
+    readonly item: FocusFlowItem | null;
+}
+/**
+ * Cross-build cache for the focus flow derivation: per-node derived items,
+ * the tool-row models the groups fold, and whole tool-group rows. Keyed by
+ * stable node/call ids, holding only immutable snapshot references, so it
+ * never grows beyond the conversation and is discarded with the view.
+ */
+export interface FlowBuildCache {
+    readonly items: Map<string, CachedFlowItem>;
+    readonly rows: ToolRowModelCache['rows'];
+    /** One emitted tool-group row per run (its node keys), valid while the
+     *  run's blocks keep their references and the group absorbed no context
+     *  batch (an absorption changes the group's shape). */
+    readonly groups: Map<string, {
+        blocks: readonly ToolCallBlock[];
+        item: FocusFlowItem;
+    }>;
+}
+/** One cache instance per mounted focus view (the build is React-free). */
+export declare function createFlowBuildCache(): FlowBuildCache;
+/**
+ * Every chat-target node kind's disposition in this module, compile-checked
+ * against the merge-extensible {@link ChatNodeKind}: a new upstream kind (the
+ * map grows) fails the `Record` for its missing key, and a removed kind fails
+ * the excess-property check — a renamed event can no longer degrade silently
+ * into the `unknown` fallback row (the gap behind the system-prompt /
+ * turn-process / turn-max-tokens regressions).
+ */
+export declare const CHAT_KIND_DISPOSITION: {
+    'assistant-step': string;
+    command: string;
+    compaction: string;
+    context: string;
+    'manual-compaction': string;
+    'model-retry': string;
+    steering: string;
+    'system-prompt': string;
+    'tool-call': string;
+    'turn-error': string;
+    'turn-max-tokens': string;
+    'turn-process': string;
+    'turn-tail': string;
+    unknown: string;
+    user: string;
+};
+/**
+ * Build the condensed flow over the chat snapshot: consecutive `tool-call`
+ * nodes fold into one group per run, and directly-consecutive runs merge
+ * into a single group. A completed turn (its wall duration known) folds
+ * everything except the closing assistant's reply — every intermediate
+ * assistant row and tool run — into one `工作了 X 分 Y 秒` line, keeping the
+ * running turn unfolded. Stale keys (node vanished from the live store) are
+ * dropped.
+ * @param order - snapshot chat order (stable node keys).
+ * @param getNode - snapshot chat node reader.
+ * @param cwd - session workspace root for relative path summaries.
+ * @param home - host account home; a leftover POSIX home path displays as `~`.
+ * @param cache - optional cross-build derivation cache: unchanged nodes and
+ *  tool calls keep their previous item/row object identities, so memoized
+ *  rows bail out while only the streaming tail changes.
+ * @returns the condensed flow in order.
+ */
+export declare function buildFocusFlow(order: readonly string[], getNode: (key: string) => ChatConversationViewNode | undefined, cwd?: string, home?: string, cache?: FlowBuildCache): FocusFlowItem[];
+export {};

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

@@ -0,0 +1,5 @@
+/** The focus flow model: pure derivations over the chat snapshot (React-free). */
+export * from './types.ts';
+export * from './tools.ts';
+export * from './flow.ts';
+export * from './text.ts';

package/lib/types/client/model/text.d.ts

@@ -0,0 +1,42 @@
+/** Text derivations of the focus flow model (React-free). */
+import type { AssistantBlock, AssistantChatData } from '@deepseek-ai/dsh-client-ui-chat/client';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types';
+import type { FocusDeliverablesData } from './types.ts';
+export declare function assistantText(blocks: readonly AssistantBlock[]): string;
+/**
+ * Files one closing assistant produced: mutation paths settled at or before
+ * the closing seq, in first-seen order, deduped (the ui-deliverables
+ * derivation, reimplemented here).
+ * @param data - engine-published deliverables for one turn.
+ * @param seq - closing assistant seq; later tool settlements are excluded.
+ * @returns produced paths in first-seen order; empty when the turn wrote nothing.
+ */
+export declare function producedForClosing(data: Readonly<FocusDeliverablesData> | undefined, seq: number): readonly string[];
+/**
+ * Resolve a terminal view's working directory the way the render-intent
+ * contract assigns to the UI bridge: an absolute path is used as-is, a
+ * relative one joins under the session workspace, and an omitted one IS the
+ * session workspace (the chat derivation). Without a session cwd there is
+ * nothing to resolve against, so a relative path stays as authored.
+ * @param viewCwd - the cwd the terminal call view carries, if any.
+ * @param sessionCwd - the session workspace root, if the caller knows it.
+ * @returns the working directory for the prompt label, or undefined.
+ */
+export declare function relativizeToCwd(text: string, cwd: string | undefined): string;
+/** Concatenate text content blocks (the result body the row expands to). */
+export declare function flattenText(content: readonly ContentBlock[]): string;
+/**
+ * Assistant thinking duration: time from the step's start to its first
+ * non-empty token delta. Only meaningful once the step is settled; null
+ * when the timing boundaries are unavailable.
+ * @param data - the assistant chat node data.
+ * @returns thinking time in ms, or null when not derivable.
+ */
+export declare function thoughtDurationMs(data: AssistantChatData): number | null;
+/**
+ * Display seconds for a duration: one decimal under ten seconds, whole
+ * seconds beyond. Unit-less so the locale templates own the suffix.
+ * @param ms - Duration in milliseconds (negatives clamp to zero).
+ * @returns display number in seconds without unit.
+ */
+export declare function formatSeconds(ms: number): string;

package/lib/types/client/model/todo.d.ts

@@ -0,0 +1,38 @@
+/** Pure plan derivation for the todo_write row's one-line summary (copied
+ *  from the official chat's `toolviews/plan-summary.ts`). Several items may
+ *  be `in_progress` at once — parallel work runs concurrent tasks, so a
+ *  summary built from one active item would silently drop the rest. */
+/**
+ * One list item as the row sees it: unvalidated model JSON parsed from a
+ * call's args, so any field may be missing or mistyped.
+ */
+export interface PlanItemLike {
+    content?: unknown;
+    status?: unknown;
+}
+/**
+ * Counts plus the two halves of the summary, deliberately NOT pre-joined:
+ * the row ellipsizes its summary text, and a count concatenated onto the end
+ * of the task name is the first thing a narrow row clips — exactly when it
+ * carries information. The row renders `activeExtra` as a non-shrinking
+ * suffix beside the truncatable text.
+ */
+export interface PlanSummary {
+    done: number;
+    total: number;
+    /** First `in_progress` content, or null when that first item is unusable. */
+    activeContent: string | null;
+    /** Active items beyond the first; 0 whenever there is no `activeContent` to sit beside. */
+    activeExtra: number;
+}
+/**
+ * Derive the counts and the active summary from a whole-list snapshot. It
+ * names the first `in_progress` item and counts the remaining active ones,
+ * so a parallel plan reports how many tasks are running rather than naming
+ * one and hiding the others. `activeContent` is null when nothing is in
+ * progress, or when the first active item's content is missing, mistyped, or
+ * blank once trimmed — the row then renders the counts alone.
+ * @param todos - the whole list, in model order.
+ * @returns the done/total counts and the two summary halves.
+ */
+export declare function planSummary(todos: readonly PlanItemLike[]): PlanSummary;

package/lib/types/client/model/tools.d.ts

@@ -0,0 +1,35 @@
+import type { ToolCallBlock } from '@deepseek-ai/dsh-client-ui-chat/client';
+import type { FocusGroupThink, FocusMetricKey, FocusToolGroup, FocusToolRow } from './types.ts';
+export declare const METRIC_BY_TOOL: Readonly<Record<string, FocusMetricKey>>;
+/**
+ * Per-build tool-row cache: the derived row model keyed by call id, kept
+ * only while the underlying block reference is unchanged. Settled history
+ * dominates long sessions, and its block objects are identity-stable, so
+ * cached rows let every flow rebuild skip the args JSON parse, card
+ * materialization, and path normalization for settled calls.
+ */
+export interface ToolRowModelCache {
+    readonly rows: Map<string, {
+        block: ToolCallBlock;
+        row: FocusToolRow;
+    }>;
+}
+/**
+ * Derive the condensed row model from a frozen call slice (the chat row
+ * model's derivation, reimplemented here), caching by call id: a repeat
+ * build over an unchanged block reference reuses the previous row object —
+ * same identity, so memoized rows never re-render.
+ * @param block - running call or settled result node.
+ * @param cwd - session workspace root; workspace-rooted path summaries display relative to it.
+ * @param home - host account home; a leftover POSIX home path displays as `~`.
+ * @param cache - optional per-session row cache (stable across builds).
+ * @returns the row model.
+ */
+export declare function toolRowModel(block: ToolCallBlock, cwd?: string, home?: string, cache?: ToolRowModelCache): FocusToolRow;
+/** A running call paints no live row until it has run this long: fast
+ *  calls (a few hundred ms) would otherwise flash a live row that settles
+ *  into the summary a moment later — the debounce skips the flash. */
+export declare const LIVE_ROW_THRESHOLD_MS = 400;
+/** Fold one consecutive run of root calls into a group model. */
+export declare function toolGroup(blocks: readonly ToolCallBlock[], cwd: string | undefined, thoughtMs: number | null, think: readonly FocusGroupThink[], home?: string, cache?: ToolRowModelCache): FocusToolGroup;
+/** Resolve one node's data into the flow item family, or null to skip (turn-tail chrome). */

package/lib/types/client/model/turn-slice.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Remote turn-slice projection: the durable event slice of one completed
+ * turn → the focus flow items its expanded row renders. React-free, in the
+ * same posture as `toolRowModel`: the chat's derivations, reimplemented here
+ * because the bundle cannot import another plugin's runtime values.
+ *
+ * Fold semantics align with `flow.ts` (0.1.22): consecutive tool calls fold
+ * into one group, directly-consecutive runs merge, context injections
+ * (including turn-less notices, counted as background jobs) absorb into the
+ * adjacent run, steering interjections stay visible rows between runs, and
+ * the closing reply's reasoning moves out of the reply row. Settled history
+ * never consumes chunk rows — `assistant/message` carries the final blocks;
+ * chunks feed the step timing (thinking time, TTFT, decode throughput) only.
+ * @module dsh-focus-chat/client/model/turn-slice
+ */
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types';
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
+import type { AssistantBlock } from '@deepseek-ai/dsh-client-ui-chat/client';
+import type { FocusFlowItem } from './types.ts';
+/** One projected turn: the work rows, the closing reply, and the turn tail. */
+export interface TurnSlice {
+    /** The turn's interior rows in flow order: context folds, tool groups, intermediate rows, steering bubbles. */
+    readonly work: readonly FocusFlowItem[];
+    /** The closing reply's assistant row; null when the turn has no text reply. */
+    readonly closing: FocusFlowItem | null;
+    /** The turn-tail row (branch disabled; the deliverables lane is window-only). */
+    readonly tail: FocusFlowItem | null;
+}
+/** Classify one finalized assistant block (the chat's content switch). */
+export declare function toAssistantBlock(block: ContentBlock): AssistantBlock;
+/**
+ * Project one completed turn's durable event slice into the focus flow items.
+ * @param events - the `[turn/start..turn/end]` closed event slice, in seq order.
+ * @param cwd - session workspace root for relative path summaries.
+ * @param home - host account home; a leftover POSIX home path displays as `~`.
+ * @returns the turn's work rows, closing reply, and tail row.
+ */
+export declare function projectTurnSlice(events: readonly SessionEvent[], cwd?: string, home?: string): TurnSlice;