@crazx/dsh-client-ui-conversation 0.1.5-alpha.1.zw.3

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

@@ -0,0 +1,272 @@
+import type { CommandId } from '@deepseek-ai/dsh-commands/brand';
+import type { MessageId } from '@deepseek-ai/dsh-llm/brand';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm/types';
+import type { ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import type { LlmRetryEventData } from '@deepseek-ai/dsh-llm-retry/types';
+import type { TodoItem } from '@deepseek-ai/dsh-tool-todo/client';
+import type { ContextProvenanceView, KnownContextForm } from './context-provenance.ts';
+export type { TodoItem };
+/** Request configuration recorded for one provider call. */
+export interface AssistantRequestConfig {
+    provider: string;
+    model: string;
+    purpose?: string;
+    thinking?: string;
+    reasoningEffort?: string;
+    temperature?: number;
+    maxTokens?: number;
+    stop?: readonly string[];
+}
+/** Stable provider/model identity reported for one completed request. */
+export interface AssistantProvenanceView {
+    provider: string;
+    model: string;
+}
+/** Assistant content blocks sorted by what a UI target presents. */
+export type AssistantBlock = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'reasoning';
+    text: string;
+} | {
+    kind: 'image';
+    attachment: ImageAttachmentRef;
+} | {
+    kind: 'tool-call';
+    callId: string;
+    name: string;
+    argsRaw: string;
+} | {
+    kind: 'other';
+    block: unknown;
+};
+/** A finalized user message. */
+export interface UserMessageNode {
+    kind: 'user';
+    seq: number;
+    /** Unix epoch ms from the source session event. */
+    time: number;
+    content: readonly ContentBlock[];
+    source: unknown;
+}
+/** Recorded boundaries used to derive assistant latency and throughput. */
+export interface AssistantTiming {
+    /** Matching step/start timestamp, or null when it is outside the current event window. */
+    stepStartTime: number | null;
+    /** First non-empty text/reasoning/tool delta timestamp, or null when no token delta was recorded. */
+    firstTokenTime: number | null;
+    /** Final assistant/message timestamp. */
+    completedTime: number;
+}
+/** A finalized assistant message or an interruption-frozen streaming prefix. */
+export interface AssistantMessageNode {
+    kind: 'assistant';
+    seq: number;
+    /**
+     * Stable identity carried from the `assistant/message` event. Absent only on
+     * synthetic interruption fallbacks assembled from chunks without a durable
+     * assistant message.
+     */
+    messageId?: MessageId;
+    /** Unix epoch ms from the source session event (or turn/end when frozen from a partial). */
+    time: number;
+    turn: number;
+    step: number;
+    blocks: readonly AssistantBlock[];
+    usage?: unknown;
+    provenance?: AssistantProvenanceView;
+    requestConfig?: AssistantRequestConfig;
+    /** Timing derived from the recorded step/chunk/message event sequence. */
+    timing?: AssistantTiming;
+    /** Prefix of an aborted turn, rendered with a 已停止 marker. A durable
+     *  finalized prefix uses its event seq; a chunk-only fallback uses a fractional
+     *  seq derived from the closing boundary to keep it ordered inside the flow. */
+    interrupted?: true;
+}
+/** A human message admitted from the next-step inbox while a turn was running. */
+export interface SteeringMessageNode {
+    kind: 'steering';
+    /** Stable message identity shared with its pre-admission inbox occurrence. */
+    messageId: MessageId;
+    seq: number;
+    /** Unix epoch ms from the source session event. */
+    time: number;
+    content: readonly ContentBlock[];
+    source: unknown;
+}
+/** A context/system injection surfaced in the flow. */
+export interface ContextMessageNode {
+    kind: 'context';
+    seq: number;
+    /** Unix epoch ms from the source session event. */
+    time: number;
+    content: readonly ContentBlock[];
+    source: unknown;
+    /** Role and producer name projected from `source` by the target. */
+    provenance: ContextProvenanceView;
+    /** Producer-declared information form supported by the target; null presents as opaque. */
+    form: KnownContextForm | null;
+}
+/** Durable notice that a closed failed step is waiting for a model-request retry. */
+export type ModelRetryNode = LlmRetryEventData & {
+    kind: 'model-retry';
+    seq: number;
+    /** Unix epoch ms from the llm/retry session event. */
+    time: number;
+    /**
+     * Client-derived lifecycle: scheduled until a retry turn starts, started
+     * once it does, or cancelled when the failed turn aborts first.
+     */
+    retryState: 'scheduled' | 'started' | 'cancelled';
+};
+/**
+ * Durable terminal failure for a turn that ended with an error reason; the
+ * turn's settled retry chain renders separately and never replaces this node.
+ */
+export interface TurnErrorNode {
+    kind: 'turn-error';
+    /** Seq of the owning turn/end event. */
+    seq: number;
+    /** Unix epoch ms from the turn/end event. */
+    time: number;
+    turn: number;
+    step: number;
+    /** Sanitized provider message; empty when a known code owns localized copy. */
+    message: string;
+    /** Stable provider failure code, when recorded. */
+    code?: string;
+}
+/** Durable notice for a turn ended by the per-request output-token cap. */
+export interface TurnMaxTokensNode {
+    kind: 'turn-max-tokens';
+    /** Seq of the owning turn/end event. */
+    seq: number;
+    /** Unix epoch ms from the turn/end event. */
+    time: number;
+    turn: number;
+    step: number;
+}
+/** A tool result paired (when in-window) with its call head. */
+export interface ToolResultNode {
+    kind: 'tool-result';
+    seq: number;
+    /** Unix epoch ms from the tool/result session event. */
+    time: number;
+    callId: string;
+    /** Parent Tool call for a Code Dispatch result; absent on a root Session result. */
+    parentCallId?: string;
+    /** Call head backfilled from the in-window tool/call; null when window truncation left the call outside (card head shows callId). */
+    call: {
+        name: string;
+        argsRaw: string;
+    } | null;
+    /** Unix epoch ms of the paired tool/call when the call is still in-window; used for call-row duration. */
+    callTime: number | null;
+    content: readonly ContentBlock[];
+    isError: boolean;
+    error?: {
+        name: string;
+        code: string;
+    };
+    meta?: unknown;
+    /** Child calls owned by this call, in dispatch order. */
+    subCalls: readonly ToolCallBlock[];
+}
+/**
+ * One landed compaction, marked at the checkpoint's own log position. The
+ * conversation it shadowed on the model surface stays in the transcript above
+ * it: the marker reports where the model stopped seeing that history, it does
+ * not replace it. The framed checkpoint payload is an instruction envelope
+ * written for the model and never renders.
+ */
+export interface CompactionSummaryNode {
+    kind: 'compaction';
+    /** Seq of the replacement `user/message` that landed the checkpoint. */
+    seq: number;
+    /** Unix epoch ms of the checkpoint event. */
+    time: number;
+    /** Summary text from the checkpoint's cited `compaction/summary` event; null when
+     *  the window cut left that event outside (the marker is then not expandable). */
+    summary: string | null;
+    /** Seq of the loaded `compaction/summary` event, or null when that event is outside the window. */
+    summaryEventSeq: number | null;
+    /** Number of surface items replaced, or null when the summary event is unavailable or malformed. */
+    shadowedItemCount: number | null;
+    /** Estimated token price of the replaced items, or null when the summary event is unavailable or malformed. */
+    shadowedTokenCount: number | null;
+}
+/**
+ * Fallback for surface events this UI version does not know: the documented
+ * default arm of `SessionEventMap`, which is merge-extensible, so the
+ * projection's switch cannot end in `assertNever`. No event produces this node
+ * because `isAppendSurfaceEvent` admits only the four types in core's
+ * `SurfaceEventType`, and each has its own arm (`system/message` is claimed by
+ * a Chat Definition that renders no transcript row) — and it exists so widening
+ * that set core-side degrades to a raw row instead of dropping the event silently.
+ */
+export interface UnknownSurfaceNode {
+    kind: 'unknown';
+    seq: number;
+    /** Unix epoch ms from the source session event when known. */
+    time: number;
+    type: string;
+    data: unknown;
+}
+/**
+ * One slash-command lifecycle folded from the log-only `command/run` /
+ * `command/done` pair (paired by commandId, mirroring tool call↔result).
+ * Log-only events are not surface events, so the command Definition indexes
+ * them separately and the Chat builder orders the resulting node by seq. A window cut
+ * between the pair soft-falls like tool pairs: a done with no in-window run
+ * still builds a node (name/args null), and a run with no done renders as
+ * still executing.
+ */
+export interface CommandNode {
+    kind: 'command';
+    /** Seq of the command/run event; the done event's seq when only the done is in-window. */
+    seq: number;
+    /** Unix epoch ms of the anchoring event. */
+    time: number;
+    /** Pairing id minted by the host executor. */
+    commandId: CommandId;
+    /** Command name (run payload's structured field); null when the run fell outside the window. */
+    name: string | null;
+    /**
+     * Verbatim rawInput after the name, including separator whitespace; null
+     * when omitted by the command or when the run fell outside the window.
+     */
+    args: string | null;
+    /** Settlement outcome (done payload); null while the command is still executing. */
+    outcome: {
+        kind: 'success' | 'error';
+        text?: string;
+        /** Earlier authoritative domain event for a richer client-computed presentation. */
+        sourceEventSeq?: number;
+    } | null;
+}
+/** Finalized conversation node union (kind discriminates; seq is the React key). */
+export type ConversationNode = UserMessageNode | AssistantMessageNode | SteeringMessageNode | ContextMessageNode | ModelRetryNode | TurnErrorNode | TurnMaxTokensNode | ToolResultNode | CommandNode | CompactionSummaryNode | UnknownSurfaceNode;
+/** In-flight tool card material: tool/call seen, tool/result not yet. */
+export interface RunningToolCall {
+    callId: string;
+    /** Parent Tool call for a Code Dispatch start; absent on a root Session call. */
+    parentCallId?: string;
+    name: string;
+    argsRaw: string;
+    turn: number;
+    step: number;
+    /** Unix epoch ms when the tool/call event was logged. */
+    time: number;
+    /** Child calls owned by this call, in dispatch order. */
+    subCalls: readonly ToolCallBlock[];
+}
+/** One running or settled call, recursively owning its child calls. */
+export type ToolCallBlock = RunningToolCall | ToolResultNode;
+/** In-progress assistant output (chunk accumulator product). */
+export interface PartialAssistant {
+    turn: number;
+    step: number;
+    blocks: readonly AssistantBlock[];
+}
+//# sourceMappingURL=records.d.ts.map

package/lib/types/client/contract/request-inspection.d.ts

@@ -0,0 +1,131 @@
+import type { ContentBlock, ToolSchema } from '@deepseek-ai/dsh-llm/types';
+import type { SessionEvent } from '@deepseek-ai/dsh-session/types';
+import type { AssistantProvenanceView, AssistantRequestConfig } from './records.ts';
+export type { AssistantProvenanceView, AssistantRequestConfig, } from './records.ts';
+/**
+ * Complete model-visible request state in force for an ordinary generation:
+ * the `request/header` config and tools plus the system prompt held by the
+ * current `system/message` surface node.
+ */
+export interface ConversationPromptSnapshot {
+    /** Provider/model and sampling configuration from the effective request header. */
+    config: AssistantRequestConfig;
+    /**
+     * Rendered text of the `system/message` surface node in force for the
+     * request; empty when the surface has no system prompt or the node lies
+     * outside the loaded history window.
+     */
+    system: string;
+    /** Complete tool catalog sent with the request, including tools that were never called. */
+    tools: readonly ToolSchema[];
+}
+/** Effective prompt or introduced system node, anchored at the event that establishes it. */
+export interface SystemPromptNode {
+    /** Sequence of the system event or replacement that establishes this prompt. */
+    seq: number;
+    /** Unix epoch ms of that event. */
+    time: number;
+    /** Turn the loop committed the node in. */
+    turn: number;
+    /** Step the loop committed the node in. */
+    step: number;
+    /** Rendered system prompt text; empty records "no system prompt". */
+    text: string;
+    /**
+     * True for a prompt appended after an earlier loaded system node: an
+     * in-history update the model reads at this position, presented where it
+     * was committed rather than by the next request header.
+     */
+    update: boolean;
+}
+/** System/tool change introduced while preparing one ordinary request, or by an in-history prompt update. */
+export interface RequestPromptChange {
+    /**
+     * Sequence of the event that introduced this state: the `system/message`
+     * node when it introduced, replaced, or updated the system prompt, otherwise the
+     * `request/header` event.
+     */
+    seq: number;
+    /** Unix epoch ms of that event. */
+    time: number;
+    /** How the model-visible prompt differs from the previous recorded state. */
+    kind: 'initial' | 'system' | 'tools' | 'system-and-tools';
+    /** State immediately before this change; absent for the initial header. */
+    previous?: ConversationPromptSnapshot;
+}
+/** Canonical prompt snapshot and any model-visible change introduced by one request header. */
+export interface RequestPromptInspection {
+    /** Complete prompt state in force for the header's request. */
+    prompt: ConversationPromptSnapshot;
+    /** System/tool change relative to the preceding loaded header. */
+    change?: RequestPromptChange;
+}
+/**
+ * The {@link inspectRequestPrompt} signature as a value seam: Chat and
+ * Trajectory Definitions receive it from the uiConversation service because a
+ * client bundle cannot value-import another plugin's module.
+ */
+export type RequestPromptInspector = (previous: ConversationPromptSnapshot | undefined, event: SessionEvent<'request/header'>, system: SystemPromptNode | undefined) => RequestPromptInspection;
+/**
+ * Canonicalize one request header against the system node in force and
+ * classify the model-visible prompt change.
+ * @param previous - Prompt from the preceding loaded request header, when available.
+ * @param event - Durable full request header to inspect.
+ * @param system - Effective nonempty system prompt after loaded surface replacements; empty when removed.
+ * An in-history update already presented its text at its own position, so the header reports no system change for it.
+ * @returns The canonical prompt and an initial/system/tool change when it can be established.
+ */
+export declare function inspectRequestPrompt(previous: ConversationPromptSnapshot | undefined, event: SessionEvent<'request/header'>, system: SystemPromptNode | undefined): RequestPromptInspection;
+/** Lifecycle fields shared by ordinary generation and compaction requests. */
+interface RequestViewBase {
+    /** Sequence that opened the operation represented by this request. */
+    startSeq: number;
+    startedAt: number;
+    completedAt: number | null;
+    status: 'running' | 'complete' | 'error';
+    error?: string;
+    /** Stable provider code for localized presentation of known failures. */
+    errorCode?: string;
+    provenance?: AssistantProvenanceView;
+    requestConfig?: AssistantRequestConfig;
+    usage?: unknown;
+    /** Assistant message or compaction summary sequence produced by this request. */
+    resultSeq?: number;
+}
+/** One ordinary assistant generation assembled from durable request events. */
+interface AssistantRequestView extends RequestViewBase {
+    purpose: 'assistant';
+    turn: number;
+    /** Agent-loop step that issued this request. */
+    step: number;
+    /** Effective ordinary request input, inherited until a later header changes it. */
+    prompt?: ConversationPromptSnapshot;
+    /** Prompt change logged while preparing this request. */
+    promptChange?: RequestPromptChange;
+    /** Retry ordinal scheduled after a failed ordinary request. */
+    retry?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+}
+/** One compaction provider request, either turn-owned or standalone between turns. */
+interface CompactionRequestView extends RequestViewBase {
+    purpose: 'compaction';
+    /** Owning turn, or `null` when manual compaction ran between turns. */
+    turn: number | null;
+    /** Direct compaction requests do not consume an agent-loop step. */
+    step: 0;
+    /** Compaction replacement message sequence, when one was committed. */
+    replacementSeq?: number;
+    /** Safe compaction summary projection. */
+    summary?: readonly ContentBlock[];
+    /** Complete compaction provider output before the safe projection. */
+    rawOutput?: readonly ContentBlock[];
+}
+/** One provider request assembled from durable request lifecycle events. */
+export type RequestView = AssistantRequestView | CompactionRequestView;
+/** Request data consumed by the stage-oriented Trajectory layout. */
+export interface RequestInspectionSnapshot {
+    requests: readonly RequestView[];
+    callSchemas: ReadonlyMap<string, ToolSchema>;
+}
+//# sourceMappingURL=request-inspection.d.ts.map